ping-rust 0.2.1

Menu-driven installer and manager for the shoes proxy server
ping-rust-0.2.1 is not a library.

ping-rust

crates.io GitHub Release CI License: MIT

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

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

当前稳定版:v0.2.1。本版本聚合 Update Center、Verified Hot Reload、Chain Proxy 2.0、规则路由和受验证范围内的 H2MUX。**热重载需要固定 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 · 快速开始 · 链式代理 · 故障排查

一键安装(推荐)

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

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 <(curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/Jyanbai/ping-rust/main/scripts/install.sh) \
  --version v0.2.1

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 <(curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/Jyanbai/ping-rust/v0.1.15/scripts/install.sh) \
  --version v0.1.15

功能

  • 从 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 和常用构建工具:

# 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 安装已发布的稳定版本:

cargo install ping-rust --locked
sudo ping-rust

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

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

从当前源码安装:

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

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

233boy 风格快速部署

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

$ 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 时也会执行同一安全入口。

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

$ sudo prs

------------- ping-rust v0.2.1 -------------
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,或执行:

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) 链式代理:

------------- 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 后输出;失败会恢复原配置和服务状态。

非交互方式:

# 自动安装 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 用户等参数。

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

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 路径默认安全随机生成;需要固定路径时可使用完整命令:

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

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

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

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

Hysteria2 与 TUIC

快速生成:

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

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

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 字节密钥:

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 签发。

# 生产:提供与域名匹配的受信任证书和私钥
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 可重复,格式为 [名称:]密码。未提供用户时自动创建一个随机密码用户:

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 组合使用:

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 指定,否则安全随机生成。

常用命令

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 才会允许:

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 后删除:

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

客户端导出

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 导出只包含公钥,永远不包含服务器私钥。

备份与恢复

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 或菜单二次确认才会删除配置。

故障排查

查看服务和日志:

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。

仓库结构

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
├── Cargo.lock
├── Cargo.toml
├── COMPLETION_AUDIT.md
├── LICENSE
├── README.md
└── SOURCE_SNAPSHOT.md

项目仓库

源码仓库:Jyanbai/ping-rust

许可证

MIT License