重写为多协议管理器: 6 协议, CLI + curses TUI, 用户级 systemd

2026-11-01 06:38:56 +08:00
1 parent c43ab4a16e
commit 237b958e41
@@ -1,112 +1,207 @@
 # sbp

-`sbp` 在用户级别搭建和管理 sing-box Hysteria2 服务. 不需要 root. 服务由 systemd user 管理.
+`sbp` 在用户级别安装和管理 sing-box 代理服务. 不需要 root. 服务由 systemd user 管理.
+它提供六个协议, 一个命令行接口, 和一个全屏 TUI.

-## 部署到 VPS
+## 安装

-一条命令下载并安装 `sbp`:
+一条命令安装 `sbp` 命令:

 ```bash
 curl -fsSL https://raw.githubusercontent.com/justypist/sbp/main/install.sh | bash
-sbp install
+sbp
 ```

-下载后直接开始搭建:
+`install.sh` 把程序放到 `~/.local/share/sbp/app`, 并建立 `~/.local/bin/sbp` 符号链接.
+环境变量 `SBP_BIN` 改变命令目录. `SBP_APP_DIR` 改变程序目录.
+
+安装后运行 `sbp install` 搭建服务. 也可以让安装脚本直接搭建:

 ```bash
 curl -fsSL https://raw.githubusercontent.com/justypist/sbp/main/install.sh | bash -s -- --run
 ```

-`install.sh` 只安装 `sbp` 命令. 环境变量 `SBP_BIN` 可以改变安装目录 (默认 `~/.local/bin`).
+依赖: Linux, systemd user, openssl, python3 3.9 或更高版本, curl. 网络必须能访问 GitHub.

-也可以手动复制:
+## 快速开始

 ```bash
-install -m 755 sbp ~/.local/bin/sbp
-sbp --version
+sbp install                 # 安装全部六个协议, 自动分配端口, 生成用户 u1
+sbp                         # 打开 TUI
+sbp status                  # 查看状态
+sbp user show u1            # 打印 u1 的全部分享链接
 ```

-依赖: Linux, systemd user, openssl, python3 (标准库). 网络可访问 GitHub.
+## 协议

-## 用法
+| 协议 | 传输 | 证书 | 说明 |
+| --- | --- | --- | --- |
+| Hysteria2 | UDP | 需要 | 默认开启 salamander 混淆 |
+| VLESS + REALITY | TCP | 不需要 | 借用真实网站的 TLS 握手 |
+| Trojan | TCP | 需要 | 经典 TLS 代理 |
+| Shadowsocks 2022 | TCP | 不需要 | 每个用户独立密钥 |
+| TUIC v5 | UDP | 需要 | QUIC 传输 |
+| AnyTLS | TCP | 需要 | 使用填充方案 |
+
+默认安装全部协议. 用 `--protocols` 选择子集:

 ```bash
-sbp install                 # 下载最新 sing-box, 生成证书和用户, 启动服务, 打印配置
-sbp install --port 8443 --sni www.example.com --host 203.0.113.10
+sbp install --protocols hysteria2,vless-reality
+```
+
+每个协议使用独立端口. 默认从 `20000` 开始分配空闲端口. 用 `--base-port` 改变起点.
+
+REALITY 需要一个域名作为握手目标. 默认使用 `--sni` 的值. 如果 `--sni` 是 IP,
+REALITY 会拒绝启动. 请显式指定域名:
+
+```bash
+sbp install --sni www.example.com
+```
+
+## 命令行
+
+### 安装与升级
+
+```bash
+sbp install --host 203.0.113.10 --sni www.example.com
 sbp install --cert fullchain.pem --key privkey.pem --sni example.com
-sbp new phone               # 新增用户并打印配置
-sbp list                    # 列出用户和分享链接
-sbp show phone              # 打印用户的完整配置
-sbp show phone --uri        # 只打印分享链接
-sbp show phone --json       # 只打印 sing-box 客户端配置
-sbp show --cert             # 打印服务端证书
-sbp del phone               # 删除用户
-sbp status                  # 服务状态
-sbp log -f                  # 查看日志
+sbp install --protocols hysteria2,trojan --base-port 30000
 sbp upgrade                 # 升级 sing-box
-sbp uninstall               # 停止并删除服务和程序, 保留配置
+sbp uninstall               # 删除服务和程序, 保留配置
 sbp uninstall --purge       # 同时删除配置和证书
 ```

-`install` 的选项:
+### 协议

