# API 参考 > ServerBee REST API 概览、认证方式、WebSocket 端点和 Swagger UI 交互式文档。 URL: https://docs.serverbee.app/zh/docs/api-reference ServerBee 把 Web 管理面板使用的能力同时通过 REST 和 WebSocket API 暴露。最权威的 schema 级参考由服务端二进制中的 OpenAPI 注解自动生成。 ## Swagger UI [#swagger-ui] 内置交互式文档地址： ```text https://your-server/swagger-ui/ ``` 你可以在 Swagger UI 中查看请求/响应模型和认证要求，并直接向自己的部署发送测试请求。原始 OpenAPI 文档地址： ```text https://your-server/api-docs/openapi.json ``` ## 响应格式 [#响应格式] REST 成功响应统一包装为： ```json { "data": {} } ``` 应用错误包含错误码和消息，还可能包含 `details`： ```json { "error": { "code": "BAD_REQUEST", "message": "Bad request: description of what went wrong" } } ``` ## 认证方式 [#认证方式] ### Session Cookie [#session-cookie] Web 管理面板登录后自动使用： ```bash 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] 自动化场景推荐使用 API Key。Admin 可在 Settings → API Keys 创建。 ```bash 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 [#bearer-session-token] 移动端流程在部分 REST 和 WebSocket 端点中使用 Bearer token： ```bash curl https://your-server/api/auth/me \ -H "Authorization: Bearer " ``` ## 公开端点 [#公开端点] | 方法 | 路径 | 说明 | | ---- | -------------------------------------------------- | -------------------------------------------------- | | POST | `/api/auth/login` | Web 登录 | | GET | `/api/auth/oauth/providers` | 列出已启用的 OAuth Provider | | GET | `/api/auth/oauth/{provider}` | OAuth 授权跳转 | | GET | `/api/auth/oauth/{provider}/callback` | OAuth 回调 | | POST | `/api/mobile/auth/login` | 移动端登录 | | POST | `/api/mobile/auth/refresh` | 刷新移动端会话 | | POST | `/api/mobile/auth/pair` | 兑换移动端配对码 | | POST | `/api/agent/register` | 使用 Agent 提议的 run token claim 已绑定的 enrollment offer | | GET | `/api/status/config` | 公开状态页配置 | | GET | `/api/status` | 公开状态页包含的服务器 | | GET | `/api/status/servers/{id}` | 已公开服务器的详情 | | GET | `/api/status/servers/{id}/metrics` | 已公开服务器的指标 | | GET | `/api/status/servers/{id}/uptime-daily` | 已公开服务器的每日可用性 | | GET | `/api/status/network`、`/api/status/network/{id}` | 公开网络概览和单台服务器详情 | | GET | `/api/status/ip-quality` | 公开 IP 质量概览 | | GET | `/api/status/incidents`、`/api/status/maintenances` | 公开事件公告和维护窗口 | | GET | `/api/settings/brand` | 公开品牌设置 | | GET | `/api/brand/logo` | 返回上传的 Logo | | GET | `/api/brand/favicon` | 返回上传的 Favicon | ## 已认证读取端点 [#已认证读取端点] 这些端点需要用户凭据。Admin 和 Member 都可以使用下列读取操作，以及只作用于当前账号的操作；API Key 的权限与所属用户相同。仅限 Admin 的管理端点单独列在下一节。 | 端点族 | 代表端点 | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 当前用户和凭据 | `GET /api/auth/me`、`PUT /api/auth/password`、`GET /api/auth/api-keys`、`DELETE /api/auth/api-keys/{id}` | | 2FA 和 OAuth 账号 | `/api/auth/2fa/*`、`GET/DELETE /api/auth/oauth/accounts/*` | | 移动端会话和设备 | `POST /api/mobile/auth/logout`、`GET /api/mobile/auth/devices`、`DELETE /api/mobile/auth/devices/{id}`、`POST /api/mobile/pair`、`POST /api/mobile/push/register`、`POST /api/mobile/push/unregister` | | 服务器 | `GET /api/servers`、`GET /api/servers/{id}`、`GET /api/servers/{id}/records`、`GET /api/servers/{id}/gpu-records` | | Agent Authority | `GET /api/servers/{id}/agent-authority`、`GET /api/agent-authority/events?server_id={id}` | | 分组和标签 | `GET /api/server-groups`、`GET /api/servers/{id}/tags` | | 可用性和流量 | `GET /api/servers/{id}/uptime-daily`、`GET /api/servers/{id}/traffic` | | GeoIP | `GET /api/geoip/status` | | Ping 任务 | `GET /api/ping-tasks`、`GET /api/ping-tasks/{id}/records` | | 网络探测 | `GET /api/network-probes/targets`、`GET /api/network-probes/setting`、`GET /api/network-probes/overview`、`GET /api/servers/{id}/network-probes/targets`、`GET /api/servers/{id}/network-probes/records`、`GET /api/servers/{id}/network-probes/summary`、`GET /api/servers/{id}/network-probes/anomalies` | | Traceroute 结果 | `GET /api/servers/{id}/traceroute/{request_id}` | | Docker 读取 | `GET /api/servers/{id}/docker/containers`、`stats`、`info`、`events`、`networks`、`volumes` | | 服务监控 | `GET /api/service-monitors`、`GET /api/service-monitors/{id}`、`GET /api/service-monitors/{id}/records` | | 状态页配置 | `GET /api/status-page` | | 仪表盘 | `GET /api/dashboards`、`GET /api/dashboards/default`、`GET /api/dashboards/{id}` | | 成本洞察 | `GET /api/cost/overview`、`GET /api/servers/{id}/cost-insights` | | 告警事件 | `GET /api/alert-events`、`GET /api/alert-events/{alert_key}` | ## 管理员写入和管理端点 [#管理员写入和管理端点] 下列管理和主机控制操作需要 Admin 权限。上一节中只作用于当前账号的操作仍可由已认证的 Member 使用。 | 端点族 | 代表端点 | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 创建 API Key | `POST /api/auth/api-keys` | | 服务器管理 | `POST /api/servers`（幂等 onboarding）、`PUT/DELETE /api/servers/{id}`、`POST /api/servers/{id}/upgrade` | | Agent Authority | `/api/servers/{id}/agent-authority/*` 下的重新接入、offer 发出/替换/吊销及 authority 吊销 | | 分组和标签 | `POST /api/server-groups`、`PUT/DELETE /api/server-groups/{id}`、`PUT /api/servers/{id}/tags` | | Ping 和网络探测 | `POST /api/ping-tasks`、`PUT/DELETE /api/ping-tasks/{id}`、`POST /api/network-probes/targets`、`PUT/DELETE /api/network-probes/targets/{id}`、`PUT /api/network-probes/setting`、`PUT /api/servers/{id}/network-probes/targets` | | Traceroute | `POST /api/servers/{id}/traceroute` | | 文件管理 | 所有 `/api/files/*` 端点，包括列目录、获取元数据、读取、下载、传输管理和文件修改 | | Docker 操作 | `POST /api/servers/{id}/docker/containers/{cid}/action` | | 服务监控 | `POST /api/service-monitors`、`PUT/DELETE /api/service-monitors/{id}`、`POST /api/service-monitors/{id}/check` | | 仪表盘 | `POST /api/dashboards`、`PUT/DELETE /api/dashboards/{id}` | | 品牌外观 | `PUT /api/settings/brand`、`POST /api/settings/brand/logo`、`POST /api/settings/brand/favicon` | | 状态页 | `PUT /api/status-page` | | 事件公告 | `GET/POST /api/incidents`、`PUT/DELETE /api/incidents/{id}`、`POST /api/incidents/{id}/updates` | | 维护窗口 | `GET/POST /api/maintenances`、`PUT/DELETE /api/maintenances/{id}` | | 告警和通知 | 管理 `/api/alert-rules`、`/api/notifications`、`/api/notification-groups` 及其 `/{id}` 路由 | | 任务 | `GET/POST /api/tasks`、`GET/PUT/DELETE /api/tasks/{id}`、`GET /api/tasks/{id}/results`、`POST /api/tasks/{id}/run` | | 用户 | `GET/POST /api/users`、`GET/PUT/DELETE /api/users/{id}` | | 审计和设置 | `GET/DELETE /api/audit-logs`、`GET/PUT /api/settings`、`POST /api/settings/backup`、`POST /api/settings/restore` | | GeoIP | `POST /api/geoip/download` | 备份端点返回原始 SQLite 下载；恢复端点接受 `Content-Type: application/octet-stream` 的原始 SQLite body，并要求重启 Server。两者都是仅限 Admin 的高风险操作，已验证命令与保护措施见[备份与恢复](/zh/docs/deployment#备份与恢复)。 ## Agent Authority 与接入 [#agent-authority-与接入] 所有响应遵循统一的 `{ "data": ... }` 包装格式。Agent Authority 管理操作需要 Admin；状态与事件历史属于已认证读取端点。 ### `POST /api/servers` —— Onboard Server [#post-apiservers--onboard-server] 原子地创建 Server 配置及其初始绑定 offer。`onboarding_request_id` 必填，并按当前认证操作者隔离。使用相同 ID 和相同标准化输入重试会返回同一个 `server_id`；同一 ID 搭配不同输入会返回 `409 ONBOARDING_IDEMPOTENCY_CONFLICT`。 ```json { "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 [#post-apiagentregister--claim-offer] 此公开 Agent 端点使用 `Authorization: Bearer ` 认证，并要求 Agent 自己生成 token： ```json { "proposed_run_token": "<至少 32 个非空白字符>" } ``` 成功后会消费 offer、只保存 run token 哈希，并返回 `{ "data": { "server_id": "..." } }`。Server 永不返回明文 run token。 ### Agent Authority 状态与历史 [#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 操作 [#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 端点 [#websocket-端点] | 路径 | 认证 | 说明 | | --------------------------------- | ----------------------------------------- | ------------------------------------- | | `/api/agent/ws` | Agent Bearer token（兼容旧 Agent 的 `?token=`） | Agent 指标、命令、Ping、文件、Docker、Traceroute | | `/api/ws/servers` | Session cookie、API Key 或 Bearer token | 浏览器/移动端实时服务器更新 | | `/api/ws/terminal/{server_id}` | 已认证 Admin + `CAP_TERMINAL` | Web 终端代理；JSON 文本消息，终端数据 base64 编码 | | `/api/ws/docker/logs/{server_id}` | 已认证 Admin + `CAP_DOCKER` | 按容器流式传输 Docker 日志 | ## 常见状态码 [#常见状态码] | 状态码 | 含义 | | --- | ---------------------------------- | | 400 | 请求错误或操作无效 | | 401 | 未认证 | | 403 | 无权限：角色、capability 或 Agent 本地策略阻止操作 | | 404 | 资源不存在、服务器离线或公开页面已禁用 | | 409 | 冲突，例如 slug/name 重复 | | 422 | 参数校验失败 | | 429 | 请求过于频繁 | | 500 | 服务器内部错误 |