github/sub2api
1
0
Fork 0
mirror of https://github.com/Wei-Shaw/sub2api.git synced 2026-03-30 04:42:38 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
32d25f76fc0b91a15c6ddf730e7b138373e59b7f
sub2api/PR_REPORT_20260311_db_write_hotspots.md

10 KiB
Raw Blame History

PR Report: DB 写入热点与后台查询拥塞排查

背景

线上在高峰期出现了几类明显症状：

  • 管理后台仪表盘接口经常超时，/api/v1/admin/dashboard/snapshot-v2 一度达到 50s 以上
  • 管理后台充值接口 /api/v1/admin/users/:id/balance 出现 15s 以上超时
  • 登录态刷新、扣费、错误记录在高峰期出现大量 context deadline exceeded
  • PostgreSQL 曾出现连接打满，后续回退连接池后，主问题转为 WAL/刷盘拥塞

本报告基于 /home/ius/sub2api 当前源码，目标是给出一份可直接拆成 PR 的修复方案。

结论

这次故障的主因不是单一“慢 SQL”，而是请求成功路径上的同步写库次数过多，叠加部分后台查询仍直接扫 usage_logs，最终把 PostgreSQL 的 WAL 刷盘、热点行更新和 outbox 重建链路一起放大。

代码层面的核心问题有 6 个。

1. 成功请求路径同步写库过多

backend/internal/service/gateway_service.go:6594 的 postUsageBilling 在单次请求成功后，可能同步触发以下写操作：

  • userRepo.DeductBalance
  • APIKeyService.UpdateQuotaUsed
  • APIKeyService.UpdateRateLimitUsage
  • accountRepo.IncrementQuotaUsed
  • deferredService.ScheduleLastUsedUpdate（这一项已经做了延迟批量，是正确方向）

也就是说，一次成功请求不是 1 次落库，而是 3 到 5 次写入。

这和线上看到的现象是吻合的：

  • UPDATE accounts SET extra = ...
  • INSERT INTO usage_logs ...
  • INSERT INTO ops_error_logs ...
  • scheduler_outbox backlog

2. API Key 配额更新存在额外读写放大

backend/internal/service/api_key_service.go:815 的 UpdateQuotaUsed 当前流程是：

  1. IncrementQuotaUsed
  2. GetByID
  3. 如超限再 Update

对应仓储实现：

  • backend/internal/repository/api_key_repo.go:441 只做自增
  • 然后 service 再回表读取完整 API Key
  • 之后可能再整行更新状态

这让“每次扣费后更新 API Key 配额”从 1 条 SQL 变成了最多 3 次数据库交互。

3. accounts.extra 被当成高频热写字段使用

两个最重的热点都落在 accounts.extra：

  • backend/internal/repository/account_repo.go:1159 UpdateExtra
  • backend/internal/repository/account_repo.go:1683 IncrementQuotaUsed

问题有两个：

  1. 两者都会重写整块 JSONB，并更新 updated_at
  2. UpdateExtra 每次写完都会额外插入一条 scheduler_outbox

尤其 UpdateExtra 现在被多处高频调用：

  • backend/internal/service/openai_gateway_service.go:4039 持久化 Codex rate-limit snapshot
  • backend/internal/service/ratelimit_service.go:903 持久化 OpenAI Codex snapshot
  • backend/internal/service/ratelimit_service.go:1013 / 1025 更新 session window utilization

这类“监控/额度快照”并不会改变账号是否可调度，却仍然走了：

  • JSONB 更新
  • updated_at
  • scheduler_outbox

这是明显的写放大。

4. scheduler_outbox 设计偏向“每次状态变更都写一条”，高峰期会反压调度器

backend/internal/repository/scheduler_outbox_repo.go:79 的 enqueueSchedulerOutbox 非常轻，但它被大量调用。

例如：

  • UpdateExtra 每次都 enqueue AccountChanged
  • BatchUpdateLastUsed 也会 enqueue 一条 AccountLastUsed
  • 各类账号限流、过载、错误状态切换也都会 enqueue

