sing-box 管理脚本详细教程：安装、节点配置、订阅与安全更新

在 Linux VPS 上维护 sing-box，不只是写一份 JSON：内核、systemd、端口、证书、客户端参数和更新兼容性，任何一项没对上，都可能让节点无法连接。

本文介绍我的 LuoPoJunZi/sing-box 管理脚本。项目原名 Sing-box-EV，现已更名为 sing-box，服务器上的快捷命令仍然是 sb。它提供终端菜单与命令行两种入口，将节点创建、链接导出、诊断、备份和组件更新集中管理。

2026-10-01 更新：本文按仓库 main 分支的脚本版本 v26.9.25 整理。当前项目推荐 sing-box 稳定内核 1.14.2，不再沿用“1.14 仍是 alpha”的旧说明。脚本版本、内核版本和客户端版本是三回事，正式发布与后续变更以 项目 Releases 和 更新记录 为准。

请仅在自己拥有或获得授权的服务器、网络中使用，并遵守适用规定和服务商条款。本文示例不包含真实密码、UUID、私钥或 Tunnel Token，实际使用时以自己的节点输出为准。

一、先分清项目、内核与客户端

本项目不是 SagerNet 官方客户端，也不是浏览器 Web 管理面板。它基于 233boy 生态做重构与扩展，按职责拆分源码；开源协议为 GPL-3.0。

项目能力

• 安装和更新管理脚本、sing-box 内核，以及按需使用的 Caddy/cloudflared。
• 添加、修改、删除和查看节点，支持 20 多种协议及传输组合。
• 输出分享链接、本地二维码、Base64 订阅和临时 Web 订阅。
• 管理 Reality 域名池，按健康状态、权重和区域选择 SNI。
• 控制服务、日志、自动维护任务和 DNS。
• 用 doctor 检查环境、配置、监听、证书固定和兼容风险。
• 在关键变更前创建配置快照，提供手动备份、回滚与 dry-run 预演。
• 用安装清单查看脚本管理的文件、服务和端口。

自动诊断与回滚用于降低维护风险，不是“更新绝不会失败”的保证，也不能替代异机备份和客户端实际连接检查。

二、安装前准备

本文命令在 Linux VPS 的 Bash 终端执行，不是在本地 Windows 的 Hexo 博客目录中执行。<配置名>、<端口> 等为说明占位符，不能把尖括号原样粘贴到 Shell。

1. 系统、架构与权限

需要：

• root 权限；
• 能正常使用的 systemd；
• x86_64 或 arm64 架构；
• 能访问 GitHub API、Release、Raw 及依赖软件源；
• 可用的服务器网络、DNS 和客户端连接路径。

README 列出了 Ubuntu 20.04+、Debian 11+、CentOS 7+ 等环境，这是项目的兼容说明，不等于这些旧发行版仍适合新装。新服务器优先选择仍在安全维护期内的发行版。

当前安装器实际识别 apt-get、yum、zypper。只有其他包管理器、没有 systemd 的容器或精简系统，不要直接套用；先确认脚本是否支持自己的环境。系统时间也应正确：

1

timedatectl status

2. 不要与已有安装混用

建议在用途清晰的 VPS 上部署。已有 sing-box、Caddy、cloudflared 或其他代理脚本时，先检查命令路径、配置和服务，避免覆盖：

1
2
3

command -v sb
command -v sing-box
systemctl list-unit-files | grep -E 'sing-box|caddy|cftunnel'

本项目默认将 /usr/local/bin/sing-box 和 /usr/local/bin/sb 指向管理入口，真实内核位于 /etc/sing-box/bin/sing-box。不要只看到命令名称相同，就认为它与系统软件包安装的上游程序是同一个入口。

3. 端口、防火墙与云安全组

云安全组与 VPS 防火墙是两层配置。服务正在监听，不代表公网已经放通。

自动端口由脚本分配，不要假设所有节点都使用 443。创建后从 sb info 获取实际地址和端口，再设置云安全组。

例如自己的 Reality 节点使用 TCP 45625，在 UFW 中可放行：

1

ufw allow 45625/tcp

Hysteria2 使用相同数字的 UDP 端口时，规则是：

1

ufw allow 45625/udp

按实际节点选择，不必把两种协议都放行，也不要为了省事开放所有端口。脚本可能处理本机规则，但不会替你修改云厂商安全组。

