ping-rust 0.2.2

Menu-driven installer and manager for the shoes proxy server
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
# ping-rust

[![crates.io](https://img.shields.io/crates/v/ping-rust.svg)](https://crates.io/crates/ping-rust)
[![GitHub Release](https://img.shields.io/github/v/release/Jyanbai/ping-rust)](https://github.com/Jyanbai/ping-rust/releases/latest)
[![CI](https://github.com/Jyanbai/ping-rust/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Jyanbai/ping-rust/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

`ping-rust` 是一个纯 Rust 编写的 [cfal/shoes](https://github.com/cfal/shoes) 安装与管理工具。它提供类似 233boy 脚本的数字菜单,在 Linux VPS 上完成 shoes 安装、受管协议配置、systemd 管理和日常运维。

核心逻辑全部位于 Rust 源码中;`scripts/install.sh` 只负责执行 Rust 前的架构检测、下载、SHA-256 校验与严格解包,原子安装、快捷命令所有权判断和首次部署均由已校验的 Rust 二进制完成。

> 当前稳定版:[`v0.2.2`](https://github.com/Jyanbai/ping-rust/releases/tag/v0.2.2)。v0.2.0 引入 Update Center、Verified Hot Reload、Chain Proxy 2.0、规则路由和受验证范围内的 H2MUX;v0.2.1 增加 Pool 节点批量测试、热重载不可用原因提示和 NaiveProxy 测试证书有效期管理;v0.2.2 将默认安装的 shoes 固定为经过验证的 v0.2.7(已装更新的未验证版本时提示回退命令),YAML 库换成 serde-saphyr(修复 RUSTSEC-2024-0449),`--version` 额外输出构建 commit。**热重载需要固定 pin 构建;默认一键安装使用 GitHub Release 来源,监听变更使用受控重启。**支持 VLESS-Reality-Vision、Hysteria2、TUIC v5、Shadowsocks、AnyTLS、VLESS-TLS-Vision、VLESS-WS-TLS、Trojan-TLS、Trojan-REALITY、VMess-WS-TLS、SOCKS5、Snell v3 和 NaiveProxy 十三种受管协议。用户只选择完整协议,不需要理解或手动组合传输层、安全层与内层协议。

完整文档:[Wiki](https://github.com/Jyanbai/ping-rust/wiki) · [快速开始](https://github.com/Jyanbai/ping-rust/wiki/Quick-Start) · [链式代理](https://github.com/Jyanbai/ping-rust/wiki/Chain-Proxy) · [故障排查](https://github.com/Jyanbai/ping-rust/wiki/Troubleshooting)

## 一键安装(推荐)

无需预装 Rust。在 Ubuntu 22.04/24.04、Debian 12、Rocky Linux 9、AlmaLinux 9 等 systemd Linux 上执行:

```bash
bash <(curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/Jyanbai/ping-rust/main/scripts/install.sh)
```

这一个命令会继续自动下载 shoes、选择随机可用端口、生成全部安全凭据、启动 systemd,并直接输出可导入 v2rayN 的 `vless://` 链接,不询问协议或端口。部署完成后使用 `sudo prs` 进入日常管理菜单。

安装指定版本或目录:

```bash
bash <(curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/Jyanbai/ping-rust/main/scripts/install.sh) \
  --version v0.2.2

bash <(curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/Jyanbai/ping-rust/main/scripts/install.sh) \
  --install-dir /usr/local/bin --quiet --no-bootstrap
```

Stage 0 自动识别 x86_64/aarch64,从 GitHub Releases 下载对应 musl 静态包,并在首次执行前强制验证 `SHA256SUMS`、归档结构和二进制版本。随后由隐藏的 Rust 安装入口原子写入 `/usr/local/bin/ping-rust`,安全创建 `prs → ping-rust`,并调用现有 Rust `bootstrap` 完成默认 Reality 部署。检测到已有配置时自动跳过,`--no-bootstrap` 可用于只安装管理工具。若系统已有其它 `prs` 命令,安装器会保留它并提示改用 `ping-rust`;升级时只会移除确实指向同目录 `ping-rust` 的旧 `sb` 链接。轻量 Stage 0 协议从 `v0.1.16` 开始;令牌、密码和代理配置都不会被上传。

### 版本兼容

默认命令安装最新稳定版。`v0.1.16` 起,一键安装脚本通过已校验二进制的 `install-self` 完成原子安装。安装 `v0.1.15` 或更早版本时,必须同时使用对应 tag 内的旧脚本:

```bash
bash <(curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/Jyanbai/ping-rust/v0.1.15/scripts/install.sh) \
  --version v0.1.15
```

## 功能

- 默认安装经过验收的固定 shoes Release(当前 `v0.2.7`,见 `src/installer.rs` 的 `SHOES_RELEASE_TAG`),不跟随上游 latest;上游有更新 Release 时 Update Center 仅提示“未经验证”,不会自动安装
- 从 GitHub Release 下载 shoes,自动匹配 x86_64/aarch64 与 GNU/musl,强制校验官方 SHA-256 digest;GNU 资产不兼容时安全回退 static musl
- 使用 cargo 从与 schema CI 相同的 cfal/shoes 固定源码提交编译安装;低于 1 GiB 内存时自动单任务并关闭 LTO,避免换页风暴
- 生成经过固定 shoes schema 验证的协议预设;每项均是可直接部署的完整协议栈
- `prs` 数字菜单与 `prs add/a` 快捷命令:自动端口、自动凭据,部署完成后输出分享链接或完整手动连接参数
- 在 Rust 内生成 X25519 Reality 密钥、UUID、short ID、随机密码和自签名证书
- Reality 未显式指定 SNI 时,从与本地 233boy 脚本一致的 Amazon、eBay、PayPal、Cloudflare 域名列表中随机选择(不含 Apple);客户端指纹与该脚本一致固定为 `chrome`
- 在同目录候选文件上调用 `shoes --dry-run`,通过后才原子提交并启用 systemd 服务
- systemd unit 限制内核调优、内核模块、控制组、地址族、可执行内存和非原生 ABI;Ubuntu/Debian 验收会实际启动加固后的 shoes
- 多配置添加、列表、删除、端口冲突保护
- Chain Proxy 2.0:由 Nodes、Pools、有序多跳 Chains、路由规则和默认路由组合出口;规则可选择 DIRECT、BLOCK、Chain 或多 Chain 轮询
- Verified Hot Reload(固定 pin 来源):对可观察的监听变更验证 MainPID 与端口,失败恢复旧配置和服务状态;默认 Release 来源使用受控重启
- Update Center:管理 ping-rust 更新、固定 shoes pin、安全状态检查与显式 Release 安装;默认拒绝已知降级
- H2MUX 客户端偏好:在已验证的 VMess/VLESS WebSocket TLS 与 Trojan TLS 范围内提供 sing-box 导出
- SOCKS5、Snell v3、NaiveProxy 和 Shadowsocks 2022 + ShadowTLS v3 受管配置
- 跨进程配置锁、配置/sidecar 精确回滚,更新与恢复保留服务原运行状态
- 服务启停、重启、状态、journalctl 日志、更新与卸载
- BBR、TCP/UDP 端口检查、敏感配置备份与安全恢复
- 导出 Clash Meta、sing-box 和 Nekobox 分享链接
- Rust 原生更新 ping-rust 自身:GitHub Release + `SHA256SUMS` 双重校验、版本探针、原子替换与失败回滚

### 协议分级

| 标签 | 协议或功能 | 说明 |
|---|---|---|
| 稳定 | VLESS-Reality-Vision、Hysteria2、TUIC v5、Shadowsocks、AnyTLS、VLESS-TLS-Vision、VLESS-WS-TLS、Trojan-TLS、Trojan-REALITY、VMess-WS-TLS、SOCKS5、Shadowsocks 2022 + ShadowTLS v3 | 受管部署及对应范围的 CI 验收 |
| 实验性 | Snell v3、NaiveProxy、H2MUX 客户端偏好 | 导出面受限,已验证的客户端兼容范围较窄;使用前核对下文各协议限制 |

## 支持环境

| 系统 | 架构 | Release 安装 | cargo 安装 |
|---|---|---:|---:|
| Ubuntu 22.04 / 24.04 | x86_64 / aarch64 | 是 | 是 |
| Debian 12 | x86_64 / aarch64 | 是 | 是 |
| Rocky Linux 9 / AlmaLinux 9 | x86_64 / aarch64 | 是 | 是 |

要求系统使用 systemd。一键安装 ping-rust 与 shoes Release 安装都不要求服务器预装 Rust;只有 cargo 安装方式需要稳定版 Rust 工具链。

## 其他安装方式

使用 cargo 安装前,最小 VPS 需要 C linker 和常用构建工具:

```bash
# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y build-essential pkg-config git ca-certificates

# Rocky Linux / AlmaLinux
sudo dnf install -y gcc gcc-c++ make pkgconf-pkg-config git ca-certificates
```

从 [crates.io](https://crates.io/crates/ping-rust) 安装已发布的稳定版本:

```bash
cargo install ping-rust --locked
sudo ping-rust
```

直接从已公开的 GitHub `main` 安装:

```bash
cargo install --git https://github.com/Jyanbai/ping-rust.git --locked
sudo ping-rust
```

从当前源码安装:

```bash
git clone https://github.com/Jyanbai/ping-rust.git
cd ping-rust
cargo install --path . --locked
sudo ping-rust
```

首次启动、生成系统配置、管理 systemd、BBR、备份恢复和卸载都需要 root。生成到自定义路径、查看帮助和本地端口检查不要求 root。

## 233boy 风格快速部署

执行一键安装命令后,无需再输入任何内容:

```text
$ bash <(curl -fsSL https://raw.githubusercontent.com/Jyanbai/ping-rust/main/scripts/install.sh)

首次安装:自动部署 VLESS-REALITY
正在自动安装 shoes、选择随机端口并生成安全凭据……

部署成功,shoes 服务已启动。

-------------- VLESS-REALITY-30060.yaml -------------
协议 (protocol)         = vless
端口 (port)             = 30060
传输层安全 (TLS)        = reality
------------- 链接 (URL) -------------
vless://...security=reality...pbk=...&sid=...#VLESS-REALITY-30060
------------- 二维码 (QR) -------------
(终端在这里显示可直接扫描的块字符二维码)
------------- END -------------
```

安装脚本只在配置文件和管理状态都不存在时触发默认部署。Rust `bootstrap` 会自动下载 shoes、选择随机可用端口、生成 UUID/X25519 密钥/short ID、执行 `shoes --dry-run`、启动并确认 systemd 服务,然后输出可直接导入 v2rayN 的链接;检测到任何已有配置时绝不覆盖。通过 cargo 安装的用户第一次运行 `sudo prs` 时也会执行同一安全入口。

部署完成后的常规菜单如下:

```text
$ sudo prs

------------- ping-rust v0.2.2 -------------
shoes: running
项目: https://github.com/Jyanbai/ping-rust

1) 添加配置
2) 更改配置
3) 查看配置
4) 删除配置
5) 运行管理
6) 更新
7) 卸载
8) 帮助
9) 其他
10) 关于
0) 退出

请选择 [0-10]: 1

选择协议:

1) TUIC
2) Hysteria2
3) Shadowsocks
   ├─ Shadowsocks 2022
   └─ Shadowsocks 2022 + ShadowTLS v3(推荐)
4) VLESS-REALITY(推荐)
5) AnyTLS
6) VLESS-TLS-Vision
7) VLESS-WS-TLS
8) Trojan-TLS
9) Trojan-REALITY
10) VMess-WS-TLS
11) SOCKS5
12) Snell v3
13) NaiveProxy
0) 返回

请选择 [0-13]: 4
输入端口(直接回车自动选择随机端口):

部署成功,shoes 服务已启动。
-------------- VLESS-REALITY-25448.yaml -------------
协议 (protocol)         = vless
端口 (port)             = 25448
------------- 链接 (URL) -------------
vless://...security=reality...pbk=...&sid=...#VLESS-REALITY-25448
------------- 二维码 (QR) -------------
(终端在这里显示可直接扫描的块字符二维码)
------------- END -------------
```

菜单 `2. 更改配置` 会先选择现有配置,再按协议提供端口、名称、公网地址、凭据、Reality SNI、Shadowsocks/Snell cipher、Snell/SOCKS5 UDP 开关或 AnyTLS 用户密码等修改项。新配置必须通过真实 `shoes --dry-run` 才会原子提交;应用失败时自动恢复修改前的配置与 systemd 状态。Snell v3 没有统一标准分享 URI,因此成功后显示完整手动连接参数,不生成伪 URI 或二维码。

### Hot Reload

热重载要求 shoes 来源为 `verified-pin`,revision 等于 `386b11532424b8665ee3e46340c6236fb3c47595`,服务已运行、unit 内容与加载路径未被修改、没有 drop-in,且受保护的文件锚点已就绪。默认一键安装使用 GitHub Release 来源,因此不启用 Verified Hot Reload;新增监听、修改端口或删除非最后节点时,使用受控重启,并输出原因和切换方法。此路径的 MainPID 改变是预期结果。

在 `prs → 6) 更新 → shoes 内核` 中选择已验证固定 pin,或执行:

```bash
sudo ping-rust update --method cargo
```

切换需要 Rust、C linker、Git 与构建依赖,会从源码编译 shoes,耗时取决于 CPU、磁盘和缓存。低于 1 GiB 内存不建议编译;需为编译预留内存、swap 和磁盘空间,实测耗时与峰值见验收记录。安装成功后 provenance 才记录为 `verified-pin`。切回 Release 不会启用热重载;已知降级仍需明确允许。

满足前置条件时,新增监听、修改监听端口和删除非最后节点会尝试 shoes 原生配置热重载。ping-rust 保留聚合配置的原子替换,用文件锚点通知固定 shoes 的 watcher;只有 MainPID 不变、服务保持 active、预期监听出现且旧监听消失时才算成功。候选配置仍先通过 `shoes --dry-run`。已开始的热重载未能确认时,操作失败并恢复旧配置与服务状态,必要时重新启动旧服务。

只改显示名称或公网地址等不影响运行 YAML 的信息无需服务动作。凭据等无法从监听端口证明已生效的修改继续重启 shoes;首次部署仍启动服务,删除最后一个节点仍停止服务。备份恢复、链式代理切换和 shoes 二进制更新保持原有服务处理流程。

每个节点都会保存为 `/etc/shoes/profiles/` 下的真实独立 YAML 文件;查看、更改和删除时直接显示该文件名,例如 `VLESS-REALITY-53453.yaml` 或 `SNELL-8389.yaml`。支持分享 URI 的协议会以相同文件基名作为 URI 标签,并在添加或查看时显示终端二维码;Snell v3 只显示手动连接参数。只有一个配置时自动选中,多个配置时才显示数字列表。shoes 继续加载由 Rust 确定性聚合的 `/etc/shoes/config.yaml`,内部 UUID 仅用于安全定位。

### 链式代理 2.0

从主菜单进入 `9) 其他 → 1) 链式代理`:

```text
------------- Chain Proxy 2.0 -------------
状态:启用 / 禁用
默认路由:DIRECT

1) 节点管理
2) Pool 管理
3) Chain 管理
4) 路由规则
5) 默认路由
6) 启用 / 禁用
7) 测试节点 / Chain
8) 查看当前拓扑
0) 返回
```

配置按 **Nodes → Pools → Chains → Routing Rules → Default Route** 组合。Chain 可以包含有序的多跳;Pool 在某一 hop 内轮询节点;多条完整 Chain 可以通过 whole-chain round-robin 轮询。规则支持 IPv4/IPv6 CIDR、精确主机名和通配主机名,并提供 DIRECT、BLOCK、Chain 和多 Chain 轮询目标。默认路由覆盖未匹配规则的 IPv4 与 IPv6 流量。

Pool 与多 Chain 轮询只表示连接分布,不提供健康检查、自动故障切换或延迟选择。可在 `9) 其他 → 1) 链式代理 → 7) 测试节点 / Chain → 3) 测试 Pool 内全部节点` 手动逐个排查。

当前支持 SOCKS5、HTTP/HTTPS、Shadowsocks、VLESS TCP/TLS/Reality/WebSocket、Trojan TLS/WebSocket,以及由 ping-rust 生成的 VMess WebSocket TLS 分享链接。由于当前 shoes 内核没有对应客户端实现,Hysteria2、TUIC、WireGuard/WARP 不能作为链式出口;ping-rust 会返回明确错误,不生成近似配置。HTTP、SOCKS5 和 Trojan 出口不支持 UDP-over-TCP,启用或切换时会再次警告;相关 UDP 请求会失败,不会自动回退直连。

“测试节点 / Chain”严格复用临时 shoes SOCKS5 入口执行完整代理请求;Chain 测试会验证所有有序 hop,而不是逐节点测试的集合。Pool 手动测试按成员顺序输出每个节点的可用性、失败原因和耗时,不改变在线路由。测试进程和权限为 `0600` 的临时配置随后立即删除。它不会修改当前出口或线上 systemd 服务。

新建 v2 状态的默认路由是 DIRECT;在节点管理中“选择出口”会创建或更新单跳默认 Chain,兼容旧版操作习惯。旧版 `active_node` 状态在内存中迁移为单跳 Chain,保留原启用状态与出口;仅读取状态不会改写文件。仍被 Pool、Chain、规则或默认路由引用的对象不能删除。固定 shoes 0.2.8 的 Hysteria2/TUIC UDP 服务端路径会忽略 client chain 并直接创建 UDP socket,因此存在这些入站时会拒绝启用全局链式代理。节点凭据保存在权限为 `0600` 的管理状态和配置文件中,备份同样包含这些敏感信息。

示例:`JP Pool = jp-1, jp-2`;`HK-JP Chain = HK → JP Pool`;规则 `10.0.0.0/8 → DIRECT`、`*.finance.example → TW Chain`、`*.ads.example → BLOCK`;默认路由 `HK-JP Chain`。规则顺序与菜单顺序相同,先匹配的规则优先;可上移和下移。Chain/路由修改继续走候选 `shoes --dry-run`、原子提交、systemd 重启与失败回滚;普通 profile 的已验证 Hot Reload 行为不变。

### H2MUX 客户端偏好

VMess WebSocket TLS、非 Vision VLESS WebSocket TLS 和 Trojan TLS 可在“更改配置”中设置 H2MUX;链式代理的相应节点可独立设置。默认关闭。连接数模式默认 `max_connections=4`、`min_streams=4`、`max_streams=0`、`padding=false`;最大 streams 模式与连接数模式互斥。GitHub Release shoes v0.2.7 与固定 pin 服务端均自动识别 H2MUX,无需更改服务端 YAML;来源矩阵见 `COMPLETION_AUDIT.md`。只修改受管 profile 的客户端偏好时,运行配置不变,服务无需重启或热重载;修改链式节点会更新运行配置并走现有安全重启路径。

sing-box 导出会携带 `multiplex.protocol=h2mux`;固定 shoes 上的 VMess/VLESS WebSocket TLS 和 Trojan TLS 已通过本地 TCP、并发流、half-close 与大 payload 验证,sing-box 1.14.2 已通过导出配置检查及 Trojan H2MUX 数据面测试。Mihomo H2MUX 存在已知兼容问题,开启偏好时拒绝 Mihomo 导出;NekoBox、普通分享 URI 与 QR 仍可用于普通连接,但不携带 H2MUX 设置。VLESS Vision、Shadowsocks、SS2022 + ShadowTLS、Snell v3 及其它协议不提供 H2MUX 开关。H2MUX UDP 尚未验证或启用;Pool、Chain 和路由语义不受该偏好影响。

首次安装流程是:`install.sh → 自动安装 ping-rust/shoes → 自动随机端口部署 VLESS-REALITY → 复制 URL`,中间零输入。Reality 未指定 SNI 时会从 `www.amazon.com`、`www.ebay.com`、`www.paypal.com`、`www.cloudflare.com`、`dash.cloudflare.com`、`aws.amazon.com` 中随机选择;列表不含 Apple,客户端指纹固定为本地 233boy 脚本使用的 `chrome`。后续日常流程是:`prs → 1 → 选择协议 → 输入端口/直接回车随机`;Shadowsocks 会额外选择加密方式和密码,SS 2022 密码不符合所选 cipher 的 Base64 密钥长度时会警告并自动替换。其余协议自动生成 UUID、密码、Reality 密钥、WebSocket 路径或证书。SOCKS5 快速添加默认生成安全随机用户名和密码并启用 UDP ASSOCIATE;Snell v3 快速添加默认生成随机密码并启用 UDP-over-TCP。NaiveProxy 要求明确选择受信任证书或自签名测试模式,不会静默生成生产自签名配置。添加或查看配置成功后直接退出 `prs`;主菜单输入 `0` 退出,任意子菜单输入 `0` 返回主菜单。自动端口从 `20000..=65535` 的高位范围选择;菜单协议选择固定使用连续编号 `1..=13`。信息只会在配置通过 `shoes --dry-run`、原子写入、systemd 启动且确认为 active 后输出;失败会恢复原配置和服务状态。

非交互方式:

```bash
# 自动安装 shoes、随机端口和凭据;标准输出只返回一行链接
sudo prs add reality --yes --plain

# 233boy 风格短别名和指定端口
sudo prs a r 443
sudo prs add ss 8388

# 自动随机端口也可显式写出;指定公网地址可跳过自动探测
sudo prs add reality --random-port --server-address 203.0.113.10
```

高级用户原有的 `generate` 命令全部保留,可精细指定 cipher、证书、Reality fallback、AnyTLS 用户等参数。

新增协议也可直接使用短命令,无需组合底层参数:

```bash
sudo prs add vless-tls
sudo prs add vless-ws-tls
sudo prs add trojan-tls
sudo prs add trojan-reality
sudo prs add vmess-ws-tls
sudo prs add socks5
sudo prs add snell
```

SOCKS5 支持 TCP CONNECT 与 UDP ASSOCIATE,默认启用用户名/密码认证。SOCKS5 本身不提供传输加密,更适合作为工具型代理、内网代理或链式出口。高级添加可关闭 UDP,或在明确警告后主动选择无认证模式。Snell v3 高级添加可选择 cipher、密码和 UDP-over-TCP 开关。

WebSocket 路径默认安全随机生成;需要固定路径时可使用完整命令:

```bash
sudo ping-rust generate vless-ws-tls --port 443 \
  --server-name proxy.example.com --websocket-path /vless
```

重新显示已保存链接(多个配置时使用名称或 UUID):

```bash
sudo prs info
sudo prs url reality-main
sudo prs qr reality-main
```

添加配置、`qr` 与菜单中的 `3) 查看配置` 使用内置 Rust 编码器在终端生成二维码,不依赖 `qrencode`,也不会把含凭据的 URL 发送给第三方网站。`add --plain` 和 `url` 始终只输出一行链接,适合脚本调用。

## Hysteria2 与 TUIC

快速生成:

```bash
sudo ping-rust generate hysteria2 --name hy2 --port 8443 --server-name proxy.example.com
sudo ping-rust generate tuic --name tuic --port 10443 --server-name proxy.example.com
```

未指定证书时会创建自签名证书。工具导出客户端配置时会设置相应的跳过校验字段,并显示风险提示;生产环境推荐使用受信任证书:

```bash
sudo ping-rust generate hysteria2 \
  --name hy2 \
  --port 8443 \
  --server-name proxy.example.com \
  --cert /etc/letsencrypt/live/proxy.example.com/fullchain.pem \
  --key /etc/letsencrypt/live/proxy.example.com/privkey.pem
```

`--cert` 与 `--key` 必须同时提供。

## Shadowsocks 与 AnyTLS

Shadowsocks 默认使用 shoes 推荐列表中的 2022 AES-256-GCM,并生成标准 Base64 编码的 32 字节密钥:

```bash
sudo ping-rust generate shadowsocks --name ss-main --port 8388

# 指定其它 shoes 支持的 cipher;2022 密码会严格检查解码后长度
sudo ping-rust generate shadowsocks \
  --name ss-aes128 \
  --port 8389 \
  --cipher 2022-blake3-aes-128-gcm

# Shadowsocks 2022 + ShadowTLS v3;握手目标默认由 SNI 推导为 SNI:443
sudo ping-rust generate shadowsocks --shadowtls \
  --name ss-shadowtls \
  --port 8443 \
  --server-name www.cloudflare.com

# 快速添加:旧命令保持普通 Shadowsocks;只有显式参数才启用 ShadowTLS
sudo prs add shadowsocks
sudo prs add shadowsocks --shadowtls
```

ShadowTLS v3 由当前固定 shoes 内核原生承载,服务端仍只有一个 shoes 进程和一个受管 YAML,不需要额外安装或运行 `shadow-tls`。该模式只接受三种 Shadowsocks 2022 cipher,并分别安全生成合规 SS2022 Base64 密钥与独立 ShadowTLS 密码。当前首版明确为 TCP-only:sing-box 的 ShadowTLS outbound 只暴露 TCP,因此不会生成 `udp: true` 或声称 UDP/UoT 可用。

客户端兼容性以实际 schema 为准:sing-box 导出为 `shadowsocks` outbound 通过 `detour` 连接 `shadowtls` v3 outbound;Mihomo 导出为 Shadowsocks 的 `plugin: shadow-tls` 与 `plugin-opts`。NekoBox 专用 URI、标准 `ss://`、普通二维码和 chain outbound 均不伪造,使用时请导出 sing-box 或 Mihomo 配置。

## NaiveProxy

NaiveProxy 使用 shoes 内置的 TLS + HTTP/2 CONNECT 服务端,ALPN 固定为 `h2`,padding 默认开启,不需要额外代理进程。生产环境应使用真实域名与受信任 TLS 证书;自签名仅供测试,不推荐生产使用。当前没有自动 ACME 签发。

```bash
# 生产:提供与域名匹配的受信任证书和私钥
sudo prs add naiveproxy --server-name naive.example.com \
  --cert /etc/ssl/naive/fullchain.pem --key /etc/ssl/naive/privkey.pem

# 测试:明确选择自签名模式
sudo prs add naiveproxy --server-name naive.example.com --self-signed
```

用户名、密码默认安全随机生成,fallback 可选绝对静态目录路径。UDP/UoT 尚未完成端到端验证,首版仅支持 TCP。sing-box 原生 `type: naive` 导出只适用于包含 Naive/Chromium 支持的平台或特殊构建;Mihomo、NekoBox、标准 URI、普通二维码和 chain outbound 暂不支持。当前 sing-box Naive outbound 明确拒绝 `insecure: true`,因此自签名测试导出会嵌入公开证书供客户端验证,绝不导出服务器私钥。

NaiveProxy 自签测试证书从生成时刻前 1 小时开始生效,按 **CA/B Forum Ballot SC-081v3** 时间表及证书自身的 `notBefore` 确定有效期,并比该阶段上限少 1 天:2026-03-15 起 199 天,2027-03-15 起 99 天,2029-03-15 起 46 天(更早的 `notBefore` 为 397 天)。有效期会逐步缩短;2029 年起大约每 6 周需要重新生成一次,生产环境应使用受信任证书。其他协议的自签生成方式保持原样;最终兼容性以客户端实测结果为准。添加和查看会显示实际有效期和 UTC 到期日期,`sudo prs status`(或 `service status`、菜单中的服务状态)会在剩余不足该证书有效期的 1/3 或已过期时警告。证书到期后,执行 `sudo prs regenerate-test-certificate <配置名称>`,或在“更改配置”菜单中选择“重新生成测试证书”。操作经过 shoes dry-run、原子提交和受控重启,失败会恢复原配置、证书及服务状态。重新生成后须重新导出客户端配置并信任新证书。

**v0.2.0 迁移说明**:旧版 NaiveProxy 自签测试证书有效期过长,与 Chromium 系客户端不兼容。升级后,缺少有效期元数据的旧自签 NaiveProxy 节点,以及记录的有效期超过其 `notBefore` 所在阶段上限的测试节点(例如此前生成的 397 天证书),都会提示需要重新生成;不会自动替换旧证书。仅调整 NaiveProxy 测试模式,因为实机确认的问题来自其 Chromium 证书有效期校验;生产受信任证书和其他协议证书不受此次变更影响。证书有效期修复不代表客户端信任已通过实机验证。

AnyTLS 默认使用普通 TLS 外层;`--user` 可重复,格式为 `[名称:]密码`。未提供用户时自动创建一个随机密码用户:

```bash
sudo ping-rust generate anytls \
  --name anytls-main \
  --port 9443 \
  --server-name proxy.example.com \
  --user alice:'replace-with-a-long-random-password' \
  --user bob:'another-long-random-password' \
  --padding stop=8 \
  --padding 0=30-30 \
  --padding 1=50-100 \
  --fallback 127.0.0.1:80
```

不指定 `--cert/--key` 时会生成自签名证书。高级 Reality+AnyTLS 组合使用:

```bash
sudo ping-rust generate anytls \
  --name anytls-reality \
  --port 10443 \
  --anytls-mode reality \
  --server-name www.cloudflare.com \
  --dest www.cloudflare.com:443 \
  --user default:'replace-with-a-long-random-password'
```

`padding_scheme` 必须包含且只包含一个 `stop=N`;非法范围会在写配置前被拒绝。Reality short ID 可用 `--short-id` 指定,否则安全随机生成。

## 常用命令

```bash
ping-rust --help
sudo ping-rust info
sudo prs url <配置名或 UUID>
sudo prs qr <配置名或 UUID>
sudo ping-rust service status
sudo ping-rust service restart
sudo ping-rust logs -n 200
ping-rust check-port 443 --kind both
sudo ping-rust enable-bbr
sudo ping-rust update --method release
sudo ping-rust self-update
```

主菜单 `6) 更新` 打开统一更新中心:可以更新 ping-rust、安装 ping-rust 已验证的 shoes 固定版本,或检查 ping-rust、shoes 与 upstream 状态。推荐使用验证过的固定提交;GitHub Release 是高级选项。

`update` 只更新 shoes 内核;`self-update` 更新 ping-rust 本身。已知较低的 GitHub Release 默认会被拒绝,只有明确使用 `--allow-downgrade` 才会允许:

```bash
sudo ping-rust self-update --version v0.2.0
sudo ping-rust update --method release --allow-downgrade
```

成功自更新后当前旧进程会退出,请重新运行 ping-rust。shoes 安装来源记录在 `/var/lib/ping-rust/shoes-install.json`;legacy 安装没有来源记录时显示为 unknown。定期运行的 `shoes-upstream-drift` workflow 会构建并验证 cfal/shoes master,但不会自动修改生产 pin。

自更新支持 Linux x86_64/aarch64,下载对应 musl 静态包,校验 GitHub API digest 与 `SHA256SUMS`,确认新二进制版本后才替换当前程序。程序位于 `/usr/local/bin` 时通常需要 `sudo`;用户目录内可写的 cargo 安装则不需要。

多个配置使用不同端口。查看 ID 后删除:

```bash
sudo ping-rust info
sudo ping-rust delete <配置-UUID> --yes
```

## 客户端导出

```bash
sudo ping-rust export clash-meta --profile <配置-UUID> --server 203.0.113.10 --output clash.yaml
sudo ping-rust export sing-box --profile <配置-UUID> --server proxy.example.com --output sing-box.json
sudo ping-rust export nekobox --profile <配置-UUID> --server 203.0.113.10
```

只有一个配置时可以省略 `--profile`。SOCKS5 可导出 percent-encoded `socks5://` URI、终端 QR、sing-box `type: socks` 和 Clash Meta/Mihomo `type: socks5`;IPv6 地址会使用方括号。NekoBox 没有在本项目核实到稳定、明确的专用 SOCKS5 导入 schema,因此 `export nekobox` 会明确拒绝,不把普通 URI 冒充已验证的 NekoBox 格式。

Snell v3 使用 shoes 原生服务端,支持三个固定 shoes cipher 和 UDP-over-TCP。Mihomo/Clash Meta 可导出 `type: snell`、`version: 3`、`psk` 和 `udp`;为避免不兼容,当前只对 Mihomo v3 明确支持的 `aes-128-gcm` 配置开放无损导出。当前 sing-box Snell 只支持 v4/v6,NekoBox 也没有已核实的 v3 导入能力,因此两者明确拒绝。Snell v3 没有统一、跨客户端的标准 URI,`url`、`qr` 和 `--plain` 不会生成伪 `snell://`。链式代理 outbound 尚未实现 Snell。Mihomo 同样不支持 AnyTLS+Reality,标准 AnyTLS URI也无法表达 Reality 公钥;所有不兼容情况都会返回中文错误。所有 Reality 导出只包含公钥,永远不包含服务器私钥。

## 备份与恢复

```bash
sudo ping-rust backup ./shoes-backup.tar.gz
sudo ping-rust restore ./shoes-backup.tar.gz
```

备份包含私钥、UUID 和密码,文件权限为 `0600`,请加密保存。恢复过程拒绝绝对路径、`..`、符号链接和特殊文件;新配置未通过 shoes 校验时会自动恢复旧目录。成功恢复后,旧目录仍保留为 `/etc/shoes.pre-restore-<时间戳>`,确认无误后再手动清理。

## 文件位置与权限

| 路径 | 用途 | 权限 |
|---|---|---:|
| `/usr/local/bin/shoes` | shoes 内核 | `0755` |
| `/usr/local/bin/prs` | 指向 ping-rust 的安全短命令符号链接 | symlink |
| `/etc/shoes/profiles/<协议>-<端口>.yaml` | 每个节点的真实独立配置文件 | `0600` |
| `/etc/shoes/config.yaml` | Rust 从全部节点确定性聚合、供 shoes 实际加载的配置 | `0600` |
| `/etc/shoes/ping-rust-state.json` | 多配置元数据与客户端导出凭据 | `0600` |
| `/etc/shoes/cert-*.pem` | 自动生成证书 | `0644` |
| `/etc/shoes/key-*.pem` | 自动生成证书私钥 | `0600` |
| `/run/lock/ping-rust.lock` | 配置操作进程间互斥 | `0600` |
| `/etc/systemd/system/shoes.service` | systemd unit | `0644` |

卸载默认保留 `/etc/shoes`。只有 `uninstall --purge` 或菜单二次确认才会删除配置。

## 故障排查

查看服务和日志:

```bash
sudo systemctl status shoes --no-pager
sudo journalctl -u shoes -n 200 --no-pager
sudo /usr/local/bin/shoes --dry-run /etc/shoes/config.yaml
```

- `Address already in use`:运行 `ping-rust check-port <端口>`,换用未占用端口。
- Reality 连接失败:检查 VPS 防火墙、安全组、UUID、公钥、short ID、SNI 和 fallback 是否一致,并用 `timedatectl status` 确认客户端与服务端时钟已同步。
- Hysteria2/TUIC 失败:确认 UDP 端口已放行,并检查证书域名。
- Shadowsocks 2022 导入失败:确认客户端 cipher 使用标准名称,且 Base64 密钥解码长度与 AES-128(16 字节)或 AES-256/ChaCha20(32 字节)一致。
- AnyTLS 失败:确认选择的 TLS/Reality 模式、SNI、密码与证书校验设置一致;AnyTLS+Reality 请使用 sing-box 导出。
- 链式节点显示端口可达但不能使用:进入 `9) 其他 → 1) 链式代理 → 7) 测试节点 / Chain → 1) 测试节点`;新版测试会验证密码/UUID、TLS/Reality 握手和真实 HTTP 出口,不再只测 TCP 端口。
- `systemctl` 不存在:当前系统不是 systemd 环境,服务管理功能无法使用。
- GitHub API 请求支持可选 `GITHUB_TOKEN` 或 `GH_TOKEN`(前者优先,空值忽略)。使用 sudo 时可执行 `sudo --preserve-env=GITHUB_TOKEN,GH_TOKEN ping-rust ...`;token 仅发送到 `api.github.com`,不会用于 Release 资产下载。403、429、5xx 与连接失败最多尝试 3 次并退避;尊重服务端等待提示,超过 120 秒等待上限则停止并明确报错。历史 CI 缺少底层输出时不能据此判定为限流。
- 自更新提示权限不足:若当前程序位于 `/usr/local/bin`,改用 `sudo ping-rust self-update`;不要手工覆盖正在更新的文件。
- cargo 安装版本较旧:GitHub Release 与 crates.io 的发布时间可能不同,优先选择 Release。
- cargo 编译很慢:低内存 VPS 上源码模式可能需要数十分钟;这是回退通道,默认部署应优先使用 Release。

## 开发与验证

本地门禁:`cargo fmt --all -- --check`、`cargo clippy --locked --all-targets --all-features -- -D warnings`、`cargo test --locked --all-targets`。CI、systemd acceptance、实机 VPS 与未验证范围的逐项证据见 [COMPLETION_AUDIT.md](COMPLETION_AUDIT.md)。

## 仓库结构

```text
ping-rust/
├── .github/
│   ├── workflows/
│   │   ├── chain-systemd.yml
│   │   ├── ci.yml
│   │   ├── performance-baseline.yml
│   │   ├── release.yml
│   │   ├── security-audit.yml
│   │   ├── shoes-schema.yml
│   │   ├── shoes-upstream-drift.yml
│   │   └── ubuntu-acceptance.yml
│   └── dependabot.yml
├── docs/
│   └── SHOES_PIN_UPGRADE.md
├── examples/
│   ├── anytls.yaml
│   ├── chain-e2e-client.yaml
│   ├── chain-e2e-downstream.yaml
│   ├── chain-e2e-upstream.yaml
│   ├── chain-proxy.yaml
│   ├── hysteria2.yaml
│   ├── naiveproxy-self-signed.yaml
│   ├── reality.yaml
│   ├── shadowsocks.yaml
│   ├── snell.yaml
│   ├── socks5-no-auth.yaml
│   ├── socks5-no-udp.yaml
│   ├── socks5.yaml
│   ├── ss2022-shadowtls-v3.yaml
│   ├── trojan-reality.yaml
│   ├── trojan-tls.yaml
│   ├── tuic.yaml
│   ├── vless-tls-vision.yaml
│   ├── vless-ws-tls.yaml
│   └── vmess-ws-tls.yaml
├── scripts/
│   ├── ci/
│   │   ├── validate-h2mux.py
│   │   └── validate-shoes-schema.sh
│   └── install.sh
├── src/
│   ├── chain_proxy/
│   │   └── state.rs
│   ├── config/
│   │   ├── presets/
│   │   │   ├── anytls.rs
│   │   │   ├── hysteria2.rs
│   │   │   ├── naiveproxy.rs
│   │   │   ├── reality.rs
│   │   │   ├── shadowsocks.rs
│   │   │   ├── snell.rs
│   │   │   ├── socks5.rs
│   │   │   ├── tls.rs
│   │   │   ├── trojan_reality.rs
│   │   │   ├── trojan_tls.rs
│   │   │   ├── tuic.rs
│   │   │   ├── vless_tls_vision.rs
│   │   │   ├── vless_ws_tls.rs
│   │   │   └── vmess_ws_tls.rs
│   │   ├── commit.rs
│   │   ├── presets.rs
│   │   ├── routing.rs
│   │   ├── schema.rs
│   │   ├── transaction.rs
│   │   └── validation.rs
│   ├── menu/
│   │   └── chain.rs
│   ├── chain_proxy.rs
│   ├── cli.rs
│   ├── client.rs
│   ├── config.rs
│   ├── deployment.rs
│   ├── fast_add.rs
│   ├── h2mux.rs
│   ├── install_self.rs
│   ├── installer.rs
│   ├── main.rs
│   ├── menu.rs
│   ├── operations.rs
│   ├── performance.rs
│   ├── self_update.rs
│   ├── service.rs
│   └── utils.rs
├── systemd/
│   └── ping-rust.service
├── tests/
│   ├── chain_menu.exp
│   ├── chain_proxy_e2e.rs
│   ├── chain_systemd_e2e.rs
│   ├── chain_v2_e2e.rs
│   ├── performance_baseline.rs
│   └── performance_change.exp
├── .gitattributes
├── .gitignore
├── build.rs
├── Cargo.lock
├── Cargo.toml
├── COMPLETION_AUDIT.md
├── LICENSE
└── README.md
```

## 项目仓库

源码仓库:[Jyanbai/ping-rust](https://github.com/Jyanbai/ping-rust)

## 许可证

[MIT License](LICENSE)