- 审计注册表为可由系统任务、定时任务发起的动作声明落库策略(always/on_success/outcome/log_only/none),未声明按 log_only - 人工、开放接口、个人客户、外部系统发起的动作始终写审计表 - log_only 写所在服务 app.log(logger=audit),不含快照 - 对接日志不再补写 integration.attempt_started,无上游审计时 audit_event_id 为空 - 新增 audit.persist_overrides 按动作覆盖策略 - 审计覆盖扫描要求机器动作必须声明策略 - 新增 OpenSpec 提案 refactor-audit-log-persistence 与技术方案文档 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
38 KiB
审计日志写入改造技术方案
日期:2026-11-05 状态:方案已定,未实施(结论见第 10 节) 关联:
openspec/changes/add-audit-integration-write-switches(全局写入开关,本方案是其后的"按动作分级") 范围:本方案基于Iteration/8-11迭代实施,只部署到测试环境(推送 8-11 由.gitea/workflows/deploy.yaml自动部署)。本方案不修改生产环境的代码、配置或服务;第 1 节的生产数据只用来说明问题和估算效果。
1. 背景
1.1 现状数据(生产近 14 天,只读统计)
| 指标 | 数值 |
|---|---|
tb_audit_event 日均新增 |
约 122 万条(含停机重试风暴);扣掉风暴约 20 万条 |
机器发起(system_task / scheduled_job)占比 |
99% 以上 |
| 人、开放接口、个人客户、外部系统发起 | 约 1,210 条/天 |
| 每条事件含索引 | 约 1.9 KB;每条资源快照约 1.2 KB;平均 2–3 条资源 |
| 日均新增存储 | 约 6 GB(风暴期)/ 约 1 GB(平时) |
| 索引数 | tb_audit_event 14 个、tb_audit_event_resource 7 个、tb_integration_log 13 个 |
测试环境日均约 12.6 万条,几乎全是系统任务:流量同步 5.6 万、扣减 2.6 万、网络状态同步 2.5 万、优先轮询约 1.4 万。
1.2 问题
- 审计表被当成过程日志用。 每次轮询同步、每次扣减、每次对接调用开始、每次失败重试都写一条事件加 2–3 条资源快照。一次业务动作产生多次写入,而且每次写入要维护 21 个索引。
- 失败重试没有收敛。 退款后处理停机失败(
refund.process_asset)和自动停机失败(iot_card.auto_stop),每重试一次就写一条审计。11-05 10:16–11:47,86 张卡产生了 26.1 万次停机失败,一个风暴就占了当天审计量的六成以上。 - 对接日志顺带写审计。
integrationlog.Repository.Start在没有上游审计事件时,会补写一条integration.attempt_started(internal/infrastructure/integrationlog/repository.go:119),这一项每天约 45.6 万条。它与tb_integration_log本身完全重复。 - 后果。 11-03 生产 PostgreSQL IO 打满,轮询停摆约 1.7 天,审计和对接日志的写入与留存扫描是主要 IO 来源之一。
1.3 老系统做法(/home/zoujin/works/golang/kg/qc,供参考)
- 人工后台操作:写
tbl_system_log。 - 业务过程:按业务各写一张表,如
tbl_order_log、tbl_card_wallet_auto_renew_log、tbl_next_month_log,以及充值、短信日志。 - 下游代理调用我方接口:只这一类写
tbl_agent_pool_api_call_log。 - 网关调用和轮询:全部写 log4j 按天滚动的文本日志,不进数据库。
2. 目标与原则
目标:审计表只回答两个问题:
- 人(或代表人的外部系统)做了什么;
- 钱和套餐、卡的业务状态是怎么变的。
审计日均降到几千条,一年不到 10 GB,不再依赖归档和清理来扛量。
原则:
| 原则 | 说明 |
|---|---|
| 人工操作全留 | 后台账号、个人客户、开放接口、外部系统发起的动作,成功和失败都写审计 |
| 机器动作只留"结果" | 系统任务和定时任务只在资金或业务状态真正改变时写审计;无变化、同步、读取不写 |
| 每次失败都可查,审计只记结论 | 自动重试的每一次尝试都完整记在业务尝试记录表里(时间、第几次、错误码、上游返回),可分页查询;审计只记这件事的最终结论:成功,或重试用尽转人工 |
| 过程数据去业务表 | 已有专门记录表的(停复机记录、采集记录、扣减效果、日流量),审计不再重复写 |
| 排查用的走文本日志 | 只用于排查、不需要按业务查询的,写入现有应用日志 app.log,沿用现有轮换,由日志同步服务器归集 |
| 不改变业务结果 | 写不写审计,都不影响业务事务成功与否(与现状 Append 吞错一致) |
3. 数据分层
| 层 | 存储 | 放什么 | 保留 |
|---|---|---|---|
| L1 审计 | tb_audit_event + tb_audit_event_resource |
人工操作;机器发起的资金、套餐生命周期、停复机成功等状态变化 | 按现有留存策略 |
| L2 业务记录 | 各业务专表 | 停复机调用 tb_card_stop_resume_record、流量采集 tb_card_traffic_collection、扣减效果与日流量、对接调用 tb_integration_log、退款单上的后处理状态 |
按各表策略 |
| L3 文本日志 | 现有应用日志 app.log(zap JSON + lumberjack 轮换) |
机器过程类动作的结构化日志,例如停机原因更新、网络状态同步、通知投递、优先轮询、流量重置明细 | 沿用 logging.app_log 轮换;长期留存由日志同步服务器负责 |
| L4 不写 | — | 与 L1/L2 完全重复的,例如 integration.attempt_started |
— |
4. 动作去向清单
4.1 保留在审计(L1)
人工及外部发起(约 1,210 条/天,全部保留):
| 发起方 | 日均 | 主要动作 |
|---|---|---|
| 后台账号 | 约 404 | 手动刷新卡、设备切卡、回收、设 WiFi、手动复机、改套餐到期、设备重启、下单、退款、审批、登录等 |
| 开放接口 | 约 612 | 下单、代理钱包扣款、开放接口复机 |
| 个人客户 | 约 182 | 绑资产、建手机号关联、更新微信身份、绑手机号 |
| 外部系统 | 约 9 | 支付确认、外部回调接收 |
机器发起但改变资金或业务状态(方案 A 约 3,510 条/天):
| 动作 | 日均 | 方案 B 去向 |
|---|---|---|
iot_card.auto_start 自动复机 |
1,127 | 移到 L2 停复机记录 |
package_usage.reset_traffic 流量重置 |
1,049 | 移到 L2(套餐自身的重置时间加日流量记录) |
iot_card.auto_stop 自动停机,仅成功 |
380 | 移到 L2 停复机记录 |
commission.calculate 分佣计算 |
238 | 保留 |
package_usage.expire / activate / 退款失效 |
176 / 90 / 6 | 保留 |
| 导入建卡、建设备、设备分配 | 93 / 52 / 44 | 保留 |
| 系统下单、订单套餐失效明细、员工代收账单 | 77 / 74 / 51 | 保留 |
| 外部回调接收、审批同步、退款批准、佣金回溯判定 | 27 / 13 / 6 / 6 | 保留 |
refund.process_asset,仅成功 |
4 | 保留 |
4.2 移出审计
| 动作 | 现在日均(估算) | 去向 | 说明 |
|---|---|---|---|
integration.attempt_started |
约 45.6 万 | L4 不写 | tb_integration_log 已有同样内容;audit_event_id 留空 |
refund.process_asset 失败 |
约 32.6 万 | L2 退款后处理尝试记录 | 每次尝试一条,记在新表 tb_refund_post_process_attempt;退款单上保留当前状态、次数和最后错误;审计只在最终成功或转人工时写一条 |
iot_card.auto_stop 失败 |
约 31.5 万 | L2 停复机记录 | tb_card_stop_resume_record 每次实际调用一条,已含错误分类 |
iot_card.auto_stop_reason_update |
约 3.8 万 | L3 文本 | 只改停机原因、不改停复机状态 |
iot_card.worker_traffic_sync |
约 3.1 万(正常时 6–8 万) | L2 采集记录 | tb_card_traffic_collection 已经记录每次采集 |
iot_card.worker_network_sync |
约 2.6 万(正常时 6–8 万) | L3 文本 | 结果就是卡上的网络状态字段 |
package_usage.deduct_traffic |
约 2.1 万 | L2 | 采集记录、扣减效果、日流量三张表已经能还原 |
notification.deliver、polling_priority.* 等 |
约 0.5 万 | L3 文本 | — |
4.3 方案选择
采用方案 B。停复机和流量重置都已经有更合适的业务表,审计里只留人工操作和资金、套餐生命周期类动作。
| 方案 | 审计事件/天 | 占现在 | 每天新增存储 |
|---|---|---|---|
| 现在 | 约 122 万 | 100% | 约 6 GB |
| 方案 A:4.1 全留 | 约 4,700 | 0.39% | 约 24 MB |
| 方案 B:停复机、流量重置移到 L2 | 约 2,200 | 0.18% | 约 11 MB |
5. 技术设计
5.1 注册表增加"落库策略"
internal/infrastructure/audit/registry.go 的 ActionDefinition 新增字段:
// PersistPolicy 决定动作是否写入审计表。
type PersistPolicy string
const (
PersistAlways PersistPolicy = "always" // 成功失败都写(人工动作默认)
PersistOnSuccess PersistPolicy = "on_success" // 只写成功;失败写文本日志
PersistOutcome PersistPolicy = "outcome" // 只写最终结论:成功、或重试用尽转人工;中间失败不写审计(每次尝试在业务尝试记录表)
PersistLogOnly PersistPolicy = "log_only" // 不写表,写 L3 文本日志
PersistNone PersistPolicy = "none" // 什么都不写
)
type ActionDefinition struct {
// ……现有字段
Persist PersistPolicy // 为空时按操作者决定,见 5.2
}
动作的策略在注册表中集中定义,调用方不改代码。这样一份清单就能看清哪些动作进审计,评审和后续调整也只需改这一处。
5.2 默认规则
Persist 为空时,按本次写入的操作者类型决定:
操作者 actor_kind |
默认策略 |
|---|---|
account、personal_customer、openapi、external_system |
always |
system_task、scheduled_job |
log_only |
因此新增机器动作默认不进审计,要进审计必须在注册表显式声明 always、on_success 或 outcome。这能防止后面新增的轮询、同步类动作再次把审计表写满。
同一动作可能同时由人和机器触发,例如 order.create、iot_card.manual_start 与开放接口复机。策略按"动作 + 操作者"判断:注册表里的 Persist 只约束机器操作者,人工操作者始终是 always。
5.3 Writer 改造
只改 internal/infrastructure/audit/writer.go 的 AppendAndGet,在注册校验通过后、组装事件前分流:
action, ok := w.registry.Action(input.ActionCode)
// ……现有校验
switch w.persistDecision(ctx, tx, action, input) {
case decisionSkip:
return nil, nil
case decisionLog:
w.machineLog.Info("audit", auditLogFields(action, input)...)
return nil, nil
}
// ……现有写表逻辑
要点:
- 调用方兼容:
Append本来就吞错并返回 nil,调用方不受影响。AppendAndGet有 11 处调用(refund/clawback.go、refund/service.go、businessusergroup、packagetrafficalert、distribution、refund_channel、integrationlog),实施时逐一确认能处理返回的nil事件。这 11 处大多是人工或资金动作,仍然是always,实际不会拿到 nil。 outcome的判定:由调用方在写审计时标明这次是不是最终结论,AppendInput增加Final bool。- 中间失败(
Final=false)不写审计表,只写一行应用日志,日志里带尝试记录 ID 方便对照; - 最终成功,或重试用尽转人工(
Final=true)写一条审计,metadata带总尝试次数、首次失败时间、最后错误码; - 用业务键作
EventID(例如refund-asset:{refund_id}:outcome),保证同一件事的结论只有一条。 - 每一次尝试的细节都不丢,都在业务尝试记录表里(见 5.5),可分页查询(见 5.9)。
- 中间失败(
- 文本日志写入现有应用日志:不新建日志文件,也不新增轮换配置。Writer 直接使用
logger.GetAppLogger().Named("audit"),写入现有的app.log,轮换沿用logging.app_log(测试环境配置见 5.8),由日志同步服务器自动归集。NewWriter签名不变,调用方不用改。- 每行固定
"logger":"audit"、"msg":"audit_event",便于在同步端按 logger 名过滤和建索引; - 字段:
action_code、actor_kind、actor_id、source、result、resource_type、resource_key、correlation_id、request_id、error_code、summary;中间失败额外带attempt(第几次)和尝试记录 ID; - 级别:成功为 Info,失败为 Warn;
- 不写 before/after 快照与主体数据,避免敏感数据进入文本日志;需要变化值的动作(如流量重置前后用量)只写必要的数值字段。
- 每行固定
- 运行时覆盖:在
add-audit-integration-write-switches的全局开关之外,增加一个按动作覆盖的配置audit.persist_overrides(动作编码 → 策略)。出问题时不发版就能把某个动作临时降为log_only,或恢复为always。
5.4 对接日志不再补写审计
internal/infrastructure/integrationlog/repository.go 的 Start:
- 删除
input.AuditEventID == nil时补写integration.attempt_started的逻辑(第 118–120 行)。上游有审计事件时照常关联;没有时audit_event_id留空。 - 注册表里的
integration.attempt_started设为none,作为兜底。 auditEventIDForSeries按trigger_series回查审计的逻辑保留,但需要确认它不会走慢查询(它会查审计表)。
5.5 失败重试收敛(与停机风暴止血配套)
审计只记结论之后,排查问题靠的是每一次尝试的记录,同时重试本身要收敛。这两件可以单独开 Change,但必须先于或同时上线:
- 退款后处理(
internal/service/refund/approval_decision.go的ProcessAssetPostProcessing,stopAsset→ManualStopCard):- 退款单增加或复用后处理字段:
asset_post_status、asset_post_attempts、asset_post_last_error、asset_post_next_at,表示当前状态; - 新增尝试记录表
tb_refund_post_process_attempt,每次尝试一条,不修改、不删除。字段:refund_id、step(停机、套餐失效、钱包回收等)、asset_type、asset_id、iccid、attempt、trigger(outbox 投递、补偿扫描、人工重试)、result、error_code、error_message、stop_resume_record_id(关联到那次停机调用)、duration_ms、created_at。按月分区。每单最多 10 次,量可控; - 失败按指数退避,超过 N 次(建议 10 次)标记为"需人工处理",不再自动重试;
- outbox 与
RecoverRefundPostProcessing都按这几个字段判断,不再无限重投。
- 退款单增加或复用后处理字段:
- 自动停机:8-11 上的停机已经走停复机指令队列(
stop-resume-command-queue),按错误分类处理:终态不可操作不重试,限流按退避处理。退款停机只请求停机评估。本次不改这部分。- 每次实际调用上游,已经在
tb_card_stop_resume_record记一条,包括第几次、错误类别、上游返回码与信息、耗时。 - 指令在调用上游前就结束的情况(已是目标状态、条件不再满足、卡不允许停复机)现在没有记录。改为在停复机记录里写
result=skipped,并写明原因,保证"为什么没停"也能查到。限流推迟后还会再执行,不写记录,沿用现有的分钟计数。
- 每次实际调用上游,已经在
5.6 方案 B 的业务表补位
| 移出的动作 | 补位方式 | 现状 |
|---|---|---|
iot_card.auto_start / auto_stop 成功 |
tb_card_stop_resume_record(每次实际调用一条,含来源、场景、原因、结果) |
Iteration/8-11 已有 |
package_usage.reset_traffic |
套餐使用记录的 last_reset_at / next_reset_at 加日流量记录 |
已有;重置前后用量写一行 app.log(logger=audit)备查 |
iot_card.auto_start / auto_stop 的停机原因、触发场景 |
tb_card_stop_resume_record 的 source、scene、reason |
已有;原审计里的 before/after 卡状态不再保留,卡当前状态以卡表为准 |
后台"卡操作记录"之类的页面如果要看到停复机时间线,查询侧改为合并审计和停复机记录两个来源,不要回头再写审计。
5.7 审计覆盖治理
internal/governance/auditcoverage/scanner.go 扫描每个入口的 AuditEvent、DomainLedger、IntegrationLog 分类。本次需要做三件事:
- 对移到 L2、L3、L4 的入口,把
AuditEvent分类改为不写,并在DomainLedger里写明对应的业务表; - 覆盖扫描增加一条校验:机器操作者的动作必须在注册表显式声明
Persist,否则扫描失败; - 同步更新
openspec/specs/operations-audit和external-integration中"每个入口都写审计"的要求。
5.8 应用日志增量与轮换(测试环境)
测试环境由 docker-compose.prod.yml 部署,api、worker 两个容器的现状:
- 日志级别是
LEVEL=info、DEVELOPMENT=false,即 JSON 格式,可以按"logger":"audit"过滤; - 两个容器都把宿主机
./logs挂载到/app/logs,且都没有设置JUNHONG_LOGGING_APP_LOG_FILENAME,所以都使用默认的/app/logs/app.log; - 轮换参数也是默认值:100 MB 一个文件、3 个备份、7 天、压缩。
问题:api 和 worker 写的是宿主机上同一个 /opt/junhong_cmp/logs/app.log。两个进程各自用 lumberjack 按大小轮换,会互相把对方正在写的文件改名、压缩,导致丢日志和备份错乱。这个问题与审计改造无关,但 L3 日志要落在 app.log 里,所以要一并修。
调整原则:每个服务写在自己运行目录下的 logs/。审计日志不新增路径、不改文件名,跟着所在进程的应用日志走。测试环境的问题只在于两个容器共用了同一个宿主机目录,所以只改挂载:
| 服务 | 挂载(宿主机 → 容器) | 宿主机日志位置 |
|---|---|---|
| api | ./api/logs:/app/logs |
/opt/junhong_cmp/api/logs/app.log、access.log |
| worker | ./worker/logs:/app/logs |
/opt/junhong_cmp/worker/logs/app.log |
-
容器内仍然是默认的
/app/logs/app.log,不设置APP_LOG_FILENAME;目录结构与生产/opt/junhong_cmp/api/logs、/opt/junhong_cmp/worker/logs一致; -
轮换只加两项:
JUNHONG_LOGGING_APP_LOG_MAX_BACKUPS=40、JUNHONG_LOGGING_APP_LOG_MAX_AGE=14,其余用默认值(100 MB、压缩); -
容量:两个进程合计约 1 GB,每个进程是 100 MB 当前文件加 40 个压缩备份。每个备份约 10 MB 是估算值,部署后按实际备份大小微调;
-
.gitea/workflows/deploy.yaml里mkdir -p ${DEPLOY_DIR}/logs改为创建api/logs、worker/logs; -
原来的
/opt/junhong_cmp/logs不再写入,旧文件保留不动。 -
新增量:方案 B 在测试环境移到 L3 的动作,每天约 8 万–10 万行:流量同步改由采集记录承担,不写日志;需要写日志的有网络状态同步约 2.5 万、优先轮询约 1.4 万、停机原因更新与通知若干。按每行约 400 B 计算,每天约 30–40 MB(压缩前),相对单文件 100 MB 没有压力。
文本日志是排查补充。丢几行不影响业务,也不影响审计表。写日志失败时不重试、不报错。
5.9 记录查询接口
审计里移出去的数据,要能在后台查得到,否则等于丢了。凡是独立成表的记录,都要提供分页 + 条件筛选的查询接口。L3 文本日志不提供接口,由日志同步服务器检索。
公共约定(与现有 ListStopResumeRecords 一致):
| 项 | 约定 |
|---|---|
| 分页 | page 默认 1;page_size 默认 20,最大 100(采集记录沿用现有的最大 200);返回 total、page、page_size、items |
| 时间范围 | start_time、end_time 必填,跨度不超过 31 天,按上海时间解析;单卡接口为空时默认取最近 31 天 |
| 卡标识 | identifier 支持虚拟号、ICCID、MSISDN,先解析成卡 ID 再查,保证走"卡 ID + 时间"索引;找不到卡时直接返回空页 |
| 排序 | 按记录时间倒序,同一时间按 ID 倒序 |
| 单个与全部 | 每类记录提供一个列表接口,identifier 选填:传了就查单卡或单资产,不传就查全部。现有的单卡接口保留给前端兼容,与列表接口共用同一个查询 |
| 筛选 | 按业务排查需要来定,下面逐表列出,不受现有索引限制;为这些筛选新建或重建索引 |
| 时间范围的作用 | 表按月分区,时间范围用于分区裁剪,所以查全部时也只带时间范围、不要求其他条件 |
| 权限 | 平台账号;代理和企业账号是否开放、按归属范围过滤,另行确定 |
接口清单:
| 记录 | 表 | 列表接口 | 筛选条件 | 现状 |
|---|---|---|---|---|
| 运营商流量采集记录(成功,失败见 5.10) | tb_card_traffic_collection |
GET /traffic-collections |
identifier、carrier_id(运营商账户)、decision(扣减判定)、source、scene、has_delta(是否产生增量)、stale_guarded |
只有单卡接口 GET /assets/:identifier/traffic-collections,只能按时间分页 |
| 停复机记录 | tb_card_stop_resume_record |
GET /card-stop-resume-records |
identifier、carrier_id、action、source、scene、reason、result、error_category、command_id |
已有跨卡接口,但只能用 ICCID 查卡,也不能按场景、原因、指令号筛选;单卡接口没有筛选 |
| 套餐日流量详单 | tb_package_usage_daily_record |
GET /package-usage-daily-records |
identifier、package_usage_id、package_id、carrier_id、日期范围 |
只有单套餐接口 GET /package-usages/:id/daily-records,不分页 |
| 卡日流量 | tb_card_daily_usage |
GET /card-daily-usages |
identifier、carrier_id、日期范围、min_usage_mb(用量下限,排查异常大流量) |
无接口 |
| 套餐流量冲正流水 | tb_package_usage_adjustment |
GET /package-traffic-adjustments |
identifier、package_usage_id、操作人、调整方向(补扣或退回)、时间范围 |
只有单套餐接口,没有时间筛选 |
| 对接日志 | tb_integration_log |
现有 GET /audit/integrations |
现有条件已覆盖 | 不改 |
| 退款后处理尝试记录 | tb_refund_post_process_attempt(见 5.5) |
GET /refund-post-process-attempts |
refund_id、退款单号、identifier、step、result、error_code、trigger、时间范围 |
新增。退款列表同时增加 asset_post_status 筛选(可查"需人工处理"),列表和详情返回后处理次数、最后错误、下次重试时间 |
索引:按上面的筛选设计,需要时新建或重建。分区表的索引建在父表上,会自动应用到各个分区。
| 表 | 索引 |
|---|---|
tb_card_traffic_collection |
保留 (iot_card_id, observed_at DESC);新增冗余列 carrier_id,采集时写入;新增 (observed_at DESC)、(carrier_id, observed_at DESC)、(decision, observed_at DESC);失败表索引见 5.10 |
tb_card_stop_resume_record |
现有 (card_id, created_at)、(carrier_id, created_at)、(result, created_at) 重建为倒序;新增 (created_at DESC)、(scene, created_at DESC)、(command_id) |
tb_card_daily_usage |
现有唯一键 (iot_card_id, date);新增 (date, usage_mb DESC),支撑查全部和按用量下限筛选 |
tb_package_usage_daily_record |
新增 (package_usage_id, date DESC)、(date) |
tb_package_usage_adjustment |
新增 (iot_card_id, created_at DESC)、(created_at DESC) |
tb_refund_post_process_attempt |
(refund_id, created_at DESC)、(created_at DESC)、(result, created_at DESC)、(error_code, created_at DESC) |
其余低选择性的条件,如 source、stale_guarded、调整方向,和上面的索引组合使用即可,不单独建索引。上线后在测试环境看慢查询日志,按实际情况调整。
说明:
- 流量扣减结果直接从采集记录查:每条采集记录都带
decision、delta_mb、month_used_mb、event_id,再结合日流量详单,能还原每次扣了多少。 - 扣减效果表
tb_card_observation_effect不对外提供接口。它只保存 outbox 事件的处理进度,没有卡 ID。排查扣减卡住时,在采集记录里按event_id关联查。 - 新增接口都要在路由
RouteSpec中声明输入、输出 DTO,并同步生成接口文档。
5.10 流量采集记录成功与失败分表
现状(测试库近 3 天,只读统计):
| 读数结果 | 扣减判定 | 条数 | 平均行大小 |
|---|---|---|---|
ok |
written(写入增量) |
104.2 万 | 432 B |
ok |
queue_not_full(队列未满,暂不判断) |
17.3 万 | 285 B |
ok |
slope_negative、baseline、settled_existing |
800 | 约 420 B |
failed |
— | 14.5 万 | 136 B |
no_reading |
— | 400 | 144 B |
- 成功和失败写在同一张
tb_card_traffic_collection里,失败约占 11%,测试环境每天约 4.8 万条。 - 失败记录只存了失败类型。
polling_carddata_handler在调用recordUnreadable时丢掉了具体错误,查不到失败原因,只能再去对接日志里按observation_id找。 - 失败记录也只给"采集时刻有套餐"的卡写,为此每条失败都要额外查一次有效套餐。
调整:
| 表 | 写什么 | 保留 |
|---|---|---|
tb_card_traffic_collection(现有) |
只写成功读数(result=ok),包括所有扣减判定;新增原始请求与响应字段 |
在线保留 2 个月,到期月分区导出为压缩包后删除(见下文"到期归档") |
tb_card_traffic_collection_failure(新增) |
只写失败:failed、rate_limited、invalid_payload、no_reading、invalid_reading;带原始请求与响应 |
与成功表相同:在线 2 个月,到期归档后删除 |
失败表字段:iot_card_id、iccid、carrier_id、observed_at、observation_id(等于对接日志的 integration_id,可直接关联)、source、scene、result(失败类型)、error_category(按网关错误分类:超时、限流、上游报错、响应格式错等)、provider_code、provider_message(截断到 500 字)、duration_ms、created_at,加上下面的原始数据字段。按 observed_at 按月分区,只新增不修改。
原始数据:成功表和失败表都保存运营商网关的原始请求与原始响应,有据可查。
| 字段 | 内容 |
|---|---|
raw_request |
加密前的业务请求体(明文 JSON,只有卡号等查询参数),jsonb |
http_status |
HTTP 状态码;没拿到响应(超时、连接失败)时为空 |
gateway_code、gateway_msg、gateway_trace_id |
网关响应外层的 code、msg、trace_id |
raw_response |
网关原始响应体,原样保存。能解析成 JSON 的存 jsonb,不能解析的按文本存在 raw_response_text。超过 4 KB 时截断,并标记 raw_truncated=true |
gateway_attempts |
网关客户端内部重试次数;保存的是最后一次的请求和响应 |
- 获取方式:网关客户端(
internal/gateway/client.go的executeWithRetry)已经读到了完整响应体和外层的code、msg、trace_id,但只返回data。新增按请求上下文挂载的原始数据收集器gateway.WithRawCapture(ctx),调用方挂上后,客户端把最后一次的请求体、状态码、响应体和重试次数写进收集器。没挂收集器的调用不受影响。 - 写入:
polling_carddata_handler调QueryFlow前挂上收集器,成功读数和各类失败都把收集器内容带进TrafficObservation,写入对应的表。 - 安全:只存明文业务请求体,不存加密后的报文、签名、
app_id、密钥和请求头。 - 量的估算:流量查询响应很小(
iccid、used、unit加外层字段,约 150–250 B),每行增加约 300–400 B。测试环境成功读数每天约 40 万条,每天增加约 120–160 MB;在线保留 2 个月,原始数据部分约 7–10 GB。失败每天约 4.8 万条,2 个月约 1 GB。部署后按实际行大小复核。
到期归档:
- 在线保留:当月加上最近 2 个整月。月分区的月末早于"当前时间减 2 个月"时,判定为到期。例如 2027-01-01 起,2026-10 的分区到期。常量
TrafficCollectionRetentionDays=90改为TrafficCollectionRetentionMonths=2,成功表和失败表共用。 - 执行位置:沿用 leader worker 现有的分区维护循环
startTrafficCollectionPartitionMaintainer,每 12 小时运行一次。原来"到期直接DROP TABLE"的逻辑,改为下面的四步:- 摘出分区:
ALTER TABLE ... DETACH PARTITION,到期分区不再参与在线查询。 - 导出压缩包:用
COPY (SELECT * FROM 分区 ORDER BY observed_at, id) TO STDOUT WITH (FORMAT csv, HEADER)流式读出,边读边 gzip 写到 worker 运行目录下的archive/traffic-collection/目录,不在内存里攒整个月的数据。文件名为tb_card_traffic_collection_202610.csv.gz或tb_card_traffic_collection_failure_202610.csv.gz。原始请求与响应以 JSON 文本形式保存在 CSV 列里。 - 校验:写完后重新读一遍压缩包,统计行数并与分区
count(*)比对;同时生成同名的.manifest.json,记录表名、月份、行数、最早和最晚采集时间、文件大小、SHA-256 和导出时间。 - 删除分区:行数一致后才
DROP TABLE已摘出的分区。导出或校验失败时保留已摘出的表,记 Error 日志,下一轮重试;不会出现"数据删了但没有压缩包"的情况。
- 摘出分区:
- 文件同步:压缩包和 manifest 由你们的同步服务器拉走。本地只保留最近 3 个月的压缩包,更早的自动删除,个数可配置。先写成
.tmp,校验通过后再改名为正式文件名,避免同步到写了一半的文件。 - 测试环境挂载:worker 容器增加
./worker/archive:/app/archive,宿主机目录为/opt/junhong_cmp/worker/archive/traffic-collection/。 - 压缩包大小估算:测试环境成功表每月约 1,200 万行,CSV 约 8–10 GB,gzip 后约 1–1.5 GB;失败表每月约 150 万行,压缩后约 50 MB。
- 回查:要查归档月份的数据,解压后用 CSV 工具查看,或者临时
COPY FROM导回一张临时表。线上接口只查在线的 2 个月。
写入规则:
- 失败记录不再判断是否有套餐,所有轮询到的卡都写,省掉每条失败的有效套餐查询。运营商接口出问题和有没有套餐无关,排查时需要看全量。
TrafficObservation增加失败详情(错误类别、上游返回码与信息、耗时),由polling_carddata_handler在网关调用失败时填入,不再丢弃错误。- 成功表仍在观测事务之外写入,规则不变;写入失败只告警,不影响扣减。
- 成功表已有的失败历史数据保留,到期随分区删除;新数据按新规则分表写入。
查询接口(与 5.9 公共约定一致:可查单个也可查全部,分页,时间范围必填):
| 接口 | 筛选条件 | 索引 |
|---|---|---|
GET /traffic-collections(成功) |
identifier、carrier_id、decision、source、scene、has_delta、stale_guarded |
见 5.9 |
GET /traffic-collection-failures(失败) |
identifier、carrier_id、result、error_category、provider_code、source、scene |
(iot_card_id, observed_at DESC)、(observed_at DESC)、(carrier_id, observed_at DESC)、(error_category, observed_at DESC)、(observation_id) |
成功表不再有失败数据,所以 5.9 里成功表的 result 筛选和 (result, observed_at DESC) 索引都去掉。单卡接口 GET /assets/:identifier/traffic-collections 增加 include_failures 参数,默认不含失败;传了就把两张表合并后按时间倒序返回,方便在一张卡上连起来看。
6. 存量数据
- 不删除、不迁移已有审计数据,由现有留存和归档任务按策略自然过期。
- 如果要尽快释放空间,可以另行评估"按动作编码清理机器过程类历史数据"的一次性任务。本方案不包含它。
7. 分支与范围
- 基于 Iteration/8-11 实施。该分支已有
tb_card_stop_resume_record、采集记录和扣减效果表,方案 B 的补位表都存在。 - 只部署测试环境:8-11 推送后自动部署到测试环境;不在生产执行任何代码替换、配置修改或服务重启。生产什么时候、以什么方式合入,不在本方案范围内。
- 全局写入开关
add-audit-integration-write-switches已在 8-11 上,本方案与它互不替代:全局开关用于应急全停,本方案是常态下的按动作分级。
8. 实施步骤
| 步骤 | 内容 | 涉及 |
|---|---|---|
| 1 | 注册表增加 Persist,补齐全部机器动作的策略,并加上 5.2 的默认规则 |
internal/infrastructure/audit/registry.go、pkg/constants/audit.go |
| 2 | Writer 按策略分流:outcome 只写最终结论;log_only 写现有应用日志(logger=audit) |
internal/infrastructure/audit/writer.go |
| 3 | 对接日志去掉 attempt_started 补写 |
internal/infrastructure/integrationlog/repository.go |
| 4 | 退款后处理加重试上限和退避,新增尝试记录表;停机业务性失败不重投,调用前被拦截的写 skipped 停复机记录 |
internal/service/refund、internal/service/iot_card、migrations |
| 5 | 增加 audit.persist_overrides 运行时覆盖配置 |
pkg/config |
| 6 | 审计覆盖扫描和 OpenSpec 规格同步 | internal/governance/auditcoverage、openspec/specs |
| 7 | 查询侧:卡、设备时间线合并停复机记录(方案 B) | internal/query/audit |
| 8 | 测试环境 api、worker 各自挂载自己的 logs/ 目录,轮换改为 40 个备份(见 5.8) |
docker-compose.prod.yml、.gitea/workflows/deploy.yaml |
| 9 | 记录查询接口:每类记录一个列表接口,可查单个也可查全部;按 5.9 的筛选条件建立或重建索引;采集记录增加 carrier_id 冗余列 |
internal/routes、internal/handler/admin、internal/model/dto、internal/store/postgres、migrations |
| 10 | 采集记录成功与失败分表:新增失败表,补全失败详情,失败不再判断有无套餐;两张表保存网关原始请求与响应(网关客户端新增原始数据收集器);提供失败查询接口(见 5.10) | internal/gateway/client.go、internal/application/cardobservation、internal/task/polling_carddata_handler.go、internal/model、internal/store/postgres、migrations |
| 11 | 采集记录到期归档:分区维护改为摘出、导出 csv.gz、校验、删除四步;测试环境 worker 挂载 archive 目录 |
internal/store/postgres/card_traffic_collection_store.go、cmd/worker/main.go、pkg/constants、docker-compose.prod.yml |
建议按"1–3 → 4 → 5–11"分三次提交,每次推送 8-11 后在测试环境验证。
9. 测试与验证(测试环境)
测试环境逐项验证(项目规定自动化测试为 N/A,按 ENG-TEST-001 在测试环境验证,以下各项是验证要点):
-
每种策略在
account、openapi、system_task下的写入结果; -
outcome:中间失败不写审计,尝试记录表每次都有一条;最终成功或转人工写一条审计,带总次数;同一件事重复写结论只保留一条; -
log_only不写表、文本日志有记录且不含快照; -
覆盖配置能把
always降为log_only,也能反过来恢复。 -
对接调用没有上游审计时,
tb_integration_log.audit_event_id为空,审计表无新增; -
退款后处理失败超过上限后状态为"需人工处理",outbox 不再重投。
-
流量查询成功写成功表、各类失败写失败表,两张表都带原始请求与响应;失败记录有错误类别和上游返回码;无套餐的卡失败也写;
-
网关响应超过 4 KB 时截断并标记;原始请求里没有密钥、签名或加密报文;
-
到期归档:构造一个过期月分区,执行维护后生成
csv.gz和 manifest,行数与 SHA-256 一致后分区被删除;模拟导出失败时,已摘出的表保留,下一轮重试成功; -
记录查询接口:每个接口都能查单卡、也能查全部,分页总数正确,各筛选条件生效。
测试环境观察(部署后 24 小时):
- 审计日增从约 12.6 万降到约 300 条(只读查询走
created_at索引、按小时统计); app.log中出现logger=audit的行,轮换正常,日志同步服务器能收到并按 logger 名过滤;- 停复机记录、扣减效果写入量没有变化,业务结果没有变化;成功表加失败表的写入量合计,与改造前采集记录的量相当(失败表多出无套餐卡的失败);
- 新接口在测试库数据量下没有慢查询;
/opt/junhong_cmp/worker/archive/traffic-collection/目录可写,同步服务器能拉到文件。第一次真实归档要等到在线数据满 2 个月之后,在此之前用单元测试和集成测试覆盖。
10. 已定事项(2026-11-05)
| 事项 | 结论 |
|---|---|
| 方案 | 方案 B |
| 范围 | 基于 Iteration/8-11,只部署测试环境 |
| L3 文本日志 | 写入所在服务自己运行目录下的 logs/app.log,沿用现有轮换,由日志同步服务器归集 |
| 测试环境日志保留 | api、worker 各自的 logs/ 目录,各保留 40 个压缩备份,合计约 1 GB;部署后按实际备份大小微调 |
| 退款后处理重试上限 | 10 次,指数退避,最长间隔 1 小时;超过后标记"需人工处理" |
| 失败记录 | 每次尝试都记录在业务尝试记录表(退款后处理尝试、停复机记录),可分页查询;审计只记最终结论,不按首次失败去重 |
| 停机业务性失败 | 按网关错误分类判定为不可重试,不再重投 |
| 运行时覆盖 | 提供 audit.persist_overrides,可按动作临时调整策略 |
| 存量审计数据 | 不删除、不迁移,按现有留存策略自然过期 |
| 采集记录分表 | 成功写现有表,失败写新表 tb_card_traffic_collection_failure,带完整错误详情,所有卡都写;两张表都保存网关原始请求与响应 |
| 采集记录保留 | 两张表在线保留 2 个月(当月加最近 2 个整月);到期月分区先导出为 csv.gz 压缩包并校验,再删除;压缩包由同步服务器拉走,本地保留 3 个月 |
| 记录查询 | 所有独立成表的记录都提供分页加条件筛选接口,可查单个也可查全部;筛选条件按排查需要来定,索引随之新建或重建,清单见 5.9;文本日志不提供接口 |
| 页面依赖 | 实施第 7 步(时间线合并停复机记录)前,与前端或运营确认是否有页面依赖机器动作审计 |