对应的 outbox worker 在：

  • backend/internal/service/scheduler_snapshot_service.go:199
  • backend/internal/service/scheduler_snapshot_service.go:219

它会不断拉取 outbox，再触发 GetByID、rebuildBucket、loadAccountsFromDB。

所以当高频写入导致 outbox 增长时，系统不仅多了写，还会反向带出更多读和缓存重建。

5. 仪表盘只有一部分走了预聚合，models/groups/users-trend 仍然直接扫 usage_logs

好消息是，dashboard stats 本身已经接了预聚合表：

  • backend/internal/repository/usage_log_repo.go:306
  • backend/internal/repository/usage_log_repo.go:420
  • 预聚合表定义在 backend/migrations/034_usage_dashboard_aggregation_tables.sql:1

但后台慢的不是只有 stats。

snapshot-v2 默认会同时拉：

  • stats
  • trend
  • model stats

见：

  • backend/internal/handler/admin/dashboard_snapshot_v2_handler.go:68

其中：

  • GetUsageTrendWithFilters 只有“无过滤、day/hour”时才走预聚合，见 usage_log_repo.go:1657
  • GetModelStatsWithFilters 直接扫 usage_logs，见 usage_log_repo.go:1805
  • GetGroupStatsWithFilters 直接扫 usage_logs，见 usage_log_repo.go:1872
  • GetUserUsageTrend 直接扫 usage_logs，见 usage_log_repo.go:1101
  • GetAPIKeyUsageTrend 直接扫 usage_logs，见 usage_log_repo.go:1046

所以线上会出现：

  • stats 快
  • 但 snapshot-v2 仍然慢
  • /admin/dashboard/users-trend 单独也慢

这和你线上看到的日志完全一致。

6. 管理后台充值是“读用户 -> 整体更新用户 -> 插审计记录”

backend/internal/service/admin_service.go:694 的 UpdateUserBalance 当前流程：

  1. GetByID
  2. 在内存里改 balance
  3. userRepo.Update
  4. redeemCodeRepo.Create 记录 admin 调账历史

而 userRepo.Update 是整用户对象更新，并同步 allowed groups 事务处理：

  • backend/internal/repository/user_repo.go:118

这个接口平时不一定重，但在数据库已经抖动时，会比一个原子 UPDATE users SET balance = balance + $1 更脆弱。

额外观察

ops_error_logs 虽然已异步化，但单条写入仍然很重

错误日志中间件已经做了队列削峰：

  • backend/internal/handler/ops_error_logger.go:69
  • backend/internal/handler/ops_error_logger.go:106

这点方向是对的。

但落库表本身很重：

  • backend/internal/repository/ops_repo.go:23
  • backend/migrations/033_ops_monitoring_vnext.sql:69
  • backend/migrations/033_ops_monitoring_vnext.sql:470

ops_error_logs 不仅列很多，还带了多组 B-Tree 和 trigram 索引。高错误率时，即使改成异步，也还是会把 WAL 和 I/O 压上去。

建议的 PR 拆分

建议拆成 4 个 PR，不要在一个 PR 里同时改数据库模型、后台查询和管理接口。

PR 1: 收缩成功请求路径的同步写库次数

目标：把一次成功请求的同步写次数从 3 到 5 次，尽量压到 1 到 2 次。

建议改动：

  1. 把 APIKeyService.UpdateQuotaUsed 改为单 SQL

    • 新增 repo 方法，例如 IncrementQuotaUsedAndMaybeExhaust
    • 在 SQL 里同时完成 quota_used += ? 和 status = quota_exhausted
    • 返回 key/status/quota/quota_used 最小字段，直接失效缓存
    • 删掉当前的 Increment -> GetByID -> Update

  2. 把账号 quota 计数从 accounts.extra 拆出去

    • 最理想：新增结构化列或独立 account_quota_counters 表
    • 次优：至少把 quota_used/quota_daily_used/quota_weekly_used 从 JSONB 中剥离

  3. 对“纯监控型 extra 字段”禁止 enqueue outbox

    • 例如 codex snapshot、session_window_utilization
    • 这些字段不影响调度，不应该触发 SchedulerOutboxEventAccountChanged

  4. 复用现有 DeferredService 思路

    • last_used 已经是批量刷盘，见 deferred_service.go:41
    • 可继续扩展 deferred quota snapshot flush

