rest api

REST API 参考

所有业务接口挂在 /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	内置游戏目录（硬编码）

WebSocket 与第三方服务

接口	方法	说明
/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	当前在线第三方服务列表

SMTP 邮件通知

接口	方法	说明
/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 官方域名）

操作记录（1.5.1_1 起）

接口	方法	说明
/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）。

相关页面

• WebSocket 事件推送
• 联机房间操作
• 中继服务器与游戏目录
• SMTP 邮件通知