审计表里已经有 72 条记录:我为什么先补了一个只读入口

micro-one-api 拆解第 33 篇(v0.42.0):审计表里已经有 72 条记录,却只能靠直连数据库看。这次先补一个只读入口——iam.audit.read 固定执行点、跨 schema 用户名回退、150 迁移索引与 Web 审计页,并写清验收边界。

《micro-one-api 拆解》第 33 篇 代码核对:v0.42.0 / 6d722b73(2026-11-12) 主要改动:只读业务操作审计端点与 Web 审计页 主要来源:release-v0.42.0、shared resource_write_audits 迁移、Admin/Web 审计实现


0. 写进表里的记录,不等于能被解释

v0.42.0 上线前,oneapi_admin.resource_write_audits 里已经有 72 条真实记录。它们来自之前的配置发布、备份、权限和其他资源写入,结构上一直存在,但我没有一个统一入口把“谁在什么时候、对哪个资源做了什么、结果怎样”读出来。

这并不代表审计没有写。resource_write_audits 在迁移 112 就建好了,写入路径也一直在记录 operation、actor、resource、decision versions、reason、时间和 result。缺的是读侧:没有 endpoint,没有页面,没有把 actor ID 变成人能看懂的用户名,也没有一个明确的权限门。

我先做的不是自动修复、导出或批量操作,而是一个只读入口。原因很简单:写审计表是业务事务的一部分,读审计表则可能泄露整个管理面的操作轨迹。先把读取边界做窄,再谈怎么用这些记录。

这篇核对的是 v0.42.0 的代码和 11 月 12 日的线上验收。项目仍然按我的单实例部署口径写,表里的 72 条记录不是“真实用户活动”,只是此前受控操作留下的审计数据。


1. 来源与表结构

这一篇没有新的业务写路径,核心是把已有的 shared audit table 读出来。来源分三层:

层 来源 关键事实
数据表 migrations/112_create_resource_write_audits.sql、migrations/postgres/112_create_resource_write_audits.sql event_id 主键;actor、operation、resource、decision_versions、reason、occurred_at、result;不保存资源正文和凭据
读取端 app/admin/internal/biz/operation_audit.go、app/admin/internal/data/operation_audit.go DO、repo 接口、筛选、排序、分页
入口与页面 app/admin/internal/server/operation_audit.go、app/admin/internal/service/operation_audit.go、web/src/pages/admin/OperationAuditsPage.tsx GET-only 端点、固定执行点、详情页

表结构本身已经把读取范围限得很小:

event_id, actor_user_id, operation, resource_id,
decision_versions, reason, occurred_at, result

没有请求正文,没有凭据,没有任意对象 JSON。页面能看到的是“某个 actor 对某个 resource 做过某 operation,结果是 success/failure,以及当时的决策版本和原因”。这比“把所有写操作 payload 都存一份”更容易解释,也避免审计表自己变成另一个敏感数据仓库。

新端点是:

GET /api/v1/admin/operation-audits

它没有复用 IAM 授权审计事件接口。两者读的表和语义不同:IAM audit 关注角色、成员和授权决策;业务操作审计关注 resource write 的 operation、resource ID 和决策版本。把两者合成一个页面会让权限和分页语义都变模糊。

这里也没有把审计读取做成写接口的反向投影。写路径可以经过多个 owner,每个 owner 自己决定审计出现时机;读路径只认已经落库的 immutable row,不重新拼业务对象,也不根据当前配置推断当时发生了什么。decision_versions 是写入时留下的版本证据,页面只格式化展示;如果用当前版本重算,历史记录就会被现在的状态污染。

这也是我不把导出放在第一版的原因。导出会扩大数据外带面,还要回答文件名、权限、脱敏、保留和下载缓存;列表页先解决的是“有没有、是谁、结果如何”,不是把所有字段搬出去。读侧先固定 GET、no-store、分页上限和固定执行点,后面要加能力再单独审。


