Sing-box-EV 详细教程：从安装、节点配置到诊断与安全更新

Sing-box-EV 详细教程：从安装、节点配置到诊断与安全更新

在 Linux 服务器上手工维护 sing-box，往往不只是写一份 JSON 配置。你还需要处理内核安装、systemd 服务、端口、防火墙、TLS 证书、节点链接、订阅、日志、更新和故障回滚。

Sing-box-EV 是一个面向 Linux 服务器的 Bash 管理项目，目标是把这些操作集中到统一的终端菜单和命令行工具中。它既适合第一次接触 sing-box 的用户，也保留了便于自动化和排错的 CLI 命令。

本文以 v26.8.11 为基线，从零开始介绍安装、创建节点、导入客户端、日常管理、安全更新和故障排查。文中的示例不会包含真实密码、UUID 或证书信息，请用自己服务器生成的内容替换。

请只在自己拥有或获得明确授权的服务器和网络中使用本项目，并遵守所在地法律、服务商条款和网络管理规定。修改配置或升级前，建议先创建备份。

目录

一、项目能做什么

Sing-box-EV 将常见的服务器端操作整合在一个项目里，主要包括：

  • 安装和更新 sing-box 内核、管理脚本、Caddy 与 cloudflared。
  • 通过终端菜单创建、修改、删除和查看节点。
  • 支持 Reality、Hysteria2、TUIC、Trojan、VMess、VLESS、Shadowsocks、AnyTLS、SOCKS 和 CFtunnel 等配置。
  • 输出节点分享链接、二维码和订阅内容。
  • 管理 Reality 伪装域名池，并根据健康状态自动选择 SNI。
  • 管理 systemd 服务、日志、定时任务和 DNS 设置。
  • 使用 doctor 检查系统、端口、服务、配置、证书指纹和客户端兼容性。
  • 在修改前创建快照，并提供手动备份、回滚和 dry-run 预览。
  • 记录项目管理的文件、服务和端口，帮助完整卸载。

项目同时提供两种使用方式：

  1. 交互式菜单：适合新手，输入 sb 后按编号操作。
  2. 命令行模式：适合熟悉流程后快速操作，也便于脚本化。

二、安装前准备

1. 支持的环境

建议准备一台全新的 Linux VPS，并满足以下条件：

  • Ubuntu 20.04 或更高版本。
  • Debian 11 或更高版本。
  • CentOS 7 或兼容发行版。
  • x86_64 或 arm64 架构。
  • 拥有 root 权限。
  • 系统使用 systemd。
  • 服务器能够访问 GitHub Release 和软件依赖源。

脚本会按需处理 curl、wget、tar、jq 等依赖，但服务器本身必须能够正常联网和解析域名。

2. 端口和安全组

云服务商的安全组与 Linux 本机防火墙是两层不同的限制。即使服务已经监听，如果云安全组没有放行，对外仍然无法连接。

常见规则如下：

使用场景 需要放行的方向和协议
VLESS Reality、Trojan、VMess TCP 类节点 对应节点端口的 TCP 入站
Hysteria2、TUIC、VMess-QUIC 对应节点端口的 UDP 入站
Caddy 自动申请证书 通常需要 TCP 80 和 443
SSH 管理 保留自己的 SSH TCP 端口

不要为了省事开放所有端口。节点创建完成后，只放行实际使用的端口和协议。

3. 域名是否必需

不同协议对域名的要求不同：

  • VLESS Reality：通常不需要拥有域名，适合作为第一个节点。
  • Hysteria2、TUIC：可以使用脚本生成的自签证书，但客户端必须正确处理证书固定信息。
  • VLESS/VMess/Trojan + TLS：建议准备解析到服务器的域名，由 Caddy 申请和管理证书。
  • Cloudflare Tunnel：需要 Cloudflare 账户、已托管域名和 Tunnel Token。

三、安装 Sing-box-EV

1. 建议先下载并查看安装脚本

对任何需要 root 权限的在线脚本，先下载、查看，再执行会更稳妥：

1
2
3
curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/sing-box-ev/main/install.sh -o install.sh
less install.sh
bash install.sh

如果你已经确认来源，也可以使用项目提供的一键安装命令：

