WeKnora/website-docs/04-api/02-api-system.md

282 lines
11 KiB
Markdown
Raw Normal View History

# API 参考:系统与平台管理
提供部署级系统信息和平台管理接口,包括全局设置、任务队列、平台 API Key、跨空间审计和用户密码重置。功能说明见[平台管理与系统管理员](../03-features/20-platform-admin.md)。
`/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":...}` 包装。
### 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。
### 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"
```
### 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"}'
```
### 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"
```
## 实现参考
路由注册:`internal/router/routes_auth_tenant.go` 的 `RegisterSystemAdminRoutes` 与 `RegisterSystemRoutes`。Handler:`internal/handler/system.go`、`internal/handler/audit_log.go`。