Skip to content

fix(usage): 分组日汇总重建与保留期清理不阻塞 usage_logs 写入 - #8693

Merged
Wei-Shaw merged 1 commit into
Wei-Shaw:mainfrom
feeeei:fix/group-usage-rollup-nonblocking
Nov 16, 2026
Merged

Wei-Shaw merged 1 commit into
Wei-Shaw:mainfrom
feeeei:fix/group-usage-rollup-nonblocking

Conversation

@feeeei

@feeeei feeeei commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

背景

usage_logs 上有一个 AFTER INSERT 语句级触发器,每次插入都要对单行表 usage_group_rollup_state(id=1)取 FOR KEY SHARE。分组日汇总同步 SyncGroupUsageRollups 是在一个事务里先对这一行取 FOR UPDATE,再重算 usage_group_daily_rollups。重算期间,所有 usage_logs 插入都要排队。

保留期清理每 6 小时跑一次,每次进程重启也会跑。它删除过期的 usage_logs 后,DELETE 行级触发器和 cleanupUsageLogsBatches 都会把水位 closed_before 拉回被删记录的日期,也就是保留窗口的起点。下一次同步因此要在持有 FOR UPDATE 的情况下重算整个保留窗口,耗时随保留天数和数据量增长。在我们的生产环境上(usage_logs 保留 90 天,约千万行),每次重算约 28 秒,超过了写入超时(postUsageBillingTimeout 15 秒,同步兜底同样 15 秒)。结果是请求已经扣费,但 usage_log 丢失。每个清理周期都会发生,持续丢记录。

同一行上持有 FOR UPDATE 的还有:

  • 后台用量清理批次(DeleteUsageLogsBatch)
  • RecomputeRange:在 FOR UPDATE 下重算看板,并在同一事务里重建分组汇总
  • 分区删除
  • DELETE/UPDATE 行级触发器

其中凡是需要大范围重算的,都会以同样的方式卡住写入。

改动

1. 保留下界 expired_before

  • 保留期清理先把截止点对齐到服务端配置时区的自然日零点,再用一条 UPDATE 把 expired_before 和 retained_from 推进到该零点,最后才删除。
  • 触发器对 created_at < expired_before 的记录(INSERT/DELETE/UPDATE)一律不失效。被删的过期记录不属于任何可读日桶,所以清理不再触发重算。
  • 读路径:历史日桶从 max(retained_from, expired_before) 所在日开始读,尾段起点也不早于 expired_before。清理推进了下界、但尚未删完的过期记录不会被计入。
  • 计费去重表的截止点不晚于 usage_logs 的截止点。

2. 重建拆为三个事务,计算阶段不阻塞写入

状态行新增 building_until、build_dirty_from 两列。每轮流程如下:

阶段 状态行锁 内容
登记 FOR UPDATE(毫秒级) 确定 [start, today),写入 building_until = today,清空 build_dirty_from
计算 FOR KEY SHARE 删除旧日桶,INSERT … SELECT 重算;只写入本地日期不早于 start 的日桶
发布 FOR UPDATE(毫秒级) closed_before = COALESCE(build_dirty_from, today),清空登记
  • 触发器:受影响日期早于 closed_before 时照旧后退水位;早于 building_until 时记入 build_dirty_from(取 LEAST)。如果脏日期已经不晚于受影响日期,就不写状态行,避免批量删除时对同一行反复 UPDATE。
  • 正确性依据:登记和发布持 FOR UPDATE,触发器持 FOR KEY SHARE。因此任何源记录变更,要么在登记之前提交,被计算阶段的快照看到;要么看到登记,被记入脏日期。发布时水位不越过脏日期,存在脏区间时最多再续建 3 轮,没收敛的部分留给下一次同步。
  • 同步全程持有会话级 advisory lock,拿不到锁就跳过,同一时刻只有一个重建。解锁失败、或加锁查询出错时,丢弃该物理连接,避免锁随连接回到连接池。
  • 同步前先不加锁地预检:已经发布到今日就直接返回,不再每分钟取一次 FOR UPDATE。

3. 其他持锁路径

  • DELETE/UPDATE 行级触发器的锁从 FOR UPDATE 改为 FOR KEY SHARE。
  • 后台用量清理批次去掉显式加锁和 Go 侧失效,由行级触发器负责。
  • RecomputeRange 用一条独立语句调用 invalidate_group_usage_rollups_at,从 max(start, expired_before) 所在日开始失效;不再持锁,也不在看板重算的事务里重建分组汇总,交给后台同步。
  • 分区删除:
    • 删除后,按分区内不早于下界的最早时刻失效。只有在改过配置时区、分区边界与当前日界不一致时,这一步才可能生效。
    • 父表锁等待限定 3 秒;超时跳过该分区,其中的过期记录由按行删除清理,空分区留到下次清理再删。

