安装与构建

三平台一致：同一份源码、同一套命令、同一份二进制行为。所有路径与命令均与仓库 CI 一致。

1. 环境要求

Rust 工具链

需要 Rust 1.97+（工作区声明 rust-version = "1.97"，edition 2024）。推荐用 rustup 管理工具链：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustc --version    # 确认版本 ≥ 1.97
cargo --version

C 编译器

部分依赖需要 C 编译器（ring / boringtun 的 C 部分、Windows Wintun 驱动的 FFI）：

平台	要求	安装示例
Linux	gcc / clang + libc 头文件	`apt install build-essential libudev-dev pkg-config`
macOS	Xcode Command Line Tools	`xcode-select --install`
Windows	MSVC 生成工具	安装 Visual Studio Build Tools，勾选「使用 C++ 的桌面开发」

2. 源码构建

Release 构建

git clone https://github.com/mcdn-git/tunnel_proxy.git
cd tunnel_proxy
cargo build --release
# 产物：target/release/tunnel_proxy（Windows 为 tunnel_proxy.exe）

建议构建 release 版本：含优化，性能为 debug 的数倍。开发调试用 cargo build 即可。

质量门禁（CI 强制）

提交前仓库在 .github/workflows/ci.yml 对三平台矩阵强制执行以下门禁：

cargo fmt --check           # 0 diff
cargo clippy --workspace --all-targets -- -D warnings   # 0 warning
cargo test --workspace      # 全量测试全绿（当前 325 个）
cargo build --release       # 产物构建

另有独立 security-scan job（ubuntu）：cargo audit（RustSec 漏洞库）+ cargo deny check（advisories/licenses/bans/sources）+ gitleaks（密钥泄漏）。

3. 三平台说明

Linux

功能最全的平台。透明代理（redirect）默认用 iptables REDIRECT（需 root）；无 root 时自动回退 TUN 透明代理（需 TUN 设备）。串口 / ICMP / WireGuard / netns 均可用。

macOS

与 Linux 行为一致。redirect / redu 用 TUN 透明代理实现（需管理员权限 + 系统扩展授权）。ICMP 用 raw socket（需 root 或设置 sysctl net.inet.icmp.icmplim）。

Windows

全功能可用：Unix socket 与 named pipe 统一（Runix）、串口、WireGuard、TUN/TAP（需 Wintun 驱动 + 管理员）、ICMP（用 Win32 Winsock API）。全平台对齐是最高准则——无「仅某平台可用」的对外功能。

已知平台差异（2026-08-29 实测）：Windows 系统保留端口段（WSL2/Hyper-V WinNAT 动态保留，用 netsh interface ipv4 show excludedportrange protocol=tcp 查询）内的端口绑定会报 os error 10013——这是 Windows 系统行为（非代码问题），换用未保留端口即可。另外 Windows named pipe（Runix）无 POSIX half-close 语义，stdio 客户端在数据完成后可能不自动退出。详见 docs/platform-support.md。

4. 系统服务

systemd（Linux）

# /etc/systemd/system/tunnel-proxy.service
[Unit]
Description=tunnel_proxy_rs
After=network.target

[Service]
ExecStart=/usr/local/bin/tunnel_proxy run -C /etc/tunnel-proxy/router.yaml
Restart=always
User=nobody

[Install]
WantedBy=multi-user.target

systemctl enable --now tunnel-proxy

Windows 服务

用 NSSM 或 WinSW 包装：

nssm install tunnel_proxy "C:\tools\tunnel_proxy.exe" run -C C:\tools\router.yaml
nssm set tunnel_proxy AppDirectory C:\tools
nssm set tunnel_proxy AppStdout C:\tools\out.log
nssm set tunnel_proxy AppStderr C:\tools\err.log
nssm start tunnel_proxy

5. 验证安装

# 版本与子命令
tunnel_proxy --help

# 本地起一个 SOCKS5 代理，验证可用
tunnel_proxy socks5 -l 127.0.0.1:1080 &
curl -x socks5h://127.0.0.1:1080 https://example.com

# 端到端验证（无需外部服务）
tunnel_proxy bench echo -l 127.0.0.1:9000   # 终端 1：echo 目标
tunnel_proxy bench ping -s 127.0.0.1:1080 -e 127.0.0.1:9000   # 终端 2：经代理测延迟

6. 卸载

源码构建无全局写入，删除源码目录与 target/ 即完成卸载；若配置了系统服务，先停服务再删配置。