ping-rust 0.2.0

Menu-driven installer and manager for the shoes proxy server
ping-rust-0.2.0 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.0。本版本聚合 Update Center、Verified Hot Reload、Chain Proxy 2.0、规则路由和受验证范围内的 H2MUX。支持 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.0

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
  • 多配置添加、列表、删除、端口冲突保护
  • 全局链式代理:从分享链接导入受支持的上游节点,选择、启停、测试和删除;启用后所有受管入站经当前节点转发
  • 跨进程配置锁、配置/sidecar 精确回滚,更新与恢复保留服务原运行状态
  • 服务启停、重启、状态、journalctl 日志、更新与卸载
  • BBR、TCP/UDP 端口检查、敏感配置备份与安全恢复
  • 导出 Clash Meta、sing-box 和 Nekobox 分享链接
  • Rust 原生更新 ping-rust 自身:GitHub Release + SHA256SUMS 双重校验、版本探针、原子替换与失败回滚

支持环境

系统 架构 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.0 -------------
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 已运行且服务 unit 未被修改时,新增监听、修改监听端口和删除非最后一个节点会尝试 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 轮询只表示连接分布,不提供健康检查、自动故障切换或延迟选择。

第一版支持 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,而不是逐节点测试的集合。测试进程和权限为 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 模式与连接数模式互斥。固定 shoes 服务端自动识别 H2MUX,无需更改服务端 YAML。只修改受管 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,因此自签名测试导出会嵌入公开证书供客户端验证,绝不导出服务器私钥。

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.1.15
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) 链式代理 → 4) 测试节点(完整代理);新版测试会验证密码/UUID、TLS/Reality 握手和真实 HTTP 出口,不再只测 TCP 端口。
  • systemctl 不存在:当前系统不是 systemd 环境,服务管理功能无法使用。
  • GitHub API 限流:稍后重试,或使用 install --method cargo。
  • 自更新提示权限不足:若当前程序位于 /usr/local/bin,改用 sudo ping-rust self-update;不要手工覆盖正在更新的文件。
  • cargo 安装版本较旧:GitHub Release 与 crates.io 的发布时间可能不同,优先选择 Release。
  • cargo 编译很慢:低内存 VPS 上源码模式可能需要数十分钟;这是回退通道,默认部署应优先使用 Release。

开发与验证

cargo fmt --all -- --check
cargo test --locked --all-targets
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo build --release
cargo doc --no-deps

