ping-rust 0.3.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
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
# ping-rust

> **VLESS-Sudoku 没有任何加密和认证。** Sudoku 只是混淆,下行打包编码没有密钥,上行置换种子空间有限;普通 VLESS 的 UUID、目标地址、非 HTTPS 内容都能在链路上被还原。需要加密时请使用 VLESS-ENC + Sudoku 或 VLESS-REALITY。

[![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.3.2`](https://github.com/Jyanbai/ping-rust/releases/tag/v0.3.2),升级要求见[发版说明](docs/RELEASE_NOTES_v0.3.2.md)。v0.3.2 在需要 Sudoku 时自动检测并升级不兼容的 shoes 内核,统一终端菜单与结果页返回行为,并修复 RUSTSEC-2026-0538。v0.3.1 汇总 shoes v0.3.7、VLESS-XHTTP-REALITY、VLESS-Sudoku、VLESS-ENC Sudoku 外观、统一协议菜单和严格 Release 门禁。v0.3.0 新增 VLESS-ENC,自动迁移通配符路由规则,并将新建 Snell v3 节点默认 cipher 改为 aes-128-gcm。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、Hysteria2、Shadowsocks、[VLESS-XHTTP-REALITY](docs/wiki/VLESS-XHTTP-REALITY.md)、VLESS-ENC、NaiveProxy、AnyTLS、TUIC、VLESS-TLS-Vision、Trojan-TLS、VLESS-WS-TLS、Trojan-REALITY、Snell v3、VMess-WS-TLS、SOCKS5 和 [VLESS-Sudoku](docs/wiki/VLESS-Sudoku.md) 十六种受管协议。用户只选择完整协议,不需要理解或手动组合传输层、安全层与内层协议。

完整文档:[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.3.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.3.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 / ShadowTLS v3 未指定 SNI 时,并行检测内置候选名单,从握手最快的至多 3 个可用目标中随机选择;客户端指纹固定为 `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-ENC(v0.3.0)

快速和高级添加菜单第 **5) VLESS-ENC** 项,或运行 `sudo prs add vless-enc`。默认使用 x25519、native、0rtt、600s,Vision 默认关闭。密钥由已安装的 shoes 生成。

**此预设不套 TLS 或 Reality;安全性完全依赖 VLESS Encryption。** 服务端为原生 TCP,客户端为 `security=none&type=tcp`。decryption 只写入权限 0600 的节点 profile 和聚合运行配置;state、分享链接及客户端导出仅保存客户端 encryption。

| 外观 | 区别 |
| --- | --- |
| native | 原生 VLESS Encryption 握手外观,默认选项 |
| xorpub | 对公钥采用 XOR 外观处理 |
| random | 随机外观;会关闭 TCP splice |

添加和更改配置均提供外观、x25519/mlkem768 认证、Vision 和重新生成密钥。mlkem768 链接约 1.6 KB,二维码可能无法扫描;链接超过 1200 字节时终端不生成二维码,并说明原因。更改外观、认证或重新生成密钥后必须更新客户端链接。

```bash
sudo prs add vless-enc
sudo prs add vless-enc --encryption-mode xorpub --vision
sudo prs add vless-enc --encryption-auth mlkem768
```

支持 Mihomo 的 `encryption` 字段,Vision 开启时同时导出 `flow: xtls-rprx-vision`。**不支持 sing-box 或 NekoBox 导出,不支持用作链式出口,也不提供 H2MUX 开关。**

客户端请使用 CI 实测通过的 Xray **v26.6.27** 或 Mihomo **v1.19.33**;未验证更旧版本,不能据此推断其可用。Xray 已通过三种外观 × Vision 开关的 x25519 六种组合及一次 mlkem768;Mihomo 已通过 native/x25519 的 Vision 关闭和开启两种组合。结果和 run/job ID 见 [C 阶段报告](docs/VLESS_ENC_REPORT.md)。VLESS-ENC 与其他协议使用相同的热重载资格:固定 pin 构建支持热重载,GitHub Release 来源使用受控重启。

### 可选的 Sudoku 外观

默认关闭,已有节点升级后不会自动开启。添加时用 `--sudoku`,或在菜单中回答“启用 Sudoku 外观?”(默认 N,输入 0 返回)。例如:

```sh
sudo prs add vless-enc --sudoku
sudo prs add vless-enc --sudoku --sudoku-ascii ascii --sudoku-padding-min 0 --sudoku-padding-max 10 --vision
```

`--sudoku-password` 省略时安全随机生成 24 位字母数字;显式密码按原样比较,不做 trim。`--sudoku-ascii` 可选 `prefer-entropy`(默认)、`entropy`、`prefer-ascii`、`ascii`,服务端及分享链接使用下划线形式。padding 默认 `0–0`,范围 `0–100`;max 小于 min 会报错。使用默认熵布局,不开放 `custom_tables`。

Sudoku 是混淆,不是加密或认证,传输安全仍由 VLESS Encryption 提供。上行约 4 倍(无 padding),10% padding 约 4.5 倍,单次写入最多约 9 倍;下行约 1.33 倍。关闭原始 TCP splice,每条连接多占约 64 KiB 缓冲。只支持 TCP,没有 UDP/QUIC 掩码;在 TCP 内转发的 UDP 仍可用。

客户端需要 **Xray ≥ v26.3.27** 或 v2rayN 等基于它的客户端。分享链接以 URL 编码的紧凑 JSON `fm=` 携带整个 `streamSettings.finalmask` 对象,二维码内容与链接相同。开启后拒绝 Clash Meta / Mihomo、sing-box 和 NekoBox 导出,并提示:“该客户端导出不支持 Xray FinalMask Sudoku,请用分享链接导入 v2rayN 或 Xray ≥ v26.3.27”。关闭时保持原导出行为。

在“2 更改配置”中可开启或关闭 Sudoku,或重新生成 Sudoku 密码。重新生成密码不再额外确认;变更沿用 dry-run、原子提交和失败回滚流程。`prs info` 显示 ASCII 模式和 padding 范围,不额外显示服务端 decryption。

格式参考:[shoes v0.3.7 文档](https://github.com/cfal/shoes/blob/v0.3.7/docs/src/content/docs/zh-cn/protocols/sudoku.md)、[shoes 与 Xray 互通测试](https://github.com/cfal/shoes/blob/v0.3.7/tests/cases/optional_peer/vless_encryption/sudoku_mask.rs)、[v2rayN 分享链接处理](https://github.com/2dust/v2rayN/blob/master/v2rayN/ServiceLib/Handler/Fmt/BaseFmt.cs)。

### VLESS-Sudoku(无加密)

**VLESS-Sudoku 没有任何加密和认证。** Sudoku 只是混淆,下行打包编码没有密钥,上行置换种子空间有限;普通 VLESS 的 UUID、目标地址、非 HTTPS 内容都能在链路上被还原。需要加密时请使用 VLESS-ENC + Sudoku 或 VLESS-REALITY。

普通 VLESS 外面始终包一层 shoes `sudoku_mask`,不使用 VLESS Encryption、TLS、REALITY 或 Vision。这是 Xray FinalMask Sudoku,不是 Mihomo 的 `sudoku` 隧道协议。快速和高级添加均为 **16) VLESS-Sudoku**,选择后直接进入参数输入,不再输出协议警告或追加确认,主菜单编号不变。

```sh
sudo prs add vless-sudoku --server-address 203.0.113.10
sudo prs add vless-sudoku --sudoku-ascii ascii --sudoku-padding-min 0 --sudoku-padding-max 10
```

无需 `--sudoku`;密码、ascii、padding 参数与 VLESS-ENC Sudoku 相同。上行约 4 倍(无 padding),10% padding 约 4.5 倍,单次写入最多约 9 倍;下行约 1.33 倍。关闭原始 TCP splice,每条连接多占约 64 KiB 缓冲。只支持 TCP,没有 UDP/QUIC 掩码;TCP 内转发的 UDP 仍可用。客户端需要 **Xray ≥ v26.3.27** 或基于它的 v2rayN。

链接使用 `encryption=none&security=none&type=tcp&fm=`(URL 编码的紧凑 FinalMask JSON),二维码内容相同。`prs info` 显示连接参数和 ascii、padding 范围,不重复输出协议说明。Clash Meta / Mihomo、sing-box、NekoBox 导出均明确拒绝。菜单“2 更改配置”支持端口、ascii、padding 和重新生成 Sudoku 密码;重置密码不再额外确认。配置修改沿用 dry-run、原子提交和失败回滚。

state 将新节点放在顶层 `sudoku_profiles` 扩展,v0.2.1 可忽略并读取原有节点;已有协议的 state 输出不变。旧版不支持管理该节点,降级操作前请先用新版删除并备份配置。详见 [VLESS-Sudoku wiki](docs/wiki/VLESS-Sudoku.md)。

## 协议与客户端兼容

快速和高级添加使用相同的协议名称与顺序,不显示协议等级标签。各协议的安全提示、确认流程和客户端限制仍保留;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` 时也会执行同一安全入口;在终端里会先确认一次(直接回车即部署,输入 `n` 跳过并进入主菜单),避免连不上 GitHub 时每次进菜单都要等待下载重试。

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

```text
$ sudo prs

------------- ping-rust v0.3.2 -------------
https://github.com/Jyanbai/ping-rust

shoes: • running

节点 (3):
• VLESS-Reality-Vision - 端口: 20443
• Shadowsocks 2022 - 端口: 31002
• Hysteria2 - 端口: 40001

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

请选择 [0-10]: 1

选择协议:

1) VLESS-REALITY
2) Hysteria2
3) Shadowsocks
4) VLESS-XHTTP-REALITY
5) VLESS-ENC
6) NaiveProxy
7) AnyTLS
8) TUIC
9) VLESS-TLS-Vision
10) Trojan-TLS
11) VLESS-WS-TLS
12) Trojan-REALITY
13) Snell v3
14) VMess-WS-TLS
15) SOCKS5
16) VLESS-Sudoku
0) 返回

