管理 API 参考

管理路由挂载在 /api/v1/admin 下，覆盖仪表盘、观测、审计日志、会话、用户、角色、权限、站点设置、模型、SSO、通知、团队、记忆、Agent、工具、Skills、工作流、工作流指标、TOTP、包管理、知识库和消息投递。它们由管理后台使用，响应遵循统一的 code/data/msg 结构，不是面向匿名调用的公共 API。

权限模型

每个端点通过依赖声明所需的权限码（admin:* 或 audit:*）：

• 超级管理员直接放行：拥有 is_superuser 的账号跳过所有权限码校验。
• 其他调用者按权限码判定：账号必须通过角色持有该端点声明的权限码。权限码由启动时同步的系统权限定义管理，可在角色中自由组合（见 /api/v1/admin/roles、/api/v1/admin/permissions）。
• API Key 同权校验：API Key 按其绑定用户的权限集合校验，因此不要给 API Key 授予不必要的 admin:* 权限。
• 知识库分组是例外：/api/v1/admin/knowledge-bases 复用平台知识库路由，但会按请求路径前缀把权限码切换为 admin:knowledge-base:{read,test,create,update,delete}，并跳过团队成员校验，使管理视图可以跨团队读取和修改知识库。

分组与权限码

常用端点

工作流指标

工作流执行指标不在 /api/v1/workflows 下，而在管理前缀下的 /api/v1/admin/workflows/metrics/*。其路由自带 /workflows/metrics 前缀，因此与管理工作流的 /api/v1/admin/workflows CRUD 共存而不冲突。

curl -X GET "https://your-domain.com/api/v1/admin/workflows/metrics/dashboard" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

消息投递日志

GET /api/v1/admin/deliveries 读取飞书与微信 Agent 会话共用的持久化出站队列 integration_deliveries。它是只读端点，需要 admin:integrations:settings:read，超级管理员绕过检查；消息正文、平台资源键（media_key）、凭据和文件内容都不会返回。管理后台的监控 > 投递记录（/deliveries）页面使用同一端点。

sent 只表示平台接受了回复请求，不代表接收人已读、打开了卡片或下载了附件。

查询参数

provider_type 内部 OR、status 内部 OR，两组之间 AND。响应为 {items, total, limit, offset}，按 created_at、id 倒序。

curl -X GET "https://your-domain.com/api/v1/admin/deliveries?provider_type=feishu&provider_type=wechat&status=error&status=unknown&limit=25&offset=0" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "provider_type": "feishu",
        "run_id": "1c2f1a2e-0f4e-4a8f-9d4a-2b0d7b3dcb6d",
        "user_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "chat_id": "oc_xxx",
        "message_id": "om_xxx",
        "event_key": "final-asset",
        "sequence": 0,
        "kind": "asset",
        "filename": "report.pdf",
        "content_type": "application/pdf",
        "size": 12345,
        "media_type": "file",
        "status": "error",
        "error": "feishu_agent_asset_upload_failed",
        "error_detail": "FeishuAPIError: Feishu API error 234001: Invalid request param. | HTTP 400 | code 234001 | {...}",
        "has_media_key": false,
        "created_at": "2026-10-22T10:03:13Z",
        "updated_at": "2026-10-22T10:03:13Z"
      }
    ],
    "total": 1,
    "limit": 25,
    "offset": 0
  },
  "msg": "success"
}

状态

字段与错误

error 是稳定的机器可读键（如 feishu_agent_asset_upload_failed）；error_detail 保留平台返回的原文、HTTP 状态与错误码，便于定位权限、参数或大小问题。

升级关系

单表 integration_deliveries 取代旧的 feishu_agent_deliveries 与 wechat_agent_deliveries。首次启动时 API 复制旧表数据并删除旧表，因此 API、所有 worker 与 Beat 必须部署到匹配版本：旧进程会向已删除的表写入。仅回滚应用镜像无法重建队列表；回滚必须使用升级前的数据库备份。

页面行为、筛选与排障建议见投递记录。

调用示例

curl -X GET "https://your-domain.com/api/v1/admin/users?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

集成建议

• 第三方应用优先使用 Agent、工作流、会话和知识库资源端点，而不是管理端点。
• 管理自动化必须固定 Clouisle 版本，记录所需权限码，并在升级前检查 OpenAPI Schema。
• 审计和用户管理操作包含敏感数据，应使用短期密钥并配合最小限速。
• 只有确实需要跨团队运维时才授予 admin:*；日常使用应通过团队角色授予平台权限（如 workflow:read、kb:read）。

常见错误

Last Updated: 2026-09-26