LangGraph Sidecar 运维手册

日常监控

1. 健康检查

生产环境建议配置 30 秒定时健康检查:

curl -f http://localhost:9000/api/v1/health

预期返回 {"status":"ok"}。组件降级时返回 {"status":"degraded"}。

2. Prometheus 指标

GET /metrics

关键指标:
- agent_calls_total{agent_type="chat|recommend|analysis"}
- agent_duration_seconds{agent_type="..."}
- llm_calls_total{model="deepseek-chat",status="ok|error"}
- llm_duration_seconds{model="..."}
- kb_sync_duration_seconds        # 知识库同步耗时

3. 日志

JSON 格式日志可直接接入 ELK / Loki:

{"timestamp":"2026-07-20T10:00:00","level":"WARN","logger":"app.main","message":"SLOW_REQUEST: POST /api/v1/chat took 8.23s"}

常见问题

Python 服务无法启动

# 检查依赖
pip list | grep -E "fastapi|langchain|langgraph"

# 检查配置
python -c "from app.config import settings; print(settings.llm_model)"

# 检查端口占用
netstat -ano | grep 9000

LLM 调用失败

检查 .env.production 中的 LLM_API_KEY 是否有效
检查 LLM_BASE_URL 是否可访问
查看日志: docker-compose logs langgraph-svc | grep llm_call

ChromaDB 损坏

# 删除后重建 (知识库会自动同步)
rm -rf data/chroma_db/
docker-compose restart langgraph-svc

# 或触发手动同步
curl -X POST http://localhost:9000/api/v1/admin/kb-sync

知识库同步失败

# 检查 Java 后端是否可访问
curl http://localhost:9082/health

# 检查文章接口
curl -X POST http://localhost:9082/api/article/updated-since \
  -H "Content-Type: application/json" \
  -d '{"since":"2026-01-01T00:00:00","status":"published"}'

# 手动触发同步
docker-compose exec langgraph-svc python -c "
import asyncio
from app.tasks.knowledge_sync import sync_knowledge_base
asyncio.run(sync_knowledge_base())
"

Java 端回退 Dify

如果 Python 服务异常, Java 会自动回退 Dify:

# application.yml 检查配置
python:
  enabled: true
  circuit-breaker:
    failure-threshold: 3
    reset-timeout-ms: 30000

熔断器打开时, Java 侧日志会输出 AiGateway 熔断器已打开, 等待 reset-timeout-ms 后自动半开重试。

扩缩容

LangGraph 服务是无状态的 (ChromaDB 在共享存储上):

# docker-compose 增加副本数
services:
  langgraph-svc:
    deploy:
      replicas: 2

注意: ChromaDB 文件模式不支持并发写入, 多副本时知识库同步需加锁或切 PGVector。

备份

# ChromaDB 数据
tar czf chroma_backup_$(date +%Y%m%d).tar.gz data/chroma_db/

operations.md 2.6 KB 永久链接 文件历史 原始文件