所有业务接口挂在 /api 下。除登录 / 登出与第三方 WebSocket 服务端点外，统一经过鉴权中间件。
| 方式 |
适用场景 |
说明 |
| Cookie 会话 |
浏览器面板 |
登录成功下发的 astral_session Cookie（HttpOnly + SameSite=Lax）；服务重启后所有会话失效 |
| HTTP Basic Auth |
curl / 外部脚本 |
Authorization: Basic base64(username:password)，用户名不允许含 :
|
未配置用户名（username 为空）时关闭鉴权；配置后任一方式通过即可访问。未通过鉴权返回 401 {"error":"unauthorized"}。
| 接口 |
方法 |
说明 |
/api/status |
GET |
节点状态快照（前端 3 秒轮询一次） |
/api/logs?tail=N |
GET |
节点环形日志，默认 200 条、上限 800 条 |
/api/profile |
GET |
资料 / 网络 / 守护进程设置（头像以 base64 内联返回） |
/api/profile |
PUT |
更新上述设置并写回 config.toml
|
/api/config |
GET |
返回 config.toml 原文及路径 |
/api/config |
PUT |
保存配置文件（restart=true 时保存后立即重启实例） |
/api/start |
POST |
启动（重启）EasyTier 实例，可携带完整 TOML 文本 |
/api/stop |
POST |
停止当前实例 |
/api/restart |
POST |
用最近一次配置重启实例 |
| 接口 |
方法 |
说明 |
/api/credentials |
GET |
列出全部凭据 |
/api/credentials |
POST |
生成凭据，请求体：ttl_seconds（有效期秒数）、reusable（是否可复用，缺省 true） |
/api/credentials/:id |
DELETE |
撤销指定凭据 |
| 接口 |
方法 |
说明 |
/api/room/create |
POST |
创建房间，请求体：game_id、game_name、display_name（可选） |
/api/room/join |
POST |
加入房间，请求体：input（短码 / 完整链接 / AG1. 离线串） |
/api/room/leave |
POST |
离开房间（停止实例、清空当前房间、广播 room.left） |
/api/room/current |
GET |
当前房间与分享链接（无房间时 room 为 null） |
| 接口 |
方法 |
说明 |
/api/servers |
GET |
全部中继服务器（含启用状态、排序） |
/api/servers |
POST |
新增服务器，请求体：name、uri（如 tcp://1.2.3.4:11010），默认启用 |
/api/servers/ping |
GET |
并发测速所有服务器，返回 TCP 连接耗时（毫秒；失败 / 超时返回 -1） |
/api/servers/:id |
PUT |
按 id 修改服务器（name / uri / enabled 均可选） |
/api/servers/:id |
DELETE |
按 id 删除服务器 |
/api/games |
GET |
内置游戏目录（硬编码） |
| 接口 |
方法 |
说明 |
/api/ws |
GET |
面板端 WebSocket 升级（鉴权与 REST 一致） |
/api/ws/service |
GET |
第三方服务 WebSocket 升级（ws_key 密钥鉴权，免面板登录） |
/api/ws/key |
GET |
查看当前第三方服务连接密钥 |
/api/ws/key/rotate |
POST |
刷新密钥（旧密钥立即失效，已连接服务被断开） |
/api/ws/services |
GET |
当前在线第三方服务列表 |
| 接口 |
方法 |
说明 |
/api/smtp |
GET |
SMTP 配置摘要（密码不回传，仅返回 password_set） |
/api/smtp/recipients |
PUT |
更新收件人邮箱列表（全量覆盖；自动去重并校验格式） |
/api/smtp/test |
POST |
发送测试邮件验证 SMTP 配置 |
/api/smtp/send-now |
POST |
一键发送当前房间详情邮件给所有收件人 |
| 接口 |
方法 |
说明 |
/api/update/check |
GET |
检查 GitHub 最新发行版（返回当前 / 最新版本与更新状态） |
/api/update/apply |
POST |
下载指定版本并替换自身二进制后重启，请求体：download_url（仅允许 GitHub 官方域名） |
| 接口 |
方法 |
说明 |
/api/audit-logs?tail=N |
GET |
最近 N 条操作记录（默认 100，上限 500，新→旧排列）；保留最近 14 天、上限 2000 条 |
返回结构：
{"logs": [{"ts": 1792059565, "kind": "login", "action": "登录成功", "ip": "192.168.1.10"}]}kind 取值：login（登录成功）、login_failed（登录失败）、logout（登出）、
modify（修改操作）、modify_denied（未授权的非 GET 请求尝试）。
第三方 WS 控制指令的 action 带「第三方服务指令：」前缀。
| 接口 |
方法 |
说明 |
/api/auth/login |
POST |
校验账密，成功下发 HttpOnly Cookie 会话 |
/api/auth/logout |
POST |
删除内存会话并使 Cookie 立即过期 |
# 登录并取得 Cookie（保存到本地文件）
curl -c cookies.txt -X POST http://<服务器>:8080/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"yourpass"}'
# 用 Cookie 获取节点状态
curl -b cookies.txt http://<服务器>:8080/api/status
# 或使用 Basic Auth 直接调用（无需先登录）
curl -u admin:password http://<服务器>:8080/api/room/current
curl -u admin:password -X POST http://<服务器>:8080/api/room/leave
curl -u admin:password -X POST http://<服务器>:8080/api/smtp/test错误响应统一为 {"error": "..."} 并携带对应 HTTP 状态码（如 400、401、404、502、504）。