docs(perf): 新增后端热点API性能优化审计行动计划
This commit is contained in:
yangjianbo
249
docs/backend-hotspot-api-performance-optimization-20260222.md
Normal file
249
docs/backend-hotspot-api-performance-optimization-20260222.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# 后端热点 API 性能优化审计与行动计划（2026-02-22）
|
||||
|
||||
## 1. 目标与范围
|
||||
|
||||
本次文档用于沉淀后端热点 API 的性能审计结果，并给出可执行优化方案。
|
||||
|
||||
重点链路：
|
||||
- `POST /v1/messages`
|
||||
- `POST /v1/responses`
|
||||
- `POST /sora/v1/chat/completions`
|
||||
- `POST /v1beta/models/*modelAction`（Gemini 兼容链路）
|
||||
- 相关调度、计费、Ops 记录链路
|
||||
|
||||
## 2. 审计方式与结论边界
|
||||
|
||||
- 审计方式：静态代码审阅（只读），未对生产环境做侵入变更。
|
||||
- 结论类型：以“高置信度可优化点”为主，均附 `file:line` 证据。
|
||||
- 未覆盖项：本轮未执行压测与火焰图采样，吞吐增益需在压测环境量化确认。
|
||||
|
||||
## 3. 优先级总览
|
||||
|
||||
| 优先级 | 数量 | 结论 |
|
||||
|---|---:|---|
|
||||
| P0（Critical） | 2 | 存在资源失控风险，建议立即修复 |
|
||||
| P1（High） | 2 | 明确的热点 DB/Redis 放大路径，建议本迭代完成 |
|
||||
| P2（Medium） | 4 | 可观收益优化项，建议并行排期 |
|
||||
|
||||
## 4. 详细问题清单
|
||||
|
||||
### 4.1 P0-1：使用量记录为“每请求一个 goroutine”，高峰下可能无界堆积
|
||||
|
||||
证据位置：
|
||||
- `backend/internal/handler/gateway_handler.go:435`
|
||||
- `backend/internal/handler/gateway_handler.go:704`
|
||||
- `backend/internal/handler/openai_gateway_handler.go:382`
|
||||
- `backend/internal/handler/sora_gateway_handler.go:400`
|
||||
- `backend/internal/handler/gemini_v1beta_handler.go:523`
|
||||
|
||||
问题描述：
|
||||
- 记录用量使用 `go func(...)` 直接异步提交，未设置全局并发上限与排队背压。
|
||||
- 当 DB/Redis 变慢时，goroutine 数会随请求持续累积。
|
||||
|
||||
性能影响：
|
||||
- `goroutine` 激增导致调度开销上升与内存占用增加。
|
||||
- 与数据库连接池（默认 `max_open_conns=256`）竞争，放大尾延迟。
|
||||
|
||||
优化建议：
|
||||
- 引入“有界队列 + 固定 worker 池”替代每请求 goroutine。
|
||||
- 队列满时采用明确策略：丢弃（采样告警）或降级为同步短路。
|
||||
- 为 `RecordUsage` 路径增加超时、重试上限与失败计数指标。
|
||||
|
||||
验收指标：
|
||||
- 峰值 `goroutines` 稳定，无线性增长。
|
||||
- 用量记录成功率、丢弃率、队列长度可观测。
|
||||
|
||||
---
|
||||
|
||||
### 4.2 P0-2：Ops 错误日志队列携带原始请求体，存在内存放大风险
|
||||
|
||||
证据位置：
|
||||
- 队列容量与 job 结构：`backend/internal/handler/ops_error_logger.go:38`、`backend/internal/handler/ops_error_logger.go:43`
|
||||
- 入队逻辑：`backend/internal/handler/ops_error_logger.go:132`
|
||||
- 请求体放入 context：`backend/internal/handler/ops_error_logger.go:261`
|
||||
- 读取并入队：`backend/internal/handler/ops_error_logger.go:548`、`backend/internal/handler/ops_error_logger.go:563`、`backend/internal/handler/ops_error_logger.go:727`、`backend/internal/handler/ops_error_logger.go:737`
|
||||
- 入库前才裁剪：`backend/internal/service/ops_service.go:332`、`backend/internal/service/ops_service.go:339`
|
||||
- 请求体默认上限：`backend/internal/config/config.go:1082`、`backend/internal/config/config.go:1086`
|
||||
|
||||
问题描述：
|
||||
- 队列元素包含 `[]byte requestBody`，在请求体较大且错误风暴时会显著占用内存。
|
||||
- 当前裁剪发生在 worker 消费时，而不是入队前。
|
||||
|
||||
性能影响：
|
||||
- 容易造成瞬时高内存与频繁 GC。
|
||||
- 极端情况下可能触发 OOM 或服务抖动。
|
||||
|
||||
优化建议：
|
||||
- 入队前进行“脱敏 + 裁剪”，仅保留小尺寸结构化片段（建议 8KB~16KB）。
|
||||
- 队列存放轻量 DTO，避免持有大块 `[]byte`。
|
||||
- 按错误类型控制采样率，避免同类错误洪峰时日志放大。
|
||||
|
||||
验收指标：
|
||||
- Ops 错误风暴期间 RSS/GC 次数显著下降。
|
||||
- 队列满时系统稳定且告警可见。
|
||||
|
||||
---
|
||||
|
||||
### 4.3 P1-1：窗口费用检查在缓存 miss 时逐账号做 DB 聚合
|
||||
|
||||
证据位置：
|
||||
- 候选筛选多处调用：`backend/internal/service/gateway_service.go:1109`、`backend/internal/service/gateway_service.go:1137`、`backend/internal/service/gateway_service.go:1291`、`backend/internal/service/gateway_service.go:1354`
|
||||
- miss 后单账号聚合：`backend/internal/service/gateway_service.go:1791`
|
||||
- SQL 聚合实现：`backend/internal/repository/usage_log_repo.go:889`
|
||||
- 窗口费用缓存 TTL：`backend/internal/repository/session_limit_cache.go:33`
|
||||
- 已有批量读取接口但未利用：`backend/internal/repository/session_limit_cache.go:310`
|
||||
|
||||
问题描述：
|
||||
- 路由候选过滤阶段频繁调用窗口费用检查。
|
||||
- 缓存未命中时逐账号执行聚合查询，账号多时放大 DB 压力。
|
||||
|
||||
性能影响：
|
||||
- 路由耗时上升，数据库聚合 QPS 增长。
|
||||
- 高并发下可能形成“缓存抖动 + 聚合风暴”。
|
||||
|
||||
优化建议：
|
||||
- 先批量 `GetWindowCostBatch`，仅对 miss 账号执行批量 SQL 聚合。
|
||||
- 将聚合结果批量回写缓存，降低重复查询。
|
||||
- 评估窗口费用缓存 TTL 与刷新策略，减少抖动。
|
||||
|
||||
验收指标：
|
||||
- 路由阶段 DB 查询次数下降。
|
||||
- `SelectAccountWithLoadAwareness` 平均耗时下降。
|
||||
|
||||
---
|
||||
|
||||
### 4.4 P1-2：记录用量时每次查询用户分组倍率，形成稳定 DB 热点
|
||||
|
||||
证据位置：
|
||||
- `backend/internal/service/gateway_service.go:5316`
|
||||
- `backend/internal/service/gateway_service.go:5531`
|
||||
- `backend/internal/repository/user_group_rate_repo.go:45`
|
||||
|
||||
问题描述：
|
||||
- `RecordUsage` 与 `RecordUsageWithLongContext` 每次都执行 `GetByUserAndGroup`。
|
||||
- 热路径重复读数据库，且与 usage 写入、扣费路径竞争连接池。
|
||||
|
||||
性能影响：
|
||||
- 增加 DB 往返与延迟，降低热点接口吞吐。
|
||||
|
||||
优化建议：
|
||||
- 在鉴权或路由阶段预热倍率并挂载上下文复用。
|
||||
- 引入 L1/L2 缓存（短 TTL + singleflight），减少重复 SQL。
|
||||
|
||||
验收指标：
|
||||
- `GetByUserAndGroup` 调用量明显下降。
|
||||
- 计费链路 p95 延迟下降。
|
||||
|
||||
---
|
||||
|
||||
### 4.5 P2-1：Claude 消息链路重复 JSON 解析
|
||||
|
||||
证据位置：
|
||||
- 首次解析：`backend/internal/handler/gateway_handler.go:129`
|
||||
- 二次解析入口：`backend/internal/handler/gateway_handler.go:146`
|
||||
- 二次 `json.Unmarshal`：`backend/internal/handler/gateway_helper.go:22`、`backend/internal/handler/gateway_helper.go:26`
|
||||
|
||||
问题描述：
|
||||
- 同一请求先 `ParseGatewayRequest`，后 `SetClaudeCodeClientContext` 再做 `Unmarshal`。
|
||||
|
||||
性能影响：
|
||||
- 增加 CPU 与内存分配，尤其对大 `messages` 请求更明显。
|
||||
|
||||
优化建议：
|
||||
- 仅在 `User-Agent` 命中 Claude CLI 规则后再做 body 深解析。
|
||||
- 或直接复用首轮解析结果，避免重复反序列化。
|
||||
|
||||
---
|
||||
|
||||
### 4.6 P2-2：同一请求中粘性会话账号查询存在重复 Redis 读取
|
||||
|
||||
证据位置：
|
||||
- Handler 预取：`backend/internal/handler/gateway_handler.go:242`
|
||||
- Service 再取：`backend/internal/service/gateway_service.go:941`、`backend/internal/service/gateway_service.go:1129`、`backend/internal/service/gateway_service.go:1277`
|
||||
|
||||
问题描述：
|
||||
- 同一会话映射在同请求链路被多次读取。
|
||||
|
||||
性能影响：
|
||||
- 增加 Redis RTT 与序列化开销，抬高路由延迟。
|
||||
|
||||
优化建议：
|
||||
- 统一在 `SelectAccountWithLoadAwareness` 内读取并复用。
|
||||
- 或将上层已读到的 sticky account 显式透传给 service。
|
||||
|
||||
---
|
||||
|
||||
### 4.7 P2-3：并发等待路径存在重复抢槽
|
||||
|
||||
证据位置：
|
||||
- 首次 TryAcquire：`backend/internal/handler/gateway_helper.go:182`、`backend/internal/handler/gateway_helper.go:202`
|
||||
- wait 内再次立即 Acquire：`backend/internal/handler/gateway_helper.go:226`、`backend/internal/handler/gateway_helper.go:230`、`backend/internal/handler/gateway_helper.go:232`
|
||||
|
||||
问题描述：
|
||||
- 进入 wait 流程后会再做一次“立即抢槽”，与上层 TryAcquire 重复。
|
||||
|
||||
性能影响：
|
||||
- 在高并发下增加 Redis 操作次数，放大锁竞争。
|
||||
|
||||
优化建议：
|
||||
- wait 流程直接进入退避循环，避免重复立即抢槽。
|
||||
|
||||
---
|
||||
|
||||
### 4.8 P2-4：`/v1/models` 每次走仓储查询与对象装配，未复用快照/短缓存
|
||||
|
||||
证据位置：
|
||||
- 入口调用：`backend/internal/handler/gateway_handler.go:767`
|
||||
- 服务查询：`backend/internal/service/gateway_service.go:6152`、`backend/internal/service/gateway_service.go:6154`
|
||||
- 对象装配：`backend/internal/repository/account_repo.go:1276`、`backend/internal/repository/account_repo.go:1290`、`backend/internal/repository/account_repo.go:1298`
|
||||
|
||||
问题描述：
|
||||
- 模型列表请求每次都落到账号查询与附加装配，缺少短时缓存。
|
||||
|
||||
性能影响：
|
||||
- 高频请求下持续占用 DB 与 CPU。
|
||||
|
||||
优化建议：
|
||||
- 以 `groupID + platform` 建 10s~30s 本地缓存。
|
||||
- 或复用调度快照 bucket 的可用账号结果做模型聚合。
|
||||
|
||||
## 5. 建议实施顺序
|
||||
|
||||
### 阶段 A（立即，P0）
|
||||
- 将“用量记录每请求 goroutine”改为有界异步管道。
|
||||
- Ops 错误日志改为“入队前裁剪 + 轻量队列对象”。
|
||||
|
||||
### 阶段 B（短期，P1）
|
||||
- 批量化窗口费用检查（缓存 + SQL 双批量）。
|
||||
- 用户分组倍率加缓存/上下文复用。
|
||||
|
||||
### 阶段 C（中期，P2）
|
||||
- 消除重复 JSON 解析与重复 sticky 查询。
|
||||
- 优化并发等待重复抢槽逻辑。
|
||||
- `/v1/models` 接口加入短缓存或快照复用。
|
||||
|
||||
## 6. 压测与验证建议
|
||||
|
||||
建议在预发压测以下场景：
|
||||
- 场景 1：常规成功流量（验证吞吐与延迟）。
|
||||
- 场景 2：上游慢响应（验证 goroutine 与队列稳定性）。
|
||||
- 场景 3：错误风暴（验证 Ops 队列与内存上限）。
|
||||
- 场景 4：多账号大分组路由（验证窗口费用批量化收益）。
|
||||
|
||||
建议监控指标：
|
||||
- 进程：`goroutines`、RSS、GC 次数/停顿。
|
||||
- API：各热点接口 p50/p95/p99。
|
||||
- DB：QPS、慢查询、连接池等待。
|
||||
- Redis：命中率、RTT、命令量。
|
||||
- 业务：用量记录成功率/丢弃率、Ops 日志丢弃率。
|
||||
|
||||
## 7. 待补充数据
|
||||
|
||||
- 生产真实错误率与错误体大小分布。
|
||||
- `window_cost_limit` 实际启用账号比例。
|
||||
- `/v1/models` 实际调用频次。
|
||||
- DB/Redis 当前容量余量与瓶颈点。
|
||||
|
||||
---
|
||||
|
||||
如需进入实现阶段，建议按“阶段 A → 阶段 B → 阶段 C”分 PR 推进，每个阶段都附压测报告与回滚方案。
|
||||
Reference in New Issue
Block a user