# LangGraph Sidecar 部署文档

## 前置依赖

- Docker + Docker Compose (推荐)
- 或 Python 3.11+ + pip (直接部署)
- LLM API Key (DeepSeek / OpenAI 兼容)

## 目录结构

```
cfc-langgraph/
├── Dockerfile
├── docker-compose.yml
├── prometheus.yml
├── .env.production          # 生产配置 (手动创建, 不上传 git)
├── app/                     # 服务代码
│   ├── main.py              # FastAPI 入口
│   ├── config.py            # 配置管理
│   ├── api/                 # HTTP 接口
│   ├── agents/              # Agent 定义
│   ├── graphs/              # LangGraph StateGraph
│   ├── tools/               # Agent Tool
│   ├── rag/                 # RAG Pipeline
│   ├── memory/              # 三层记忆
│   └── tasks/               # 定时任务
├── data/
│   └── chroma_db/           # ChromaDB 持久化 (自动创建)
└── docs/
    ├── deployment.md        # 本文件
    └── operations.md        # 运维手册
```

## Docker Compose 部署

```bash
# 1. 创建生产配置
cp .env.example .env.production
# 编辑 .env.production 填入 LLM_API_KEY

# 2. 构建并启动
docker-compose up -d

# 3. 验证
curl http://localhost:9000/api/v1/health

# 4. 查看日志
docker-compose logs -f langgraph-svc
```

## 直接部署 (无 Docker)

```bash
# 1. 安装依赖
pip install -e .

# 2. 配置环境变量
export LLM_API_KEY=sk-xxx
export JAVA_BASE_URL=http://localhost:9082

# 3. 启动
gunicorn app.main:app \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:9000 \
  --workers 2 \
  --timeout 60 \
  --access-logfile - \
  --error-logfile -
```

## 环境变量说明

| 变量 | 必填 | 说明 |
|------|------|------|
| LLM_API_KEY | 是 | LLM API Key |
| LLM_BASE_URL | 否 | 默认 https://api.deepseek.com/v1 |
| LLM_MODEL | 否 | 默认 deepseek-chat |
| JAVA_BASE_URL | 是 | Java 后端地址 |
| CHROMA_DB_PATH | 否 | ChromaDB 持久化路径, 默认 ./data/chroma_db |
| LOG_LEVEL | 否 | 日志级别, 默认 info |
| JSON_LOGS | 否 | 启用 JSON 日志格式, 默认 false |

## 健康检查

```
GET /api/v1/health

Response:
{
  "status": "ok",
  "components": {
    "chromadb": {"status": "ok", "path": "...", "exists": true},
    "llm": {"status": "ok"},
    "java_backend": {"status": "ok"}
  }
}
```