1
bash <(curl -s -L https://raw.githubusercontent.com/LuoPoJunZi/sing-box-ev/main/install.sh)

网络无法访问 raw.githubusercontent.com 时，可以尝试 GitHub 仓库地址：

1
bash <(curl -s -L https://github.com/LuoPoJunZi/sing-box-ev/raw/main/install.sh)

安装完成后，重新打开终端或直接运行：

1
sb

2. 确认安装状态

先执行以下命令：

1
2
3
sb version
sb status
sb doctor

其中：

  • sb version 查看脚本和相关组件版本。
  • sb status 查看 sing-box、Caddy 等服务状态。
  • sb doctor 执行综合诊断，并给出明确的成功、提醒或错误信息。

如果 sb 提示命令不存在，可以重新登录 SSH，然后再试。仍然无效时，检查安装输出是否中途失败，并重新执行安装程序。

四、认识菜单和命令行

直接运行 sb 会进入主菜单。菜单适合完成节点添加、修改、删除、更新、日志查看、备份回滚等操作。

常用命令如下：

1
2
3
4
5
6
7
8
sb help
sb status
sb add <协议> [端口] [其他参数]
sb info [配置名]
sb url [配置名]
sb sub
sb all
sb log

命令支持部分简写，例如：

1
2
3
4
sb a reality
sb i <配置名>
sb c <配置名>
sb d <配置名>

不确定某个协议需要哪些参数时，直接进入 sb 菜单创建最合适。交互流程会逐项提示，不必记忆所有命令参数。

五、创建第一个 Reality 节点

对于没有域名、希望快速完成第一个节点的用户，推荐从 VLESS Reality 开始。Reality 使用 TCP，因此要记得在云安全组中放行对应的 TCP 端口。

1. 自动创建

下面的命令会自动选择端口，并从 Reality 域名池中选择合适的 SNI：

1
sb add reality auto auto --auto-sni

也可以运行 sb，在协议列表中选择 VLESS-REALITY，然后按提示操作。

新建 Reality 节点时，脚本会生成必要的密钥、UUID 和 Short ID。当前实现使用明确的 8 位十六进制 Short ID，并在分享链接中导出 sid，以提高客户端导入兼容性。

2. 检查服务和端口

创建完成后执行：

1
2
sb status
sb doctor

也可以在 Linux 中查看监听端口：

1
ss -lntup

重点确认三件事：

  1. sing-box 服务处于运行状态。
  2. Reality 节点端口正在监听 TCP。
  3. 云服务商安全组已经放行同一个 TCP 端口。

3. 查看并导出节点

1
2
3
sb all
sb info
sb url

如果服务器中有多个配置，命令会要求选择配置，或者可以直接在命令后写配置名。

六、怎样选择其他协议

项目支持的协议与传输组合较多，包括：

  • TUIC
  • Trojan
  • Hysteria2
  • VMess-WS、VMess-TCP、VMess-HTTP、VMess-QUIC
  • Shadowsocks
  • VMess-H2-TLS、VMess-WS-TLS
  • VLESS-H2-TLS、VLESS-WS-TLS
  • Trojan-H2-TLS、Trojan-WS-TLS
  • VMess-HTTPUpgrade-TLS、VLESS-HTTPUpgrade-TLS、Trojan-HTTPUpgrade-TLS
  • VLESS-REALITY、VLESS-HTTP2-REALITY
  • AnyTLS
  • CFtunnel
  • Socks

1. Hysteria2

Hysteria2 基于 UDP，在某些高延迟或不稳定网络下可能有不错的表现。自动选择端口创建：

1
sb add hysteria2 auto auto

必须在云安全组中放行对应的 UDP 端口。只放行 TCP 是最常见的配置错误之一。

2. TUIC

TUIC 同样基于 UDP，创建时可以直接在菜单中选择 TUIC。完成后检查 UDP 监听和安全组规则，并使用最新客户端重新导入配置。

3. 带域名的 TLS 节点

如果你拥有域名，可以在菜单中选择 VLESS、VMess 或 Trojan 的 TLS 传输组合。开始前确认：

  • 域名 A/AAAA 记录指向当前服务器。
  • 申请证书期间，Cloudflare 代理状态和 DNS 设置符合证书签发要求。
  • TCP 80、443 或实际使用的 TLS 端口可以从公网访问。
  • Caddy 服务运行正常。

不同传输方式的参数较多，建议使用交互式菜单创建，而不是直接拼接命令。

4. Shadowsocks 和 SOCKS

这两类配置适合明确知道使用场景的用户。SOCKS 示例：

1
sb add socks auto test-user test-pass

示例用户名和密码仅用于展示，实际部署时请使用强随机凭据，并限制端口访问来源。不要将 SOCKS 端口无保护地暴露给整个公网。

七、导出节点并导入客户端

1. 单节点信息和链接

1
2
sb info <配置名>
sb url <配置名>

sb info 适合查看完整参数和客户端兼容提示，sb url 适合复制分享链接或扫描二维码。

2. 查看全部节点

1
sb all

该输出以方便复制为目标，会集中展示当前节点链接。

3. 生成订阅

1
sb sub

订阅内容包含节点访问凭据，应当和密码一样保护。不要把订阅地址、二维码或完整链接发布到公开网页、聊天群和截图中。

4. 客户端兼容性说明

近年的 v2rayN、Xray-core 和 sing-box 对跳过证书验证与证书固定字段的处理发生了变化。Sing-box-EV 当前采用以下原则：

  • Reality 链接导出明确的 sni、pbk、sid 和 fp。
  • Trojan 和 VMess-QUIC 使用 pcs 证书指纹，不再导出 insecure、allowInsecure 或 allow_insecure。
  • Hysteria2 自签证书链接使用官方 URI 方案中的 insecure=1，并且必须同时提供 pinSHA256。
  • TUIC 通用链接使用 insecure=1 与 pcs，同时在节点信息中给出 sing-box 客户端所需的 SPKI 固定配置提示。
  • 无法计算证书指纹时，脚本会拒绝输出链接、二维码和订阅条目，而不是生成不安全或不可用的配置。

需要特别注意：部分客户端的 Xray 内核与 sing-box 内核对分享链接字段的映射并不完全相同。以 v2rayN 为例，某些 URI 中的 pcs 目前不会自动转换成 sing-box 出站所需的 certificate_public_key_sha256。遇到这种情况，请查看 sb info 输出的 JSON 片段，并按照客户端实际使用的内核填写。

项目升级修正导出规则后，客户端中已经导入的旧节点不会自动改变。请重新执行 sb url 或 sb sub，删除旧配置并重新导入。

八、日常管理命令

1. 服务控制

1
2
3
4
sb start
sb stop
sb restart
sb status

如果同时使用 Caddy，可在菜单或相应服务操作中检查 Caddy 状态。

2. 查看日志

1
sb log

连接失败时，建议同时观察服务日志和客户端日志。服务端没有收到连接，通常意味着安全组、防火墙、地址或端口有误；服务端收到请求但握手失败，则更可能是 SNI、密钥、UUID、证书指纹或传输参数不一致。

3. 修改和删除节点

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

也可以使用简写：

1
2
sb c <配置名>
sb d <配置名>

删除属于危险操作。执行前确认配置名，并先创建手动备份。

4. DNS 设置

1
sb dns

升级后的 doctor 会检查旧版 sing-box DNS 配置字段。如果发现已废弃的 .dns.servers[].address，更新过程只有在候选内核可以成功验证迁移后的配置时才会写入，避免直接破坏现有服务。

九、使用 doctor 一键诊断

遇到问题时，先运行：

1
sb doctor

它会检查或提示以下内容：

  • Linux 发行版、架构、权限和基本运行环境。
  • 终端颜色能力，以及 NO_COLOR、TERM=dumb 和非 TTY 输出状态。
  • curl、jq、sha256sum 等依赖和版本。
  • sing-box、Caddy、cloudflared 等相关服务状态。
  • TCP/UDP 监听端口与节点配置的对应关系。
  • sing-box 配置语法和候选内核验证结果。
  • 网络、DNS、磁盘空间、快照和安装清单状态。
  • Reality、Trojan、Hysteria2、TUIC、VMess-QUIC 的客户端兼容风险。
  • 旧 DNS 字段和可迁移性。

终端不显示彩色输出时，也可以用无色模式获得结构清晰的诊断结果：

1
NO_COLOR=1 sb doctor

这对于保存日志、CI 输出和向他人提供排错信息更方便。分享诊断结果前，请先检查其中是否含有服务器 IP、域名、配置名或其他敏感信息。

十、备份、回滚与 dry-run

1. 手动创建备份

1
sb backup create "升级前备份"

查看已有快照：

1
sb backup list

项目在关键配置变更前也会创建安全快照，但重要操作前手动创建一份并写明原因，后续会更容易辨认。

2. 回滚

1
sb rollback

或者指定快照 ID：

1
sb rollback <snapshot_id>

回滚后应重新运行：

1
2
sb status
sb doctor

3. 用 dry-run 预览操作

不确定修改会影响哪些内容时，可以先预览：

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

dry-run 不应写入配置或删除文件。它特别适合用于端口变更、卸载和其他影响范围较大的操作。

4. 查看安装清单

1
2
3
sb manifest summary
sb manifest list
sb manifest raw

安装清单记录脚本管理的文件、服务、计划任务和防火墙状态。summary 用于快速了解范围，list 用于查看明细，raw 适合排错或审计。

十一、安全更新机制

Sing-box-EV 可以分别更新不同组件：

1
2
3
4
sb update core
sb update sh
sb update caddy
sb update cloudflared

也可以进入 sb 菜单完成更新。

从 v26.8.11 开始，更新流程进一步加强：

  • 官方 GitHub Release 资产会进行 SHA-256 校验。
  • 缺少校验信息或摘要不匹配时会直接停止，不会继续安装。
  • 下载流程不再使用跳过 TLS 证书检查的选项。
  • sing-box 和 Caddy 会先安装到候选位置，通过配置验证后再替换当前版本。
  • 替换后会检查服务健康状态，失败时自动恢复旧二进制和服务状态。
  • 更新管理脚本时会保留安装清单、快照和自定义 Reality 域名数据。
  • 更新 cloudflared 后会检查正在运行的 Tunnel 服务。

更新前建议执行：

1
2
3
4
sb backup create "更新前备份"
sb doctor
sb update core
sb doctor

如果只想更新管理脚本，则使用 sb update sh。项目版本采用 vYY.M.D 日期格式，例如 v26.8.11 表示 2026 年 8 月 11 日发布。

十二、Reality 域名池

Reality 节点需要合适的伪装目标。项目提供域名池管理命令：

1
2
3
4
5
sb domain list
sb domain test
sb domain pick
sb domain add <域名>
sb domain del <域名>

各命令用途：

  • list：查看内置、自定义和禁用域名。
  • test：检测域名可用性并更新健康缓存。
  • pick：根据健康、权重、地区和近期使用情况选择域名。
  • add：添加自定义域名。
  • del：删除自定义域名或禁用不希望使用的域名。

自动创建 Reality 节点时，可以使用：

1
sb add reality auto auto --auto-sni

自动选择只是降低配置成本，不代表任何域名在所有网络和地区都始终可用。节点异常时，可以重新测试域名池并更换 SNI。

十三、域名 TLS 与 Cloudflare Tunnel

1. 域名 TLS 节点

创建域名 TLS 节点前，依次确认：

  1. 域名已经正确解析到服务器公网 IP。
  2. DNS 传播已经完成，可以在服务器外解析到正确地址。
  3. TCP 80、443 或配置所需端口没有被安全组拦截。
  4. Caddy 没有被其他 Web 服务占用端口。
  5. 证书申请和续期日志没有报错。

常用检查：

1
2
3
4
5
dig +short example.com
ss -lntup
sb status
sb log
sb doctor

将 example.com 替换为自己的域名。

2. Cloudflare Tunnel

CFtunnel 适合没有方便公网入站条件、或者已经使用 Cloudflare Tunnel 的场景。配置前需要：

  • 在 Cloudflare 控制台创建 Tunnel。
  • 获取并妥善保存 Tunnel Token。
  • 在控制台配置公开主机名和目标服务映射。
  • 确认 cloudflared 服务正常运行。

Token 属于敏感凭据，不要写入博客、公开 Issue 或截图。更新 cloudflared 后，可以通过 sb status 和 sb doctor 检查 Tunnel 服务。

十四、常见故障排查

1. Hysteria2 能用，但 VLESS Reality 不能用

这是很典型的端口协议差异问题。Hysteria2 使用 UDP，Reality 通常使用 TCP。你可能只放行了 Hysteria2 的 UDP 端口，却没有放行 VLESS 的 TCP 端口。

排查顺序：

1
2
3
sb status
sb doctor
ss -lntup

然后检查：

  • Reality 配置中的 TCP 端口是否正在监听。
  • 云安全组是否放行同一端口的 TCP 入站。
  • 本机防火墙是否放行 TCP。
  • 客户端中的地址、端口、UUID、SNI、Public Key 和 Short ID 是否与最新导出一致。

2. 终端没有显示颜色

项目会在以下情况自动关闭颜色：

  • 环境变量中存在 NO_COLOR。
  • TERM=dumb。
  • 输出被重定向或当前环境不是 TTY。

执行：

1
2
sb doctor
printf '\033[36m青色标题\033[0m\n\033[32m绿色成功\033[0m\n\033[33m黄色提醒\033[0m\n\033[31m红色错误\033[0m\n'

项目使用兼容性更广的 ANSI 基础色 30-37。如果测试命令有颜色，而 sb 没有颜色，检查：

1
env | grep -E '^(NO_COLOR|TERM)='

3. 客户端能导入，但无法连接

先删除旧节点，用服务器最新输出重新导入：

1
sb url <配置名>

然后确认客户端实际选择的内核，并对照 sb info 中的证书固定提示。对于自签证书节点，不要手工删除证书指纹，也不要随意添加已经被新版本移除的 allowInsecure 参数。

4. 域名 TLS 证书申请失败

重点检查：

  • 域名解析是否正确。
  • 80/443 端口是否被其他程序占用。
  • 云安全组和本机防火墙是否允许访问。
  • Cloudflare 代理设置是否影响当前验证方式。
  • Caddy 日志中是否有证书签发错误。

5. 更新后服务启动失败

新更新流程会验证候选二进制和配置，并在健康检查失败时尝试自动回滚。仍有问题时执行：

1
2
3
4
sb status
sb doctor
sb log
sb backup list

必要时使用 sb rollback 恢复更新前快照。

6. 脚本拒绝输出节点链接

对于需要证书固定的协议，如果脚本无法计算证书指纹，会主动拒绝生成 URL、二维码或订阅条目。这是一种安全保护，不应该通过添加跳过验证参数绕过。

处理方法是修复或重新生成服务端证书，确认 sha256sum 等依赖正常，然后再次运行：

1
2
3
sb doctor
sb info <配置名>
sb url <配置名>

十五、完整卸载

先查看脚本管理的内容：

1
2
sb manifest summary
sb manifest list

再预览卸载动作：

1
sb dry-run uninstall

确认范围无误后执行：

1
sb uninstall

完整卸载会根据安装清单处理脚本创建的配置、日志、二进制、systemd 服务、定时任务、Caddy/CFtunnel 相关内容和已跟踪的防火墙端口。它不会自动为卸载创建快照，因此有保留需求时，请在卸载前手动运行 sb backup create，并将重要配置另行保存。

十六、项目结构与发布方式

Sing-box-EV 主要由 Bash 编写，核心代码已经按职责拆分：

1
2
3
4
5
6
7
src/core/admin/    菜单、命令分发、更新和卸载
src/core/node/     节点新增、修改和删除
src/core/query/    节点信息、URL、订阅和证书指纹输出
src/core/domain/   Reality 域名池
src/core/runtime/  doctor、备份、回滚和运行时安全
src/lib/           文件、JSON、systemd、防火墙、网络等共享函数
scripts/           本地检查、结构检查和回归测试

项目使用 GitHub Actions 执行 ShellCheck、shfmt、结构检查和发布前验证。新版本采用日期版本号，GitHub Release 的公开说明只保留面向用户的“主要变化”，便于快速了解版本差异。

需要查看更新内容时，可访问：

十七、常见问题

Q1：新手应该先选哪个协议？

没有域名时，建议先使用 VLESS Reality，并通过 --auto-sni 自动选择伪装域名。如果服务器的 TCP 网络受限，但 UDP 条件较好，可以再测试 Hysteria2 或 TUIC。

Q2：为什么节点更新后客户端还是旧参数？

分享链接和订阅不会反向修改客户端中已经保存的配置。服务端修改或脚本升级后，应重新导出并导入节点。

Q3：可以一直开启 allowInsecure 吗？

不建议。Xray 和 v2rayN 的相关实现已经转向证书固定字段。项目对 Trojan、VMess-QUIC 等导出使用 pcs，Hysteria2 使用 insecure=1 + pinSHA256 的官方组合。应以 sb info 的当前提示为准，不要自行添加旧参数。

Q4：为什么 sb doctor 比只看服务状态更有用？

服务显示 running 只代表进程存在，不代表安全组、监听协议、配置兼容、证书指纹和客户端参数都正确。doctor 会把这些环节放在一起检查。

Q5：更新失败会破坏现有服务吗？

当前版本使用候选二进制、配置验证、服务健康检查和自动回滚来降低风险。不过任何自动机制都不能替代备份，生产环境更新前仍建议手动创建快照。

结语

Sing-box-EV 的重点不是把所有复杂性藏起来，而是把安装、节点管理、诊断、安全更新和回滚组织成一条可以检查、可以理解、也可以恢复的流程。

第一次使用时，可以记住这组最短路径：

1
2
3
4
sb add reality auto auto --auto-sni
sb status
sb doctor
sb url

日常维护时，再记住三件事：修改前备份，异常先运行 sb doctor，协议导出规则更新后重新导入客户端。这样大多数问题都能在影响扩大之前被发现。

参考资料