# LangGraph Sidecar 运维手册

## 日常监控

### 1. 健康检查

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

```bash
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:

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

## 常见问题

### Python 服务无法启动

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

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

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

### LLM 调用失败

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

### ChromaDB 损坏

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

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

### 知识库同步失败

```bash
# 检查 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:

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

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

## 扩缩容

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

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

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

## 备份

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