面向 sing-box 与 mihomo 的跨平台原生管理器
用一个 Ratatui 控制台、系统托盘和脚本友好的 CLI，统一管理核心、配置、订阅、系统代理与 TUN。
功能 · 架构 · 平台与模式 · 下载 · 快速开始 · 命令参考 · 交互 · 安全 · 故障排查
Proxy RS 是 Proxy.ps1 的 Rust 实现，适合希望在桌面或服务器上自行管理
sing-box 与
mihomo 的用户。它不提供代理节点，也不内置核心或用户配置；项目负责的是核心生命周期、配置与订阅操作、系统集成以及运行状态展示。
默认的 service 后端把高权限核心进程交给原生系统服务托管，日常使用的 TUI、托盘和 CLI 则保持在普通用户权限。需要兼容旧工作流或使用任意自定义核心路径时，也可以切换到 direct 后端。
- 双核心管理：选择、启动、停止、重启、校验并显示 sing-box / mihomo 版本；从对应上游 GitHub Releases 查询和安装核心。
- 透明的发布来源：sing-box 来自
reF1nd/sing-box-releases，mihomo 来自MetaCubeX/mihomo；可配置 GitHub 下载镜像，镜像失败时回退到原始下载地址。 - 可靠更新：TUI 展示查询、下载、解压、校验、替换与恢复进度；替换失败时恢复原核心。sing-box 可选择稳定版、预发布版或历史版本。
- 四种代理模式：提供
system、tun、mixed、manual，按模式控制配置修补、系统代理与 TUN。 - 结构化配置处理：使用 JSON/YAML 结构化编辑修补入站；sing-box 优先调用
jq，不可用时回退到内置实现。修改前创建备份，校验失败则恢复。 - 配置与订阅工作流：导入、选择、编辑、校验、修补和删除本地配置；添加订阅并批量更新。
- 原生桌面体验：Ratatui TUI、系统托盘、大小写一致的快捷键、真实布局命中区域、列表滚轮和可点击操作。
- 可观测性：读取 stdout/stderr 日志，执行连通性测试；配置提供 Clash API 时展示实时流量、活动连接、进程与目标排行，否则明确降级为设备级系统统计。
- 脚本友好：通过
headless子命令执行启停、状态查询、配置修补、配置校验和托盘自启动设置。 - 受控的高权限边界：Windows Service、macOS LaunchDaemon 或 Linux systemd 服务持有核心生命周期；本机 IPC 具备协议版本、帧大小限制、安装用户访问控制和 256 位令牌认证。
默认 service 后端的数据流如下：
flowchart LR
subgraph User["普通用户会话"]
TUI["Ratatui TUI"]
Tray["系统托盘"]
CLI["Headless CLI"]
Manager["Manager 控制层"]
TUI --> Manager
Tray --> Manager
CLI --> Manager
end
Manager -->|"本机 IPC<br/>协议 v2 · 最大 1 MiB · 令牌认证"| Service["原生系统服务"]
Service --> Core["sing-box / mihomo"]
Service <--> Config["配置 · 订阅 · 日志 · 备份"]
Core --> API["Clash API / 系统统计"]
API --> TUI
Manager --> Proxy["系统代理 / 登录自启动"]
- Windows 使用受 ACL 保护的本机命名管道；Unix 使用权限受限的本地 Socket。
- 服务安装时生成 32 字节随机令牌，并将客户端令牌限制给安装用户。
direct后端不经过服务，核心和运行状态位于所选--root下，TUN 模式按次请求管理员权限。
| 平台 | TUI | 系统托盘 | 原生服务后端 | 登录时启动托盘 |
|---|---|---|---|---|
| Windows | 支持 | 支持 | Windows Service | 当前用户 HKCU\...\Run |
| macOS | 支持 | 支持 | LaunchDaemon | LaunchAgent |
| Linux | 支持 | 支持 | systemd | XDG Autostart |
托盘需要图形桌面会话；纯终端或服务器环境可以只使用 TUI 与 headless 命令。具体桌面集成能力仍取决于操作系统和桌面环境。
| 模式 | 自动修补配置 | 系统代理 | TUN | 适用场景 |
|---|---|---|---|---|
system |
是 | 开启 | 关闭 | 常规桌面应用代理 |
tun |
是 | 关闭 | 开启 | 需要虚拟网卡接管的流量 |
mixed |
是 | 开启 | 开启 | 同时使用系统代理与 TUN |
manual |
否 | 不修改 | 不修改 | 完全由现有配置控制 |
tun 和 mixed 需要管理员权限。使用已安装的 service 后端时，高权限由系统服务持有；使用 direct 后端时，启动 TUN 会按次提权。
- Rust 工具链：项目使用 Rust 2024 edition；请安装 Rust 1.85 或更高版本的稳定工具链。推荐通过 rustup 安装。
- 受支持的操作系统：Windows、macOS 或 Linux。
- 网络连接：下载 Rust 依赖、核心和订阅时需要访问对应上游地址。
- 系统权限：首次安装或修复系统服务，以及
direct后端启动 TUN 时，需要接受 Windows UAC 或 Unixsudo提示。 - 图形会话：只有使用系统托盘时需要。
- 可选的
jq：安装后会优先用于 sing-box JSON 配置修补；未安装时程序使用内置结构化实现。
Important
仓库不包含代理核心、代理节点、订阅或示例用户配置。首次运行后，请在“核心”页安装核心，并导入你有权使用的配置。
可从 GitHub Releases 下载预编译的 v0.1.0。各平台资产如下：
| 操作系统 | 架构 | 发布资产 |
|---|---|---|
| Windows | x86-64 | proxy-rs-v0.1.0-x86_64-pc-windows-msvc.zip |
| Linux | x86-64 | proxy-rs-v0.1.0-x86_64-unknown-linux-gnu.tar.gz |
| macOS | Intel x86-64 | proxy-rs-v0.1.0-x86_64-apple-darwin.tar.gz |
| macOS | Apple silicon ARM64 | proxy-rs-v0.1.0-aarch64-apple-darwin.tar.gz |
同时下载 SHA256SUMS.txt，并将它与待验证的归档放在同一目录。将下面的 $asset / asset 改为实际下载的文件名。
Linux：
set -euo pipefail
asset=proxy-rs-v0.1.0-x86_64-unknown-linux-gnu.tar.gz
grep -F " $asset" SHA256SUMS.txt | sha256sum -c -macOS：
set -euo pipefail
asset=proxy-rs-v0.1.0-aarch64-apple-darwin.tar.gz
grep -F " $asset" SHA256SUMS.txt | shasum -a 256 -c -Windows PowerShell：
$asset = 'proxy-rs-v0.1.0-x86_64-pc-windows-msvc.zip'
$line = @(Get-Content .\SHA256SUMS.txt | Where-Object { $_.EndsWith(" $asset") })
if ($line.Count -ne 1) { throw "SHA256SUMS.txt 中未找到唯一的 $asset" }
$expectedHash, $fileName = $line[0] -split ' ', 2
$actualHash = (Get-FileHash -LiteralPath $fileName -Algorithm SHA256).Hash
if ($actualHash -ne $expectedHash) { throw "$fileName 的 SHA-256 校验失败" }
"$fileName 的 SHA-256 校验通过"每个归档都只有一个同名的版本化顶层目录（去掉 .zip 或 .tar.gz 后缀），其中包含 proxy-rs.exe（Windows）或 proxy-rs（Linux/macOS）、README.md 和 LICENSE。归档不包含 sing-box、mihomo、代理配置、订阅或任何运行时数据。
Linux 二进制动态依赖 GTK 3、xdo 和 Ayatana AppIndicator 等桌面原生库。在 Ubuntu 上构建或补齐相关依赖时可运行：
sudo apt update
sudo apt install libgtk-3-dev libxdo-dev libayatana-appindicator3-devWarning
当前发布资产没有任何代码签名：Windows 二进制未经过 Authenticode 签名，macOS 二进制未使用 Apple Developer ID 签名且未公证，Linux 二进制也未签名。操作系统可能显示安全警告；请先核对 SHA-256，并仅在信任此项目及对应发布标签时运行。
git clone https://github.com/MiChongs/Proxy-RS.git
cd Proxy-RS
cargo run --release -- --root . tui首次进入 TUI 后：
- 默认
service后端会检测系统服务；未安装时自动请求一次管理员权限进行安装或修复。 - 切换到“核心”页，按
U选择并安装 sing-box 或 mihomo 版本。 - 切换到“配置”页，按
I导入本地配置，或按N添加订阅。 - 按
Enter选中配置，在“总览”页按S启动核心。 - 按
M在四种代理模式之间切换；不希望程序修改配置或系统设置时请选择manual。
Windows 用户也可以双击 Proxy-Rust.bat。脚本会切换到项目目录；若 release 二进制不存在，则先执行 cargo build --release，随后以该目录作为 --root 打开 TUI。
cargo build --release
.\target\release\proxy-rs.exe --root . tui省略 tui 子命令同样会打开 TUI：
.\target\release\proxy-rs.exe --root .cargo build --release
./target/release/proxy-rs --root . tui也可以由 Cargo 直接启动：
cargo run --release -- --root . tui--root 是全局参数，指定其下用于保存本地运行数据的 data/ 目录。未传入时，程序依次尝试 PROXY_RS_ROOT、可执行文件附近的项目目录和当前工作目录。
下文使用 proxy-rs 代表已加入 PATH 的二进制；如果没有安装到 PATH，请替换为 .\target\release\proxy-rs.exe 或 ./target/release/proxy-rs。
proxy-rs --root . tui
proxy-rs --root . tray
tui：打开 Ratatui 控制台；没有子命令时也是此行为。tray：启动系统托盘。托盘进程通过运行锁保持唯一；退出托盘不会停止正在运行的核心。- 托盘中的“打开控制台”会创建新的可见终端窗口；“打开日志目录”可直接定位运行日志。
proxy-rs --root . service install
proxy-rs --root . service status
proxy-rs --root . service start
proxy-rs --root . service stop
proxy-rs --root . service uninstall
| 命令 | 作用 |
|---|---|
service install |
首次安装或修复系统服务，并部署受保护的服务文件与令牌 |
service status |
查询服务状态 |
service start |
启动原生系统服务 |
service stop |
停止原生系统服务 |
service uninstall |
移除服务注册，保留用户配置与日志 |
service run 是系统服务的内部入口，不应手动调用。服务默认在开机启动时恢复当前核心；可在 TUI“设置”页按 G 切换该行为。按 B 可在 service 与 direct 后端之间切换，按 I 可安装或修复服务。
为避免高权限服务执行任意外部文件，service 后端不接受自定义核心路径。需要使用自定义可执行文件时，请先切换到 direct 后端。
proxy-rs --root . headless status
proxy-rs --root . headless start
proxy-rs --root . headless stop
proxy-rs --root . headless restart
proxy-rs --root . headless patch
proxy-rs --root . headless validate
proxy-rs --root . headless autostart true
proxy-rs --root . headless autostart false
| 命令 | 作用 |
|---|---|
headless status |
输出核心、模式、后端、PID、配置、端口、系统代理和托盘自启动状态 |
headless start / stop / restart |
控制当前核心 |
headless patch |
按当前模式修补当前配置 |
headless validate |
使用当前核心校验当前配置 |
headless autostart true|false |
启用或禁用登录时启动托盘 |
登录自启动实际运行 proxy-rs --root <项目目录> tray，只启动普通用户托盘，不直接启动高权限核心。托盘启动失败时可查看 data/logs/tray-launch.log。
所有字母快捷键均不区分大小写。
| 页面 | 按键 | 行为 |
|---|---|---|
| 全局 | Tab / →、Shift+Tab / ← |
切换页面 |
| 全局 | ↑ / ↓ |
移动当前列表选择 |
| 全局 | ? |
打开帮助页 |
| 全局 | Q / Ctrl+C |
退出 TUI，核心继续运行 |
| 总览 | S / R |
启动或停止 / 重启核心 |
| 总览 | M / K |
切换代理模式 / 当前核心 |
| 总览 | A |
切换登录时启动托盘 |
| 总览 | C |
为当前配置启用 Clash API |
| 总览 | X |
关闭选中的活动连接 |
| 总览 | P / V / T |
修补配置 / 校验配置 / 连通性测试 |
| 配置 | Enter |
选中当前配置 |
| 配置 | I / N / U |
导入配置 / 添加订阅 / 批量更新订阅 |
| 配置 | E / V / P / D |
编辑 / 校验 / 修补 / 删除 |
| 核心 | 1 / 2 / C |
选择 sing-box / 选择 mihomo / 切换核心 |
| 核心 | U |
打开稳定版、预发布版与历史版本更新向导 |
| 核心 | X |
设置自定义核心路径（仅 direct 后端） |
| 设置 | B / I / G |
切换后端 / 安装或修复服务 / 切换服务启动时恢复核心 |
| 设置 | M / A / J |
切换模式 / 托盘自启动 / 启动前自动修补 |
| 设置 | O / X |
设置 mixed 端口 / GitHub 下载镜像 |
| 日志 | L / C |
切换 stdout/stderr / 清空当前日志 |
鼠标左键可以切换页签、点击页面操作、选择配置与活动连接，以及操作更新弹窗；滚轮移动当前列表或弹窗中的版本选择。命中区域按每帧实际布局计算，终端缩放后无需重新启动。
Proxy-RS/
├── src/
│ ├── main.rs # Clap CLI 与程序入口
│ ├── manager.rs # 核心、配置、订阅与后端协调
│ ├── ui.rs # Ratatui TUI 与输入处理
│ ├── tray.rs # 跨平台系统托盘
│ ├── service.rs # 原生系统服务管理
│ ├── service_runtime.rs # 服务端核心生命周期
│ ├── service_protocol.rs # IPC 协议与命令模型
│ ├── service_ipc.rs # 命名管道 / Unix Socket
│ ├── config.rs # JSON / YAML 配置处理
│ ├── core.rs # 核心发现、下载与替换
│ └── telemetry.rs # Clash API 与系统统计
├── tests/ # PowerShell 兼容实现测试
├── docs/ # 项目文档
├── Cargo.toml # Rust 包清单
├── Cargo.lock # 锁定依赖
├── Proxy-Rust.bat # Windows Rust 启动脚本
├── Proxy.ps1 # 兼容保留的 PowerShell 实现
├── Proxy.bat # PowerShell 实现启动脚本
├── README.md
└── LICENSE
data/ 由应用在运行时创建，不属于源代码发布内容。
当 --root . 时，普通用户侧数据位于：
data/
├── settings.json
├── cores/
│ ├── sing-box/
│ └── mihomo/
├── configs/
│ ├── sing-box/
│ └── mihomo/
├── logs/
└── runtime/
默认 service 后端还会把服务程序、核心、配置、日志、备份、状态与令牌部署到受保护的系统位置：
| 平台 | 服务程序 | 服务数据 |
|---|---|---|
| Windows | %ProgramFiles%\ProxyRS |
%ProgramData%\ProxyRS |
| macOS | /Library/PrivilegedHelperTools/ProxyRS |
/Library/Application Support/ProxyRS |
| Linux | /usr/local/lib/proxy-rs |
/var/lib/proxy-rs |
这些目录可能包含订阅 URL、代理节点、认证信息、访问日志、数据库、缓存和服务令牌。项目的 .gitignore 会排除整个 data/，但在复制、打包、报告问题或公开终端输出前，仍应主动检查并脱敏。
- 不要提交运行数据：不要将
data/、核心二进制、配置、订阅、日志、缓存、数据库、PID、令牌或备份上传到公开仓库。 - 最小化高权限范围：推荐使用默认
service后端。安装时请求一次 UAC /sudo，之后普通操作通过经过认证的本机 IPC 完成。 - IPC 不等于远程 API：控制端点只用于本机进程，但仍通过访问控制、64 个十六进制字符组成的令牌（32 字节）、恒定时间比较、协议版本和 1 MiB 消息上限进行约束。
- 谨慎使用
direct：该后端允许自定义核心路径；只运行来源可信且由你验证过的可执行文件。TUN 模式会按次提权。 - 审查订阅与配置：第三方配置会影响网络路由、DNS 和系统代理。请确认来源和内容，避免把未知配置直接用于高权限 TUN。
- 理解系统代理影响：
system与mixed会修改系统代理；正常停止核心会关闭由应用管理的系统代理，异常退出后应检查操作系统代理设置。 - 卸载语义：
service uninstall仅移除服务注册，不删除用户配置与日志；需要清理数据时请在确认备份后手动处理。
proxy-rs --root . service status
proxy-rs --root . service install
也可以在 TUI“设置”页按 I 安装或修复。确认已接受 UAC / sudo，并检查服务日志。若当前环境不能安装系统服务，可按 B 切换到 direct，但请留意 TUN 的提权行为。
进入“核心”页按 U 安装当前核心。若 GitHub 访问受限，可在“设置”页按 X 修改下载镜像或留空以直连 GitHub。自定义核心路径只允许在 direct 后端设置。
- 在“配置”页按
I导入配置，或按N添加订阅。 - 按
Enter选中配置。 - 按
V校验；需要按当前模式补全入站时按P修补。 - 检查
data/logs/。配置修改前会生成备份，校验失败时会尝试恢复。
总览只有在当前配置暴露可访问的 Clash API 时才能显示连接级数据。按 C 可为当前配置启用 Clash API；不可用时界面会降级为设备级系统统计，这不代表核心一定停止运行。
- 确认当前环境存在图形桌面会话。
- 手动运行
proxy-rs --root . tray观察错误。 - 使用
headless autostart true重新注册。 - 检查
data/logs/tray-launch.log；托盘进程有唯一运行锁，重复启动不会创建第二个实例。
- 运行
rustc --version和cargo --version，确认工具链支持 Rust 2024 edition。 - 更新稳定工具链：
rustup update stable。 - Linux 上若图形/托盘依赖编译失败，请按编译器提示安装当前发行版所需的原生开发包。
- 使用锁文件复现依赖：
cargo build --locked --release。
欢迎通过 Issues 报告可复现的问题，或通过 Pull Request 改进代码和文档。
- Fork 仓库并从
main创建主题分支。 - 保持改动聚焦，不要提交
data/、代理配置、订阅、日志、核心二进制或其他本机状态。 - 新行为应补充可观察、可重复且与平台隔离的测试。
- 提交前建议执行与改动相关的检查：
cargo fmt --check
cargo check --locked
cargo test --locked
cargo run --locked -- --help修改 PowerShell 兼容实现时，请同时查看 tests/ 中对应的 Pester 测试。提交问题日志前，请删除订阅 URL、代理节点、令牌、文件路径和其他个人信息。
- sing-box 与 mihomo：提供代理核心能力。
- Ratatui 与 Crossterm：提供跨平台终端界面基础。
- Clap、tray-icon 与 service-manager：支撑 CLI、托盘和原生服务集成。
- 原
Proxy.ps1实现及所有测试、反馈与上游开源项目，为本项目的行为和兼容性提供了基础。
本项目基于 MIT License 开源。代理核心及其依赖保留各自的许可证与使用条款；使用者需自行确认配置、订阅和网络服务符合所在地法律及相关服务条款。