请选择 [0-16]: 1
请输入端口(默认:随机,输入 0 返回):

配置添加成功。

按回车返回主菜单...
```

主菜单 1–7 保持原位置和功能,8–10 调整如下,方便老用户查找:

| 原位置 | 新位置 |
|---|---|
| 1–4 | 不变 |
| 5) 运行管理 | 不变,末尾新增“查看日志” |
| 6) 更新 | 不变,统一提供 ping-rust 更新入口 |
| 7) 卸载 | 不变 |
| 8) 帮助 | 10) 帮助与关于 |
| 9) 其他 → 链式代理 | 8) 链式代理 |
| 9) 其他 → 查看日志 | 5) 运行管理 → 7) 查看日志 |
| 9) 其他 → 其余工具 | 9) 工具(顺序见下) |
| 9) 其他 → 更新 ping-rust | 删除重复入口,使用 6) 更新 |
| 10) 关于 | 10) 帮助与关于 |

快速添加与 `9) 工具 → 2) 高级添加配置` 的协议列表完全一致,末尾为 `0) 返回`。`3) Shadowsocks` 内选择 SS2022 / ShadowTLS v3,保留原有 cipher、密码校验与默认值;`5) VLESS-ENC` 内可选 Sudoku(默认 N),不占额外顶层编号;`7) AnyTLS` 内选择 TLS / REALITY。`16) VLESS-Sudoku` 直接进入参数输入,不追加协议说明和确认。

`9) 工具` 按顺序提供:1) 导出客户端配置、2) 高级添加配置、3) SNI 检测、4) SNI 扫描、5) 端口检查、6) 开启 BBR、7) 备份配置、8) 恢复配置,输入 0 返回。SNI 检测可输入空格分隔的域名,直接回车则检测默认名单和现有节点;SNI 扫描复用 `prs sni scan` 的确认流程。两者只输出结果,不修改节点配置。

主界面保留节点数量,逐个以“• 协议 - 端口: 数字”显示,不显示节点名称;运行状态的“• running”为绿色,`shoes:` 为默认颜色。没有节点或读取 state 失败时显示提示,菜单仍可使用。`10) 帮助与关于` 汇总版本、项目链接和常用命令。

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

### Hot Reload

热重载要求 shoes 来源为 `verified-pin`,revision 等于 `ee44a397e6850193e86a1ae66639f037f963822d`(v0.3.7),服务已运行、unit 内容与加载路径未被修改、没有 drop-in。shoes v0.3.7 监听配置父目录,源码中的去抖窗口为 5 秒(`src/process.rs` 的 `RELOAD_DEBOUNCE`,与 v0.3.6 相同);默认一键安装使用 GitHub Release 来源,因此不启用 Verified Hot Reload。

在 `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 通过同一目录内的原子替换触发父目录 watcher,等待时间高于 shoes 的去抖窗口;不会再触碰额外锚点文件,避免重复重载。只有 MainPID 不变、服务保持 active、预期监听出现且旧监听消失时才算成功。候选配置仍先通过 `shoes --dry-run`;失败会恢复旧配置与服务状态,并记录 journal 中的实际重载次数。

