sing-box 1.14.0-alpha.32 这次容易读错：Dashboard 新字段属于 api service，USB/IP 新字段属于 service 列表里的设备共享能力。它们都不是节点、规则、DNS 或 TUN 的替代品。先把功能边界分清，再决定要不要碰配置。

1.14.0-alpha.32 是预发布版本。本文只按 2026-07-08 官方 release、changelog 和配置文档解读字段，不建议把 USB/IP 写进普通代理模板。

1.14.0-alpha.32 到底新增了什么？

官方 release notes 把这次变化分成两条：API service 支持 Dashboard，另一个是 USB/IP service。前者让 sing-box API service 能下载、更新并通过自己的 listener 直接服务 sing-box Dashboard；后者新增 USB/IP Server 和 USB/IP Client 两类 service，用来导出或导入 USB 设备。

读配置时先看下面这张表。它不是功能清单，是防误判用的。

字段或 service放在哪一层解决什么事先检查什么
type: "api"services[]暴露 sing-box 运行状态、日志、连接和控制接口listen、secret、TLS、CORS
dashboardapi service 内部下载、更新并在 /dashboard/ 服务网页面板enabled、path、download_url、update_interval
type: "usbip-server"services[]导出本机 USB 设备provider、devices、权限、端口 3240
type: "usbip-client"services[]导入远端 USB 设备server、server_port、devices
provider: "dynamic"USB/IP Server 内部由 GUI、Dashboard 或 API 运行时供应设备平台是否支持运行时供应设备

如果你只是在排查网页打不开、订阅导入失败、DNS 没命中，这几个新字段通常不是第一现场。不要把 USB/IP 当成网络代理功能去调。

Dashboard 字段应该放在哪里？

dashboard 不在旧的 experimental.clash_api 下面，也不是独立顶层字段。它是 type: "api" 这个 service 里的一个 option。官方 API service 文档写到，Dashboard 会通过 API listener 的 /dashboard/ 服务，其他浏览器请求会重定向过去。

一个最小可读模板长这样，路径按 Linux 常见目录写；macOS 或 Windows 自己换成实际 profile 目录。

{
  "log": {
    "level": "info"
  },
  "services": [
    {
      "type": "api",
      "tag": "local-api",
      "listen": "127.0.0.1",
      "listen_port": 9090,
      "secret": "change-this-long-random-token",
      "dashboard": {
        "enabled": true,
        "path": "/var/lib/sing-box/dashboard",
        "download_url": "https://github.com/SagerNet/sing-box-dashboard/archive/refs/heads/gh-pages.zip",
        "update_interval": "1d"
      }
    }
  ],
  "inbounds": [],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "final": "direct"
  }
}

这里有两个容易漏的点。第一，secret 为空会关闭认证；本机测试可以短期开，但局域网或远程管理别这么干。第二，dashboard.path 如果是空目录，sing-box 会下载 Dashboard，并用 .etag 跳过未变化更新；如果目录非空且没有 .etag，文档说明它会按现有文件服务，不自动更新。

Dashboard 打不开时先看 listener 还是下载目录？

先看 listener。Dashboard 是通过 API service 的 listener 服务出来的，path 目录里有文件不代表浏览器能访问。最小检查顺序是：API 端口是否监听、/dashboard/ 是否有响应、认证头是否正确、再看下载目录。

本机验证可以用下面两条。第一条看 listener 是否活着；第二条看 Dashboard 路径是否由 API listener 接住。

curl -i http://127.0.0.1:9090/dashboard/
curl -i -H "Authorization: Bearer change-this-long-random-token" http://127.0.0.1:9090/dashboard/

你可能看到的日志和响应大概是这类形状。不要照抄时间戳，只看字段和状态。

INFO[0000] service/api[local-api]: listening at 127.0.0.1:9090
INFO[0001] service/api[local-api]: serving dashboard from /var/lib/sing-box/dashboard
HTTP/1.1 200 OK
content-type: text/html; charset=utf-8

如果第一条直接连不上，问题在 listen、listen_port、系统防火墙或服务没启动。连得上但 401，再处理 secret。只有 listener 正常、权限正常、页面仍旧空白时，才去看 dashboard.path 是否可写、download_url 是否能取到 zip、目录里有没有异常旧文件。

USB/IP Server 和 Client 是什么关系？

usbip-server 负责把本地 USB 设备导出，usbip-client 负责从远端导入这些设备。官方文档说它基于 sing-usbip，增加 hotplug 等扩展，同时保持和标准 USB/IP 的互操作性。这个描述很关键：它处理的是 USB 设备层，不是网络流量分流层。

最小结构可以这样读。服务端选择要导出的设备，客户端连接服务端地址。

