title	Admin API 参考
weight	5
description	HotPlex Gateway 管理 API 完整参考：Session 管理、Cron 任务、系统配置与监控端点

Admin API 完整参考

HotPlex Admin API 提供网关运维管理能力：会话管理、健康检查、监控指标、配置审计、日志查询和定时任务控制。默认监听 localhost:9999，独立于网关主端口（8888）。

认证

所有 Admin 端点（/admin/health 和 /admin/health/ready 除外）均需 Bearer Token 认证。Token 通过以下两种方式传递：

# 方式一：Authorization header（推荐）
curl -H "Authorization: Bearer <token>" http://localhost:9999/admin/stats

# 方式二：Query string（适用于浏览器场景）
curl http://localhost:9999/admin/stats?access_token=<token>

Token 使用 crypto/subtle.ConstantTimeCompare 进行常量时间比较，防止时序攻击。

Token 配置

admin:
  enabled: true
  addr: "localhost:9999"
  tokens:                          # 简单 token，使用 default_scopes
    - "my-admin-token"
  token_scopes:                    # 细粒度 scope token
    "ops-token": ["session:read", "stats:read", "health:read"]
    "admin-token": ["session:read", "session:write", "session:delete", "stats:read", "health:read", "config:read", "config:write", "admin:read", "admin:write"]
  default_scopes: ["session:read", "stats:read", "health:read"]  # 简单 token 的默认 scope

Scope 权限矩阵

不同的 Scope 控制着对 Admin API 不同模块的访问级别。

Scope Token	Health	Sessions	Stats	Config	Debug	Cron	覆盖的核心端点 (Endpoints)
`health:read`	🟢 Read	-	-	-	-	-	`/admin/health/workers`
`session:read`	-	🟢 Read	-	-	-	-	`GET /admin/sessions` `GET /admin/sessions/{id}/stats`
`session:write`	-	🟠 Write	-	-	-	-	`POST /admin/sessions/{id}/terminate`
`session:delete`	-	🔴 Delete	-	-	-	-	`DELETE /admin/sessions/{id}`
`stats:read`	-	-	🟢 Read	-	-	-	`GET /admin/stats` `GET /admin/metrics`
`config:read`	-	-	-	🟢 Read	-	-	`POST /admin/config/validate`
`config:write`	-	-	-	🟠 Write	-	-	`POST /admin/config/rollback`
`admin:read`	-	-	-	-	🟢 Read	🟢 Read	`GET /admin/logs` `GET /admin/debug/...` `GET /admin/bots` `GET /admin/cron/jobs`
`admin:write`	-	-	-	-	-	🟠 Write	`POST/PATCH/DELETE /admin/cron/jobs` `POST /admin/cron/jobs/{id}/run`

💡 图例：🟢 Read (只读查询) | 🟠 Write (状态变更/操作) | 🔴 Delete (物理删除)

安全中间件

按以下顺序执行：

CORS — Access-Control-Allow-Origin: *，允许 GET/POST/DELETE/OPTIONS
Panic Recovery — defer recover() 捕获 handler panic，返回 500 Internal Server Error
Rate Limiting — 令牌桶算法（默认 10 req/s，burst 20），超限返回 429 Too Many Requests
IP Whitelist — CIDR 匹配（默认 127.0.0.0/8, 10.0.0.0/8），使用 r.RemoteAddr 防止 X-Forwarded-For 伪造
Token Auth — Bearer Token 提取 + scope 校验

Rate Limit 和 IP Whitelist 支持配置热重载，无需重启生效。

端点总览

健康检查

方法	路径	Scope	说明
GET	`/admin/health`	无需认证	综合健康状态（gateway + DB + workers）
GET	`/admin/health/workers`	`health:read`	Worker 粒度健康状态
GET	`/admin/health/ready`	无需认证	就绪探针（k8s readiness）

GET /admin/health — 无需认证，适合负载均衡器探活。返回 status（healthy/degraded）、checks（gateway + database + workers）和 version。数据库不可用时降级为 degraded，database.error 附带错误信息。

GET /admin/health/workers — Worker 粒度健康状态，含 workers[]（healthy/type/pid）和 checked_at。任一 Worker 不健康时返回 503。

会话管理

方法	路径	Scope	说明
GET	`/admin/sessions`	`session:read`	列出会话（分页）
GET	`/admin/sessions/{id}`	`session:read`	获取单个会话
DELETE	`/admin/sessions/{id}`	`session:delete`	物理删除会话
POST	`/admin/sessions/{id}/terminate`	`session:write`	终止会话（状态迁移）
GET	`/admin/sessions/{id}/stats`	`session:read`	会话 Turn 统计