只改显示名称或公网地址等不影响运行 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

从主菜单进入 `8) 链式代理`:

```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 轮询只表示连接分布,不提供健康检查、自动故障切换或延迟选择。可在 `8) 链式代理 → 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.3.6 的 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.3.6 与固定 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 时会自动检测内置名单并选择可用目标(规则见下文);客户端指纹固定为 `chrome`。后续日常流程是:`prs → 1 → 选择协议 → 输入端口/直接回车随机`;Shadowsocks 会额外选择加密方式和密码,SS 2022 密码不符合所选 cipher 的 Base64 密钥长度时会警告并自动替换。其余协议自动生成 UUID、密码、Reality 密钥、WebSocket 路径或证书。SOCKS5 快速添加默认生成安全随机用户名和密码并启用 UDP ASSOCIATE;Snell v3 快速添加默认使用 `aes-128-gcm`,生成随机密码并启用 UDP-over-TCP。NaiveProxy 要求明确选择受信任证书或自签名测试模式,不会静默生成生产自签名配置。常规操作成功后按回车返回主菜单;主菜单输入 `0` 退出,子菜单输入 `0` 返回上一级。数字菜单空输入停留,无效编号仅提示“无效序号!”,参数默认值明确标注。自动端口从 `20000..=65535` 的高位范围选择;菜单协议选择固定使用连续编号 `1..=16`。信息只会在配置通过 `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
```