-| 选项 | 默认值 | 说明 |
-| --- | --- | --- |
-| `--port` | 随机空闲端口 | UDP 监听端口, 必须 >= 1024 |
-| `--listen` | `::` | 监听地址, 默认同时监听 IPv4 和 IPv6 |
-| `--sni` | `--host` 是域名时用它, 否则 `www.bing.com` | TLS server name 和证书名 |
-| `--host` | 自动探测公网 IP | 打印给客户端使用的地址 |
-| `--cert` / `--key` | 自签名证书 | 使用已有证书, 证书和私钥必须匹配 |
-| `--masquerade` | `https://<sni>` | 伪装地址 |
-| `--no-obfs` | 关闭 | 关闭 salamander 混淆 (不推荐) |
-| `--sing-box-version` | 最新版 | 指定 sing-box 版本 |
-| `--force` | 关闭 | 重装并保留已有用户 |
+```bash
+sbp protocol list
+sbp protocol enable tuic --port 24000
+sbp protocol disable tuic
+sbp protocol port tuic 24001
+sbp protocol set hysteria2 obfs false
+sbp protocol set vless-reality short_id 0123456789abcdef
+```

-## 安全设计
+### 用户

- 密码和混淆密码由 `secrets.token_urlsafe(32)` 生成, 每个用户独立.
- 默认自签名 ECDSA P-256 证书, 有效期 10 年, 只含一个 SAN.
- TLS 最低版本 1.3, ALPN 只用 `h3`.
- 客户端配置使用 `certificate_public_key_sha256` 固定证书公钥. 不开启 `insecure`.
- 服务以非特权用户运行, 只监听 >= 1024 的端口.
- 下载的 sing-box 压缩包与 GitHub 发布的 `sha256` 摘要比对.
- systemd 加固: `NoNewPrivileges`, `ProtectSystem=strict`, `ProtectHome=read-only`,
-  `PrivateTmp`, `PrivateDevices`, `ProtectProc=invisible`, `ProcSubset=pid`,
-  `ProtectKernelTunables`, `ProtectKernelModules`, `ProtectKernelLogs`,
-  `RestrictAddressFamilies` (含 `AF_NETLINK`), `RestrictNamespaces`,
-  `MemoryDenyWriteExecute`, `SystemCallFilter=@system-service`, 空 capability 集等.
- `InaccessiblePaths` 屏蔽家目录中的常见凭据目录 (`~/.ssh`, `~/.gnupg`, `~/.aws`,
-  `~/.kube`, `~/.docker`, 浏览器配置等). 只屏蔽已存在的路径.
- 配置和状态文件权限 `0600`, 证书目录权限 `0700`.
- 日志级别 `warn`, 不记录访问日志.
+```bash
+sbp user list
+sbp user add phone
+sbp user del phone
+sbp user show phone
+sbp user show phone --protocol hysteria2 --uri
+sbp user show phone --protocol hysteria2 --json
+```

-## 分享链接与 pinSHA256
+`--json` 输出完整的 sing-box 客户端配置. 客户端保存为 `client.json` 后运行:

-分享链接中的 `pinSHA256` 是证书 DER 的 SHA-256, 十六进制. 这与 Hysteria 2 URI 规范一致.
+```bash
+sing-box run -c client.json
+```

-部分客户端不支持 `pinSHA256`. 这些客户端会拒绝自签名证书. 请改用 `sbp show <name> --json`
-输出的 sing-box 客户端配置. 不要为了兼容而关闭证书校验.
+客户端配置包含 `127.0.0.1:1080` 的 mixed 入站. 它同时提供 SOCKS5 和 HTTP 代理.

-客户端配置使用 `certificate_public_key_sha256`. 该字段要求 sing-box 1.13 或更高版本.
-旧客户端无法解析.
+### 服务与设置
+
+```bash
+sbp service start|stop|restart
+sbp service logs -n 200
+sbp settings host 203.0.113.10
+sbp settings sni www.example.com
+sbp settings cert --cert fullchain.pem --key privkey.pem --sni example.com
+sbp cert show
+sbp cert renew
+```
+
+### TUI
+
+```bash
+sbp tui
+```
+
+TUI 提供这些页面:
+
+- Dashboard: 状态总览, 启动, 停止, 重启.
+- Protocols: 启用, 停用, 改端口, 改选项.
+- Users: 增加, 删除, 查看分享链接和客户端配置.
+- Settings: 修改 host 和 SNI, 更换证书, 升级, 重装, 卸载.
+- Logs: 查看 journal.
+
+操作键: `↑`/`↓` 或 `j`/`k` 移动, `Enter` 确认, `q` 返回.
+
+## 证书
+
+默认生成自签名 ECDSA P-256 证书, 有效期 10 年. 客户端配置使用
+`certificate_public_key_sha256` 固定证书公钥. 分享链接使用 `pinSHA256` 或
+`allowInsecure=1`.
+
+自签名证书适合个人使用. 如果需要兼容更多客户端, 使用已有证书:
+
+```bash
+sbp settings cert --cert fullchain.pem --key privkey.pem --sni example.com
+```

 ## 文件位置

 | 路径 | 内容 |
 | --- | --- |
