# ping-rust
> **VLESS-Sudoku 没有任何加密和认证。** Sudoku 只是混淆,下行打包编码没有密钥,上行置换种子空间有限;普通 VLESS 的 UUID、目标地址、非 HTTPS 内容都能在链路上被还原。需要加密时请使用 VLESS-ENC + Sudoku 或 VLESS-REALITY。
[](https://crates.io/crates/ping-rust)
[](https://github.com/Jyanbai/ping-rust/releases/latest)
[](https://github.com/Jyanbai/ping-rust/actions/workflows/ci.yml)
[](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 中写入该字段,避免升级后给现有用户引入隐式默认限制。