P1 AIP

管理后台

用户、角色、权限、设置、审计——AIP 的治理面。前端路径 /admin/*，后端接口全部要求 admin 角色，每次写操作都留审计。看完这 3 个故事，你就能独立完成建号、配权限、追查审计的完整流程。

IT 管理员安全审计员用户管理角色权限点审计日志共 3 个故事

能 / 不能速览

✅ 这个主题能做

用户管理：创建 / 查询 / 更新 / 删除用户，重置密码、锁定 / 解锁
角色管理：创建 / 重命名 / 删除角色，给用户分配 / 移除角色
权限点绑定：给角色整体设置 table / column / row 三类权限
权限清单查询（/api/v1/permissions）
系统设置 CRUD（/api/v1/settings，key / value / type / description）
审计日志查询（/api/v1/audit/logs，支持按用户 / 事件类型 / 时间过滤与分页）
/api/v1/me 查看当前用户信息、角色与 is_admin

⛔ 这个主题做不了

不能删除自己（cannot delete yourself）
admin 不能移除自己的 admin 角色（服务层自护）
非 admin 访问全部 admin 接口返回 403（无 token 401）
locked 字段必填、密码至少 6 位，缺字段直接 400
v0.1 权限点是"配置记录"，行 / 列级强制执行依赖深度权限配置与安全服务

适用角色

本主题面向两个角色：

IT 管理员（赵工）：用户、角色、权限、设置的日常维护——是核心使用者。
安全审计员（孙姐）：用审计日志做合规排查与事件追溯。

业务分析师与普通用户只消费数据，不触碰管理后台；角色权限由管理员统一维护。

能力速览（能做什么）

用户管理

创建用户、重置密码、锁定 / 解锁、分配 / 移除角色；用户 ID 为 UUID，删除自己会被拒绝。

角色与权限点

角色 CRUD + 权限点（table / column / row）整体绑定，写入 role_permissions，改权限不动用户。

系统设置

key-value 设置项 CRUD（upsert 语义，重复 key 为更新），是 LLM 等配置的载体。

审计日志

按 user_id / event_type / 时间范围过滤 + limit / offset 分页，事件含 NLQ_QUERY、USER_CREATED、ROLE_* 等。

权限治理链路

用户 → 角色 → 权限点 →（配合深度权限配置的 RLS / CLS），治理有据可查。

扩展管理页（模块 11-17）

工作流编排（/admin/workflows）、飞书设置（/admin/feishu）、邮件设置（/admin/email）、评测管理（/admin/eval）、监控看板（/admin/monitoring）、知识库（/knowledge）、运维状态（/ops）都在登录 / admin 体系下，与用户 / 角色 / 审计同一套鉴权。

调整指南（怎么调整）

最小权限：角色只开需要的表与列，普通用户不给 admin 角色。
权限整体替换：PUT /roles/:id/permissions 是整体替换语义，先取当前、修改后再提交，避免误清空。
账号治理：离职 / 冻结用"锁定"而非删除，保留审计关联。
设置 upsert：重复 key 是更新不是新增；key 为空返回 400。
审计异步：审计日志异步落库，刚发生的操作稍等片刻再查。

做得好的场景

管理后台把"管人、管权、留证"收进同一套系统，特别适合以下场景：

全部写操作留审计：谁在何时改了什么角色 / 权限 / 用户，一查便知。
角色与权限点解耦：改权限不动用户、不影响在线，权限变更即时生效。
防呆自护：不能删自己、不能移除自己的 admin 角色，避免"删光管理员"事故。
前端 /admin/* 与后端一一对应：用户管理、角色与权限、审计、设置页面路径清晰。

限制与不足

以下是明确的边界，使用前先知道：

权限点是配置记录：v0.1 不在这里做行 / 列级强制过滤，强制执行依赖深度权限配置与安全服务。
审计异步落库：刚发生的操作有几百毫秒延迟，急查会漏。
无批量操作：没有批量建号、角色复制、权限继承。
严格参数校验：用户 ID 为 UUID，非法 ID 返回 400；缺 locked / 短密码直接 400。
只认 admin 角色：接口按角色判定，普通用户 403，无 token 401。

场景故事

故事 1 新同事入职，赵工 2 分钟建号并分配"分析师"角色

场景：用户管理角色：IT 管理员耗时：约 3 分钟

背景: 小陈是刚入职的业务分析师。赵工是 IT 管理员，要给她建一个 AIP 账号、分配"分析师"角色，让她能登录查数但不能进管理后台。整个过程在管理后台的"用户管理"页完成，没写一行脚本。

传统做法对比: 以前建账号要走 OA 审批、IT 手工建库账号 + 写权限脚本，快则半天慢则 1~3 天；现在管理后台里"创建用户 → 分配角色"两步，2 分钟搞定，即刻生效。

角色: IT 管理员（赵工）。

操作步骤

用 admin / admin1 登录，进入 /admin/users
新建用户：用户名 chen，设置一个临时密码（至少 6 位）
进入用户详情，分配"分析师"角色
（可选）后续可重置密码、锁定 / 解锁账号
让小陈用新账号登录验证

系统响应

POST /api/v1/users 返回 201 + user（id 为 UUID）；POST /api/v1/users/:id/roles 返回 assigned=true；GET /api/v1/users 列表出现新用户；审计日志记录 USER_CREATED 与 USER_ROLE_ASSIGNED 事件：

{
  "user": { "id": "3f2b...", "username": "chen", "roles": ["分析师"] }
}
{
  "assigned": true, "role_id": 3
}

结果洞察: 小陈用新账号登录后是普通用户（is_admin=false），能正常用智能查询，但访问 /admin/* 会 403 或被前端拦下；角色分配即时生效，无需重启服务。审计日志里"谁在何时给谁分配了什么角色"一目了然。

调整建议: 密码用临时密码，让用户首次登录后自行修改；离职 / 冻结用"锁定"而非删除，保留审计关联；默认管理员账号可用环境变量 DEFAULT_ADMIN_USERNAME / DEFAULT_ADMIN_PASSWORD 定制。

动手试一试: 登录：admin / admin1。页面路径：/admin/users。输入内容：新建用户（如 u_test / Test@1234），再分配"分析师"角色。预期结果：创建 201、分配 assigned=true；退出用新账号登录，验证无法进入 /admin/*。

限制提示: 不能删除自己；admin 不能移除自己的 admin 角色；重复分配同一角色返回 409；密码少于 6 位返回 400；用户 ID 为 UUID，非法 ID 返回 400。

故事 2 配置角色权限点：分析师只能查 orders、看不到客户邮箱

场景：权限配置角色：IT 管理员耗时：约 5 分钟

背景: 销售明细比较敏感。赵工要收紧权限：让"分析师"角色只能查 orders 表、不能读 customers.email 列，同时给"销售总监"角色保留更多权限。他在"角色与权限"页用权限点配置完成。

传统做法对比: 以前改权限要么写 SQL grant / revoke 脚本（要排期、易出错），要么线下申请走流程 2~3 天；现在在管理后台配置，PUT 一次整体生效，还能随时在权限清单里核对。

角色: IT 管理员（赵工）。

操作步骤

进入 /admin/roles，选择"分析师"角色
打开权限配置，设置 table=[orders]
设置 column 限制（如 customers.email 列级权限）
保存（整体替换语义）
GET /roles/:id/permissions 核对 is_assigned

系统响应

PUT /api/v1/roles/:id/permissions 请求体与响应：

// 请求体：table / column / row 三类权限点
{ "table": ["orders"], "column": { "customers": ["email"] } }
// 响应：权限列表（含分配状态）
[ { "permission_type": "TABLE_ACCESS", "resource_name": "orders", "is_assigned": true },
  { "permission_type": "COLUMN_ACCESS", "resource_name": "customers.email", "is_assigned": true } ]

结果洞察: 权限点写入 role_permissions 表；GET /api/v1/permissions 能看到全部权限清单；审计记录 ROLE_PERMISSIONS_UPDATED。配合深度权限配置里的 RLS / CLS 策略，敏感列在查询链路会被过滤，权限治理形成闭环。

调整建议: 权限是"整体替换"——先 GET 当前配置、修改后再 PUT，避免误清空；行级过滤用 row 字段（如 region='east'）；新增"运营"角色给独立权限集，别复用 admin。

动手试一试: 登录：admin / admin1。接口：PUT /api/v1/roles/:id/permissions。输入内容：table orders + column 限制 customers.email。预期结果：GET /roles/:id/permissions 返回权限且 is_assigned=true；再提交一次空对象，观察权限被清空。

限制提示: v0.1 权限点是"配置记录"，强制执行依赖深度权限配置与安全服务；空对象提交等于清空该角色全部权限；table 传非数组返回 400；非 admin 访问返回 403。

故事 3 追查数据泄露疑点——审计日志按事件与时间分钟级定位

场景：审计排查角色：安全审计员耗时：约 10 分钟

背景: 孙姐是安全审计员。有人反馈一张"含客户邮箱的销售明细"截图疑似从系统流出，时间大约在周三下午。她要查：是谁、在什么时间、查了什么数据。她用管理后台的审计日志页，按事件类型与时间范围过滤，十几分钟锁定目标。

传统做法对比: 以前查"谁查过什么"要么翻数据库 slow log（看不出业务含义）、要么全凭人工回忆，一次排查 1~2 天；现在 GET /api/v1/audit/logs 支持按 user_id / event_type / 时间范围过滤与分页，分钟级定位。

角色: 安全审计员（孙姐，admin 账号）。

操作步骤

进入 /admin/audit
按 event_type=NLQ_QUERY、时间范围（周三 12:00 ~ 18:00）过滤
按 user_id 聚焦某个账号
查看 action_details 里的 query / sql / rows
结合权限配置判断是否存在越权

系统响应

审计日志返回记录，event_type=NLQ_QUERY、result=SUCCESS，action_details 含完整查询与 SQL：

{
  "logs": [
    { "event_type": "NLQ_QUERY", "result": "SUCCESS", "user_id": "u-101",
      "timestamp": "2026-08-06T14:32:11+08:00",
      "action_details": "{\"query\":\"查询所有客户邮箱和订单明细\",\"intent\":\"data_query\",\"sql\":\"SELECT ... email ...\"}" }
  ]
}

结果洞察: 定位到周三 14:32 某普通用户账号连续 8 次 NLQ_QUERY，查询包含"客户邮箱""全部订单含联系方式"；确认该账号被授予了过宽的角色权限。整改动作：收紧该角色权限点、重置该账号密码、必要时锁定账号，并同步给业务侧预警。

调整建议: 定期导出审计日志做异常检测；对敏感表设置更严权限点，从源头减少"能查"；审计异步落库，排查时先等片刻再刷新；大量历史用 limit / offset 分页拉取。

动手试一试: 登录：admin / admin1。页面路径：/admin/audit。操作：先在智能查询里问几个问题（会写 NLQ_QUERY 日志），再到审计页按 event_type=NLQ_QUERY 过滤。预期结果：能看到每次查询的 query 与 sql 字段（action_details）。

限制提示: 审计日志异步写入，刚发生的操作可能有几百毫秒延迟；时间过滤参数要求 RFC3339 格式，写错会静默忽略；审计记录的是事件与查询摘要，不含完整返回数据。

常见问题

非 admin 能进管理后台吗？

不能。前端 /admin/* 与全部 /api/v1 管理接口都要求 admin 角色：无 token 返回 401，普通用户返回 403（"admin role required"）。

权限配置后马上生效吗？

角色-权限点绑定写入即生效，无需重启；但"强制执行"依赖深度权限配置里的 RLS / CLS 策略与安全服务，管理后台本体只维护权限配置记录。

审计日志为什么"慢半拍"？

审计服务是异步写入的：先返回业务结果、后台落库，刚发生的操作可能有几百毫秒到 1 秒延迟，排查时稍等再刷新即可。

能删掉 admin 角色吗？

接口层面允许（测试记录过该行为），但删掉后管理员判定会失败，所有 admin 接口将不可用，属于高危操作，请谨慎。

用户 ID 为什么是 UUID 形式？

用户主键是 UUID 字符串，路径参数校验严格：非法 UUID 返回 400，合法但不存在返回 404。这与数据源 ID（数字自增）是不同的约定。

工作流 / 评测 / 监控这些管理页也在 /admin 下吗？

是。AdminLayout 下已有 /admin/workflows（工作流编排）、/admin/feishu（飞书设置）、/admin/email（邮件设置）、/admin/eval（评测管理）、/admin/monitoring（监控看板）等，均要求 admin 角色；知识库（/knowledge）与运维状态（/ops）是登录即可访问的非 admin 页面。新增管理页都会同步注册路由与侧边栏入口。

主题小结

一句话：管理后台是 AIP 的"治理面"——用户、角色、权限、设置、审计五件套，全部写操作留痕。记住几个边界：权限点是配置记录、审计异步落库、接口仅 admin 可用、防呆自护（不能删自己）已内置。