新建 VLESS Reality、Trojan Reality、AnyTLS Reality 和 Shadowsocks + ShadowTLS v3 时,未指定 SNI 会并行检测编译时内置的 [`data/reality-sni-candidates.txt`](data/reality-sni-candidates.txt)。每个候选从系统 DNS 解析到 TLS 握手整体限时 3 秒;只提供 TLS 1.3 和 `h2`,要求协商 `h2`,并用内置公共根证书校验证书链和域名。检测不发送 HTTP 请求。通过后,从握手最快的 3 个候选中随机选 1 个;不足 3 个时从全部通过者中随机选。ShadowTLS 默认握手目标为 `<选中域名>:443`。

菜单 SNI 一步可选“自动选择(默认)”“检测与推荐”“手动输入”。可选检测会额外验证 HTTPS 跳转、Cloudflare 和真实 shoes 本机数据面;`prs sni check [域名...]`、`prs sni scan` 只输出结果,不改配置。支持导入自己电脑上的 RealiTLScanner CSV;VPS 扫描需明确接受风险。操作及风险见 wiki [SNI 选择](docs/wiki/SNI-选择.md)。

可用 `sudo prs add reality --server-name target.example.com` 或菜单手动输入覆盖 SNI。显式指定时只检测一次,失败在 stderr 警告,仍使用指定值;普通 TLS 证书名称不检测。菜单 `2. 更改配置` 支持三种 Reality 的“更改 SNI”,以及 ShadowTLS 的 SNI 修改;默认的 `<旧域名>:443` 目标会同步改名,自定义目标保留,修改仍走备份、原子提交、服务验证和失败回滚。升级不会自动修改已有节点的 SNI 或客户端配置。

终端会显示逐个候选结果和选中域名;非交互时只在 stderr 输出一行选择摘要,`--plain` 的 stdout 仍只输出分享链接。全部候选失败时,终端允许输入经过格式校验的 SNI(失败仍只警告)或输入 `0` 取消;非终端及安装器的 `bootstrap` 不读 stdin,直接提示用 `prs add reality --server-name <域名>` 重试。`prs generate` 不进行连通性检测:未指定时从同一名单随机选,并在 stderr 提示“未做连通性检测”。AnyTLS Reality 的标准分享 URI/二维码和 Mihomo 导出、ShadowTLS 的标准分享 URI/二维码继续明确拒绝;这些组合请使用支持的客户端配置导出。

高级用户原有的 `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
sudo prs add vless-xhttp-reality
```

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

