API 参考

ServerBee 把 Web 管理面板使用的能力同时通过 REST 和 WebSocket API 暴露。最权威的 schema 级参考由服务端二进制中的 OpenAPI 注解自动生成。

Swagger UI

内置交互式文档地址：

https://your-server/swagger-ui/

你可以在 Swagger UI 中查看请求/响应模型和认证要求，并直接向自己的部署发送测试请求。原始 OpenAPI 文档地址：

https://your-server/api-docs/openapi.json

响应格式

REST 成功响应统一包装为：

{
  "data": {}
}

应用错误包含错误码和消息，还可能包含 details：

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Bad request: description of what went wrong"
  }
}

认证方式

Session Cookie

Web 管理面板登录后自动使用：

curl -X POST https://your-server/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}' \
  -c cookies.txt

curl https://your-server/api/servers -b cookies.txt

API Key

自动化场景推荐使用 API Key。Admin 可在 Settings → API Keys 创建。

curl https://your-server/api/servers \
  -H "X-API-Key: serverbee_your-api-key-here"

API Key 使用 serverbee_ 前缀，创建时只显示一次。API Key 会以所属用户的身份完成认证，它是凭据，不是独立角色。请求继承所属用户当前的 Admin 或 Member 权限。只有 Admin 可以创建新的 API Key。

Bearer Session Token

移动端流程在部分 REST 和 WebSocket 端点中使用 Bearer token：

curl https://your-server/api/auth/me \
  -H "Authorization: Bearer <session-token>"

公开端点

已认证读取端点

这些端点需要用户凭据。Admin 和 Member 都可以使用下列读取操作，以及只作用于当前账号的操作；API Key 的权限与所属用户相同。仅限 Admin 的管理端点单独列在下一节。

管理员写入和管理端点

下列管理和主机控制操作需要 Admin 权限。上一节中只作用于当前账号的操作仍可由已认证的 Member 使用。

备份端点返回原始 SQLite 下载；恢复端点接受 Content-Type: application/octet-stream 的原始 SQLite body，并要求重启 Server。两者都是仅限 Admin 的高风险操作，已验证命令与保护措施见备份与恢复。

Agent Authority 与接入

所有响应遵循统一的 { "data": ... } 包装格式。Agent Authority 管理操作需要 Admin；状态与事件历史属于已认证读取端点。

POST /api/servers —— Onboard Server

原子地创建 Server 配置及其初始绑定 offer。onboarding_request_id 必填，并按当前认证操作者隔离。使用相同 ID 和相同标准化输入重试会返回同一个 server_id；同一 ID 搭配不同输入会返回 409 ONBOARDING_IDEMPOTENCY_CONFLICT。

{
  "onboarding_request_id": "019f...",
  "name": "edge-tpe-1",
  "tags": ["production"],
  "ttl_secs": 600
}

首次执行返回 replayed: false 和 enrollment: { id, code, code_prefix, expires_at }。重放返回 replayed: true，绝不再次返回明文 code，并可能返回 outstanding_offer 元数据。

POST /api/agent/register —— Claim offer

此公开 Agent 端点使用 Authorization: Bearer <enrollment_code> 认证，并要求 Agent 自己生成 token：

{ "proposed_run_token": "<至少 32 个非空白字符>" }

成功后会消费 offer、只保存 run token 哈希，并返回 { "data": { "server_id": "..." } }。Server 永不返回明文 run token。

Agent Authority 状态与历史

• GET /api/servers/{id}/agent-authority 返回 status（claimed 或 unclaimed）以及当前 outstanding_offer（如有）。
• GET /api/agent-authority/events?server_id={id}&limit=100 返回不含密钥的状态转换历史。Server 删除后事件仍会保留。

Offer 与 authority 操作

• POST /api/servers/{id}/agent-authority/re-enrollment 携带 { "mode": "graceful" | "emergency", "ttl_secs": 600 }，为 claimed authority 开始重新接入。Graceful 保留旧 authority，emergency 立即吊销并隔离它。
• POST /api/servers/{id}/agent-authority/offers 携带可选的 { "ttl_secs": 600 }，仅在 authority 为 unclaimed 时发出 offer。
• POST /api/servers/{id}/agent-authority/offers/{offer_id}/replace 精确替换当前 outstanding offer，并仅返回一次新的明文 code。
• DELETE /api/servers/{id}/agent-authority/offers/{offer_id} 精确吊销该 offer。
• DELETE /api/servers/{id}/agent-authority 吊销当前 authority 并断开 Agent，但不生成 offer。

每个 Server 同时最多一个 outstanding offer。它的终态严格为 consumed、revoked、replaced 或 expired 之一。精确 ID 替换采用 compare-and-swap，过期页面或已进入终态的 offer 返回 409，不能覆盖更新状态。

WebSocket 端点

常见状态码