4. 哪些场景需要自己的域名

• Reality：通常不需要拥有域名，但仍需要合适的握手目标和可达的 TCP 网络。
• Hysteria2/TUIC 自签路线：可以直接使用 IP，客户端要保留对应证书固定值。
• 带域名的 VLESS/VMess/Trojan TLS 组合：准备正确解析到服务器的域名，并满足证书申请条件。
• CFtunnel：准备 Cloudflare 账户、相应域名、Tunnel Token 和公开主机名映射。

NAT/内网 VPS 使用直接节点时，还需要正确的公网地址与端口映射。脚本显示一个 IP，并不证明该 IP 对客户端可达。

三、安装：首次会自动创建 Reality 节点

1. 下载并阅读安装器

登录 VPS，取得 root 权限。使用一个未被其他文件占用的保存路径：

1
2
3

curl -fL https://raw.githubusercontent.com/LuoPoJunZi/sing-box/main/install.sh -o /root/sb-install.sh
less /root/sb-install.sh
bash /root/sb-install.sh

确认来源后，也可以使用一键方式，二选一：

1

bash <(curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/sing-box/main/install.sh)

GitHub 备用入口：

1

bash <(curl -fsSL https://github.com/LuoPoJunZi/sing-box/raw/main/install.sh)

缺少 curl 时先通过本机包管理器补齐。备用链接同样依赖 GitHub，不代表 GitHub 完全不可达时仍能使用。

安装入口来自 main，当前在线安装流程会获取正式 Release 的脚本包和上游内核，并检查下载摘要与包结构。先阅读入口不等于已经审核后续下载的全部代码，仍要确认来源与终端报错。行为见 安装器源码。

2. 安装器完成哪些工作

当前安装器会：

1. 检查 root、架构、systemd 和依赖。
2. 下载、校验内核及管理脚本发布包。
3. 安装脚本和命令链接，初始化主配置与服务。
4. 自动创建首个 VLESS Reality 节点，输出连接信息。
5. 初始配置生成或校验失败时报告安装未完成，不再直接提示成功。

因此首次安装完成后，应先查看已经创建的节点，不必立刻再运行 sb add reality 创建第二个节点。

3. 查看安装结果

1
2
3
4
5

sb version
sb status
sb info
sb doctor
sb url

多节点环境可在提示中选择，或指定实际配置名。后文还有 sb all，用于集中显示全部链接。

如果 sb 不存在，先看安装是否中途失败，再检查命令链接；必要时重新登录 SSH。不要把重复执行安装器当作无影响的“更新脚本”方式，已有环境更新应使用后面的 sb update。

首次成功后的最短路线：

1
2
3
4
5

安装器自动创建节点
    → sb info：确认参数和实际端口
    → 放行云安全组
    → sb url：导入客户端
    → sb doctor：检查服务端环境

四、菜单与 CLI 命令速查

直接执行 sb 进入菜单。当前主菜单按节点、系统和高级工具分组：

1
2
3
4
5
6
7
8
9
10
11

节点管理
  (1) 添加配置       (2) 更改配置
  (3) 查看节点       (4) 删除配置

系统控制
  (5) 启动/停止      (6) 自动维护
  (7) 完全卸载       (8) 帮助文档

高级工具
  (9) 进阶选项       (10) 关于脚本
  (0) 退出

“进阶选项”包含订阅、全部节点、日志、DNS、手动更新、doctor、快照、回滚和安装清单等工具。编号以后可能变动，按实际菜单与 sb help 为准。

配置名来自脚本列出的节点名称，不是客户端备注或 UUID。多个节点时，先在菜单或 /etc/sing-box/conf/ 中确认实际文件名，再操作。

不同协议的参数位置不完全相同，例如 Reality 使用端口、UUID、SNI，Hysteria2 使用端口、密码。新手直接用菜单添加，更不容易把参数填错。

五、新增 Reality 节点与域名池

1. 需要第二个节点时再新增

自动选择端口、UUID 和 SNI：

1

sb add reality auto auto --auto-sni

需要指定端口时，例如：

1

sb add reality 45625 auto --auto-sni

两条是不同方案，不是要连续运行。端口 45625 必须未被占用，并在安全组中开放 TCP。

脚本生成 Reality 密钥、UUID 和 Short ID。当前新建节点使用 8 位十六进制 Short ID，导出链接包含 sni、pbk、sid 和 fp；不要漏掉这些参数。

2. 对照监听与客户端

1
2
3
4
5

sb status
sb doctor
ss -lntp 'sport = :45625'
sb info
sb url

端口按实际值替换，核对 TCP 监听、安全组及客户端参数。Reality 不需要自己的 CA 域名证书，并不意味着 SNI 或握手目标可以随便填写。

3. 管理 Reality 域名池

1
2
3

sb domain list
sb domain test
sb domain pick

• list：查看内置、自定义与禁用条目。
• test：做 DNS/TCP443/TLS 健康检查并更新缓存。
• pick：预览当前选择结果，不会自动把所有已有节点都切换成这个 SNI。

添加自定义目标，权重与区域为可选参数：

1

sb domain add www.cloudflare.com 12 global

区域支持项目定义的 us、eu、apac、global，按自己的实际使用场景选择。这些标签是选择策略，不是自动测定的服务器物理位置。

删除自定义域名或禁用内置域名：

1

sb domain del www.cloudflare.com

以上是功能示例，不是建议同时添加再删除。内置条目被删除时会进入禁用清单，不会修改源码。

池数据默认保存在 /etc/sing-box/sh/：

1
2
3
4

domain_custom.list
domain_disabled.list
domain_health.cache
domain_recent.list

自动健康检查只能降低选择成本，不能保证某个目标在所有地区、线路和客户端上一直适用。已有节点更换 SNI 后，需要重新导出并更新客户端。

六、其他协议怎么选

1. 协议与传输组合

项目菜单目前提供以下组合：

• QUIC/UDP：Hysteria2、TUIC、VMess-QUIC。
• VMess：WS、TCP、HTTP，以及 H2-TLS、WS-TLS、HTTPUpgrade-TLS。
• VLESS：H2-TLS、WS-TLS、HTTPUpgrade-TLS、REALITY、HTTP2-REALITY。
• Trojan：基础节点，以及 H2-TLS、WS-TLS、HTTPUpgrade-TLS。
• 其他：Shadowsocks、AnyTLS、CFtunnel、Socks。

“菜单里有”不等于“所有客户端都支持”。旧传输、新内核和导入字段之间仍可能存在兼容差异；尤其 VMess-QUIC，项目也提示它属于兼容风险较高的旧路线，新建节点不要只看协议数量。

2. Hysteria2 / TUIC

Hysteria2 示例，端口和密码自动生成：

1

sb add hysteria2 auto auto

TUIC 示例，自动生成所需参数：

1

sb add tuic auto auto

都需要放行实际节点的 UDP 端口，并按 sb info 的当前提示处理自签证书固定。

这里的 Hysteria2 由 sing-box 内核提供，与 hy2ctl 管理的独立 Hysteria2 程序不同。不要混用服务名、配置路径或内核版本；同一 VPS 同时部署两套工具时，也不能占用同一个 UDP 监听端口。

3. 域名 TLS 组合

通过菜单选择 VLESS/VMess/Trojan 的 TLS 传输组合，开始前确认：

1. 域名 A/AAAA 指向当前服务器，错误的 AAAA 不应保留。
2. 域名解析已生效，证书申请路径可达。
3. TCP 80/443 与实际公开 TLS 端口按配置放通。
4. Caddy 没有与已有 Web 服务冲突。
5. 客户端域名、SNI、路径与传输方式一致。

本项目通常让 Caddy 提供公开 TLS 入口，sing-box 节点监听本机内部端口。内部监听端口可能与客户端连接的 HTTPS 端口不同，以导出结果为准，不要把内部端口直接拿来连接公网。

4. Shadowsocks 与 SOCKS

需要明确了解密码、加密方式及客户端支持情况。SOCKS 命令格式示意：

1

sb add socks auto '替换为用户名' '替换为强随机密码'

不能原样使用示例凭据。SOCKS 用户名/密码并不让 SOCKS 传输自动变成 TLS，限制来源地址，不要把它当作可无保护开放的公网加密节点。

七、客户端导入：链接、二维码与证书固定

1. 导出单节点和全部节点

1
2
3

sb info
sb url
sb all

sb info 查看完整信息及兼容片段，sb url 获取单节点分享链接，sb all 集中显示有效链接。多个节点时指定实际配置名，可以减少选错节点的机会。

优先复制完整链接到客户端导入，然后核对实际使用的内核。导入成功只说明客户端接受了文本，不证明字段映射、证书验证和通信都正确。

2. 按协议保留固定字段

以上是本项目策略，不是所有图形客户端都能自动正确转换这些字段。详情见 证书固定输出源码。

无法计算证书指纹时，项目会拒绝输出该节点的链接、二维码或订阅条目。不要添加 allowInsecure 来绕过，应先修复证书文件、匹配的私钥及 OpenSSL 环境。

3. Sing-box 公钥指纹不能用 pcs 代替

• pinSHA256 / pcs：这里是整张证书的 SHA-256 指纹。
• certificate_public_key_sha256：证书公钥的 SHA-256，使用 Base64 编码。

不是同一个值，也不是换一个字段名就能互用。部分图形客户端不会把 pcs 转成 Sing-box 所需的公钥字段，所以项目在 sb info 中另外给出 TLS 片段。

按本项目当前输出，自签 Sing-box 客户端片段示意为：

1
2
3
4
5
6
7
8

"tls": {
  "enabled": true,
  "server_name": "请使用节点实际输出的 SNI",
  "insecure": false,
  "certificate_public_key_sha256": [
    "请使用 sb info 输出的公钥指纹"
  ]
}

这是需要嵌入相应 outbound 的片段，不是完整 JSON 配置。Hysteria2/TUIC 还应保留输出中的 alpn 等实际参数，不要照抄占位值。字段要求参考 Sing-box TLS 文档。

4. 客户端版本与证书变更

项目给出的旧版安全/兼容下限包含 v2rayN 7.24.9 和 Xray-core 26.7.11，不能把它们当作长期停留旧版的理由。

截至本文更新日，v2rayN 7.25.4 正式版 已说明支持 sing-box 1.14。原文的“1.14 仍未稳定”和旧客户端建议不再适用，但仍需检查图形客户端实际选择和安装的内核。

修改 UUID、密码、端口、SNI 或重新生成证书后，客户端里已经保存的节点不会自动变化。重新导出并覆盖旧配置；重新签发自签证书时，证书/公钥固定值也可能变化。

5. 二维码的隐私边界

使用 sb qr 可在装有 qrencode 的终端中显示二维码。二维码内容与完整节点链接一样包含凭据。

项目还会给出在线二维码生成地址。在浏览器打开第三方二维码链接，会将完整节点 URL 提交给该服务。优先使用本地终端二维码或直接复制链接，不要把凭据交给不信任的在线转换网站。

八、订阅导出与临时 Web 服务

进入菜单的订阅功能，或运行：

1

sb sub

1. Base64 剪贴板订阅

脚本收集有效分享链接，再编码为一段 Base64，可在支持这种格式的客户端中从剪贴板导入。

Base64 只是编码，不是加密。订阅里包含密码、UUID 和连接地址；泄露这一段文本，等同于泄露其中的节点链接。

这种聚合不是 Sing-box 完整 JSON，也不是 Clash/Mihomo 配置。客户端必须支持这类链接订阅，不能因为名字都叫“订阅”就直接互用。

2. 临时 Web 订阅的实际行为

当前实现检测到 Python3 时，还会启动：

1
2
3

文件目录：/tmp/sb_sub/
监听端口：TCP 9866
地址示意：http://服务器IP:9866/sub.txt

它使用 Python HTTP 服务，没有 TLS、没有登录认证，路径也不是随机秘密地址。脚本还会尝试结束占用 9866/TCP 的进程，因此该端口已有其他业务时不要使用这条路径。

建议优先使用剪贴板方案。确实使用临时 Web 方式时：

• 先确认端口空闲，仅允许可信客户端访问，不要为它长期开放公网。
• 不经明文网络传递敏感订阅，优先采用受控安全通道。
• 导入后按回车结束临时服务，并确认监听关闭。
• 不把该地址当作永久订阅；临时服务关闭后，客户端自动刷新会失败。
• SSH 中断或进程异常时，不要假设服务已被清理。

查看是否仍有监听：

1

ss -lntp 'sport = :9866'

具体行为见 订阅实现。界面的成功提示不应被理解为对所有网络条件的安全保证。

九、日常管理、日志与 DNS

1. 服务控制

按需选择命令，不要把启动、停止、重启当作必须连续执行的一组：

1
2
3
4

sb start
sb stop
sb restart
sb status

使用 Caddy 时可单独操作：

1

sb restart caddy

部分服务控制在后台发起，执行后再看实际状态。CFtunnel 的状态还需要查看对应 cftunnel-端口.service，sb status 不是所有相关服务的完整清单。

2. 日志

1

sb log

当前命令跟踪 /var/log/sing-box/access.log；按 Ctrl+C 结束。文件不存在或服务启动阶段失败时，查看 systemd 日志：

1
2

journalctl -u sing-box.service --no-pager -n 100
journalctl -u caddy.service --no-pager -n 100

提高日志等级会修改配置并重启，不是只读查看：

1

sb log debug

排查完成后按需恢复 info，避免长时间记录过多内容。sb log none 和 sb log del 有关闭日志或删除日志的效果，保留需要的故障证据后再操作。

3. 修改与删除节点

先备份，再使用：

1
2

sb change <配置名>
sb del <配置名>

例如只预演端口变化：

1

sb dry-run change <配置名> port auto

确认影响后再执行真实修改，同步云安全组和客户端。删除节点、换端口后，也要检查是否仍保留不需要的防火墙放行规则。

4. DNS 设置

1

sb dns

这里主要处理 sing-box 配置中的 DNS，不等于修改了所有应用的系统 DNS。既有配置应先备份，出现新版兼容提示时按文件定位问题，不要为了消除警告随意删掉 DNS 规则。

十、doctor 能检查什么，不能证明什么

遇到问题先运行：

1

sb doctor

当前诊断涵盖：

• 发行版、架构、权限、systemd、基础依赖；
• 终端颜色、磁盘、安装清单与快照状态；
• 相关服务、节点端口、主配置与节点 JSON；
• Reality 的身份字段、TCP 监听和握手参数；
• 自签证书、公钥固定与客户端兼容风险；
• sing-box 版本及旧 DNS/规则字段；
• Caddy 自定义配置的已知风险组合；
• 受管 cloudflared 隧道的重启次数与最近日志。

1. 当前版本基线

项目区分 sing-box 最低兼容值 1.13.19 与推荐稳定值 1.14.2。达到最低值不代表已经采用推荐版本，达到推荐值也不表示配置无需迁移。上游稳定补丁可对照 sing-box 1.14.2 发布页。

2. 诊断不是外部连接测试

doctor 在服务器本机检查，不会替你完整验证：

• 云安全组是否对实际客户端开放；
• 客户端网络是否允许 TCP/UDP；
• 图形客户端是否把 URI 正确转成相应内核配置；
• 端到端证书握手、DNS、路由与实际业务流量。

所以“服务 running”和“doctor 没有阻断项”仍需要客户端实际连接确认。

3. 无色模式与保存结果

1

NO_COLOR=1 sb doctor

当前实现会在 NO_COLOR 非空、TERM=dumb 或非 TTY 输出时关闭颜色，这是正常的纯文本模式。

需要检查终端是否支持 ANSI 色彩时，可运行：

1
2

printf '\033[36m青色标题\033[0m\n\033[32m绿色成功\033[0m\n\033[33m黄色提醒\033[0m\n\033[31m红色错误\033[0m\n'
env | grep -E '^(NO_COLOR|TERM)='

诊断输出不会自动等同于已经脱敏。对外分享前检查 IP、域名、配置名、UUID、密码和日志内容，不要上传整套配置或 Token。

十一、备份、回滚、dry-run 与安装清单

1. 手动快照

1
2

sb backup create "升级前备份"
sb backup list

默认快照目录是 /etc/sing-box/sh/backups/。当前实现保存主配置 config.json、节点目录 conf/，以及适用时脚本自己的 Caddy 配置片段和版本元信息。

只保留最近 20 个快照。关键操作前创建有说明的手动快照更容易辨认，但不能把它当作永久历史记录。

2. 快照不是整机备份

当前配置快照不包含所有内容，例如：

• /etc/sing-box/bin/ 中的内核和共享自签证书/私钥；
• 全部 Caddy 数据及 ACME 账户、证书缓存；
• 全部系统服务定义、Tunnel Token、二进制；
• 云安全组和完整系统防火墙状态。

重要节点应另行备份证书、匹配的私钥、必要的服务配置及环境记录，并保存到服务器或安装目录之外。Reality 私钥也可能存于节点 JSON 中，快照同样属于敏感文件。

快照范围以 当前实现 为准。

3. 回滚配置

选择快照：

1

sb rollback

指定快照 ID：

1

sb rollback <snapshot_id>

可先预演：

1

sb dry-run rollback <snapshot_id>

sb rollback 主要恢复配置，不会按元信息里的版本号自动降级内核、脚本或恢复所有外部资源。它也可能覆盖当前节点目录；确认所选快照后再执行。

回滚后检查：

1
2

sb status
sb doctor

再用客户端连接，必要时重新导出旧参数。不能因为命令打印“回滚完成”就认定服务健康和公网连接都已恢复。

4. dry-run 的边界

常用预演：

1
2

sb dry-run change <配置名> port auto
sb dry-run uninstall

当前版本对未支持详细预演的命令会明确提示未执行，不会直接落入真实操作。预演用于看操作范围，不是配置实际生效、服务可用或网络连接成功的证明；执行真实操作前仍要备份。

5. 安装清单

1
2
3

sb manifest summary
sb manifest list
sb manifest raw

清单默认位于 /etc/sing-box/sh/.install_manifest。它记录脚本管理的文件、目录、服务、计划任务和端口，不是所有共享组件的完整依赖分析。

raw 适合排障，但原始记录同样可能包含不想公开的路径或配置信息，对外分享前检查。

十二、组件更新与 sing-box 1.14 迁移

1. 四种更新目标

默认内核更新跟随上游正式 Release，不自动追随预发布版本。指定版本属于主动选择，应先确认兼容性，不要在生产环境为试用字段切到 alpha。

旧脚本先更新管理代码，再按诊断结果决定内核升级：

1
2
3
4

sb backup create "管理脚本更新前"
sb update sh
sb version
sb doctor

确认兼容问题处理好后，再安排内核维护：

1
2
3
4

sb backup create "内核升级前"
sb update core
sb status
sb doctor

2. 更新保护机制与边界

当前更新流程会：

• 使用 HTTPS 下载并检查 GitHub Release 提供的 SHA-256；
• 校验信息缺失或不匹配时拒绝替换；
• 对内核、Caddy 先运行候选文件并验证适用配置；
• 替换后检查服务，异常时尝试恢复旧二进制与适用配置；
• 更新脚本时保留清单、快照与 Reality 域名数据；
• 更新 cloudflared 时检查受管且原先运行中的 Tunnel 服务。

这些检查不能覆盖所有故障；恢复命令自身也可能失败。配置快照与更新器的临时二进制恢复是不同机制，不要以为 sb rollback 能替代任何组件的版本回退。

3. 旧 DNS 不能只换一个字段名

当前升级检查会扫描主配置和节点目录里的旧格式：

• dns.servers[].address；
• 特殊旧 DNS server、FakeIP；
• DNS outbound/strategy、旧响应匹配规则；
• 缓存字段和内联 ACME；
• 远程规则集 download_detour；
• 未显式配置 HTTP client 的规则下载方式。

普通主配置的旧 DNS address 可以生成候选 type/server 配置，只有候选内核验证通过才提交。特殊 DNS、节点目录中的旧格式及冲突规则，可能要求先手动迁移。

不是所有 WARN 都会自动迁移，也不是把 address 一律替换成 server 就完成了升级。按 sb doctor 列出的具体文件处理，再参考 sing-box 官方迁移文档。

计划在后续版本移除的弃用字段，可以现在逐步整理；不要为消除提醒直接删除仍承担分流或解析功能的规则。

4. JSONC 与证书对

当前项目要求其管理流程中的配置是标准 JSON。手工加入注释的 JSONC，先转换为标准 JSON，不要粗暴删除所有包含 // 的文本，以免破坏 URL 等字段。

已有证书不会仅因打开菜单或查询而自动重签。只剩证书或私钥时，应恢复匹配的一对文件；随意重新签发会改变客户端固定值。

5. Caddy 与 cloudflared 提示

当前脚本会拒绝更新到 cloudflared 2026.8.0/2026.8.1，并对受管隧道的频繁重启、Docker bridge/QUIC 崩溃特征及未回退 HTTP/2 的日志给出提示。检查没发现特征，不等于所有版本、容器网络都已兼容。

Caddy 自定义配置组合 forward_auth 与 reverse_proxy 时，有已公开的上游错连风险；官方公告列出修复版本 2.11.5。以当前正式 Release 和实际配置核对，不要把脚本里某个稳定基线数字当作全面安全保证。

本项目默认配置并不使用 forward_auth，doctor 的提醒不会自动替你改 Caddy 配置或修复服务。

十三、域名 TLS 与 Cloudflare Tunnel

1. 域名 TLS 的完整链路

客户端连接的是公开 TLS 入口，Caddy 再转发到本机 sing-box 对应传输。排查时同时看：

1
2
3
4

getent ahosts node.example.com
ss -lntup
sb status
journalctl -u caddy.service --no-pager -n 100

node.example.com 替换为自己的域名。核对 DNS、公开 HTTPS 端口、证书、SNI、WebSocket/HTTP 路径和内部端口。

脚本在 80/443 被占用时可能提示改用非标准本机端口，但这不自动改变 CA 从公网访问的挑战端口要求。没有正确转发或其他验证方式时，自动分配一个端口不能保证证书申请成功。

与已有网站共用 Caddy 时，先保存站点配置，确认导入片段与监听没有冲突，不要为了节点安装覆盖网站。

2. CFtunnel 的配置顺序

本项目的 CFtunnel 场景使用 VLESS/WebSocket，经 Cloudflare 公开 HTTPS 主机名转发到本机源站。它不是把任意 Hysteria2/TUIC UDP 端口塞进普通 HTTP Tunnel。

1. 在 Cloudflare 创建 Tunnel，取得 Token。
2. 在 sb 菜单选择 CFtunnel，输入对应 Token 和准备用于节点的域名。
3. 记录生成的内部端口、UUID 与 WebSocket 路径。
4. 在 Cloudflare 配置相同的公开主机名，源站服务指向正确的本机 HTTP 地址，例如 http://127.0.0.1:内部端口。
5. 查看 cloudflared 服务，确认 Tunnel 在线后，再导出客户端链接。

源站地址是格式示意，不是可原样执行的 Shell 命令。公开域名、客户端 SNI/Host 和 WebSocket 路径要对应。协议与源站映射参考 Cloudflare 发布应用说明。

项目创建的服务名通常为 cftunnel-端口.service：

1

systemctl list-unit-files 'cftunnel-*.service'

再对实际服务使用 systemctl status、journalctl -u。Token 会用于服务配置，服务文件、命令输出和备份都可能包含它；不要把 systemctl cat 的完整 Tunnel 输出公开。

十四、重要路径与故障排查

1. 路径速查

默认服务会同时加载主配置与节点目录，不是只读取一个 JSON 文件。系统服务单元还可能有覆盖项，用 systemctl cat sing-box.service 看实际定义。

2. Hysteria2 可用，Reality 不可用

先看监听协议：Hysteria2 是 UDP，Reality 是 TCP。放行 UDP 不代表 TCP 已放行。

1
2
3

sb status
sb doctor
ss -lntup

再核对 Reality 的实际 TCP 端口、UUID、SNI、Public Key、Short ID 与客户端传输。不要直接换密码或重装整套脚本。

3. 客户端导入成功，但不能连接

1. 使用服务器当前 sb info/sb url 重新核对。
2. 检查实际内核及证书固定字段映射。
3. 确认 IP、端口、协议和 TCP/UDP 放行一致。
4. 查看客户端日志与服务端日志。
5. 修改了凭据或重签证书时，再覆盖旧节点。

服务端没有日志不一定证明完全没收到网络数据，可能只是日志等级或输出位置不同；不要把单一现象当作结论。

4. 证书指纹缺失，链接被拒绝

检查 tls.cer 是否存在、是否能由 OpenSSL 读取、私钥是否匹配。查询不会替你自动补证书。

先保存当前文件并检查备份，恢复匹配证书对；确需重签时按项目流程操作，随后更新所有使用这份证书的客户端。不要通过关闭验证绕过导出保护。

5. 更新后服务仍然失败

1
2
3
4

sb status
sb doctor
journalctl -u sing-box.service --no-pager -n 100
sb backup list

优先查看第一处有效错误：配置字段、配置目录、文件权限、二进制或服务恢复。配置问题可选择适用快照回滚；二进制或外部组件问题，需要对应的版本恢复，不能只运行 sb rollback 就假设全恢复。

6. 临时订阅无法访问或刷新

检查本次是否真的启动 Python 服务、9866 是否被占用、云安全组是否允许可信来源、客户端拿到的地址是否可达。临时服务关闭后不能刷新是预期行为，不要为了修复订阅把无认证 HTTP 服务长期留在公网。

7. 提交 Issue 前保存信息

提供操作系统、脚本/内核/客户端版本、协议与传输方式、复现步骤及脱敏的诊断/日志。不要上传完整订阅、私钥、Tunnel Token 或包含认证信息的二维码。

问题入口：项目 Issues。

十五、完整卸载：先确认共享组件

先查看范围并预演：

1
2
3

sb manifest summary
sb manifest list
sb dry-run uninstall

有保留需求时，先创建快照，并把重要配置、证书和备份复制到安装目录之外。本机快照位于 /etc/sing-box/sh/backups/，卸载安装目录时也会一起删除。

真正卸载：

1

sb uninstall

卸载不会自动先创建快照。清理范围包含安装目录、日志、命令链接、服务、定时任务、Tunnel 和相关防火墙记录。

更重要的是，当前兼容清理逻辑还可能删除整个 /etc/caddy、Caddy 二进制、cloudflared，以及匹配的 cftunnel-*.service，不是只逐条删除清单中已确认独占的资源。同一 VPS 上有网站或其他隧道共用这些组件时，不要直接执行完整卸载。

清理端口规则也可能影响使用相同端口的其他服务。云安全组和 Cloudflare 控制台配置不一定随本机卸载一起删除，应另行按实际用途处理。

范围依据见 卸载源码。卸载后不能靠已经删除的本机快照恢复。

十六、开发与发布说明

1. 按职责修改源码

1
2
3
4
5
6
7
8
9
10
11
12
13

install.sh               安装入口
sing-box.sh              CLI 入口
src/init.sh              版本、路径和初始化
src/core/admin/          菜单、命令分发、更新与卸载
src/core/node/           节点输入、JSON 生成与提交
src/core/query/          节点读取、URL、二维码与证书固定
src/core/domain/         Reality 域名池
src/core/runtime/        服务、doctor、快照和回滚
src/core/sub/            订阅生成
src/lib/                 文件、JSON、网络、systemd 等共享工具
scripts/                 lint、测试和工程检查入口
tests/                   单元、集成与 VPS 场景检查
docs/                    架构与真实 VPS 回归文档

新增字段时同步修改输入/写入、查询导出、校验和帮助；不要只改 JSON，不改分享链接。

2. 开发环境命令

1
2
3
4
5

git clone https://github.com/LuoPoJunZi/sing-box.git
cd sing-box
bash scripts/lint.sh
bash scripts/check-release.sh
bash scripts/test.sh

默认测试以隔离环境为主，真实内核与 VPS 验收是单独入口：

1
2
3
4
5
6
7
8

# 会访问 GitHub Release，下载并检查真实内核
bash tests/integration/test-sing-box-release.sh

# 真实环境 CLI 回归，先阅读脚本及文档
bash tests/e2e/regression-cli.sh

# 会创建/删除测试节点，仅在测试机执行
bash tests/e2e/smoke-reality.sh

这些命令是开发说明，不是让已有生产节点全部照做。旧教程中位于 scripts/ 的部分 smoke/regression 入口，已经迁到 tests/e2e/。

3. 版本与发布

脚本版本来源于 src/init.sh 的 is_sh_ver，使用日期格式，如 v26.9.25。GitHub Actions 从 RELEASE_NOTES.md 提取对应的“主要变化”，并等待相应检查后发布。

发布成功、模拟测试通过都不等于所有真实 VPS 的安装、重启、共享服务卸载和公网客户端已经验证。参考 架构文档 与 VPS 回归清单。

结语

首次部署，先使用安装器自动创建的 Reality 节点，核对端口、放行安全组，再导入客户端；需要其他节点时再新增。

日常维护记住四件事：修改前备份、异常先诊断、更新区分组件、客户端同步参数。订阅、证书和快照都属于敏感内容，预演和自动回滚不能替代对操作范围的确认。

参考资料

• 本文管理项目
• 项目版本与更新记录
• sing-box 官方文档
• sing-box 官方迁移说明
• sing-box TLS 配置
• Hysteria2 URI Scheme
• v2rayN 7.25.4 发布说明
• v2rayN allowInsecure 迁移讨论
• Xray 分享链接格式讨论