{
  "services": [
    {
      "type": "usbip-server",
      "tag": "usb-share",
      "listen": "127.0.0.1",
      "listen_port": 3240,
      "provider": "default",
      "devices": [
        {
          "bus_id": "1-2",
          "vendor_id": 4660,
          "product_id": 22136
        }
      ]
    },
    {
      "type": "usbip-client",
      "tag": "usb-import",
      "server": "127.0.0.1",
      "server_port": 3240,
      "devices": [
        {
          "bus_id": "1-2"
        }
      ]
    }
  ]
}

server_port 默认是 3240。devices 里的 vendor_id、product_id 是数字，不是字符串；bus_id 类似 1-2。客户端 devices 留空时，文档口径是导入全部已导出的设备。这个默认值对调试方便，对长期配置未必合适。

provider default 和 dynamic 怎么选？

provider: "default" 表示从配置里匹配本机设备并导出。官方 release notes 和 USB/IP Server 文档都写了限制：Linux、Windows、macOS 的 CLI provider 需要 elevated privileges；macOS 还需要 CGO build，导出设备还要禁用 SIP。

provider: "dynamic" 则不是从配置文件静态选设备。它由 API 客户端在运行时供应设备，官方点名的平台包括 macOS、Android 的图形客户端，以及带 sing-box Dashboard 的 Chromium 系浏览器。

provider设备来源适合读法权限风险
default配置文件里的 devices 匹配本机设备CLI 直接运行，明确知道要导出的 USB 设备Linux/Windows/macOS 需要高权限；macOS 条件更重
dynamicGUI、Dashboard 或 API 运行时供应设备图形客户端或 Dashboard 临时选择设备依赖 API service 和客户端实现
不配置 USB/IP不导出设备普通代理、DNS、TUN、规则分流配置最低，不引入设备共享面

普通用户大概率选第三行：不配置 USB/IP。除非你明确要在两台机器之间共享 USB 设备，否则不要为了“新字段完整”把它塞进模板。不看日志的排查都是玄学，不看权限边界的配置也是。

macOS 为什么不要轻易试 USB/IP？

macOS 这条要单独拎出来。官方文档写得很直：USB/IP Server 可用平台包括 Linux、Windows、macOS，但 macOS 需要 CGO build，导出设备还要求禁用 System Integrity Protection。USB/IP Client 也写了 macOS 需要 CGO build。

这不是普通 sudo 一下的成本。SIP 是系统安全边界，禁用它会影响整台机器的安全假设。你如果只是为了 Dashboard、远程控制、查看日志，没有任何 USB 设备共享需求，就不要碰这条线。

更稳的做法是把 macOS 当 Dashboard 或动态设备供应端观察，不把它当默认 USB/IP Server 模板。等 1.14 稳定版文档和 GUI 实现都固定后，再重新看是否值得进长期配置。

这类 alpha 字段怎么做最小验证？

验证时只改一个变量。先让 api service 跑起来，再开 dashboard；USB/IP 另起一份测试配置，不和现有 TUN、DNS、route 混在同一个文件里。这样日志里的错误才有指向性。

你可以用下面这个检查顺序，不需要真实启动 USB 设备共享也能先过滤掉结构错误。

sing-box version
sing-box check -c ./api-dashboard-usbip-test.json
sing-box run -c ./api-dashboard-usbip-test.json

期望看到的是版本号明确、配置检查通过、API listener 起得来。日志大概像这样：

sing-box version 1.14.0-alpha.32
INFO[0000] service/api[local-api]: listening at 127.0.0.1:9090
INFO[0000] service/api[local-api]: dashboard enabled
INFO[0000] sing-box started

如果 check 阶段已经报 unknown field 或 unknown service type，先确认你运行的不是 1.13 稳定版。1.13.14 是当前稳定线里的 release，但这些 API Dashboard 和 USB/IP 字段来自 1.14 alpha 链路；稳定版不认识很正常。

哪些边界别写进长期配置？

第一，不把 1.14.0-alpha.32 当稳定版升级建议。GitHub releases 上更高的 alpha tag 也可能已经出现，但 alpha 链路就是测试链路；字段、行为和 GUI 支持都可能继续变。

第二，不把 USB/IP 当代理功能。它不会替你处理 outbounds、route.rules、DNS 劫持或 TUN 入口。你在普通代理排障里看到 USB/IP 字段，先把它从复现配置里拿掉。

第三，不把 Dashboard 暴露到不受控网络。API service 能观察和控制运行中的 sing-box，secret、TLS、CORS 和监听地址都要一起看。只在本机看面板时，127.0.0.1 比 0.0.0.0 清楚得多。

第四，不在 macOS 上为了 USB/IP 随手改 SIP。官方条件已经把门槛写出来了；没有设备共享刚需，就把这部分当 release note 读完，不必执行。

相关阅读

下一步只建议做一件事：把现有配置复制成 api-dashboard-usbip-test.json，删到只剩 services、一个 direct outbound 和最小 route.final，先让 sing-box check 通过。过不了检查的字段，不要合回主配置。