sbp/README.md

sbp

sbp 在用户级别搭建和管理 sing-box Hysteria2 服务. 不需要 root. 服务由 systemd user 管理.

部署到 VPS

一条命令下载并安装 sbp:

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

下载后直接开始搭建:

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

install.sh 只安装 sbp 命令. 环境变量 SBP_BIN 可以改变安装目录 (默认 ~/.local/bin).

也可以手动复制:

install -m 755 sbp ~/.local/bin/sbp
sbp --version

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

用法

sbp install                 # 下载最新 sing-box, 生成证书和用户, 启动服务, 打印配置
sbp install --port 8443 --sni www.example.com --host 203.0.113.10
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 upgrade                 # 升级 sing-box
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	关闭	重装并保留已有用户

安全设计

• 密码和混淆密码由 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, 不记录访问日志.

分享链接与 pinSHA256

分享链接中的 pinSHA256 是证书 DER 的 SHA-256, 十六进制. 这与 Hysteria 2 URI 规范一致.

部分客户端不支持 pinSHA256. 这些客户端会拒绝自签名证书. 请改用 sbp show <name> --json 输出的 sing-box 客户端配置. 不要为了兼容而关闭证书校验.

客户端配置使用 certificate_public_key_sha256. 该字段要求 sing-box 1.13 或更高版本. 旧客户端无法解析.

文件位置

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

说明

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