# 后端热点 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 推进，每个阶段都附压测报告与回滚方案。