性能调优

慢，先别瞎调。按「症状 → 看哪个值」的速查表定位，再动手。

7.1 慢了，先看这三个值

两条命令定位 80% 的瓶颈。

1. 容器资源：docker stats --no-stream，看 agent、postgres 的 CPU% / MEM%
2. 健康检查耗时：curl -w "%{time_total}\n" -o /dev/null -s http://localhost:3001/health，正常 < 100ms
3. 对照下表锁定章节

小贴士： 调优前先备份，按数据备份与恢复打快照。每次只改一个参数，观察 1-2 天再动下一个。

7.2 PostgreSQL 内存参数

compose 自带的 postgres 是小内存出厂配置，按机器实际内存调三个值。

1. 编辑 compose 里 postgres 服务的 command，按下表加参数（或挂自定义 postgresql.conf）
2. 重启：docker compose up -d postgres
3. 验证：docker compose exec postgres psql -U aiagent -d aiagent -c "SHOW shared_buffers;"

注意： shared_buffers 别超物理内存 1/4。再高反而拖慢，OS 缓存被挤掉了。

7.3 索引：高频查询走索引

列表慢、历史消息卡，多半是没命中索引。

1. 开慢查询：ALTER SYSTEM SET log_min_duration_statement = '500ms'; 然后 SELECT pg_reload_conf();
2. 跑几小时后 docker compose logs postgres | grep "duration:"，挑最慢的几条用 EXPLAIN ANALYZE 看有没有 Seq Scan 大表
3. 高频字段补复合索引，必须用 CONCURRENTLY 不锁表

-- 示例：会话消息按时间倒序
CREATE INDEX CONCURRENTLY idx_msg_session_time
  ON messages (session_id, created_at DESC);

注意： 索引不是越多越好。每个索引都拖慢写入，定期用 pg_stat_user_indexes 删没用过的。

7.4 模型上游与限频

对话整体慢，多半不是本机问题，是 LLM 上游 QPS 不够。

1. agent 日志频繁出现 429 或「速率限制」= 上游套餐不够，去 admin 加多 key 轮询，或升级套餐
2. 反向代理给对话接口加每用户限速（参考反向代理 + HTTPS limit_req_zone），削峰避免一股脑打满
3. 流式接口超时设到 300 秒（见 7.5），别让长回答中途被砍

小贴士： 首字慢 vs 总长慢。首字慢 = LLM 排队或网络；首字快但总时长长 = 回答本身太长，引导用户问得更具体。

7.5 反向代理：静态资源 + 流式

登录页慢、对话「等一会儿整段蹦出来」，都是 nginx 没配对。

1. 开 gzip + 静态资源长缓存
2. 对话接口必须关代理缓冲，超时拉到 300s
3. nginx -t → nginx -s reload

gzip on;
gzip_types text/css application/javascript application/json;

location /assets/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}
location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_buffering off;          # 流式对话必须关
    proxy_read_timeout 300s;      # 留足长回答时间
}

注意： index.html 不要长缓存，只缓存带 hash 的 /assets/，否则升级后用户白屏。

7.6 何时该扩容

调参顶到天花板，单机仍跑满，就是真的该加机器。

1. 扩容前压测拿基线：ab -n 1000 -c 50 https://your-xj.com/health，记 QPS 与 P95
2. 扩容后跑同样压测对比，没提升就是没扩对地方
3. 动手前按数据备份与恢复备份

注意： 水平扩容 ≠ 直接复制容器。多实例 agent 必须共享同一份 postgres 与上传目录（NFS 或对象存储），否则会话和文件会分裂。设计不清就先把单机垂直顶住。

相关

• 反向代理 + HTTPS
• 数据备份与恢复
• 日志查看与故障排查