-| `~/.config/sbp/state.json` | 用户, 端口, 密码, 证书指纹 |
+| `~/.config/sbp/state.json` | 用户, 协议, 端口, 密钥 |
 | `~/.config/sbp/sing-box.json` | 生成的 sing-box 服务端配置 |
 | `~/.config/sbp/certs/` | 证书和私钥 |
 | `~/.local/share/sbp/bin/sing-box` | sing-box 程序 |
+| `~/.local/share/sbp/app/` | sbp 程序文件 |
 | `~/.config/systemd/user/sbp.service` | systemd user 单元 |

+路径遵循 `XDG_CONFIG_HOME` 和 `XDG_DATA_HOME`.
+
+## 安全设计
+
+- 密码, UUID, Shadowsocks 密钥由 `secrets` 或 `os.urandom` 生成, 每个用户独立.
+- 默认自签名 ECDSA P-256 证书, 只含一个 SAN.
+- TLS 最低版本 1.3, Hysteria2 和 TUIC 只用 `h3` ALPN.
+- 客户端配置固定证书公钥. 不开启 `insecure`.
+- 服务以非特权用户运行, 只监听 >= 1024 的端口.
+- 下载的 sing-box 压缩包与 GitHub 发布的 `sha256` 摘要比对.
+- 新版本 sing-box 必须通过当前配置的 `check`, 才会替换旧程序.
+- systemd 加固: `NoNewPrivileges`, `ProtectSystem=strict`, `ProtectHome=read-only`,
+  `PrivateTmp`, `PrivateDevices`, `ProtectProc=invisible`, `ProtectKernelTunables`,
+  `MemoryDenyWriteExecute`, `SystemCallFilter=@system-service`, 空 capability 集.
+- `InaccessiblePaths` 屏蔽家目录中的常见凭据目录.
+- 配置和状态文件权限 `0600`, 证书目录权限 `0700`.
+- 日志级别 `warn`, 不记录访问日志.
+
+## 代码结构
+
+```
+src/sbp/
+  cli.py              命令行入口和参数解析
+  commands/           每个命令组一个模块
+  state.py            状态模型, JSON 读写, 迁移
+  config.py           生成 sing-box 服务端和客户端配置
+  share.py            生成分享链接
+  protocols/          每个协议一个模块
+  ops/                业务操作, CLI 和 TUI 共用
+  tui/                curses 界面
+```
+
+协议模块只做三件事: 生成 inbound, 生成分享链接, 生成客户端 outbound.
+它不读写文件, 不操作服务, 不访问网络. 新增协议只需要在 `protocols/` 增加一个模块,
+并在 `protocols/__init__.py` 注册.
+
+## 测试
+
+```bash
+PYTHONPATH=src:. python3 -m unittest discover -s tests
+```
+
+测试覆盖状态迁移, 配置生成, 分享链接, 端口分配, 以及安装流程.
+测试不访问网络, 也不依赖已安装的 sing-box.
+
 ## 说明

- 主机需要公网可达的 UDP 端口. 路由器 NAT 需要端口转发.
- 防火墙需要放行 UDP 端口. `install` 会打印示例命令.
+- 主机需要公网可达的端口. 路由器 NAT 需要端口转发.
+- 防火墙需要放行协议端口. UDP 协议放行 UDP, TCP 协议放行 TCP.
 - 用户级服务依赖 lingering. 确认 `loginctl show-user $USER -p Linger` 输出 `Linger=yes`.
-  `sbp install` 在未开启 lingering 时会给出警告.
- 主机没有 IPv6 时, 默认监听 `0.0.0.0`, 不会监听 `::`.
- 首次安装后, `sbp` 会等待服务进入 `active`. 如果失败, 用 `sbp log` 查看原因.
+  `sbp install` 在未开启 lingering 时给出警告.
+- 主机没有 IPv6 时, 默认监听 `0.0.0.0`.
 - Python 的 `urllib` 不读取 `ALL_PROXY`. 使用 SOCKS 代理时请设置 `HTTPS_PROXY`.
- 文件位置遵循 `XDG_CONFIG_HOME` 和 `XDG_DATA_HOME`. 上表按默认值列出.