2. 读共享表,不把审计复制一份

新端点直接读 shared resource_write_audits,没有为页面再建一套“审计视图表”。这有两个直接后果:

  • 写入路径不用改,已有审计记录也不会因为页面发布而重算;
  • 读取必须自己处理跨 schema 的 actor 信息,不能指望一个 JOIN 解决。

actor 用户名在 Identity 的用户表里,审计表只在 oneapi_admin 中保存 actor_user_id。跨库不能 JOIN,所以读取分两步:

  1. Admin repo 从 resource_write_audits 查出当前页的记录;
  2. Service 对页面中唯一的 actor ID 去重,逐个调用 Identity GetUser 补 actor_username。

每次调用有 2 秒超时。权限不足、账号已删除、Identity 短暂不可用,都只让该字段为空,前端回退显示 #<id>,title 保留数字 ID。用户名不写回审计表,避免以后改名造成历史和当前不一致。

这里我没有把用户名解析失败当成审计读取失败。审计记录本身仍然有效;只是页面少了一个更友好的标签。权限不足时立即停止后续 actor 查询,避免一页 100 条记录对 Identity 打 100 个注定失败的请求。服务层回归专门构造了同一页里两个不同 actor,要求只调用两次 GetUser;另一个用例返回 PermissionDenied,要求整页仍 200、只调用一次、用户名为空。


3. 一个固定执行点,而不是一个路由白名单

控制台端点走 console IAM guard,HTTP 层只允许 GET,注册在 owner-route allowlist 里;兄弟路径没有前缀授权,未注册的 /export 仍然返回 404。方法不对返回 405,避免 GET 权限被扩成写权限。

服务层还会再做一次授权:

s.AuthorizeSection(ctx, "admin.business_audits", true, "iam.audit.read")

admin.business_audits 是固定的执行点声明,要求 iam.audit.read + global scope。这个执行点编译在 domain/authorization 里,不是运行时随便拼出来的字符串。也正因为如此,admin-api 和 identity-service 必须部署同一份代码:只更新 admin-api 时,identity 可能返回 ErrIAMInvalidRelation,最终表现成 authorization denied。

线上默认只有 root 角色持有 iam.audit.read,platform_admin 没有。需要给非 root 运维账号使用时,要显式补授权,不能把权限放宽到所有管理员。