4. 日界

GroupUsageTodayStart、GroupUsageYesterdayStart、ParseGroupUsageDate 返回本地日期实际开始的时刻。在夏令时于零点跳变(例如 America/Santiago 2026-09-06 没有 00:00)或零点重复的日期上,这几个函数原先会返回前一天的 23:00,导致前一天的日桶被只含最后一小时的数据覆盖。这三个函数只在分组用量链路里使用。

行为变化与取舍

  • usage_logs 按配置时区整日保留,比原来最多多留不到 1 天。
  • 手工补插到 expired_before 之前的记录不计入分组汇总;这些记录在下一次清理时会被删除。
  • 迁移 251_group_usage_rollup_nonblocking_build.sql 设置了 SET LOCAL lock_timeout = '5s'。它只在多实例滚动部署时才可能触发:如果旧实例正在长时间重建,迁移会超时、新实例启动失败并重试,而不是让插入排在 ALTER 后面。单实例部署不受影响。
  • 同一本地日期在时刻上不连续的情况(日期先到 D,又退回 D−1,再回到 D),仍受按时刻切分日界的限制,本 PR 不处理。

测试

  • unit(sqlmock):覆盖以下场景:
    • 三阶段分事务执行,各阶段的锁模式
    • 有脏区间时续建,达到最大轮数后不越界发布
    • 水位被后退但未记脏时,发布不越过当前水位
    • 时区变更后全量重建;全量重建排除过期记录
    • retained_from 夹到下界
    • 清除遗留的重建登记;拒绝未来水位;登记被替换时中止
    • advisory lock 被占用时跳过
    • 清理截止点整日对齐;分区删除顺序与锁超时跳过
    • RecomputeRange 只做失效
    • 读路径的历史日桶下界与尾段下界
    • 服务层截止点对齐;Santiago、Gaza 的日界
  • integration(PostgreSQL 18):
    • 计算阶段被卡住时,当天写入、迟到写入、窗口内删除都在 3 秒内完成;记脏后续建并发布到今日,日桶与明细逐日一致。把计算阶段改回 FOR UPDATE 后,这条用例会失败。
    • 保留期清理不移动发布水位;过期记录的写入不失效;窗口内删除照常失效。
    • 触发器忽略下界之前的记录(普通表和分区表),并在重建期间记脏。
    • 计算阶段持 FOR KEY SHARE 时,迟到写入和删除不等待。
    • 重建期间同一事务删除 2000 行,状态行只更新一次。
    • advisory lock 被占用时跳过;中断的重建在下一次同步时恢复。
    • invalidate_group_usage_rollups_at 从下界开始失效。
    • DST 零点跳变日续建时不覆盖前一天的日桶。
    • 有长读者时分区删除超时、跳过分区,清理整体成功。
    • 原有的触发器串行化用例(迟到写入、跨零点事务)保持不变并全部通过。
  • go test -tags unit ./...、go test ./...、golangci-lint run ./... 均通过;go test -tags integration ./internal/repository/ 全部通过。

保留期清理删除过期 usage_logs 时,DELETE 触发器与清理代码把分组日汇总水位拉回到被删记录的日期,
下一次同步随即在持有 usage_group_rollup_state FOR UPDATE 的事务里重算整个保留窗口(生产环境每次约
28 秒,每 6 小时与每次重启各一次)。usage_logs 的插入触发器需要同一行的 FOR KEY SHARE,期间写入全部
排队,超过写入超时后已扣费请求的 usage_log 丢失。后台用量清理、RecomputeRange、分区删除与 DELETE/UPDATE
触发器同样对该行持 FOR UPDATE。

- 保留下界 expired_before:清理把截止点对齐到配置时区的自然日零点,先推进下界再删除;早于下界的记录
  变更不触发失效,读路径的历史日桶与尾段都不早于下界。
- 重建拆为登记、计算、发布三个事务:计算阶段只持 FOR KEY SHARE,与写入兼容;登记之后落在重建区间内的
  源记录变更记入 build_dirty_from,发布不越过脏日期并续建脏区间。整个重建持会话级 advisory lock。
- DELETE/UPDATE 触发器、后台用量清理、RecomputeRange 与分区删除对状态行只持 FOR KEY SHARE;脏日期已覆盖
  的变更不写状态行。
- 分区删除限定父表锁等待 3 秒,超时跳过该分区,过期记录由按行删除清理。
- 分组日界取本地日期实际开始的时刻,覆盖夏令时在零点跳变或回拨的日期;重算只写入不早于起始日的日桶。
@Wei-Shaw
Wei-Shaw merged commit fde504e into Wei-Shaw:main Nov 16, 2026
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 16, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants