P1 AIP

管理后台

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

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

能 / 不能速览

✅ 这个主题能做

用户管理：创建 / 查询 / 更新 / 删除用户，重置密码、锁定 / 解锁
角色管理：创建 / 重命名 / 删除角色，给用户分配 / 移除角色
权限点绑定：给角色整体设置 table / column / row 三类权限
权限清单查询（/api/v1/permissions）
系统设置 CRUD（/api/v1/settings，key / value / type / description）——管理界面写入的是四层配置里优先级最高的一层，压过 config.yaml 与环境变量
Prompt 模板管理（/admin/prompts）：模板 CRUD + 版本管理，编辑即新建版本并置为生效，可回滚、可单独删除某个历史版本
审计日志查询（/api/v1/audit/logs，支持按用户 / 事件类型 / 时间过滤与分页）
/api/v1/me 查看当前用户信息、角色与 is_admin

⛔ 这个主题做不了

不能删除自己（cannot delete yourself）
admin 不能移除自己的 admin 角色（服务层自护）
非 admin 访问全部 admin 接口返回 403（无 token 401）
locked 字段必填、密码至少 6 位，缺字段直接 400
v0.1 权限点是"配置记录"，行 / 列级强制执行依赖深度权限配置与安全服务
配置改动默认不热更：要开热重载得先设环境变量 CONFIG_HOT_RELOAD=1（默认关闭），且 AIP 只是部分生效
Prompt 的当前生效版本不能删（409），须先回滚到其它版本

适用角色

本主题面向两个角色：

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

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

能力速览（能做什么）

用户管理

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

角色与权限点

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

系统设置（/admin/settings）

key-value 设置项 CRUD（upsert 语义，重复 key 为更新），是 LLM 等配置的载体。配置分四层，优先级由低到高：代码默认值 → config.yaml → 环境变量 → DB system_settings，管理界面写的就是最高的第四层，压过文件与环境变量（密文类设置项除外，不会被当明文覆盖）。

Prompt 管理（/admin/prompts）

模板以「名称 + 模型族 + 版本 + 启用状态」组织，供 NLQ / Text2SQL 渲染引用；编辑保存即新建版本并置为生效，可回滚，也可在版本弹窗里单独删除某个历史版本。

审计日志

按 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 体系下，与用户 / 角色 / 审计同一套鉴权。

界面操作指引（不写代码怎么用）

下面按「打开哪个页面 → 点哪里 → 填什么 → 看到什么」的顺序给出完整操作路径，业务用户照做即可。每步末尾的「API 等价」是给工程师对照用的，可以忽略。

1 从顶栏进管理后台 顶栏「管理后台 ▾」→「用户管理」

怎么做：管理后台入口只对管理员可见（aip_is_admin=1）；点开后是左侧菜单的一整套后台页。
会看到：左侧菜单含用户管理、角色与权限、审计日志、AI 决策审计、系统设置、Prompt 管理、LLM 网关、知识库…等。

API 等价：GET /api/v1/me

2 建用户、分配角色 管理后台 →「用户管理」

怎么做：页头「新建用户」填用户名/密码（≥6 位）；行内「分配角色」打开弹窗，勾选即生效（无需额外保存）。
会看到：锁定状态用绿/红徽标；行内还有「编辑」「重置密码」「锁定/解锁」「删除」；自己的删除按钮不显示。

API 等价：POST /api/v1/users / POST /api/v1/users/:id/roles

3 配角色权限 管理后台 →「角色与权限」

怎么做：页头「新建角色」填角色名；行内「权限配置」打开弹窗。
会看到：弹窗按表级 / 列级 / 行级分组勾选，可配置项来自已导入元数据；行级权限可填过滤条件并做实时语法校验。

API 等价：GET /api/v1/roles/:id/permissions / PUT /api/v1/roles/:id/permissions

4 改系统设置（含 PII 脱敏） 管理后台 →「系统设置」

怎么做：点「新增设置」填 Key（可从 datalist 选或自由输入）/ Value / Type；PII 卡片可编辑 PII_PATTERNS JSON 后「保存 PII_PATTERNS」。
会看到：页面常驻提示「系统设置将在服务重启后生效」；管理界面写的是最高优先级的第四层（压过 config.yaml 与环境变量）。

API 等价：PUT /api/v1/settings / DELETE /api/v1/settings/:key

5 管 Prompt 模板与版本 管理后台 →「Prompt 管理」

怎么做：行内「编辑」保存即新建版本并置为生效；点「版本管理」打开版本弹窗。
会看到：版本弹窗每行有「回滚」与「删除本版」；生效版本显示「当前版本」且两按钮均禁用（需先回滚）。

API 等价：PUT /api/v1/prompts/templates/:name / POST /api/v1/prompts/templates/:name/versions/:v/rollback / DELETE /api/v1/prompts/templates/:name/versions/:v

6 查审计日志与 AI 决策审计 管理后台 →「审计日志」/「AI 决策审计」

