2026-08-06 10:22:10 +00:00
|
|
|
|
# API 参考:系统与平台管理
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
提供部署级系统信息和平台管理接口,包括全局设置、任务队列、平台 API Key、跨空间审计和用户密码重置。功能说明见[平台管理与系统管理员](../03-features/20-platform-admin.md)。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
`/system/admin/*` 全组挂 `SystemAdmin()` 守卫;平台 API Key 按能力细分(`system_settings_read/manage`、`system_runtime_read/manage`、`system_tenants_read/manage`、`system_audit_read`)。
|
|
|
|
|
|
|
|
|
|
|
|
## 系统信息(/api/v1/system)
|
|
|
|
|
|
|
|
|
|
|
|
Handler: `internal/handler/system.go`。API key:`manage_vector_stores`/full。本组响应使用 `{"code":0,"msg":"success","data":...}` 包装。
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
### GET /api/v1/system/capabilities
|
|
|
|
|
|
|
|
|
|
|
|
Viewer+;API Key 可读。返回 `{code:0,data:{edition,capabilities}}`,每个 capability 给出 supported/reason。前端据部署版本、实际注册路由和 Docker 开关控制菜单入口;隐藏菜单不代替后端权限校验。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/system/capabilities" -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
docs: sync website-docs, homepage and changelog for v0.8.2 (#3632)
* docs: sync website-docs with changes since v0.8.0
Audit every change between v0.8.0 and the v0.8.2 release against the
documentation site, adding what users and operators need and correcting
statements that no longer match the code.
- Add local browser (BrowserSkill), built-in MCP Server endpoints, the
toolbox, conversation steer/fork/rewind and reasoning effort, the
artifacts library, sandbox terminal and desktop, the Lite host sandbox,
the rebuilt model catalog (including a protocol-compat field reference),
Confluence and DingTalk Docs sources, Bocha/Serply search, per-channel IM
locale, whitelist-only outbound, admin user creation, new configuration
variables and migrations 000091-000110.
- Fix wrong API examples and parameters (model type values, knowledge
search params, FAQ match_count cap, Notion credentials), tenant deletion
semantics, default timeouts, parser engine claims, removed tables and
commands, stale navigation paths, and route locations after the router
split into routes_*.go.
- Add screenshots for the new pages and refresh outdated ones.
* fix(frontend): link the protocol-compat field to its documentation
The model editor told users to read catalog/compat.go on the backend, a
path that no longer exists after the model catalog refactor. The hint now
says when the override is needed and links to the field reference in
website-docs/03-features/06-models.md; the config examples and the API
type comment point to the same place.
* feat(website): showcase v0.8.2 on the homepage
- Add a v0.8.2 section for the local browser (BrowserSkill), the built-in
MCP Server and conversation control, and turn the v0.8.0 release block
into a standing skills & sandbox topic with the sandbox desktop and
terminal.
- Replace the three-up galleries with a feature list beside one large
screenshot: every item's text stays visible, clicking an item or one of
its views switches the image with a cross-fade, and the list plays itself
while on screen until the visitor picks something.
- Add Confluence, DingTalk, BrowserSkill and more model vendors to the
integrations, bump the header badge to v0.8.2 and link the changelog.
- check-site reports missing docs screenshots as pending instead of
failing, since the Screenshot component renders a placeholder for them.
* docs(changelog): add v0.8.2 release notes
* docs(website): add per-version release notes pages
Add a "版本发布" docs section with one page per release, starting with
v0.8.2 and a backfilled v0.8.0. Each page walks through the highlights
with the existing product screenshots, the other improvements and fixes,
and an upgrade checklist with the actions each breaking change needs.
The sidebar orders these pages by version, newest first; the docs header
gains a 版本 entry, and the homepage's v0.8.2 section now links to the
release notes page instead of the raw CHANGELOG.
* feat(website): let the site image listen on a configurable port
The Docker image hard-coded `listen 80`, so running it with host
networking or on a platform that assigns the container port required
editing the Nginx config and rebuilding. The image now renders its
config from the official nginx template directory at startup and reads
the listen port from `PORT` (default 80); deploy/nginx.conf stays a plain
config for static deployments.
test-docker starts a second container with PORT=8080 and checks the
rendered config and that the site answers on that port; the README
documents the variable.
* fix(website): namespace the nginx listen port variable
* fix(website): support bash-wrapped container startup
* fix(website): align nginx startup with frontend entrypoint
* fix(website): pin nginx runtime for older host compatibility
* fix(website): bake the configured nginx port into the image
2026-09-24 03:26:34 +00:00
|
|
|
|
`capabilities` 中的 `settings.sandbox.host` 表示当前部署能否使用本机操作系统沙箱,目前仅 macOS 原生桌面应用可能为 supported。
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/system/host-project-dir
|
|
|
|
|
|
|
|
|
|
|
|
用途:在运行 WeKnora 的本机弹出系统文件夹选择框,供新会话绑定本机项目目录(v0.8.2 起,仅原生桌面应用)。权限:Viewer+,仅 JWT,API Key 一律拒绝。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"code":0,"msg":"success","data":{"dir":"/Users/me/project"}}`,用户取消选择时 `dir` 为空字符串;非桌面部署返回 404。
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
### GET /api/v1/system/info
|
|
|
|
|
|
|
|
|
|
|
|
用途:系统版本与引擎信息。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"code":0,"msg":"success","data":{version,edition,commit_id,build_time,go_version,keyword_index_engine,vector_store_engine,graph_database_engine,minio_enabled,db_version,started_at,uptime_seconds}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/system/info -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/system/parser-engines
|
|
|
|
|
|
|
|
|
|
|
|
用途:解析引擎列表与 DocReader 连接状态。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"code":0,"msg":"success","data":[...],"docreader_addr","docreader_transport","connected"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/system/parser-engines -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/system/parser-engines/check
|
|
|
|
|
|
|
|
|
|
|
|
用途:用给定配置探测解析引擎(`types.ParserEngineConfig` 请求体)。权限:Admin+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200,同上。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/system/parser-engines/check -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/system/docreader/reconnect
|
|
|
|
|
|
|
|
|
|
|
|
用途:重连 DocReader。权限:Admin+。请求体:`{"addr":"host:port"}`(`binding:"required"`)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"code":0,"msg":"连接成功",...,"connected":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/system/docreader/reconnect -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"addr":"docreader:50051"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/system/storage-engine-status
|
|
|
|
|
|
|
|
|
|
|
|
用途:对象存储引擎可用性。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"code":0,"msg":"success","data":{"engines":[{name,allowed,available,description}],"allowed_providers":[...],"minio_env_available":bool}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/system/storage-engine-status -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/system/storage-engine-check
|
|
|
|
|
|
|
|
|
|
|
|
用途:校验存储配置(SSRF 防护后探测)。权限:Admin+。请求体:`provider`(必填,`minio/cos/tos/s3/oss/ks3/obs`)+ 对应 `minio|cos|tos|s3|oss|ks3|obs` 配置对象。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"code":0,"data":{"ok","message","bucket_created"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/system/storage-engine-check -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"provider":"minio","minio":{"endpoint":"minio:9000"}}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 系统管理(/api/v1/system/admin,SystemAdmin 专属)
|
|
|
|
|
|
|
|
|
|
|
|
组级挂载 `SystemAdmin()` 守卫(始终强制,不受 EnableRBAC 影响);平台 API key 需对应 `system_*` capability。本组读取接口多返回原始行/数组(无包装)。Handler: `internal/handler/system.go`、`internal/handler/audit_log.go`。
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/system/admin/promote
|
|
|
|
|
|
|
|
|
|
|
|
用途:授予 SystemAdmin。请求体:`user_id`(UUID,优先)或 `email`(二选一)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `UserInfo`(原始对象)。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/system/admin/promote -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"email":"admin@ex.com"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/system/admin/revoke
|
|
|
|
|
|
|
|
|
|
|
|
用途:撤销 SystemAdmin。请求体:`{"user_id":"..."}`(`binding:"required"`)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `UserInfo`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/system/admin/revoke -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"user_id":"u-1"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/system/admin/list
|
|
|
|
|
|
|
|
|
|
|
|
用途:SystemAdmin 列表。查询参数:`offset`(默认 0)、`limit`(默认 50,上限 200)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"total":N,"admins":[UserInfo]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/system/admin/list -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
### POST /api/v1/system/admin/users/create
|
|
|
|
|
|
|
|
|
|
|
|
仅系统管理员;此接口不开放给 platform API Key。请求字段:username(2–50 字符)、email(合法邮箱)、password(可选或 null 自动生成)。显式空字符串仍要经过密码策略校验,不视为自动生成。
|
|
|
|
|
|
|
|
|
|
|
|
| HTTP 状态 | 响应与含义 |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| 201 | `{user:UserInfo,generated_password?}`,新建;仅自动生成时返回密码 |
|
|
|
|
|
|
| 200 | `{user:UserInfo}`,已有身份,不修改账号或密码 |
|
|
|
|
|
|
| 400 | 参数或密码策略不满足 |
|
|
|
|
|
|
| 409 | 邮箱与用户名对应不同身份 |
|
|
|
|
|
|
|
|
|
|
|
|
这是原始响应对象,没有 success/data 包装,也没有 idempotent 字段。用 HTTP 状态区分新增与已有账号。空间分配遵循 auth.default_tenant_mode。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -i -X POST "$BASE/api/v1/system/admin/users/create" \
|
|
|
|
|
|
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"username":"alice","email":"alice@example.com"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
### POST /api/v1/system/admin/users/reset-password
|
|
|
|
|
|
|
|
|
|
|
|
用途:重置用户密码。请求体:`email`(`binding:"required,email"`)、`new_password`(`binding:"required"`)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"message":"Password reset successfully"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/system/admin/users/reset-password -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"email":"a@ex.com","new_password":"newpass1"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/system/admin/api-keys
|
|
|
|
|
|
|
|
|
|
|
|
用途:平台 API key 列表(掩码)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[{id,name,api_key,capabilities,expires_at_unix,...}]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/system/admin/api-keys -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/system/admin/api-keys
|
|
|
|
|
|
|
|
|
|
|
|
用途:创建平台 API key(明文仅返回一次)。请求体:`name`(非空)、`capabilities`(`system_*` 列表,必填)、`expires_at_unix`(可选,须为未来时间)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:201 `{"success":true,"data":{...,"api_key":"<明文>","token":"<明文>"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/system/admin/api-keys -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"name":"ops","capabilities":["system_tenants_read"]}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/system/admin/api-keys/:key_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:删除平台 API key。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/system/admin/api-keys/3 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/system/admin/settings 与 GET /api/v1/system/admin/settings/:key
|
|
|
|
|
|
|
|
|
|
|
|
用途:平台运行时设置列表 / 单项(平台 key 需 `system_settings_read|manage`)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `[SystemSetting]` / `SystemSetting`(原始,无包装;字段:`key,value,value_type,description,last_modified_by,last_modified_at`)。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/system/admin/settings -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/system/admin/settings/:key
|
|
|
|
|
|
|
|
|
|
|
|
用途:更新设置(平台 key 需 `system_settings_manage`)。请求体:`{"value":<任意 JSON,按注册表类型校验>}`(必填)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `SystemSetting`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/system/admin/settings/default_storage_quota -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"value":10737418240}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/system/admin/settings/:key
|
|
|
|
|
|
|
|
|
|
|
|
用途:恢复设置默认值。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/system/admin/settings/default_storage_quota -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/system/admin/runtime/queues
|
|
|
|
|
|
|
|
|
|
|
|
用途:asynq 队列深度与并发状态(Lite 模式返回 `available:false`;平台 key 需 `system_runtime_read|manage`)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"available",upstream_concurrency,parse_concurrency,wiki_concurrency,pools,queues,model_limiter_available,models,timestamp}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/system/admin/runtime/queues -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/system/admin/runtime/queues/:queue/tasks
|
|
|
|
|
|
|
|
|
|
|
|
用途:队列任务列表。查询参数:`state`(`pending/active/scheduled/retry/archived/completed`)、`cursor`、`page_size`(默认 20,上限 100)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"available","tasks":[RuntimeTaskInfo],"page_size","has_more","next_cursor"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/system/admin/runtime/queues/default/tasks?state=pending" -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/system/admin/runtime/queues/:queue/tasks/:task_id/actions/:action
|
|
|
|
|
|
|
|
|
|
|
|
用途:任务操作(`action` ∈ `cancel/run_now/delete`;平台 key 需 `system_runtime_manage`)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/system/admin/runtime/queues/default/tasks/t-1/actions/cancel \
|
|
|
|
|
|
-H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/system/admin/runtime/queues/:queue/archived
|
|
|
|
|
|
|
|
|
|
|
|
用途:清空归档任务。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"deleted":N}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/system/admin/runtime/queues/default/archived -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/system/admin/tenants/apply-default-storage-quota
|
|
|
|
|
|
|
|
|
|
|
|
用途:把当前默认存储配额批量写到全部空间(平台 key 需 `system_tenants_manage`)。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"affected":N,"quota_bytes":N,"quota_gb":N}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/system/admin/tenants/apply-default-storage-quota -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/system/admin/audit-log
|
|
|
|
|
|
|
|
|
|
|
|
用途:平台级审计日志(tenant_id=0 行;平台 key 需 `system_audit_read`)。查询参数同空间审计(`after_id/limit/action/outcome/actor`)。Handler: `internal/handler/audit_log.go`
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[AuditLog],"next_cursor":N}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/system/admin/audit-log -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
2026-09-08 02:54:41 +00:00
|
|
|
|
|
|
|
|
|
|
## 实现参考
|
|
|
|
|
|
|
|
|
|
|
|
路由注册:`internal/router/routes_auth_tenant.go` 的 `RegisterSystemAdminRoutes` 与 `RegisterSystemRoutes`。Handler:`internal/handler/system.go`、`internal/handler/audit_log.go`。
|