sscli — Linux 原生 CLI Shadowsocks 分流客户端

中文 | English

一个轻量、原生 Linux、无 GUI 的 Shadowsocks 分流工具。通过 Linux TUN 接管系统流量，根据 GFW List、中国域名/中国 IP 列表、局域网规则进行 DIRECT / PROXY 分流。

Linux / WSL
     │  所有应用流量（无需设置任何代理环境变量）
     ▼
   TUN 网卡 (sscli0)
     │
     ▼
 sscli 路由引擎（gvisor 用户态 TCP/IP 栈 + 规则匹配）
     │
     ├──── DIRECT ──→ 直接出网（fwmark 防回环）
     │
     └──── PROXY ───→ 本地 SOCKS5 → sslocal → VPS

Shadowsocks 协议完全复用 shadowsocks-rust 的预编译 sslocal 二进制（托管子进程），sscli 不自行实现任何加密协议。

特性

• 三种模式：gfw（默认，仅代理 GFW List 命中目标）、bypass（默认代理，绕过中国）、global（除局域网全代理）
• TUN 接管：基于 gvisor netstack（sing-box/mihomo 同款用户态 TCP/IP 栈）
• TCP/UDP 全协议分流：TCP 与 UDP（QUIC/HTTP3、NTP、VoIP 等）走同一套 DIRECT/PROXY 决策——直连为 fwmark 原生 socket，代理为 SOCKS5 UDP ASSOCIATE
• 防代理死循环：fwmark + 独立路由表 + VPS 主机路由豁免（解析出的全部服务器地址都豁免，DNS 轮询多 A 记录不会回环）
• DNS 分流：内置分流解析器（中国域名走国内上游），直连上游用 TCP 传输防 LAN 伪造应答；服务器域名启动解析走 DoH（RFC 8484），不被 ISP 明文窥探；域名→IP 映射表支撑基于域名的 IP 连接路由
• 规则系统：GFW List / 中国域名 / 中国 IP / 自定义规则，优先级明确，Hash+基数树结构支撑数十万条目毫秒级匹配；更新带内容漂移告警
• 最小权限与资源防护：sslocal 以 nobody 降权运行、密码经 0600 临时文件传递；4096 并发流准入、DNS/UDP 流空闲回收
• 远程会话不中断：既有 TCP 连接（如登录本机的 SSH 会话）与入向新连接的应答经 conntrack ESTABLISHED 豁免直接走原路径，启动/重启不打断远程管理；新出站连接照常分流
• 安全退出：SIGINT/SIGTERM/SIGHUP 全量恢复网络状态，崩溃后可用 sscli stop 清扫残留（带 PID 验身，不误杀复用 PID 的进程）
• IPv6 防泄漏：仅当主机存在全局 IPv6 时才安装 v6 TUN 路由，避免 v6 绕过代理或拖死连接

安装

方式一：一条命令（推荐）

curl -fsSL https://raw.githubusercontent.com/Icestab/shadowsocks-linux-cli/master/scripts/install-remote.sh | bash

自动完成：解析最新版本 → 下载对应架构的 Release 包 → SHA256 校验 → 安装 sscli/sslocal/规则 → 生成配置模板。可选环境变量：SS_VERSION=v0.2.3、PREFIX=~/.local。

方式二：下载发布包（无需 Go 环境）

从 GitHub Releases 下载对应架构的 sscli-v<版本>-linux-<架构>.tar.xz（附 .sha256 校验文件）。

包内自带全部依赖：静态编译的 sscli、官方预编译 sslocal、打包时点的三份路由规则基线——安装阶段无需联网，也没有"没有代理就下不了规则"的引导问题：

echo "<官方sha256>  sscli-v0.2.3-linux-x86_64.tar.xz" | sha256sum -c -   # 可选校验
tar xJf sscli-v0.2.3-linux-x86_64.tar.xz && cd sscli-v0.2.3-linux-x86_64
sudo ./install.sh     # 离线完成部署，随后自动尝试在线刷新规则到最新

方式三：源码安装

./scripts/install.sh

脚本自动完成：构建 sscli → 下载官方预编译 sslocal（SHA256 校验）→ 安装二进制 → 生成 /etc/sscli/config.yaml 配置模板（0600）→ 下载分流规则 → 运行自检。装完只需编辑配置里的服务器信息即可 sudo sscli start。

用户级安装（不需要 root）：PREFIX=~/.local ./scripts/install.sh

手动安装

1. 构建

git clone <repo> && cd shadowsocks-linux-cli
./scripts/install.sh          # 构建并安装到 /usr/local/bin
# 或仅构建：
go build -o bin/sscli ./cmd/sscli

依赖：Go 1.22+，iproute2（ip 命令）。

2. 安装 sslocal（预编译，无需自己编译）

一键脚本会自动完成此步；手动方式：

curl -sL https://github.com/shadowsocks/shadowsocks-rust/releases/latest/download/<对应平台包>.tar.xz \
  | tar xJ -C /tmp sslocal
sudo install -m755 /tmp/sslocal /usr/local/bin/sslocal