GET /admin/sessions — 支持 query 参数过滤：

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9999/admin/sessions?limit=50&offset=0&platform=slack&user_id=U12345"

参数	类型	默认值	说明
`limit`	int	100	每页数量
`offset`	int	0	偏移量
`platform`	string	""	按平台过滤
`user_id`	string	""	按用户过滤

POST /admin/sessions/{id}/terminate — 将会话状态迁移至 terminated（软终止，保留记录）。DELETE 则为物理删除。

注意：会话创建不通过 Admin API，而是通过 Gateway API（POST /api/sessions）或 WebSocket init 握手完成。Admin API 仅提供只读查询和终止/删除操作。

监控指标

方法	路径	Scope	说明
GET	`/admin/stats`	`stats:read`	网关聚合统计
GET	`/admin/metrics`	`stats:read`	Prometheus 格式指标

GET /admin/stats — 返回 gateway（uptime/websocket_connections/sessions_active/sessions_total）、workers（按 worker_type 分组统计）和 database（sessions_count/db_size_mb）。

配置管理

方法	路径	Scope	说明
POST	`/admin/config/validate`	`config:read`	校验配置片段
POST	`/admin/config/rollback`	`config:write`	回滚到历史版本

POST /admin/config/validate — 校验配置合法性（不应用），请求体最大 1MB：

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"gateway":{"addr":":8888"},"pool":{"max_size":50}}' \
  http://localhost:9999/admin/config/validate

支持校验：gateway（buffer sizes >= 0）、db（path 长度 <= 4096）、worker（timeouts）、pool（max_size 1-10000）。返回 { "valid", "errors[]", "warnings[]" }。

POST /admin/config/rollback — 回滚到指定版本，请求体 {"version": 3}，返回 { "ok", "rolled_back", "history_index" }。无 configWatcher 时返回 503。

日志与调试

方法	路径	Scope	说明
GET	`/admin/logs`	`admin:read`	最近日志（环形缓冲区）
GET	`/admin/debug/sessions/{id}`	`admin:read`	会话调试快照

GET /admin/logs — 从 100 条环形缓冲区读取，?limit=N（最大 1000）。返回 { "logs[]", "total", "limit" }。

GET /admin/debug/sessions/{id} — 会话详情 + 调试快照（debug.available、has_worker、turn_count、last_seq_sent、worker_health）。

Cron 定时任务

方法	路径	Scope	说明
GET	`/admin/cron/jobs`	`admin:read`	列出所有任务
GET	`/admin/cron/jobs/{id}`	`admin:read`	获取单个任务
POST	`/admin/cron/jobs`	`admin:write`	创建任务
PATCH	`/admin/cron/jobs/{id}`	`admin:write`	更新任务
DELETE	`/admin/cron/jobs/{id}`	`admin:write`	删除任务
POST	`/admin/cron/jobs/{id}/run`	`admin:write`	手动触发执行
GET	`/admin/cron/jobs/{id}/runs`	`admin:read`	执行历史

Cron 未启用时返回 503 Service Unavailable。

Bot 管理

Bot 状态查询、配置管理和 Agent 配置文件操作端点。

方法	路径	Scope	说明
GET	`/admin/bots`	`admin:read`	列出所有活跃 bot
GET	`/admin/bots/{name}`	`admin:read`	单个 bot 详情
POST	`/admin/bots`	`admin:write`	注册新 bot
PATCH	`/admin/bots/{name}`	`admin:write`	更新 bot 配置（部分更新）
DELETE	`/admin/bots/{name}`	`admin:write`	删除 bot 注册
GET	`/admin/bots/config`	`admin:read`	列出所有 bot 配置
GET	`/admin/bots/{name}/config`	`admin:read`	单个 bot 完整配置
GET	`/admin/bots/{name}/config/{file}`	`admin:read`	读取 Agent 配置文件（如 SOUL.md、AGENTS.md）
PUT	`/admin/bots/{name}/config/{file}`	`admin:write`	写入 Agent 配置文件
GET	`/admin/bots/{name}/preview`	`admin:read`	预览组装后的系统提示（B+C 通道完整输出）

GET /admin/bots — 返回所有活跃 bot 列表，含 name、platform、worker_type、状态等信息。

POST /admin/bots — 注册新 bot，JSON body 含平台凭证和配置。返回 201 Created。

PATCH /admin/bots/{name} — 部分更新 bot 配置（凭证、worker_type 等）。返回 204 No Content。

GET /admin/bots/{name}/preview — 返回该 bot 组装后的完整系统提示，包含 B 通道（directives）和 C 通道（context）内容，便于调试 Agent 人格配置。

