日志审计

审计日志

HeteroFlow 的审计体系由两条相互独立的留痕通道构成：租户审计日志（tenant_audit_logs 表）由审计中间件对所有修改型 API 请求自动逐条留痕，回答"谁在何时对什么资源做了什么、结果如何"；平台日志（logs 表）由关键业务节点主动写入 AUDIT 级事件，记录登录、任务生命周期、推理后端摘除等平台侧大事。前者面向多租户合规与追责，行级完整、带脱敏与保留期管理；后者面向运维排障，按模块与级别过滤浏览。

两条通道的分工可以从一个具体问题感受：想知道"训练任务 tg-x 昨天被谁扩容到 8 副本"，查租户审计页——那里有操作者、IP、请求摘要、状态码与耗时；想知道"推理后端昨晚为什么被摘除"，查平台日志页——网关健康探测把摘除原因写成了 AUDIT 行。一者证明人的行为，一者记录系统的事件。

租户审计的设计立场是自动化优先：只要请求方法属于 POST/PUT/PATCH/DELETE，中间件就无差别留痕——包括被权限层拒绝的请求（审计层位于 scope 校验之前，越权尝试本身就是最有价值的审计素材）；业务代码无需也无处调用"记一条审计"。平台日志则相反，由各业务模块在自己认为关键的时刻显式写入，二者互不替代。

功能总览

审计中间件的位置：为什么被拒绝的请求也有审计行

理解租户审计的覆盖面，关键在中间件链的排布。一次 API 请求从外到内经过：指标采集 → panic 恢复 → 请求体大小限制 → 租户上下文注入 → 审计 → 权限范围校验（scope）→ 限流 → 业务 handler。审计层刻意排在权限校验之前——一个被 403 拒绝的越权尝试、一个被 409 挡下的非法删除，都会先留下完整审计行再被拒绝。对追责而言，"谁试图做什么但没做成"与"谁做了什么"同样重要。

请求体的留痕走旁路捕获而非预读：中间件把请求体包一层透明管道，业务 handler 读多少就透传多少（逐字节不动），审计侧同步留一份最多 4096 字节的副本。这个设计是用一次真实 P0 事故换来的——早期实现预读 4096 字节后把截断内容替换回请求体，结果任何超过 4096 字节的写请求（带训练日志的任务完成上报实测 5958 字节）到 handler 手里都是半截 JSON、解析必然 400，成功的训练永远无法推进终态，GPU 被白占到 20 分钟超时后误记为失败。如今截断只发生在审计副本一侧，业务路径零感知。

同样在这条链上，审计的响应包装层实现了 Unwrap 透传——没有它，推理代理放宽写超时所需的 SetWriteDeadline 会被包装层挡住而静默失效，高并发压测（450 并发）曾因此大面积失败。审计层作为全请求的必经包装，其工程细节直接牵动整条服务的能力边界。

审计事件全类型清单

租户审计（tenant_audit_logs）的覆盖面

租户审计按"请求形态"而非"业务枚举"覆盖——任何修改型请求都留痕，因此下表按业务语义归类，实际覆盖等于全部 mutating 路由：

平台日志（logs 表）的 AUDIT 写入点

平台日志由业务模块显式写入，当前共 14 处（grep Level: "AUDIT"/Level: "INFO" 全量核实）：

INFO/WARN/ERROR 级别在筛选器与统计卡片中可用，但当前代码的写入方只产生 AUDIT 与 INFO 两级行。

留痕字段与不可抵赖性

租户审计每行 20 列，构成完整的追责证据链——谁（user_id + IP + User-Agent）、何时（created_at）、对什么（method + path + resource_type + resource_id）、做了什么（request_summary）、结果如何（status_code + error_message + duration_ms）：

脱敏是硬规则：摘要落库前对 JSON 体递归脱敏，低歧义子串（password/passwd/secret/apikey/api_key/authorization/credential）子串包含即替换为 [REDACTED]，因此 ssh_password、root_password 这类未来新增字段天然覆盖；高歧义词（key/token）只在精确等于或 _key/_token 结尾时命中，keyword/keyboard/tokenizer 不误伤。非 JSON 请求体不落原文只记字节数，超 4096 字节的请求体不落半截 JSON（无法可靠脱敏）只记超限事实。

关于"不可抵赖"的如实边界：审计写入是异步旁路（独立 goroutine、5 秒超时），不与业务事务同生共死——业务成功而审计写库失败时，失败会被 WARN 日志如实记录但主流程不受影响，极端情况下存在单行丢失的可能。它是为合规追责设计的完整流水，不是防篡改账本：行存于同一 PostgreSQL，具备数据库权限的主体理论上可改写。日志审计页的检索过滤（时间、方法、路径、状态码）均由服务端执行，防止越权用户通过前端绕过。

保留期与清理策略

租户审计表有完整的生命周期管理：保留期默认 365 天（环境变量 HETEROFLOW_AUDIT_RETENTION_DAYS 可配，下限 30 天——配得更低会回落到默认值，避免清理退化成"删光审计"）。清理由审计写入自身触发：每累计 500 条写入、或距上次清理超过 6 小时二者其一即触发一次（低流量部署不会因攒不满计数而停摆），独立 goroutine 异步执行、CAS 防重入、60 秒超时。删除按 5000 行一批的短事务推进——此前单条大 DELETE 长时间持锁，超时回滚后下次从头再来永远删不完；分批后超时只丢最后一批，进度可累积。

