sing-box 1.14 实战：开启 API 服务与 Dashboard，网页+命令行远程管理节点

背景：节点管久了，最烦的是"改个配置就得 SSH 上去"

sing-box 是一个开源的通用代理平台：既可以在 VPS 上跑作服务端（VLESS、Trojan、Hysteria2 等协议的入站），也可以在电脑、手机上跑作客户端（路由、分流、TUN 透明代理）。自建节点的玩家里，用它的人不少。

以前在 VPS 上运维 sing-box，基本是"SSH 登录 → 改 JSON → sing-box check → 重启服务"四步走。想看一眼当前连接数、切个出站分组、踢掉一条异常连接，都得动手敲命令。

2026 年 8 月底发布的 sing-box 1.14.0 改变了这一点：它引入了一个 API 服务（gRPC 接口），可以观察和控制正在运行的实例——服务状态、日志、出站分组选择与测速、Clash 模式、连接跟踪、网络质量测试，都是同一套接口；配套还有一个 Web 版控制台 sing-box Dashboard，以及命令行客户端 sing-box api。手机和桌面图形客户端也能通过"远程控制"连到服务器上的实例。截至本文写作时（2026-10-24），1.14 系列最新稳定版是 1.14.4。

本篇是 10-21 那篇新特性解读的动手版：只做一件事——在你的 VPS 上把 API 服务和 Dashboard 开起来，并用 CLI 真实操作一遍。文中的配置字段和命令输出均来自官方文档与 1.14.2 的实机验证。

前置知识：需要一台能自己装软件的 VPS（Debian/Ubuntu 最常见），sing-box 版本 ≥ 1.14.0，sing-box version 可查。建议先备份现有配置文件。

第一步：加一段 services 配置

在配置文件的顶层加一个 services 数组（1.14 新增的顶层段）：

"services": [
  {
    "type": "api",
    "listen": "127.0.0.1",
    "listen_port": 18099,
    "secret": "<换成你自己生成的长随机字符串>",
    "dashboard": { "enabled": true }
  }
]

几个字段说明（来自官方 API 文档）：

secret 是访问口令。如果留空，认证直接关闭，任何人连上就能控制你的实例——千万别把空口令暴露到公网。生成一个长的：openssl rand -hex 32。
listen 写 127.0.0.1 最稳妥，只监听本机；想从外网访问时走 SSH 本地端口转发或内网穿透进来，不要直接 0.0.0.0 裸奔。
dashboard.enabled: true 后，sing-box 会自动从 GitHub 下载 Dashboard 前端文件，存到工作目录下的 dashboard/ 文件夹，通过监听地址的 /dashboard/ 路径对外提供；浏览器访问其他路径会自动重定向到它。

第二步：检查并重启

sing-box check -c /etc/sing-box/config.json
# 配置无误会直接通过，有问题会指出哪一行
systemctl restart sing-box   # 按你自己的部署方式重启

第三步：用 CLI 真实操作一遍

命令行客户端的连接参数可以用环境变量指定，省得每次敲：

export BOX_API_URL="http://127.0.0.1:18099"
export BOX_API_SECRET="<你配置里的 secret>"

实测输出长这样（1.14.2，测试环境）：

$ sing-box api status
State:        started
Uptime:       12s
Memory:       58 MB
Goroutines:   21
Connections:  0 in / 1 out
Uplink:       0 B/s (0 B total)
Downlink:     0 B/s (0 B total)

$ sing-box api outbounds
direct  direct  -

$ sing-box api mode
Rule

常用子命令一览（sing-box api --help 可见）：

命令	作用
`api status`	运行状态：运行时长、内存、连接数、上下行
`api logs`	打印服务日志，排错不用再翻文件
`api outbounds`	列出所有出站
`api group list/show/select/urltest`	出站分组：查看、切换、测速
`api connection list/show/close`	查看当前连接、踢掉指定连接
`api mode`	当前 Clash 模式（Rule/Global/Direct）
`api networkquality` / `api stun`	网络质量测试、STUN 测试

写错口令会直接被拒，这是实测的报错：

$ sing-box api --secret wrong-secret status
FATAL: Unauthenticated: invalid authorization

网页 Dashboard 与手机 App 远程

浏览器打开 http://<服务器>:18099/dashboard/（本地转发后就是 http://127.0.0.1:18099/dashboard/），填入 secret，就能看到和图形客户端几乎一样的界面：出站分组切换、连接列表、日志、测速，点点鼠标就行。想先睹为快但还没升级，可以打开官方的公开体验实例 dash.sing-box.app 看看长什么样（那是演示站，连的是它自己的实例）。

手机和桌面端的 sing-box 图形客户端（iOS、macOS、Android）也有"远程控制"功能，填入服务器地址和 secret 即可管理远端实例——出门在外切个节点，不用再开电脑 SSH 了。

排错：Dashboard 打开 404 怎么办

dashboard.enabled: true 依赖从 GitHub 下载前端包。实机验证时遇到过这个报错：

service/api[0]: update dashboard: Get "https://github.com/SagerNet/sing-box-dashboard/archive/refs/heads/gh-pages.zip": tls: first record does not look like a TLS handshake

当时浏览器访问 /dashboard/ 返回的就是 404——文件没下载下来，自然没东西可提供。国内 VPS 直连 GitHub 抽风是常态，两个备选方案：

download_url 换一个能访问到的镜像地址（zip 包格式与官方一致即可）；
自己把 Dashboard 构建产物放到某个目录，用 dashboard.path 指向它（该目录下非 sing-box 下载的文件会原样提供）。

Dashboard 默认每天检查一次更新（update_interval 默认 1d），不用手动操心版本。

安全清单（开之前先看完）

secret 必须设、必须长：空口令 = 无认证，官方文档原话"If empty, authentication is disabled"。
默认只监听 127.0.0.1：需要远程访问时，用 ssh -L 18099:127.0.0.1:18099 user@你的VPS 把端口转发到本地，或者走 Tailscale 内网。直接把 API 端口暴露到公网，等同于把节点管理权送人。
配置里还有 tls 字段，真要公网暴露的话至少套一层 TLS，细节见官方文档。
升级注意：1.14 要求 Go 1.25 编译，老系统直接装官方预编译包即可；从 1.13 升级前先看升级要点，有按约定移除的废弃特性。

同系列：想先看 1.14 都新增了什么再决定升不升级，参考《sing-box 1.14.3 新特性解读：Snell 协议、远程面板与升级要点》；VPS 端的抗封锁排错思路见《sing-box 抗封锁工具箱》。

*参考：sing-box 官方更新日志、API 服务配置文档，配置字段与命令输出以 2026-10-24 查阅时的文档及 1.14.2 实测为准。*