3.8 KiB
管理 API v1
所有接口与 Web UI 同源。除首次设置、登录和登录状态外，均需要 cw_session HttpOnly cookie。修改接口还需 X-CSRF-Token，令牌由登录/首次设置/密码更新及 /auth/status 返回。会话有效期 24 小时，退出或修改密码会撤销对应会话。
统一错误：{"error":"中文说明"}；认证失败 401、CSRF/跨站失败 403、输入或应用失败 400、内核未连接的实时查询 503。
| 方法 | /api/v1 下的路径 |
用途 |
|---|---|---|
| GET | /auth/status |
initialized、authenticated、csrf |
| POST | /auth/setup |
{token,password} 首次设置；密码 12–72 字节 |
| POST | /auth/login |
{password} 登录 |
| POST | /auth/logout |
退出 |
| PUT | /auth/password |
{currentPassword,password}，撤销旧会话 |
| GET | /status |
内核状态、版本、实际出口、设置和配置错误 |
| GET/POST | /subscriptions |
列表/新增 {name,url,enabled,intervalHours} |
| PUT/DELETE | /subscriptions/{id} |
编辑/删除 |
| POST | /subscriptions/{id}/refresh |
下载、解析、校验、应用；失败保留旧快照 |
| GET | /nodes |
脱敏节点信息，不返回密码、服务器地址等凭据 |
| POST | /nodes/select |
{mode:"manual",id} 或 {mode:"auto"} |
| POST | /nodes/test |
{ids:[...]}，1–500 个、并发上限 8 |
| GET | /rules |
默认顺序及自定义规则 |
| POST | /rules |
{type,value,action,enabled} |
| PUT/DELETE | /rules/{id} |
编辑/删除 |
| GET/PUT | /settings |
读取/完整替换设置；网卡与地址在当前机器校验 |
| GET | /connections |
Mihomo 活跃连接 |
| DELETE | /connections/{id} |
关闭指定连接 |
| DELETE | /connections |
关闭全部连接 |
| POST | /system/service |
{action:"start"|"stop"|"restart"}，仅固定内核 unit |
| GET | /system/network |
网卡、IPv4 转发、TUN、资源和辅助程序检查 |
| GET | /system/updates |
手动检查 Mihomo 最新稳定版；返回当前/最新版本、更新状态（无法比较时为 null）、检查时间及发布说明 URL；成功结果缓存 10 分钟，失败返回 502 |
| GET | /system/connectivity |
9 个固定 HTTPS 测试网站的 id/name/url/category |
| POST | /system/connectivity/test |
{siteId}；当前 VM Mihomo 分流测试；返回 status/detail/httpStatus/durationMS/tlsVerified/checkedAt；全服务并发上限 3，多余返回 429 |
| GET | /system/backup |
{version:1,exportedAt,state}，敏感配置导出 |
| POST | /system/restore |
同版本备份，校验与回滚；不覆盖管理员 |
| GET | /events |
SSE metrics，每 2 秒更新累计量、速率与连接数 |
| GET | /logs |
SSE log、heartbeat、disconnected |
SSE 认证失效时发送 expired 并关闭，浏览器应重新登录。代理关闭使用 settings 的 proxyEnabled=false，进入直连模式；与停止内核进程不同，DNS/网关仍运行。
Settings 字段：proxyEnabled,tunEnabled,selectionMode,selectedNode,lanIP,lanCIDR,gateway,interface,mixedPort,dnsPort,testURL,testTimeoutMS。HTTP/SOCKS 端口为 1024–65535，DNS 为 1–65535，避免与 8080/9090 冲突。开启 TUN 要求填写内网参数并使用 DNS 端口 53。
订阅 ID/规则 ID 为稳定随机 24 位十六进制标识；节点 ID 使用 订阅ID/提供者/原节点名，对路径参数需 URL 编码。规则 type 为 DOMAIN、DOMAIN-SUFFIX、IP-CIDR，action 为 DIRECT 或 PROXY。内网规则优先，其次自定义列表，再大陆规则，最后代理。
默认手动模式首次未选节点或所选节点移除时，代理策略选择 REJECT；不会静默选择其他节点或直连。内核停止时，校验通过的配置可暂存以供下次启动；控制接口认证或通信失败不会当成停止状态忽略。