agent 例行回写豁免（K74⑥）是审计表健康度的关键治理：历史上 agent 心跳每 5 秒一跳全部入审计，15 节点一天灌入约 26 万行/170MB，审计价值为零却把真正的管理操作淹没。现心跳与纯日志回写在"agent 系统密钥调用 + handler 标记例行 + 未标记必须保留（如心跳首次注册节点）+ 无运营者代报 + 状态码 < 400"全部满足时跳过留痕；终态上报、状态 CAS、节点显式注册、文件/镜像/分片通道请求都不标记，照常审计；被拒请求照记。

平台日志（logs 表）当前没有自动清理：存储层留有按天数清理与清空的方法，但无任何生产调用点接线，该表只增不减，需要运维自行清理（见已知边界）。

页面功能介绍

/tenant/audit-logs 租户审计页

多租户导航"操作审计"入口，登录即可见页面，数据接口要求租户管理员权限（见下方权限差异）。十列审计明细表，每页 50 条。

/logs 平台日志页

仅平台管理员可见（AdminRoute 守卫 + 后端 system:read 权限），60 秒自动刷新。

模块下拉的中文翻译映射（后端模块名 → 界面显示名；列表里出现映射外的新模块时按原名显示）：

权限差异一览：

member/viewer 登录后导航里能看到"操作审计"入口，但打开后数据请求被后端 403 拒绝并显示错误横幅——权限收敛在服务端强制执行，前端不隐藏入口只是体验上的已知瑕疵。审计读取收紧为管理员级是刻意决策：审计摘要历史上出现过明文凭据，收紧前任意已认证成员可读走全租户审计流（#111 修复）。

后端逻辑概念表

API 参考

租户审计接口有严格的方法守卫：非 GET/HEAD 一律 405（此前用 DELETE 也能读走审计列表，已收敛为只读语义）。列表为空时返回 [] 而非 null。

租户审计查询示例（按日期范围取第 2 页）：

curl -H "Authorization: Bearer <token>" \
  "http://localhost:3333/api/v1/tenant/audit-logs?start=2026-10-01&end=2026-10-05&limit=50&offset=50"

响应骨架（字段与顺序同 ListByTenant 的 SELECT 列一一对应）：

{
  "tenant_id": "acme",
  "limit": 50,
  "offset": 50,
  "logs": [
    {
      "id": 1024,
      "tenant_id": "acme",
      "user_id": "u-7",
      "method": "POST",
      "path": "/api/v1/task-groups",
      "resource_type": "task-groups",
      "resource_id": "",
      "status_code": 200,
      "error_message": "",
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0",
      "request_summary": "{\"training\":{\"n_nodes\":2},\"task\":{\"gpu_required\":8,\"gpu_type\":\"nvidia\"}}",
      "duration_ms": 63,
      "target_tenant_id": "",
      "acted_for_user_id": "",
      "resource_kind": "training",
      "resource_gpu_count": 8,
      "resource_node_count": 2,
      "resource_gpu_type": "nvidia",
      "created_at": "2026-10-03T09:15:22Z"
    }
  ]
}

平台日志查询示例（AUDIT 级别 + 关键字搜索"任务取消"，URL 编码后传参）：

curl -H "Authorization: Bearer <token>" \
  "http://localhost:3333/api/v1/logs?level=AUDIT&search=%E4%BB%BB%E5%8A%A1%E5%8F%96%E6%B6%88&limit=50"

响应载荷为 {data: [...], total: n} 双层结构，日志行按时间倒序，字段为 id/timestamp/level/module/message/user/node_id/task_id。

已知边界

1. 租户审计页日期筛选当前不生效：前端把日期转成 RFC3339 发送，后端按纯日期（YYYY-MM-DD）解析且失败静默忽略，两边格式不匹配导致 start/end 条件实际被丢弃（Go time.Parse 对 RFC3339 输入报 extra text 已实测复现）。API 直接调用传 YYYY-MM-DD 正常工作；前端修复待排期。

2. 平台日志无自动清理：logs 表的清理方法在存储层存在但无生产调用点，表只增不减；租户审计表则有 365 天自动保留期。长期运行需运维自行清理 logs 表。

3. WARN/ERROR 级别无当前写入方：筛选器与统计卡片支持四级，但现有代码只产生 AUDIT 与 INFO 行，两张卡片常态为零。

4. 方法过滤仅当前页生效：租户审计接口无方法参数，前端方法下拉只过滤本页 50 条，翻页后需重新面对全量——界面已如实标注。

5. member/viewer 可见审计入口但无数据权限：导航不按租户角色隐藏"操作审计"，普通成员打开得到 403 错误横幅；权限本身由服务端强制，无泄露。

6. 审计写入是异步旁路：独立 goroutine 5 秒超时，写库失败只记 WARN 不阻断业务，极端情况下单行可能丢失且不可补录（请求体已消费完毕）。

7. 审计行为防篡改能力：行存于同一 PostgreSQL，具备库权限的主体理论上可改写；平台未提供哈希链/外部锚定等防篡改机制，合规场景如有硬要求需另行建设。

8. 系统日志时间筛选的格式挑剔：后端按 RFC3339 严格解析，解析失败静默忽略该条件；前端 datetime-local 控件原生值不含秒与时区，经 API 调用时请传完整 RFC3339（如 2026-08-19T10:30:00Z）。

9. 敏感读范围刻意收窄：当前只有整租户导出一个 GET 端点纳入审计；把所有 GET 都记会淹没审计表并拖慢读路径，新增敏感读端点需在登记表显式登记。

<!-- 状态标注说明: 本文全部能力为[已实现]口径——生产代码已实现并在开发环境长期运行；已知边界第 1/4 条为前端体验缺陷如实记录 -->