
> 《micro-one-api 拆解》第 33 篇
> 代码核对：`v0.42.0` / `6d722b73`

---

## 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 端点、固定执行点、详情页 |

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

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

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

新端点是：

```text
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 权限被扩成写权限。

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

```go
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 用了绑定参数，并对 `!`、`%`、`_` 转义：

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

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

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

```sql
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]` 段 |


《micro-one-api 拆解》第 33 篇 代码核对：v0.42.0 / 6d722b73

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

后端

《micro-one-api拆解》第33篇代码核对v0.42.0版本，聚焦审计表只读API设计。新端点GET/api/v1/admin/operation-audits读取72条历史记录，固定执行点与IAM权限门限，支持筛选分页与actor用户名降级。三库索引迁移保障查询性能，CI25/25全绿通过。

代码解释

敏感数据

数据仓库

PostgreSQL

大数据

SQLite

路由

MySQL

JSON

腾讯云双十一大促

apigw

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

审计表里已经有 72 条记录：我为什么先补了一个只读入口-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