用户管理

用户管理在管理台 Users（/users）页面，按动作区分权限：查看 admin:user:read、创建 admin:user:create、修改/激活/停用/密码策略 admin:user:update、删除 admin:user:delete。内置 Admin 角色持有这四项全部权限。

本页列出每个动作的真实端点、校验规则与失败后的表现。用户角色如何影响权限见角色与权限。

列表与筛选

GET /api/v1/admin/users（admin:user:read）返回分页用户列表，参数：

状态定义：active = is_active=true；inactive = is_active=false 且 approval_status=approved；pending = 待审批（approval_status=pending，is_active=false）。

顶部统计来自 GET /api/v1/admin/users/stats（admin:user:read），返回 total / active / inactive / pending。列表默认不显示登录次数、失败登录次数、最后改密时间——这些字段接口不返回。

创建用户

POST /api/v1/admin/users（admin:user:create）：

1. 点击 Create User。
2. 填写 Username（全局唯一）、Email（全局唯一，需为合法邮箱）、Password、Active 开关（is_active）。
3. 保存。

后端行为与校验：

批量导入 / SSO 自动创建

未实现 / Roadmap。 没有 CSV/JSON/Excel 用户导入，只能逐个创建（POST /api/v1/admin/users），或在 SSO 首次登录时自动创建。

SSO 自动创建由站点设置控制（Site Settings → SSO/Security）：

未实现 / Roadmap：SSO 自动创建没有邮箱域白名单限制。

查看用户详情

点击用户打开详情/编辑面板（GET /api/v1/admin/users/{user_id}，admin:user:read）。可见字段：

• 身份：username、email、is_active、approval_status、is_superuser、auth_source（local / sso）、email_verified
• 偏好：locale、avatar_url
• 时间：created_at、last_login
• 密码状态：force_password_change、password_expiration_exempt（列表里显示为密码状态徽标）
• 授权：roles（全局角色数组）
• SSO：sso_connections（提供商、外部账号、首次/最后登录），有 admin:sso:update 时可断开连接

未实现 / Roadmap：用户管理内没有单用户活动视图、登录历史、活跃会话列表或会话撤销。账户锁定由全局登录策略 max_login_attempts / lockout_duration_minutes 强制执行；用户行为需到 Audit Logs 按用户筛选查看。

编辑用户

PUT /api/v1/admin/users/{user_id}（admin:user:update）。可提交字段：

角色改动的保护规则

roles 是整体替换（先清空再写入，未列出的角色会丢失；匹配不到的角色名被忽略）。若目标用户仍是某些团队的 owner/admin，而新角色集不再包含 team:manage（或 *），请求返回 403 operation_not_permitted（permission: team:manage）。先降级团队角色，再摘全局角色，否则顺序反了会被挡住。

提交密码时后端会向该用户发送 user.password_reset 通知。

账户状态

停用的实际效果：

• 无法登录：JWT 与 API Key 两条认证路径都会因为 is_active=false 拒绝（401 inactive_user，待审批用户是 pending_approval_user）。
• 使用他名下 API Key 的集成立即失败——Key 本身不会被改写，但认证时因用户已停用而拒绝。
• 资源、团队归属、会话全部保留；重新激活即可恢复。

激活/停用都会给用户发送 user.activated / user.deactivated 通知，并写审计日志（activate_user / deactivate_user）。

删除用户

DELETE /api/v1/admin/users/{user_id}（admin:user:delete）。唯一硬性拦截：is_superuser=true 的账户返回 cannot_delete_superuser。前端删除对话框要求输入用户名确认，并列出影响范围。

删除影响（按模型外键规则，已核对 models/*.py）：

密码与密码过期

没有「重置为临时密码」或「从管理台发送重置邮件」的流程。管理员用下面这组按用户操作配合全局密码策略：

前端只在详情页/行内菜单展示这些操作，且仅当 auth_source=local（SSO 用户没有本地密码）；全局策略配置在 Site Settings → Security。

TOTP（双因素）

用户自助的开启/关闭/备份码在个人设置里完成（见登录与账户）。

# 需要超管 Token
curl "https://your-domain.com/api/v1/admin/totp/users/$USER_ID/status" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

curl -X POST "https://your-domain.com/api/v1/admin/totp/users/$USER_ID/disable" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

批量操作

用户列表勾选多人后弹出底部工具条。注意其中多项是前端循环调用单用户接口实现的，没有对应批量端点：

因为没有真正的批量端点，单条失败不会回滚其余条目；返回的 toast 计数可能与实际成功数不一致，涉及权限/状态冲突的用户请核对后再重试。

未实现 / Roadmap：没有批量加入/移出团队、批量导出、CSV 导入/导出。

发送邮件

POST /api/v1/admin/users/send-email，请求体 {"user_ids": [...], "subject": "...", "content": "..."}，需要 admin:user:update。响应为 {"sent_count": n, "skipped_count": n, "total": n}。

限制（超过即报错，不会部分发送）：

用户角色

全局角色（可多选，roles）决定系统级与管理台能力，团队角色决定团队内级别。内置 5 个角色与权限集见角色与权限：

团队角色（owner/admin/member/viewer）在团队页面维护，不在用户详情里改：用户详情只读展示团队归属。

最佳实践

✅ 推荐：

• 定期复核用户列表，及时停用离职人员（停用即可立即阻断登录与 API Key）
• 创建后立刻指派最小必要的全局角色
• 特权账户强制启用 2FA，并为其设置 password_expiration_exempt 之外的正常轮换策略
• 用 expiring-passwords 清单提前处理即将过期账户，而不是等锁定后救火
• 停用、删除、改角色等操作前后留痕（审计日志自带）

❌ 避免：

• 多人共用管理员账户（审计日志无法区分责任人）
• 直接删除团队 owner 的账户（团队会变成无 owner 状态）
• 用 PUT /admin/users/{id} 一次性替换角色集却漏掉某角色
• 依赖「前端隐藏按钮」做权限控制——接口是独立校验的

故障排除

无法创建用户

1. 检查用户名、邮箱是否已被占用（user_with_username_exists / user_with_email_exists）。
2. 检查邮箱格式是否合法。
3. 检查调用者是否持有 admin:user:create。

用户无法登录

1. 确认 is_active=true（停用或待审批都会 401）。
2. 确认密码正确；必要时先强制改密或直接改密。
3. 确认账户未被登录策略锁定（max_login_attempts / lockout_duration_minutes）。
4. 确认 TOTP 状态；用户丢失验证器时由超管调用禁用 TOTP 接口（无 UI）。
5. 到 Audit Logs 按用户排查异常登录。

无法删除用户

• 目标是超管 → cannot_delete_superuser（先摘掉超管标记或改用停用）。
• 目标是团队 owner → 后端不会阻止删除，但团队会失去 owner；先在团队里转让所有权再删除。
• 其他情况删除都会成功，务必确认上述级联清单（对话、API Key、成员关系会一并消失）。

改角色报 403

用户仍是某些团队的 owner/admin，而新角色集里没有 team:manage。先到团队里降级他的成员角色，再改全局角色。

API 端点参考

参见：

• 登录与账户 — 密码策略、TOTP 与账户恢复
• 角色与权限 — 全局角色、权限代码与 403 排查
• 团队与成员 — 团队内成员角色与所有权转让