怎么做：审计日志按用户 ID / 事件类型 / 时间 / 条数筛选后「查询」；AI 决策审计用 Trace ID 精确过滤后展开决策链。
会看到：审计日志行可展开 action_details JSON；AI 决策审计还能配「审计定时归档」（开关 / 保留天数 / cron）。

API 等价：GET /api/v1/audit/logs / GET /api/v1/ai-audit

提示：管理后台仅管理员可达，非管理员会被重定向；系统设置需重启后生效；Prompt 版本弹窗里的「删除本版」只删单个历史版本，而列表行内「删除」是模板级、会级联删全部版本，勿混淆。

调整指南（怎么调整）

最小权限：角色只开需要的表与列，普通用户不给 admin 角色。
权限整体替换：PUT /roles/:id/permissions 是整体替换语义，先取当前、修改后再提交，避免误清空。
账号治理：离职 / 冻结用"锁定"而非删除，保留审计关联。
设置 upsert：重复 key 是更新不是新增；key 为空返回 400。
设置落哪一层：管理界面写入的是 DB system_settings 层（第四层，优先级最高）；配置文件里同名项会被它盖住，排查"改了文件为什么没用"先看设置页有没有同 key。
要不要开热重载：默认关闭（改完需重启）。设 CONFIG_HOT_RELOAD=1 开启后，AIP 只有运行期实时读取的少量字段（邮件 / 飞书 / WorkBuddy 的状态展示与启动判断、产品关闭指令的下游地址）会立刻生效；LLM key、邮件凭证、embedding、OAG、跨产品 apiClients 仍是构造期快照，要重启。
审计异步：审计日志异步落库，刚发生的操作稍等片刻再查。

做得好的场景

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

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

限制与不足

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

权限点是配置记录：v0.1 不在这里做行 / 列级强制过滤，强制执行依赖深度权限配置与安全服务。
审计异步落库：刚发生的操作有几百毫秒延迟，急查会漏。
无批量操作：没有批量建号、角色复制、权限继承。
严格参数校验：用户 ID 为 UUID，非法 ID 返回 400；缺 locked / 短密码直接 400。
只认 admin 角色：接口按角色判定，普通用户 403，无 token 401。
热重载默认关闭且只部分生效：不开 CONFIG_HOT_RELOAD 时行为与以前一致（改配置要重启）；开启后也只有运行期实时读取的少量字段生效。LLM 网关、mailer、embedding、OAG 服务、跨产品 apiClients 都是构造期快照。
密钥绝不热更：SECRET_KEY 与 masterKey 运行期更换会作废全部存量 token 与已加密数据，代码层面明确不做热更新。
Prompt 版本不能删生效中的那版：删除当前生效版本返回 409，须先回滚到其它版本；模板级删除会级联删掉该模板全部版本，两处入口不要混。

场景故事

故事 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 权限点是"配置记录"，强制执行依赖深度权限配置与安全服务；空对象提交会清空该角色的三类资源权限（表 / 列 / 行级），动作授权（ACTION_ACCESS）与功能授权（FEATURE_ACCESS）不受影响；权限目录来自已导入元数据，没导元数据时弹窗里就是空的；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 秒延迟，排查时稍等再刷新即可。

改了配置为什么没生效？配置分几层？

配置有四层，优先级由低到高：代码默认值 → config.yaml → 环境变量 → DB system_settings。管理界面写入的是最高层的 DB 设置，所以它会压过配置文件和环境变量——反过来，如果改了 config.yaml 却发现没变化，先到系统设置页看有没有同 key 的 DB 设置项把它盖住了。密文类设置项（setting_type=encrypted_string）不会被覆盖，避免把密文当明文写进配置。另外系统设置修改默认要重启 AIP 才生效；设环境变量 CONFIG_HOT_RELOAD=1 可以开启热重载（默认关闭），但 AIP 只是部分生效：邮件 / 飞书 / WorkBuddy 的状态展示与启动判断、产品关闭指令的下游 baseURL 这些运行期实时读取的字段会立刻变；LLM 网关、mailer、embedding、OAG 服务、跨产品 apiClients 与 SECRET_KEY 都不热更。

Prompt 的版本能单独删吗？

能。版本弹窗里每行有「删除本版」（DELETE /prompts/templates/:name/versions/:v）：版本不存在 404、版本号非正整数 400、成功返回 {deleted, name, version}。唯一限制是当前生效（active）的那一版不能删，会返回 409——active 是运行时读取生效版本的唯一标记，所以规则是"先回滚到其它版本，再删原版本"，生效版本那一行的按钮也是禁用的。列表行内的「删除」是另一回事：那是模板级操作，会级联删除该模板的全部版本。

能删掉 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 的"治理面"——用户、角色、权限、设置、Prompt 版本、审计，全部写操作留痕。设置写入的是四层配置里最高的 DB 层，热重载可选（默认关、AIP 部分生效，密钥绝不热更）；Prompt 编辑即出新版本，历史版本可单删但生效版本要先回滚。记住几个边界：权限点是配置记录、审计异步落库、接口仅 admin 可用、防呆自护（不能删自己）已内置。