本仓库开发阶段已完成:

  • Rust 单元测试覆盖密钥/YAML、归档解包、原子写入、systemd unit、端口检查、客户端三格式和恢复路径安全。
  • 自更新单元测试覆盖版本、架构、checksum 重复/缺失和严格单文件归档;Release job 还会真实执行一次强制自更新并复核版本。
  • shoes-schema.yml 固定 cfal/shoes commit 386b11532424b8665ee3e46340c6236fb3c47595(0.2.8),对全部预设联合配置、全部六种 Shadowsocks cipher、Snell v3 三种 cipher 与 UDP 开关、SOCKS5 auth/no-auth 与 UDP 开关、Reality+AnyTLS 执行真实 shoes --dry-run,并启动聚合配置检查监听和 SOCKS5 TCP CONNECT。
  • 通过 cargo-zigbuild + Zig 生成 x86_64/aarch64 Linux GNU release ELF,最高 GLIBC 需求为 2.34,覆盖 Rocky/Alma 9 及更新的目标发行版基线。
  • CI 覆盖 Ubuntu 22.04/24.04,并在 Debian 12、Rocky Linux 9、AlmaLinux 9 容器中执行锁定依赖测试和 release 构建;shoes schema 作业实际启动聚合监听。Ubuntu 24.04 acceptance 覆盖完整 root/systemd/PTY/回滚/导出流程,并通过第 11、12 项菜单分别部署 SOCKS5 与 Snell v3;Debian 12 systemd acceptance 同时覆盖零输入部署、严格 --plain 输出、多用户 AnyTLS 无损导出拒绝、激活失败回滚和加固 unit 启动。
  • 独立链式代理验收在 Ubuntu 24.04 主机和 Debian 12 特权 systemd 容器中运行,使用真实 PTY 菜单、两条隔离 Shadowsocks 出口和 HTTP 源地址核验覆盖完整生命周期与无直连回退。
  • 独立 security-audit.yml 固定 cargo-audit 0.22.2,每周、手动以及 Cargo.toml/Cargo.lock 变更时扫描提交的锁定依赖,并对漏洞、unmaintained、unsound 或 yanked warning fail-closed。当前本地扫描未报告安全公告。
  • 独立、非发布阻塞的 performance-baseline.yml 每周或手动在 Ubuntu 24.04 主机与 Debian 12 特权 systemd 容器中测量 Stage-0 安装、冷安装、配置修改、热添加和激活失败 回滚,记录总耗时、峰值 RSS、受管文件磁盘占用及下载、生成、真实 shoes --dry-run、提交、systemd 激活等分阶段耗时。报告只包含环境与数值,不记录公网 地址、UUID、密码、私钥或分享链接。共享 runner 与网络抖动较大,因此当前只建立可比较 基线,不宣称任意 VPS 都能满足固定五秒 SLA,也不会为加速而跳过生产 dry-run。
  • 在一台干净代理环境的 Debian 12 x86_64 VPS 上完成原生安装与运行验收:Release 路径约 2 秒完成 shoes v0.2.7 musl 安装,三协议同时通过 dry-run 并由 systemd 启动,外部 Reality 客户端的代理出口与 VPS 公网 IP 一致。
  • 实机完成 9 份客户端导出解析、BBR、端口检查、日志、备份恢复、inactive 状态保持和 Release 更新;详细证据见完成度审计。
  • 在 Ubuntu 24.04.3 x86_64 VPS 上从干净基线完成 crates.io、Git 固定提交与一键 Release 三种安装入口;Reality 从 shoes 安装到 systemd active/listening 用时约 2 秒,三协议、9 份客户端导出、备份恢复、更新、数字菜单、逐配置删除和卸载均通过。
  • Ubuntu VPS 真实重启后 shoes 自动恢复为 enabled/active,Reality TCP 443、Hysteria2 UDP 8443、TUIC UDP 9443 均恢复监听;官方 sing-box 客户端在重启前后两次完成公网 Reality 握手,代理出口均为该 VPS。

逐项需求、修复记录、ELF 哈希和外部验收边界见 COMPLETION_AUDIT.md。

全新 Ubuntu 24.04 x86_64 VPS 已完成以下实机验收:

  1. cargo install --path . --locked。
  2. Release 与 cargo 两种 shoes 安装方式各测试一次。
  3. 三种协议分别生成、启动,并从外部客户端连接。
  4. 重启 VPS,确认 shoes.service 自动启动。
  5. 验证更新、日志、BBR、备份恢复、删除和卸载。

上述清单已全部通过。测试结束后执行 uninstall --purge,并移除测试目录、导出文件、备份和回滚目录;测试期间安装的 Ubuntu 官方构建依赖与 Rust 工具链保留,便于后续源码测试。

截图建议

发布 README 时建议补充三张终端截图:

  1. 主数字菜单全景。
  2. Reality 生成完成画面(必须遮盖私钥、UUID 和 short ID)。
  3. systemctl status shoes 与客户端连通性测试。

仓库结构

ping-rust/
├── Cargo.toml
├── Cargo.lock
├── README.md
├── LICENSE
├── .gitignore
├── src/
│   ├── main.rs
│   ├── cli.rs
│   ├── menu.rs
│   ├── installer.rs
│   ├── config.rs
│   ├── config/
│   │   ├── presets.rs
│   │   ├── presets/       # 各受管协议的服务端与凭据生成
│   │   ├── schema.rs      # shoes YAML schema
│   │   ├── validation.rs
│   │   ├── transaction.rs # 配置、状态、节点与凭据回滚
│   │   └── commit.rs      # 节点聚合与原子提交
│   ├── performance.rs     # opt-in 无敏感信息阶段计时
│   ├── service.rs
│   ├── client.rs
│   ├── operations.rs
│   ├── self_update.rs
│   └── utils.rs
├── examples/
│   ├── reality.yaml
│   ├── hysteria2.yaml
│   ├── tuic.yaml
│   ├── shadowsocks.yaml
│   └── anytls.yaml
├── systemd/
│   └── ping-rust.service
└── scripts/
    └── install.sh

项目仓库

源码仓库:Jyanbai/ping-rust

许可证

MIT License