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:
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user