website-docs/04-api/02-api-system.md
这一组是部署级接口：读系统信息，以及系统管理员专属的平台控制面（全局设置、运行时队列、平台 API Key、跨空间审计、重置密码）。功能说明见平台管理与系统管理员。
路由注册：internal/router/routes_auth_tenant.go 的 RegisterSystemAdminRoutes 与 RegisterSystemRoutes。Handler：internal/handler/system.go、internal/handler/audit_log.go。
/system/admin/* 全组挂 SystemAdmin() 守卫；平台 API Key 按能力细分（system_settings_read/manage、system_runtime_read/manage、system_tenants_read/manage、system_audit_read）。
Handler: internal/handler/system.go。API key：manage_vector_stores/full。本组响应使用 {"code":0,"msg":"success","data":...} 包装。
用途：系统版本与引擎信息。权限：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}}
curl $BASE/api/v1/system/info -H "Authorization: Bearer $TOKEN"
用途：解析引擎列表与 DocReader 连接状态。权限：Viewer+。
响应：200 {"code":0,"msg":"success","data":[...],"docreader_addr","docreader_transport","connected"}
curl $BASE/api/v1/system/parser-engines -H "Authorization: Bearer $TOKEN"
用途：用给定配置探测解析引擎（types.ParserEngineConfig 请求体）。权限：Admin+。
响应：200，同上。
curl -X POST $BASE/api/v1/system/parser-engines/check -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{}'
用途：重连 DocReader。权限：Admin+。请求体：{"addr":"host:port"}（binding:"required"）。
响应：200 {"code":0,"msg":"连接成功",...,"connected":true}
curl -X POST $BASE/api/v1/system/docreader/reconnect -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"addr":"docreader:50051"}'
用途：对象存储引擎可用性。权限：Viewer+。
响应：200 {"code":0,"msg":"success","data":{"engines":[{name,allowed,available,description}],"allowed_providers":[...],"minio_env_available":bool}}
curl $BASE/api/v1/system/storage-engine-status -H "Authorization: Bearer $TOKEN"
用途：校验存储配置（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"}}
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"}}'
组级挂载 SystemAdmin() 守卫（始终强制，不受 EnableRBAC 影响）；平台 API key 需对应 system_* capability。本组读取接口多返回原始行/数组（无包装）。Handler: internal/handler/system.go、internal/handler/audit_log.go。
用途：授予 SystemAdmin。请求体：user_id（UUID，优先）或 email（二选一）。
响应：200 UserInfo（原始对象）。
curl -X POST $BASE/api/v1/system/admin/promote -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"email":"[email protected]"}'
用途：撤销 SystemAdmin。请求体：{"user_id":"..."}（binding:"required"）。
响应：200 UserInfo
curl -X POST $BASE/api/v1/system/admin/revoke -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"user_id":"u-1"}'
用途：SystemAdmin 列表。查询参数：offset（默认 0）、limit（默认 50，上限 200）。
响应：200 {"total":N,"admins":[UserInfo]}
curl $BASE/api/v1/system/admin/list -H "Authorization: Bearer $TOKEN"
用途：重置用户密码。请求体：email（binding:"required,email"）、new_password（binding:"required"）。
响应：200 {"message":"Password reset successfully"}
curl -X POST $BASE/api/v1/system/admin/users/reset-password -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"email":"[email protected]","new_password":"newpass1"}'
用途：平台 API key 列表（掩码）。
响应：200 {"success":true,"data":[{id,name,api_key,capabilities,expires_at_unix,...}]}
curl $BASE/api/v1/system/admin/api-keys -H "Authorization: Bearer $TOKEN"
用途：创建平台 API key（明文仅返回一次）。请求体：name（非空）、capabilities（system_* 列表，必填）、expires_at_unix（可选，须为未来时间）。
响应：201 {"success":true,"data":{...,"api_key":"<明文>","token":"<明文>"}}
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"]}'
用途：删除平台 API key。
响应：200 {"success":true}
curl -X DELETE $BASE/api/v1/system/admin/api-keys/3 -H "Authorization: Bearer $TOKEN"
用途：平台运行时设置列表 / 单项（平台 key 需 system_settings_read|manage）。
响应：200 [SystemSetting] / SystemSetting（原始，无包装；字段：key,value,value_type,description,last_modified_by,last_modified_at）。
curl $BASE/api/v1/system/admin/settings -H "Authorization: Bearer $TOKEN"
用途：更新设置（平台 key 需 system_settings_manage）。请求体：{"value":<任意 JSON，按注册表类型校验>}（必填）。
响应：200 SystemSetting
curl -X PUT $BASE/api/v1/system/admin/settings/default_storage_quota -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"value":10737418240}'
用途：恢复设置默认值。
响应：200 {"success":true}
curl -X DELETE $BASE/api/v1/system/admin/settings/default_storage_quota -H "Authorization: Bearer $TOKEN"
用途：asynq 队列深度与并发状态（Lite 模式返回 available:false；平台 key 需 system_runtime_read|manage）。
响应：200 {"available",upstream_concurrency,parse_concurrency,wiki_concurrency,pools,queues,model_limiter_available,models,timestamp}
curl $BASE/api/v1/system/admin/runtime/queues -H "Authorization: Bearer $TOKEN"
用途：队列任务列表。查询参数：state（pending/active/scheduled/retry/archived/completed）、cursor、page_size（默认 20，上限 100）。
响应：200 {"available","tasks":[RuntimeTaskInfo],"page_size","has_more","next_cursor"}
curl "$BASE/api/v1/system/admin/runtime/queues/default/tasks?state=pending" -H "Authorization: Bearer $TOKEN"
用途：任务操作（action ∈ cancel/run_now/delete；平台 key 需 system_runtime_manage）。
响应：200 {"success":true}
curl -X POST $BASE/api/v1/system/admin/runtime/queues/default/tasks/t-1/actions/cancel \
-H "Authorization: Bearer $TOKEN"
用途：清空归档任务。
响应：200 {"success":true,"deleted":N}
curl -X DELETE $BASE/api/v1/system/admin/runtime/queues/default/archived -H "Authorization: Bearer $TOKEN"
用途：把当前默认存储配额批量写到全部空间（平台 key 需 system_tenants_manage）。无请求体。
响应：200 {"affected":N,"quota_bytes":N,"quota_gb":N}
curl -X POST $BASE/api/v1/system/admin/tenants/apply-default-storage-quota -H "Authorization: Bearer $TOKEN"
用途：平台级审计日志（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}
curl $BASE/api/v1/system/admin/audit-log -H "Authorization: Bearer $TOKEN"