路由检查还给了一个很实用的负例证据:新端点未认证时返回 401,说明它进入了 guard;同一个兄弟路径返回 404,说明不是整个 /api/v1/admin/* 被放行。两者一起看,才能证明“路由存在且受保护”,单看 401 不够。服务层如果缺 reader,则返回 503 operation audit unavailable,不是 500;审计查询失败不能被伪装成空列表。


4. 查询边界:先校验,再触库

一个审计列表最容易被写成 WHERE 1=1 加一堆字符串拼接。这里先做了三类限制。

第一,分页和筛选在触库前校验:

  • 页码从 1 开始,默认 20 条,最多 100 条;
  • actor_user_id、开始/结束时间必须能解析为整数;
  • 开始时间不能晚于结束时间;
  • result 只接受 success / failure;
  • operation 最长 160,resource ID 最长 128。

非法输入返回 400 invalid operation audit query,不会查出一个空列表再让调用方猜。

第二,operation 是前缀匹配,不是模糊注入。SQL 用了绑定参数,并对 !、%、_ 转义:

strings.NewReplacer("!", "!!", "%", "!%", "_", "!_").Replace(value) + "%"

查询使用 LIKE ? ESCAPE '!'。否则用户输入一个 % 就会变成通配符,审计读取的范围会被悄悄扩大。

第三,分页和排序固定。Count 和列表使用同一个 filter 构造器,按 occurred_at DESC, event_id DESC 排序,避免同一毫秒内翻页出现重复或漏项。Admin 150 迁移补了两个索引:

resource_write_audits_time (occurred_at, event_id)
resource_write_audits_operation_time (operation, occurred_at, event_id)

线上用 FORCE INDEX 查过,执行计划显示 Backward index scan; Using index。这不是微优化,而是让审计列表的默认路径从一开始就有索引可走;迁移本身只追加索引,不改表和已有数据。

数据层回归覆盖 SQLite、MySQL、PostgreSQL 三方言:四个事件分别按 actor、operation prefix、resource + result、时间区间查询,第一页第二页新旧顺序都核对。这个测试同时证明 Count 和列表用的是同一组条件,不能出现“总数是 3、列表只剩 1 条”的口径漂移。


5. Web 页面:把权限受限和空态分开

前端新增懒加载页面 /admin/operation-audits,入口放在「监控与分析」分组。页面准入和接口调用都要求 iam.audit.read,没有权限时显示“没有操作审计查看权限”,而不是把 403 渲染成空列表。

筛选支持操作人 ID、操作码前缀、资源 ID、结果、开始时间和结束时间。结束时间按整分钟包含:用户选 18:30,查询要覆盖到该分钟的末尾,而不是停在 18:30:00 漏掉后半分钟记录。页面测试直接断言 datetime-local 的 2026-11-12T10:00 会发送 10:00:00.000 + 59,999ms。

页面有加载骨架、空态、错误重试和权限受限四种状态。详情弹窗展示事件 ID、时间、操作人、结果、操作代码、资源 ID、原因和格式化后的决策版本。operator 字段的数字 ID 始终保留,用户名只是补充标签。

这套页面没有做写入、删除、导出或批量处理。审计读侧先保持只读,是因为“能看”与“能改”的风险不同;删除一条审计记录会直接破坏事后解释能力,不能顺手塞进列表页。页面还把 decision_versions 按 JSON 格式化展示,失败时保留原文,不把坏数据悄悄丢掉。


6. 部署和验证:同源、索引、真实记录不变

11 月 12 日的部署边界是:

  • 新增 Admin 150 三方言索引迁移;
  • admin-api 与 identity-service 必须同源部署,因为执行点声明在共享 authorization 代码里;
  • Web dist 独立更新,admin-api 镜像重建不会自动更新宿主机挂载的前端;
  • 新端点未认证返回 401,兄弟路径返回 404;
  • 审计表原有 72 条记录未被改动;
  • Cache-Control: no-store,审计页和接口不被浏览器或中间缓存保存。

CI run 43222139066(develop 3480fafe)25/25 job 全绿,包含 Backend 的 OpenAPI、测试、race、架构、commit body、迁移治理、RBAC、IAM browser、生成文件一致性,Frontend 的 lint、test、critical coverage、build,以及 Integration、MySQL/Postgres migration smoke 和 18 个 Docker build。

本地还跑了 gofmt、Go 全量单测与 race、architecture、migration-check、RBAC 矩阵 962 行、IAM browser 13 项、markdown links 369 条、go mod tidy -diff、wire-check 和 api-check。线上做的是同源工作区构建,admin-api 的 source.digest 与提交后本地 rbac-source-digest.py 一致;identity-service 同一天早前部署了同一份执行点代码。

仍有两个诚实的限制:

  • 完整登录态数据验收需要 root 或已获 iam.audit.read 的账号,本次线上只验证了 401 / 404 路由和索引计划,没有把真实登录后的全页数据读取写成通过;
  • 本机 web 全量 vitest 有 1 例既有 jsdom 超时(PlaygroundPage.test.tsx:64,756 例中 1 例;单文件复跑 15/15 通过),test:critical 和 build 单独通过,以 CI Frontend job 为准。

7. 这轮测试实际守住的分支

这篇的代码量不大,但读侧每一层都有自己容易漏的分支。测试不是只证明“能返回 200”,而是分别守住下面这些边界:

层 红灯条件 现在的断言
biz page=0、page_size=500、result=unknown、start > end 默认 page/page_size 归一化,超过 100 截断,非法条件在触库前返回 typed error
data 同一时间排序不稳定、Count 和列表 filter 不一致 SQLite/MySQL/PostgreSQL 三库都按 occurred_at DESC, event_id DESC 翻页,总数和列表同源
service 每个 actor 调一次 Identity、权限拒绝后继续打满一页 同 actor 只查一次;PermissionDenied 后停止后续查询,仍返回审计页
server 非 GET 被路由白名单放行、未注册兄弟路径被前缀授权、缺 reader 返回 500 GET-only、405、兄弟路径 404、缺 reader 503、成功响应 no-store
Web 权限受限被渲染成空态、结束分钟少 59.999 秒 权限/错误/空态分开;结束时间按整分钟包含,筛选项逐个写入 query

这些测试里我最看重的是 service 和 server 两层。前者证明“用户名只是增强,不是读取前置条件”;后者证明“路由存在”和“路由受保护”是两件事,不能只看一个 401。data 的三库回归则防住了一个很常见的分页问题:第一页按时间倒序,第二页没有 event ID 兜底,同一毫秒内就会重复或漏项。


8. 这张审计台证明了什么

问题 证据 还没证明什么
旧审计记录能不能被读出来 shared 表、Admin repo、三库 filter/order/pagination、150 索引 真实登录态下的完整页面读取
谁在操作 actor ID + 2s Identity 查询 + 用户名回退 所有历史 actor 都仍存在或可解析
权限有没有做窄 admin.business_audits + global iam.audit.read,GET only,兄弟路径 404 platform_admin 默认授权是否足够
查询会不会被通配符放大 %/_/! 转义,绑定参数 超大表的长期查询性能
线上是否改过审计 72 条记录前后不变,端点 no-store,迁移只加索引 未来写入路径的完整性
页面能不能用 懒加载、筛选、分页、详情、权限/错误/空态、CI 25/25 真实 root 之外的运维账号旅程

我先把读入口补上,是因为审计数据已经存在,缺的是可解释性和权限门。下一步不该急着做导出和自动处置,而是等真实登录态、非 root 运维账号和更大的审计量出现后,再决定分页、检索和保留策略要不要继续加。现在这个页面能回答“表里记了什么”,但还不能替我回答“每条写入都一定完整”。

这一篇写完后,续篇的当前事实停在 v0.42.0。下一篇如果要写,应该先有一次真实的审计读取验收,而不是继续堆一个看起来更完整的控制台。

代码与阅读入口

想核对的内容 仓库入口
原 shared audit 表 migrations/112_create_resource_write_audits.sql、migrations/postgres/112_create_resource_write_audits.sql
DO、repo 接口、筛选与分页校验 app/admin/internal/biz/operation_audit.go、app/admin/internal/biz/operation_audit_test.go
共享表读取、前缀转义、排序 app/admin/internal/data/operation_audit.go、app/admin/internal/data/operation_audit_test.go
actor 用户名补全与 2 秒降级 app/admin/internal/service/operation_audit.go、app/admin/internal/service/operation_audit_test.go
只读路由、错误码和 no-store app/admin/internal/server/operation_audit.go、app/admin/internal/server/operation_audit_test.go
IAM 执行点与路由白名单 domain/authorization/execution.go、app/admin/internal/server/resource_authorization.go、docs/design/rbac/entry-matrix.csv
三方言索引 migrations/150_add_resource_write_audit_read_indexes.sql、migrations/postgres/150_add_resource_write_audit_read_indexes.sql、migrations/sqlite/150_add_resource_write_audit_read_indexes.sql
Web 页面与路由 web/src/pages/admin/OperationAuditsPage.tsx、web/src/pages/admin/OperationAuditsPage.test.tsx、web/src/router.tsx、web/src/lib/admin-permissions.ts
发布与验收 docs/releases/release-v0.42.0.md、CHANGELOG.md 的 [0.42.0] 段

上一篇是第 32 篇:新入口与结算边界。