管理 API¶
管理服务默认包含健康检查、原生 /v1 API，以及可选的 Clash/Mihomo 兼容接口。实际监听地址来自 listen.panel，接口开关和密钥来自 ui。
启用¶
listen:
panel: 127.0.0.1:9090
ui:
on: true
secret: "replace-with-a-long-random-secret"
api:
native: true
clash-compat: true
cors:
- "http://127.0.0.1:3000"
没有配置 ui.secret 时，API 不鉴权，仅允许本机 loopback 监听。
listen.share: home|all、0.0.0.0/:: 或其它非本机 listen.panel 且 ui.secret 为空时，配置编译会失败（check/run 拒绝启动）。暴露到局域网或容器网络时还必须配置 CORS allowlist。
鉴权¶
普通 API 请求支持：
或：
WebSocket/SSE 因浏览器协议限制，可使用 ?token=<secret>。普通 GET/POST 不接受 query token，避免凭据进入访问日志和 Referer。
Clash 兼容 GET /configs 的 authentication 字段只返回用户名列表，不回传 Mixed 入站密码。
PATCH /configs 的 mode（rule / global / direct）会真正改变选路； unified-delay 会立即改变未被组级配置覆盖的 URLTest；log-level 更新运行时视图。 allow-lan / tun.enable 不能热切换：值与启动配置不同时返回 501，避免 dashboard 假安全控制。
以下路径不要求密钥：
GET /GET /healthz/ui...静态 Dashboard 路径- CORS
OPTIONS预检
认证失败统一返回 401：
原生 /v1 端点¶
| 方法 | 路径 | 用途 |
|---|---|---|
GET | /v1/status | 运行状态与启动时间 |
GET | /v1/traffic | 流量统计 |
GET | /v1/nodes | 节点列表与状态 |
GET | /v1/groups | 策略组列表 |
PATCH | /v1/groups/:name | 修改策略组选择 |
GET | /v1/connections | 当前连接 |
DELETE | /v1/connections/:id | 关闭指定连接 |
GET | /v1/resolver/query | 调试 DNS 查询 |
GET | /v1/route/check | 调试路由结果 |
GET | /v1/inbounds/state | 统一入口及透明数据面状态 |
GET | /v1/capture/state | 旧版流量接管状态别名 |
GET | /v1/mesh/status | 组网监督器、后端、动态附件、资源声明与冲突快照 |
GET | /v1/smart/why | 查看 Smart 选择理由 |
POST | /v1/smart/pin | 固定节点 |
POST | /v1/smart/avoid | 临时回避节点 |
POST | /v1/smart/reset | 重置 Smart 状态 |
GET | /v1/smart/cache | 查看 Smart 缓存 |
GET | /v1/smart/nodes/:group | 查看组内 Smart 节点 |
请求参数和响应结构在 1.0 前仍可能变化。集成时应保留未知字段，并对非 2xx 响应记录状态码和脱敏后的消息。
/v1/mesh/status 只返回监督器当前内存快照的安全公开投影：handler 调用 MeshSupervisor::snapshot().public_view()，不会执行 probe、status 或 refresh，不会访问外部 daemon、触发后端启停/隔离，也不会推进快照 generation。启动、停止和默认 5 秒一次的后台监控负责发布新的内部快照。
公开投影会解析 URL endpoint，只保留 scheme、host 和 port，删除 userinfo、path、query、fragment；非法 URL、Unix socket、named pipe 与 Opaque endpoint 只返回无 value 的 hidden。version 和所有自定义字符串有长度上限并清理控制字符；diagnostic 只公开 level、安全 code 和固定 message；资源声明与冲突均不公开 coordination_key。响应模型也没有命令环境或秘密文件字段。
主程序未注入组网监督器时，该端点明确返回 503 mesh_supervisor_unavailable，不会把“未初始化”误报成“所有后端正常”。当前基础设施阶段没有注册具体产品后端，因此 statuses 可以为空；capture 以及 DNS/Mixed/API 固定监听的 reservations 仍会正常出现在快照中。
示例¶
curl \
-H "x-api-secret: $WUTHERCORE_SECRET" \
"http://127.0.0.1:9090/v1/route/check?host=example.org&port=443"
不要把密钥直接写进 Shell 历史；上例建议通过环境变量提供。
兼容 API¶
ui.api.clash-compat: true 时，服务会合并 Clash/Mihomo 兼容路由，供现有 Dashboard 查询版本、配置、代理、规则、连接、日志与流量，并执行部分控制操作。
兼容目标是常见 Dashboard 工作流，不承诺实现上游项目的每个私有或实验接口。集成前应针对实际 Dashboard 版本执行冒烟测试。
策略组 pin¶
| 方法 | 路径 | 语义 |
|---|---|---|
PUT | /proxies/:group | 请求体 {"name":"节点名"}，为任意已实现策略组设置持久 pin |
DELETE | /proxies/:group | 清除持久 pin |
GET | /group/:group/delay | 并发测速；自动组至少一个节点成功后按世代解除旧 pin，Manual 不解除 |
策略组 JSON 保留 Mihomo 常用的 fixed 字段，并增加向后兼容的 pin 对象。 数据库提交失败会返回 500，不会只改内存。自动组的固定节点失活时会临时回退， pin 本身继续保留。测速解锁后会立即刷新 now。
嵌套组额外返回 selectedChain 和 resolvedNow。now 是上层组直接选择的 下级组，resolvedNow 是实际 outbound，selectedChain 按实际 outbound 到 最外层组的顺序返回完整链。all 只返回过滤和候选数量限制后的直接成员。
GET /proxies/:name/delay 接受节点或组名。组名会递归到当前实际叶子节点，不改变 策略组 pin。只有 GET /group/:group/delay 会展开全部叶子节点并执行自动组测速 解锁。
原生 GET /v1/groups 同时返回 members, configured_members, resolved_member, selected_chain, default_selected, empty_fallback, min_members, max_members, lazy, weights, hidden 和 icon。
服务端保护¶
API 层包含：
- CORS allowlist 与 Private Network Access 响应头；
- 按来源 IP 的请求限流；
- 请求体大小限制；
- 请求超时；
- 安全响应头；
- 常量时间密钥比较；
- WebSocket/SSE 的单独处理。
这些保护不代替反向代理、防火墙或网络隔离。