feat(api-keys): add platform-scoped API keys for control-plane automation

Introduce platform API keys with capability-based access to tenant management,
system settings, runtime queues, and audit logs, plus admin UI for key lifecycle
and system audit log viewing.
This commit is contained in:
wizardchen
2026-07-21 15:05:57 +08:00
committed by lyingbug
parent c695125dce
commit 23db592c4a
42 changed files with 2967 additions and 1083 deletions
+4
View File
@@ -326,6 +326,10 @@ Wiki 模式允许 Agent 根据原始文档自动生成并维护一套结构化
- 路由级守卫会拒绝越权访问;管理类接口对 API Key Principal 默认拒绝,请为集成使用具备对应能力的 Key,而非全权 Key。
- MCP OAuth 与嵌入会话按 Principal 隔离,不同集成之间互不串号。
### 如何用一个 API Key 自动化管理多个空间?
SystemAdmin 可在 **系统管理 → 平台 API Key** 创建 `scope_type=platform` 的 Key。平台 Key 不绑定单一空间:调用普通空间 API 时必须携带 `X-Tenant-ID`,并继续受原有 capability 和知识库范围守卫约束;调用开放的系统控制面接口则需要对应的 `system_*` capability。平台 Key 不支持 `full_access`,也不能创建、轮换或吊销其他平台 Key。
## 29. 一个空间如何绑定多个对象存储实例?
0.7.0 支持**多实例存储后端**(迁移 `000068_storage_backends`)。一个空间可注册多个存储实例(`local` / `minio` / `cos` / `tos` / `s3` / `oss` / `ks3` / `obs`),不同知识库绑定到不同实例,空间维度还有一个默认实例:
+31 -2
View File
@@ -351,7 +351,7 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/tenants/10000' \
}
```
## 空间 API Key 管理(`tenant_api_keys`)
## API Key 管理(`tenant_api_keys`)
自 scoped API Key 改造后,密钥以独立记录存储,支持:
@@ -360,7 +360,36 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/tenants/10000' \
- **吊销**:`DELETE /tenants/:id/api-keys/:key_id`
- **过期**:创建时可选 `expires_at_unix`
认证上下文中的空间角色与 Key 的 `role` 一致(`viewer` / `contributor` / `admin`)。路由级 API Key 鉴权与 KB 访问守卫在 `X-API-Key` 认证后强制执行。
空间 Key 固定绑定创建时的空间。路由级 capability 鉴权与 KB 访问守卫会在 `X-API-Key` 认证后继续强制执行。
### 平台 API Key
系统管理员可在“系统管理 → 平台 API Key”创建不绑定单一空间的 Key。平台 Key 默认可以选择任意存在的空间,但每项操作仍必须具备对应 capability;平台 Key 不支持 `full_access`。
- 管理接口:`GET/POST /system/admin/api-keys`、`DELETE /system/admin/api-keys/:key_id`,仅人类 SystemAdmin 会话可调用,平台 Key 不能创建或吊销其他平台 Key。
- 调用普通空间 API 时必须同时传 `X-Tenant-ID: <空间 ID>`;服务端解析目标空间后继续复用原有空间 Context、路由 capability 和知识库范围检查。
- 调用明确开放的 `/system/admin/*` 控制面接口时不需要 `X-Tenant-ID`,需要 `system_*` capability。
- 平台 Key 明文仅在创建响应的 `data.token` 返回一次;列表仅返回脱敏值。
```bash
curl 'http://localhost:8080/api/v1/knowledge-bases' \
-H 'X-API-Key: <platform-api-key>' \
-H 'X-Tenant-ID: 10000'
```
平台 capability:
| capability | 权限 |
| --- | --- |
| `system_tenants_read` | 列出、搜索、查看全部空间 |
| `system_tenants_manage` | 创建、更新、删除空间以及应用全局空间配置 |
| `system_settings_read` | 读取系统设置 |
| `system_settings_manage` | 更新、重置系统设置 |
| `system_runtime_read` | 查看运行时队列和任务 |
| `system_runtime_manage` | 重试、立即执行、取消、删除运行时任务 |
| `system_audit_read` | 读取平台审计日志 |
平台 Key 也可以携带现有空间 capability,例如 `retrieve`、`ingest`、`manage_kbs`;这些能力作用于请求中 `X-Tenant-ID` 指定的空间。
## API Key Principal:隔离边界与安全说明
+126 -2
View File
@@ -10098,7 +10098,7 @@ const docTemplate = `{
},
{
"type": "string",
"description": "来源过滤:web / feishu / wechat / slack / ...",
"description": "来源过滤:web / embed / api / feishu / wechat / slack / ...(api、embed、IM 渠道需 Admin+)",
"name": "source",
"in": "query"
},
@@ -11545,6 +11545,105 @@ const docTemplate = `{
}
}
},
"/system/admin/api-keys": {
"get": {
"security": [
{
"Bearer": []
}
],
"description": "Lists non-workspace API keys. Full tokens are always masked. Human SystemAdmin only.",
"produces": [
"application/json"
],
"tags": [
"System Admin"
],
"summary": "List platform API keys",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"post": {
"security": [
{
"Bearer": []
}
],
"description": "Creates a capability-scoped key that may target any workspace through X-Tenant-ID. The plaintext token is returned once. Human SystemAdmin only.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"System Admin"
],
"summary": "Create a platform API key",
"parameters": [
{
"description": "Platform API key",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/internal_handler.platformAPIKeyCreateRequest"
}
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
}
},
"/system/admin/api-keys/{key_id}": {
"delete": {
"security": [
{
"Bearer": []
}
],
"description": "Immediately revokes a platform API key. Human SystemAdmin only.",
"produces": [
"application/json"
],
"tags": [
"System Admin"
],
"summary": "Revoke a platform API key",
"parameters": [
{
"type": "integer",
"description": "API key ID",
"name": "key_id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
}
},
"/system/admin/audit-log": {
"get": {
"security": [
@@ -14745,6 +14844,8 @@ const docTemplate = `{
"system.admin_promoted",
"system.admin_revoked",
"system.user_password_reset",
"system.api_key_created",
"system.api_key_revoked",
"system.queue_task_retried",
"system.queue_task_deleted",
"system.queue_task_run_now",
@@ -14771,6 +14872,8 @@ const docTemplate = `{
"AuditActionSystemAdminPromoted",
"AuditActionSystemAdminRevoked",
"AuditActionSystemUserPasswordReset",
"AuditActionSystemAPIKeyCreated",
"AuditActionSystemAPIKeyRevoked",
"AuditActionSystemQueueTaskRetried",
"AuditActionSystemQueueTaskDeleted",
"AuditActionSystemQueueTaskRunNow",
@@ -18297,6 +18400,10 @@ const docTemplate = `{
"description": "ID",
"type": "string"
},
"im_platform": {
"description": "IMPlatform is the originating IM platform (e.g. \"feishu\", \"wecom\") when\nthis session is bound to an IM channel. It is not stored on the sessions\ntable (it lives in im_channel_sessions) and is populated on read so the\nWeb console can classify a session's origin folder without a list query.",
"type": "string"
},
"is_pinned": {
"description": "IsPinned indicates whether the session is pinned in the list.",
"type": "boolean"
@@ -21473,6 +21580,23 @@ const docTemplate = `{
}
}
},
"internal_handler.platformAPIKeyCreateRequest": {
"type": "object",
"properties": {
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"expires_at_unix": {
"type": "integer"
},
"name": {
"type": "string"
}
}
},
"internal_handler.registerByInviteRequest": {
"type": "object",
"required": [
@@ -21835,7 +21959,7 @@ const docTemplate = `{
},
"securityDefinitions": {
"ApiKeyAuth": {
"description": "空间身份认证:输入 sk- 开头的 API Key",
"description": "API Key 认证:空间 Key 固定访问所属空间;平台 Key 调用空间接口时需同时传 X-Tenant-ID",
"type": "apiKey",
"name": "X-API-Key",
"in": "header"
+126 -2
View File
@@ -10091,7 +10091,7 @@
},
{
"type": "string",
"description": "来源过滤:web / feishu / wechat / slack / ...",
"description": "来源过滤:web / embed / api / feishu / wechat / slack / ...(api、embed、IM 渠道需 Admin+)",
"name": "source",
"in": "query"
},
@@ -11538,6 +11538,105 @@
}
}
},
"/system/admin/api-keys": {
"get": {
"security": [
{
"Bearer": []
}
],
"description": "Lists non-workspace API keys. Full tokens are always masked. Human SystemAdmin only.",
"produces": [
"application/json"
],
"tags": [
"System Admin"
],
"summary": "List platform API keys",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"post": {
"security": [
{
"Bearer": []
}
],
"description": "Creates a capability-scoped key that may target any workspace through X-Tenant-ID. The plaintext token is returned once. Human SystemAdmin only.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"System Admin"
],
"summary": "Create a platform API key",
"parameters": [
{
"description": "Platform API key",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/internal_handler.platformAPIKeyCreateRequest"
}
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
}
},
"/system/admin/api-keys/{key_id}": {
"delete": {
"security": [
{
"Bearer": []
}
],
"description": "Immediately revokes a platform API key. Human SystemAdmin only.",
"produces": [
"application/json"
],
"tags": [
"System Admin"
],
"summary": "Revoke a platform API key",
"parameters": [
{
"type": "integer",
"description": "API key ID",
"name": "key_id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
}
},
"/system/admin/audit-log": {
"get": {
"security": [
@@ -14738,6 +14837,8 @@
"system.admin_promoted",
"system.admin_revoked",
"system.user_password_reset",
"system.api_key_created",
"system.api_key_revoked",
"system.queue_task_retried",
"system.queue_task_deleted",
"system.queue_task_run_now",
@@ -14764,6 +14865,8 @@
"AuditActionSystemAdminPromoted",
"AuditActionSystemAdminRevoked",
"AuditActionSystemUserPasswordReset",
"AuditActionSystemAPIKeyCreated",
"AuditActionSystemAPIKeyRevoked",
"AuditActionSystemQueueTaskRetried",
"AuditActionSystemQueueTaskDeleted",
"AuditActionSystemQueueTaskRunNow",
@@ -18290,6 +18393,10 @@
"description": "ID",
"type": "string"
},
"im_platform": {
"description": "IMPlatform is the originating IM platform (e.g. \"feishu\", \"wecom\") when\nthis session is bound to an IM channel. It is not stored on the sessions\ntable (it lives in im_channel_sessions) and is populated on read so the\nWeb console can classify a session's origin folder without a list query.",
"type": "string"
},
"is_pinned": {
"description": "IsPinned indicates whether the session is pinned in the list.",
"type": "boolean"
@@ -21466,6 +21573,23 @@
}
}
},
"internal_handler.platformAPIKeyCreateRequest": {
"type": "object",
"properties": {
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"expires_at_unix": {
"type": "integer"
},
"name": {
"type": "string"
}
}
},
"internal_handler.registerByInviteRequest": {
"type": "object",
"required": [
@@ -21828,7 +21952,7 @@
},
"securityDefinitions": {
"ApiKeyAuth": {
"description": "空间身份认证:输入 sk- 开头的 API Key",
"description": "API Key 认证:空间 Key 固定访问所属空间;平台 Key 调用空间接口时需同时传 X-Tenant-ID",
"type": "apiKey",
"name": "X-API-Key",
"in": "header"
+89 -2
View File
@@ -294,6 +294,8 @@ definitions:
- system.admin_promoted
- system.admin_revoked
- system.user_password_reset
- system.api_key_created
- system.api_key_revoked
- system.queue_task_retried
- system.queue_task_deleted
- system.queue_task_run_now
@@ -320,6 +322,8 @@ definitions:
- AuditActionSystemAdminPromoted
- AuditActionSystemAdminRevoked
- AuditActionSystemUserPasswordReset
- AuditActionSystemAPIKeyCreated
- AuditActionSystemAPIKeyRevoked
- AuditActionSystemQueueTaskRetried
- AuditActionSystemQueueTaskDeleted
- AuditActionSystemQueueTaskRunNow
@@ -3060,6 +3064,13 @@ definitions:
id:
description: ID
type: string
im_platform:
description: |-
IMPlatform is the originating IM platform (e.g. "feishu", "wecom") when
this session is bound to an IM channel. It is not stored on the sessions
table (it lives in im_channel_sessions) and is populated on read so the
Web console can classify a session's origin folder without a list query.
type: string
is_pinned:
description: IsPinned indicates whether the session is pinned in the list.
type: boolean
@@ -5374,6 +5385,17 @@ definitions:
tenant_name:
type: string
type: object
internal_handler.platformAPIKeyCreateRequest:
properties:
capabilities:
items:
type: string
type: array
expires_at_unix:
type: integer
name:
type: string
type: object
internal_handler.registerByInviteRequest:
properties:
email:
@@ -12044,7 +12066,8 @@ paths:
in: query
name: keyword
type: string
- description: 来源过滤:web / feishu / wechat / slack / ...
- description: 来源过滤:web / embed / api / feishu / wechat / slack / ...(api、embed、IM
渠道需 Admin+)
in: query
name: source
type: string
@@ -12971,6 +12994,70 @@ paths:
summary: List allowed storage provider types
tags:
- StorageBackend
/system/admin/api-keys:
get:
description: Lists non-workspace API keys. Full tokens are always masked. Human
SystemAdmin only.
produces:
- application/json
responses:
"200":
description: OK
schema:
additionalProperties: true
type: object
security:
- Bearer: []
summary: List platform API keys
tags:
- System Admin
post:
consumes:
- application/json
description: Creates a capability-scoped key that may target any workspace through
X-Tenant-ID. The plaintext token is returned once. Human SystemAdmin only.
parameters:
- description: Platform API key
in: body
name: request
required: true
schema:
$ref: '#/definitions/internal_handler.platformAPIKeyCreateRequest'
produces:
- application/json
responses:
"201":
description: Created
schema:
additionalProperties: true
type: object
security:
- Bearer: []
summary: Create a platform API key
tags:
- System Admin
/system/admin/api-keys/{key_id}:
delete:
description: Immediately revokes a platform API key. Human SystemAdmin only.
parameters:
- description: API key ID
in: path
name: key_id
required: true
type: integer
produces:
- application/json
responses:
"200":
description: OK
schema:
additionalProperties: true
type: object
security:
- Bearer: []
summary: Revoke a platform API key
tags:
- System Admin
/system/admin/audit-log:
get:
description: 返回 system-scope(tenant_id=0)的审计事件,覆盖 system.setting_changed / system.admin_promoted
@@ -14827,7 +14914,7 @@ paths:
- WeKnoraCloud
securityDefinitions:
ApiKeyAuth:
description: 空间身份认证:输入 sk- 开头的 API Key
description: API Key 认证:空间 Key 固定访问所属空间;平台 Key 调用空间接口时需同时传 X-Tenant-ID
in: header
name: X-API-Key
type: apiKey