Initialize Clash Web source and deployment documentation

docs/api.md

@@ -0,0 +1,44 @@
+# 管理 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；不会静默选择其他节点或直连。内核停止时，校验通过的配置可暂存以供下次启动；控制接口认证或通信失败不会当成停止状态忽略。