# 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 条 |

返回结构：

```json
{"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 立即过期 |

## 调用示例

```bash
# 登录并取得 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 事件推送](websocket-events.md)
- [联机房间操作](rooms.md)
- [中继服务器与游戏目录](relay-servers.md)
- [SMTP 邮件通知](smtp-notifications.md)