访问控制 · LightGotham · frontend-intro-v5

1. 页面概览

访问控制页（/gotham/access）实现 Gotham 的 ABAC（属性基访问控制）：维护「allow/deny」策略（支持优先级排序、deny 一票否决），并提供前台评估测试台，用主体/资源/环境属性 + 动作现场试算决策，每次评估落「评估留痕（traces）」备查。一句话总结：本页是情报对象访问策略的创建、试算与留痕管理中心。

2. 访问入口

2.1 路由与菜单

path /gotham/access、name GothamAccess、title Gotham 访问控制，挂在父路由 /gotham（GothamLayout）下，侧边栏菜单项「访问控制」。源码 action/web/src/views/GothamAccessPage.vue。

2.2 认证与权限

子路由 meta requiresAuth: true；请求经 gothamClient.js 附带 aip_token，401 用 gotham_refresh_token 自动换新。

2.3 端口与 API 前缀

Gotham 后端 18083，前缀 /gotham-api（baseURL /gotham-api/v1，Vite 代理重写为 /api/v1）。

3. 界面布局

Gotham 访问控制（ABAC）                [刷新]
[操作结果提示 alert（可关闭）]
ABAC 评估测试台：roles / user_attrs / resource_attrs / action /
                environment_attrs[一键插入环境属性样例] / user_id
                [执行评估][填充机密样例][填充内部样例]
                → 决策 decision(ALLOW/DENY) + reason + 命中策略
                [card-note：environment_attrs 为自由键值对，样例仅示意]
创建 ABAC 策略：名称 / 效果 / 优先级 / 动作 / subject_attrs /
               resource_attrs / environment_attrs[一键插入环境属性样例] / 描述
               [创建策略]
策略列表（ID/名称/效果/优先级/动作/主体/资源/状态/操作）
评估留痕（traces，ID/时间/用户/决策/命中策略/上下文）

评估测试台：六输入 + 按钮，环境属性输入旁有「一键插入环境属性样例」，结果区按决策着色（result-allow 绿 / result-deny 红）。
创建策略卡：八个字段，名称必填，效果默认 deny；环境条件输入旁同样有「一键插入环境属性样例」。
策略列表：展示启停状态与条件 JSON，行内仅「停用/启用」切换。
评估留痕：展示最近 50 条评估记录与命中策略。

4. 交互元素

控件	位置	含义与作用
输入「主体（roles，逗号分隔）」等六项	评估测试台	试算输入；属性类输入为 JSON，默认 `{"role":"analyst"}`/`{"classification":"internal"}`
按钮「执行评估」	评估测试台	`POST /access-policies/evaluate`，非法 JSON 时提示「属性 JSON 格式错误」
按钮「填充机密样例」「填充内部样例」	评估测试台	快捷回填 user_attrs/resource_attrs（secret / internal 两档）
按钮「一键插入环境属性样例」	评估测试台	把 environment_attrs 回填为 `{"time_range":"14:30","ip_prefix":"10.0.0.5"}`；键名沿用后端注释/测试口径
按钮「一键插入环境属性样例」	创建策略卡	把 environment_attrs 回填为 `{"time_range":["08:00","20:00"],"ip_prefix":["10."]}`；策略侧为范围/前缀数组
输入「名称 *」「效果」「优先级」	创建策略卡	效果 allow/deny（deny 一票否决）；优先级数字越大越先评估
按钮「创建策略」	创建策略卡	`POST /access-policies`，name 必填，条件字段非法 JSON 时报错
按钮「停用」/「启用」	策略列表	`PUT /access-policies/:id` 传 `{enabled}` 切换状态
「刷新」按钮	页面头部	并行重拉策略与留痕两个列表

5. 后端关联

端点表（源码 action/products/gotham/server/server.go，处理器 handlers_abac.go）：