**PUT /admin/bots/{name}/config/{file}** — 写入指定 Agent 配置文件（如 SOUL.md、AGENTS.md、USER.md）。请求体为文件内容，Content-Type 为 text/plain`。

网关重启

方法	路径	Scope	说明
POST	`/admin/restart`	`admin:write`	触发网关重启

POST /admin/restart — 异步触发网关重启。Gateway 在 500ms 延迟后执行重启，立即返回 { "status": "restarting" }。使用 restart helper（独立 PGID）确保安全隔离。未配置 restart handler 时返回 503。

API Key 用户管理

管理 API Key 到用户身份的映射，用于企业级多用户 Session 隔离。需要数据库支持（SQLite），未配置 DB resolver 时返回 501 Not Implemented。

方法	路径	Scope	说明
GET	`/admin/api-keys`	`admin:read`	列出所有 API Key 映射
POST	`/admin/api-keys`	`admin:write`	创建 API Key 映射
GET	`/admin/api-keys/{id}`	`admin:read`	获取单个映射详情
PATCH	`/admin/api-keys/{id}`	`admin:write`	更新映射
DELETE	`/admin/api-keys/{id}`	`admin:write`	删除映射

POST /admin/api-keys — 创建 API Key → UserID 映射。JSON body 含 user_id（必填，最长 128 字符）和 description（可选，最长 512 字符）。API Key 由系统自动生成（32 字节随机 hex）。返回 201 Created。

GET /admin/api-keys — 返回所有映射列表，api_key 字段自动脱敏（仅显示前 8 + 后 4 位）。

**PATCH /admin/api-keys/{id}** — 更新指定映射的 user_id和description`。

DELETE /admin/api-keys/{id}` — 物理删除映射，同时清除缓存的 resolver 条目。

Gateway API 端点

Gateway API（/api/sessions）监听在网关主端口（8888），面向客户端 SDK 和 WebSocket 连接，使用 API Key 认证（非 Bearer Token）。

方法	路径	认证	说明
GET	`/api/sessions`	API Key	列出当前用户的会话
POST	`/api/sessions`	API Key	创建会话
GET	`/api/sessions/{id}`	API Key	获取单个会话
DELETE	`/api/sessions/{id}`	API Key	删除会话
POST	`/api/sessions/{id}/cd`	API Key	切换工作目录
GET	`/api/sessions/{id}/history`	API Key	获取会话历史
GET	`/api/sessions/{id}/events`	API Key	获取会话事件流

所有 Gateway API 端点启用 CORS（Access-Control-Allow-Origin: *），支持 GET、POST、DELETE、OPTIONS 方法。

POST /admin/cron/jobs — JSON body 含 name、schedule（cron:/every:/at: 前缀）、message、bot_id、owner_id、enabled。返回 201 Created。

PATCH /admin/cron/jobs/{id} — 部分更新，JSON body。返回 204 No Content。

POST /admin/cron/jobs/{id}/run — 手动触发（异步），返回 202 Accepted。

GET /admin/cron/jobs/{id}/runs — 查询执行历史。

错误响应格式

所有错误使用纯文本响应（text/plain），非 JSON：

状态码	含义	典型场景
400	请求无效	JSON 解析失败、参数校验错误
401	未认证	Token 缺失或无效
403	权限不足	Scope 不满足
404	资源不存在	Session/Cron Job 未找到
429	请求过频	触发 Rate Limit
500	内部错误	Handler panic、服务不可用
503	服务不可用	数据库故障、Cron 未启用

常用操作示例

# 快速健康检查（无需 Token）
curl http://localhost:9999/admin/health

# 查看活跃会话
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:9999/admin/sessions?limit=10

# 查看 Prometheus 指标
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:9999/admin/metrics

# 终止异常会话
curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:9999/admin/sessions/abc-123/terminate

# 查看最近日志
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9999/admin/logs?limit=20"

# 调试特定会话
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:9999/admin/debug/sessions/abc-123

# 触发 Cron 任务
curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:9999/admin/cron/jobs/daily-health/run

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Admin API 完整参考

认证

Token 配置

Scope 权限矩阵

安全中间件

端点总览

健康检查

会话管理

监控指标

配置管理

日志与调试

Cron 定时任务

Bot 管理

网关重启

API Key 用户管理

Gateway API 端点

错误响应格式

常用操作示例

FilesExpand file tree

admin-api.md

Latest commit

History

admin-api.md

File metadata and controls

Admin API 完整参考

认证

Token 配置

Scope 权限矩阵

安全中间件

端点总览

健康检查

会话管理

监控指标

配置管理

日志与调试

Cron 定时任务

Bot 管理

网关重启

API Key 用户管理

Gateway API 端点

错误响应格式

常用操作示例