5.5 用户、Token 与系统管理接口

2 months ago
ce8b067

用户、Token 与系统管理接口

本节覆盖用户、工作区、Token、OIDC、品牌和操作日志。用户、工作区、Token 和日志管理通常要求当前工作区 owner 或 admin；系统品牌还要求系统管理员。

用户与个人资料

方法 路径 说明
POST/GET /api/v1/users 创建/分页查询用户
GET/PUT/DELETE /api/v1/users/:id 详情/更新/删除
POST /api/v1/users/:id/reset-password 管理员重置密码
GET /api/v1/profile 当前用户
POST /api/v1/profile/change-password 校验旧密码后修改

创建用户示例：

{
  "username": "operator01",
  "password": "<initial-password>",
  "real_name": "运营一组",
  "email": "operator01@example.invalid"
}

用户名 3–50 字符，密码 6–50 字符。用户状态为 1 启用、0 禁用；禁用用户无法通过 JWT、API Token 或签名继续访问。

工作区与成员

方法 路径
GET/POST /api/v1/workspaces
PUT /api/v1/workspaces/current
GET/POST /api/v1/workspaces/current/members
PUT/DELETE /api/v1/workspaces/current/members/:user_id

成员角色为 owner、admin、member、viewer。这些接口中的 current 指 X-Workspace-Id 解析出的工作区。

API Token

方法 路径 说明
POST /api/v1/tokens 为当前用户和工作区创建 Token
GET /api/v1/tokens 只列出当前用户在当前工作区的 Token
DELETE /api/v1/tokens/:token_id 删除自己的 Token 
{
  "token_name": "report-job",
  "token_type": "signature",
  "expire_at": "2027-01-01T00:00:00+08:00"
}

token_type 省略时默认为 signature。签名类型仅创建时返回明文 app_secret；Bearer 类型仅创建时返回完整 token。列表只展示 App ID 或截断后的 Token。

OIDC

方法 路径 说明
GET/PUT /api/v1/admin/oidc/config 读取/保存单个提供商配置
POST /api/v1/admin/oidc/test 测试发现地址和客户端配置，不落库
POST /api/v1/auth/oidc/bind 当前用户绑定
GET /api/v1/auth/oidc/my-bindings 当前用户绑定列表
DELETE /api/v1/auth/oidc/bindings/:provider 解绑

保存配置时 client_secret 留空表示保留已有密文，读取接口永不回显 Secret。exclusive=true 会隐藏本地密码登录，服务会要求至少存在一条对应绑定以降低自锁风险。

v2.22.3 的 /api/v1/admin/oidc/* 位于认证与工作区中间件之后，但 Controller 尚未追加 owner/admin 角色检查。部署方应在网关限制这些路径，且只向受信管理员开放后台入口；后续版本应补充服务端角色校验，不能只依赖前端菜单。

系统品牌和日志

方法 路径
GET/PUT /api/v1/branding/system
POST /api/v1/branding/logo
GET /api/v1/logs

Logo 上传使用 multipart 文件，响应返回 /uploads/branding/... URL。操作日志可按用户、动作、资源、HTTP 方法、状态码和时间范围筛选；日志可能包含敏感上下文，访问和导出时遵循最小权限。

相关章节：认证与工作区、JWT 运维。