3. 配置

sudo sscli config init        # 或直接编辑 /etc/sscli/config.yaml
sudoedit /etc/sscli/config.yaml

最小配置示例：

mode: gfw            # gfw | bypass | global

server:
  address: your.server.com
  port: 443
  method: aes-256-gcm
  password: "your-password"

tun:
  name: sscli0
  mtu: 1500
  address: 198.18.0.1/15

sslocal:
  binary_path: /usr/local/bin/sslocal
  socks_addr: 127.0.0.1:1080

rules:
  - domain: github.com
    action: proxy
  - domain_suffix: corp.internal
    action: direct

配置文件含密码，权限保持 0600。

使用

sudo sscli start              # 后台守护化，立即返回（需要 root/CAP_NET_ADMIN）
sudo sscli start --foreground # 前台运行调试（Ctrl-C 停止）
sscli status                  # 查看运行状态
sscli mode bypass             # 切换模式（重启生效）
sscli route github.com baidu.com   # 查询目标的分流决策
sscli dns google.com          # 测试 DNS 解析与分流
sscli test                    # 自检（权限/TUN/DNS/SS链路/规则）
sscli update                  # 更新 GFW List / 中国域名 / 中国 IP 规则
sudo sscli stop               # 停止并恢复网络

权限说明

只有 start/stop/restart 需要 root（TUN 与策略路由是 CAP_NET_ADMIN 特权操作）。mode、route、dns、update、test、status、config 均可普通用户执行。

规则优先级

1. Private/LAN      （系统保留，所有模式直连）
2. 用户自定义规则
3. 中国域名          （gfw/bypass 生效）
4. 中国 IP           （gfw/bypass 生效）
5. GFW List
6. 当前模式默认行为   （gfw→DIRECT，bypass/global→PROXY）

规则文件位于 ~/.config/sscli/rules/（或 /etc/sscli/rules/），由 sscli update 维护，支持断点安全的原子替换——下载或校验失败不会破坏现有规则。

开发与测试

go test ./...                 # 单元测试（规则引擎/DNS/SS链路/路由决策）
./scripts/e2e-test.sh         # root 级端到端测试（需 sudo，见下）

端到端测试覆盖需求验收标准：启动后 TUN/策略路由就位、直连不被破坏、停止后 TUN/路由/ip rule 完整恢复且网络可用。

详见 docs/testing.md。

当前状态

已实现

• CLI 全命令集：start/stop/restart/status/test/update/mode/rules/route/dns/config
• 配置加载/校验/模式热切换（原子改写 YAML；sslocal.socks_addr 强制回环，防 LAN 开放代理）
• Shadowsocks 链路：托管 sslocal 子进程（密码经 0600 临时配置文件传递，不进命令行），以 nobody 降权运行；SOCKS5 + UDP ASSOCIATE 出站，本地 ssserver 回环端到端测试通过
• TUN + gvisor netstack：TCP 流终结、UDP 中继（非 53 端口同走 DIRECT/PROXY 分流，QUIC/HTTP3/NTP 可用）、DNS(53，UDP+TCP) 劫持应答；并发流准入 4096，DNS/UDP 流空闲自动回收
• 策略路由：fwmark 逃逸、14 个私有网段豁免、VPS 全部解析地址主机路由、独立表默认路由，全部操作可逆；v6 TUN 路由仅在有全局 IPv6 时安装；既有 TCP 连接豁免（mangle OUTPUT 对 conntrack ESTABLISHED/RELATED 打 fwmark 直连，snapshot-delta 管理、随 stop/崩溃清扫精确拆除；仅限 TCP——UDP 豁免会绕过 DNS 劫持饿死域名映射）
• DNS 分流解析器（直连上游走 TCP 防伪造；启动引导解析走 DoH，回退系统 DNS 时告警）+ TTL 域名映射表
• 三种模式（真实规则数据验证符合验收矩阵）
• 规则下载/校验/原子替换/内容漂移告警；日志按启动轮转
• 信号处理与网络状态恢复：SIGINT/SIGTERM/SIGHUP 全量清理，sscli stop 幂等可清扫崩溃残留（PID 验身，不误杀复用 PID 的其他进程；不依赖 systemd，手动管理为唯一方式）

未实现（第一阶段明确不做）

• Fake-IP、DoT（DNS 模块接口已预留；DoH 已用于启动引导解析）
• IPv6 完整代理（默认阻断防泄漏，架构已预留 v6 CIDR 匹配）
• GUI/Web UI/Clash API/订阅/多节点等（见需求三十二）

已知限制

• WSL2 mirrored 网络模式下策略路由可能与宿主共享栈冲突，建议 NAT 模式使用
• 崩溃（kill -9）后的残留清扫需手动执行一次 sudo sscli stop

许可

本项目代码采用 MIT；gvisor(Apache-2.0)、wireguard/tun(MIT)、miekg/dns(BSD-3)、x/net(BSD-3) 均为宽松许可；shadowsocks-rust 以外部二进制方式使用（MIT）。