Admin API
读者：需要批量运维或脚本化操作 Master 的技术人员。
Admin API 供 Master 运维面使用：管理租户、主机、逻辑节点、协议目录、审计等。路径前缀 /api/v1/admin/，认证为 AdminBearer（控制台登录签发或长期 Admin Token）。
业务用户操作请用 Adapter API，勿混用。
Authorization: Bearer <admin_token>常见 Scope（节选）：
| Scope | 能力 |
|---|---|
hosts:rw | 主机 CRUD、装机 |
tenants:rw | 租户与 Token |
logical_nodes:rw | 逻辑节点与同步触发 |
audit:r | 审计只读 |
events:admin | 事件管理 |
绑定 tenant_id 的账号（tenant_admin）调用租户相关 API 时自动过滤数据范围。
2. 常用端点（节选）
Section titled “2. 常用端点（节选）”常用路径如下（完整列表以你方 Master 版本为准）：
| 领域 | 示例路径 |
|---|---|
| 租户 | GET/POST /api/v1/admin/tenants |
| Token | POST /api/v1/admin/tenants/{id}/tokens |
| 主机 | GET/POST /api/v1/admin/hosts |
| SSH 凭证 | GET/POST /api/v1/admin/ssh-credentials |
| 逻辑节点 | GET/POST /api/v1/admin/logical-nodes |
| 同步 | POST /api/v1/admin/logical-nodes/{id}/sync |
| 协议目录 | GET /api/v1/admin/protocol-catalog |
| 设置 | GET/PATCH /api/v1/admin/settings |
| 审计 | GET /api/v1/admin/audit |
WebSSH 终端使用独立路径（避免 admin 中间件与 query token 冲突），一般为 GET /api/v1/admin/hosts/{id}/terminal（WebSocket）。
3. 使用示例
Section titled “3. 使用示例”列出主机：
curl -sS -H "Authorization: Bearer $ADMIN_TOKEN" \ "https://master.example.com/api/v1/admin/hosts"触发逻辑节点同步：
curl -sS -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \ "https://master.example.com/api/v1/admin/logical-nodes/hk-reality/sync"4. 错误响应
Section titled “4. 错误响应”失败时响应体常见字段：error、message、request_id（便于联系支持时提供）。
5. 注意事项
Section titled “5. 注意事项”- Admin Token 权限大，勿泄露给他人
- 写操作记入 审计日志
- 批量脚本注意速率，避免与在线运维争用数据库连接
6. 常见问题
Section titled “6. 常见问题”Q：能用 Admin API 创建终端用户吗？
A：应使用 Adapter /api/v1/users；Admin 用户 API 若有，也仅适合超管补救。
Q：401 但 Token 刚签发？
A：检查时钟偏差；Scope 是否包含路径所需权限。