预期收益：

  • 直接减少 WAL 写入量
  • 降低 accounts 热点行锁竞争
  • 降低 outbox 增长速度

PR 2: 给 dashboard 补齐预聚合/缓存，避免继续扫 usage_logs

目标：后台仪表盘接口不再直接扫描大表。

建议改动：

  1. 为 users-trend / api-keys-trend 增加小时/天级预聚合表
  2. 为 model stats / group stats 增加日级聚合表
  3. snapshot-v2 增加分段缓存
    • stats
    • trend
    • models
    • groups
    • users_trend 避免一个 section miss 导致整份 snapshot 重新扫库
  4. 可选：把 include_model_stats 默认值从 true 改成 false
    • 至少让默认仪表盘先恢复可用，再按需加载重模块

预期收益：

  • snapshot-v2
  • /admin/dashboard/users-trend
  • /admin/dashboard/api-keys-trend

这几类接口会从“随数据量线性恶化”变成“近似固定成本”。

PR 3: 简化管理后台充值链路

目标：管理充值/扣余额不再依赖整用户对象更新。

建议改动：

  1. 新增 repo 原子方法

    • SetBalance(userID, amount)
    • AddBalance(userID, delta)
    • SubtractBalance(userID, delta)

  2. UpdateUserBalance 改为：

    • 先执行原子 SQL
    • 再读一次最小必要字段返回
    • 审计记录改为异步或降级写

  3. 审计记录建议改名或独立表

    • 现在把后台调账记录塞进 redeem_codes，语义上不干净

预期收益：

  • /api/v1/admin/users/:id/balance 在库抖时更稳
  • 失败面缩小，不再被 allowed groups 同步事务拖累

PR 4: 为重写路径增加“丢弃策略”和“熔断指标”

目标：高峰期先保护主链路，不让非核心写入拖死数据库。

建议改动：

  1. ops_error_logs

    • 增加采样或分级开关
    • 对重复 429/5xx 做聚合计数而不是逐条插入
    • 对 request body / headers 存储加更严格开关

  2. scheduler_outbox

    • 增加 coalesce/merge 机制
    • 同一账号短时间内多次 AccountChanged 合并为一条

  3. 指标补齐

    • outbox backlog
    • ops error queue dropped
    • deferred flush lag
    • account extra write QPS

推荐实施顺序

  1. 先做 PR 1
    • 这是这次线上故障的主链路
  2. 再做 PR 2
    • 解决后台仪表盘慢
  3. 再做 PR 3
    • 解决后台充值接口脆弱
  4. 最后做 PR 4
    • 做长期保护

验证方案

每个 PR 合并前都建议做同一组验证：

  1. 压测成功请求链路，记录单请求 SQL 次数
  2. 观测 PostgreSQL：
    • pg_stat_activity
    • pg_stat_statements
    • WALWrite / WalSync
    • 每分钟 WAL 增量
  3. 观测接口：
    • /api/v1/auth/refresh
    • /api/v1/admin/dashboard/snapshot-v2
    • /api/v1/admin/dashboard/users-trend
    • /api/v1/admin/users/:id/balance
  4. 观测队列：
    • ops_error_logs queue length / dropped
    • scheduler_outbox backlog

可直接作为 PR 描述的摘要

This PR reduces database write amplification on the request success path and removes several hot-path writes from accounts.extra + scheduler_outbox. It also prepares dashboard endpoints to rely on pre-aggregated data instead of scanning usage_logs under load. The goal is to keep admin dashboard, balance update, auth refresh, and billing-related paths stable under sustained 500+ RPS traffic.

Reference in New Issue View Git Blame Copy Permalink