方法	路径	用途
GET	`/access-policies`	策略列表
POST	`/access-policies`	创建策略（name/description/effect/priority/action/subject_attrs/resource_attrs/environment_attrs/enabled）
PUT	`/access-policies/:id`	更新（本页用于启停）
POST	`/access-policies/evaluate`	试算：body 含 user_id/roles/user_attrs/resource_attrs/action/environment_attrs，返回 decision+reason+matched_policy_ids
GET	`/access-policies/traces`	评估留痕，`?limit=50`

决策口径：deny 一票否决——命中 deny 策略优先拒绝；否则按优先级（数字大者先）匹配 allow/deny；命中策略 id 列表随决策返回，前端以 matched_policy_ids 展示。
留痕机制：每次评估调用后端都会落一条 trace（含 user_id、decision、policy_ids、context），前端评估成功后自动刷新留痕列表；留痕与策略为同一服务（action/products/gotham/abac/）。
环境属性语义（environment_attrs）：后端为自由键值对映射（map[string]any），没有固定字段清单，键名由使用方约定、且评估请求与策略必须一致。matchAttr（abac/service.go:533-606）支持的约定形式：两元素数组 ["HH:MM","HH:MM"] 视为时间段、以 . 结尾的字符串视为 IP 前缀、"*" 通配、数组包含匹配。后端注释示例 {"time_range":["08:00","20:00"],"ip_prefix":["10."]}（abac/models.go:95），测试用的评估值 {"time_range":"14:30","ip_prefix":"10.0.0.5"}（server/abac_views_test.go:669-687）；前端两处「一键插入环境属性样例」即按此口径，并明确标注「样例仅示意、字段以服务端为准」。
试算与授权分离：测试台仅为调试工具，试算结果不改变真实对象授权；实际授权由后端 PEP（server/abac_pep.go）在请求链路上执行。

6. 权限与安全

页面全部接口受 JWT 保护，无公开端点。
策略效果 deny 一票否决，防止误放行机密对象；优先级用于解决策略冲突。
留痕记录每次评估的决策依据（命中策略、上下文），满足审计追溯需求。

7. 常见问题与排错

执行评估提示「属性 JSON 格式错误」：点「执行评估」后无结果直接报错；原因是 user_attrs/resource_attrs/environment_attrs 任一为非合法 JSON；处理：用「填充机密样例/填充内部样例」覆盖回合法样例，或修正手写 JSON。
评估结果与预期不符：命中 deny 策略却返回 allow，或反之；原因是策略优先级、enabled 状态、条件字段与输入属性不匹配；处理：核对策略列表的优先级与启停状态，检查试算属性是否落在策略条件内；deny 命中即拒绝。
留痕列表为空：traces 表无数据；原因是尚未执行过评估，或后端留痕服务未启用；处理：先执行一次「执行评估」再刷新；仍空则查后端 abac 日志与 traces 表。
创建策略失败：提示「创建策略失败」；原因是名称为空，或条件 JSON 非法；处理：确认名称已填；条件字段留空或填合法 JSON（如 {"role":"analyst"}）。

8. 已知缺陷与边界

项	说明
留痕截断	traces 仅展示最近 50 条，无分页翻页
试算不落授权	评估结果仅展示与留痕，不改变实际访问控制
环境属性无固定字段	`environment_attrs` 是自由键值对，键名须与策略一致；「样例」只给 `time_range`/`ip_prefix` 两个约定键，不代表服务端仅支持这些字段，其余键名需自行约定
样例非强约束	前端不做键名合法性校验，「一键插入样例」仅为格式演示，最终以服务端匹配结果为准

注：策略删除入口已于 2026-09-06 修复（admin 可见删除按钮，调用后端 DELETE）。

注：2026-09-13 修订——环境属性（environment_attrs）在评估测试台与创建策略卡两处各加「一键插入环境属性样例」按钮，键名取自后端注释/测试口径（time_range 时段、ip_prefix IP 前缀），并附常驻说明「样例仅示意、字段以服务端为准」；未新增任何后端字段或接口（environment_attrs 仍为自由键值对）。