chore: remove accidentally committed PR diagnostic report

6bb02d14 · shaw · 07bb2a5f · 07bb2a5f
Commit 6bb02d14 authored Mar 13, 2026 by shaw
--- a/PR_REPORT_20260311_db_write_hotspots.md
+++ b/PR_REPORT_20260311_db_write_hotspots.md
-# 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.