[VLESS-XHTTP-REALITY](docs/wiki/VLESS-XHTTP-REALITY.md) 使用 shoes 原生 XHTTP,放在 REALITY 目标内部,无需自己的域名或证书。只支持 v2rayN / Xray 客户端,通过分享链接或二维码导入;Mihomo、sing-box 和 NekoBox 导出明确拒绝。固定 `mode: auto`,REALITY 客户端默认走 stream-one,不支持 Vision。path 默认 `/` 加 16 位随机小写十六进制,可用 `--xhttp-path /my-path` 指定;“更改配置”支持端口、SNI 和 path,改 path 的确认默认 N。快速和高级添加均为 **4) VLESS-XHTTP-REALITY**,主菜单不变。公网监听建议按 [shoes v0.3.7 文档](https://github.com/cfal/shoes/blob/v0.3.7/docs/src/content/docs/zh-cn/protocols/xhttp.md) 显式配置 `limits`,生成器不默认开启。XHTTP 节点写入 state 的独立顶层扩展,v0.2.1 可忽略该扩展并读取原有节点的 info 和导出;旧版不支持管理 XHTTP,降级操作前请用新版删除 XHTTP 节点并备份配置。

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
```

快速添加 `7) AnyTLS` 内可选择 TLS / REALITY,高级添加同样提供这两种模式。CLI `add anytls` 默认继续使用 TLS;不指定 `--cert/--key` 时会生成自签名证书。REALITY 不需要证书,复用 SNI 预检与激活流程;没有标准分享 URI 或普通二维码,请使用 sing-box 导出,Mihomo / NekoBox 明确不支持。`generate` 的 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 本身。`--allow-downgrade` 只用于 `update`,即 shoes 内核降级;安装已知较低的 shoes GitHub Release 时需要显式使用该参数:

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

已添加 VLESS-ENC 节点时不能降级到 v0.2.x,详见[发版说明的降级限制](docs/RELEASE_NOTES_v0.3.0.md#降级限制)。

菜单内自更新完成后按回车返回主菜单,重新运行 ping-rust 可使用新版本。shoes 安装来源记录在 `/var/lib/ping-rust/shoes-install.json`;legacy 安装没有来源记录时显示为 unknown。定期运行的 `shoes-upstream-drift` workflow 会构建并验证 cfal/shoes master,但不会自动修改生产 pin。

从 v0.1.x 安装、之后只做过 `self-update` 的实例没有来源记录,执行 `sudo ping-rust update --method release` 时会提示无法确认安装来源。如确认没有手动替换过 `/usr/local/bin/shoes`,可执行 `sudo ping-rust update --method release --allow-downgrade`;安装成功后会记录来源,之后的更新不再需要该参数。也可以在菜单 `6) 更新` 中确认后继续。

自更新支持 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 原生服务端,新节点默认 `aes-128-gcm`;`aes-256-gcm` 和 `chacha20-ietf-poly1305` 保留为可选 cipher,选择时提示客户端兼容性。CI 的 Mihomo v1.19.33 实测仅 `aes-128-gcm` 可用;Mihomo/Clash Meta 仅对该 cipher 开放无损导出 `type: snell`、`version: 3`、`psk` 和 `udp`。已有节点的 cipher 不会自动修改;若已有 chacha20 或 aes-256 Snell 节点使用 Mihomo 客户端,请将节点改为 `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
```

备份包含 VLESS-ENC 服务端 decryption 密钥,请按私钥标准保管。备份还包含其他私钥、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 导出。
- 链式节点显示端口可达但不能使用:进入 `8) 链式代理 → 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)






### shoes v0.3.7 升级说明

v0.3.1 起,默认 shoes Release 和源码 pin 升级到 v0.3.7(commit `ee44a397e6850193e86a1ae66639f037f963822d`)。v0.3.7 带来 Xray 兼容的 Sudoku TCP 掩码 `sudoku_mask`(上游 #246、#252,只支持 TCP),可通过 VLESS-ENC 的 `--sudoku` 选项启用;`shoes --version` 在版本行之后追加 `target:` / `compiler:` 两行,ping-rust 只读取第一行;watcher 去抖窗口和 REALITY 目标握手记录布局要求与 v0.3.6 相同。

### shoes v0.3.6 兼容说明

v0.3.0 起,默认 shoes Release 和源码 pin 同步到 v0.3.6(commit `3737e07467387044e677ae7cf8b1c16d291f1b68`)。v0.3.6 修复了 REALITY 对最小 28 字节 `EncryptedExtensions` 目标的握手失败,并更新了 watcher:配置父目录由 watcher 监听,上游源码去抖窗口为 5 秒(背景资料约称 3 秒)。ping-rust 的热重载超时设置为 10 秒,覆盖该窗口。

REALITY 外部握手验收使用 Xray 26.x 客户端,兼容客户端至少需要 Xray 25.5.16;链式代理的 Reality 出口不再模拟 Chrome 指纹。默认 SNI 目标来自 [`data/reality-sni-candidates.txt`](data/reality-sni-candidates.txt),每个目标都应单独记录握手结果。

Snell v3 新节点默认 `aes-128-gcm`。CI 中 Mihomo v1.19.33 经代理请求仅该 cipher 通过;Mihomo 客户端仅支持 `aes-128-gcm`。已有节点保持原 cipher,不会在升级时自动修改。已有的 chacha20 或 aes-256 Snell 节点若使用 Mihomo 客户端,需要改为 `aes-128-gcm` 并重新导出客户端配置。该测试不能判断 shoes salt 改动的影响。

Chain 规则中的通配主机名会按 v0.3.6 的 `domain_pattern` 对象格式(字符串数组值)写入;旧版 `masks: '*.example.com'` 形式在 v0.3.6 中会被拒绝,升级时由 ping-rust 重新生成候选配置。

`global_limits` 保持省略,表示不启用全局限制。只有明确需要限流时才在 shoes YAML 中写入该字段,避免升级后给现有用户引入隐式默认限制。