ailine/QUICKSTART.md

快速开始指南

详细的启动和部署指南，面向开发者和运维人员。

---

🚀 快速启动（3 步）

方式一：Docker Compose（推荐 ⭐）

适合生产环境，一键启动所有服务。

1. 配置环境变量

# 复制 Docker 部署模板
cp .env.docker .env

# 编辑 .env 文件，填入真实的 API Key
vim .env  # 或使用你喜欢的编辑器

必需配置项：

• ZHIPUAI_API_KEY - 智谱 AI API 密钥（从 智谱开放平台 获取）
• VLLM_LOCAL_KEY - 本地 vLLM 服务认证 Token（与 vLLM 容器的 --api-key 参数一致）

可选配置项：

• VLLM_BASE_URL - vLLM 服务地址（默认已配置为 FRP 穿透地址）
• DB_URI - PostgreSQL 连接字符串（默认已配置，使用 Docker 服务名 postgres）

注意：Docker Compose 部署时，API_URL 由 docker-compose.yml 自动注入，无需在 .env 中配置。

2. 启动服务

docker compose -f docker/docker-compose.yml up -d --build

3. 访问应用

如果配置了 Nginx 反向代理：

• 访问地址：http://your-domain.com 或 http://your-server-ip

如果未配置 Nginx（直接访问容器）：

• 前端: http://localhost:8501
• 后端 API: http://localhost:8001

常用命令

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 重启特定服务
docker compose restart backend

# 停止所有服务
docker compose down

---

方式二：本地开发模式

适合开发和调试。

前置要求

• Python 3.10+
• Docker（用于 PostgreSQL）

1. 启动 PostgreSQL

docker run -d \
  --name postgres-langgraph \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_DB=langgraph_db \
  -p 5432:5432 \
  -v ~/docker_volumes/postgres_data:/var/lib/postgresql/data \
  postgres:16

2. 安装依赖

pip install -r requirement.txt

3. 配置环境变量

复制并编辑 .env 文件：

# 基于 Docker 模板创建，然后修改为本地配置
cp .env.docker .env
vim .env

本地开发需要修改以下配置：

ZHIPUAI_API_KEY=your_api_key_here
VLLM_LOCAL_KEY=token-abc123

# 本地开发时，vLLM 和数据库都在 localhost
VLLM_BASE_URL=http://localhost:8000/v1
DB_URI=postgresql://postgres:mysecretpassword@localhost:5432/langgraph_db?sslmode=disable

# 本地开发时，后端也在 localhost
API_URL=http://localhost:8001/chat

4. 启动服务

终端 1 - 后端：

python backend.py

终端 2 - 前端：

streamlit run frontend.py

浏览器自动打开前端页面（如果配置了 Nginx，访问 http://your-domain.com；否则访问 http://localhost:8501）

---

🐳 Docker 部署详解

文件说明

文件	用途
docker-compose.yml	服务编排配置
Dockerfile.backend	后端镜像构建
Dockerfile.frontend	前端镜像构建
.gitea/workflows/deploy.yml	CI/CD 自动化部署

docker-compose.yml 结构

services:
  postgres:     # PostgreSQL 数据库
  backend:      # FastAPI 后端服务
  frontend:     # Streamlit 前端界面

特性：

• ✅ PostgreSQL 健康检查，确保数据库就绪后才启动后端
• ✅ 数据持久化到 Docker volume
• ✅ 自动重启策略（restart: unless-stopped）
• ✅ 内部网络隔离，外部无法直接访问数据库

只更新特定服务

# 只重新构建后端（不影响数据库）
docker compose up -d --build backend

# 只重新启动前端
docker compose up -d frontend

数据持久化

PostgreSQL 数据存储在命名 volume pg_data 中：

# 查看 volume
docker volume ls | grep pg_data

# 备份数据
docker run --rm -v pg_data:/data -v $(pwd):/backup alpine tar czf /backup/pg_backup.tar.gz /data

# 恢复数据
docker run --rm -v pg_data:/data -v $(pwd):/backup alpine tar xzf /backup/pg_backup.tar.gz -C /

---

🔧 开发指南

添加新工具

在 tools.py 中添加：

@tool
def my_new_tool(param: str) -> str:
    """
    工具描述（会显示给 LLM）
    
    Args:
        param: 参数说明
        
    Returns:
        返回值说明
    """
    # 实现逻辑
    return result

工具会自动注册，无需修改其他文件。

添加新模型

在 agent.py 中：

def _create_new_model_llm(self):
    """创建新模型的 LLM"""
    return YourChatModel(
        model="model-name",
        api_key=os.getenv("YOUR_API_KEY"),
    )

# 在 initialize() 方法中注册
model_configs = {
    "zhipu": self._create_zhipu_llm,
    "local": self._create_local_llm,
    "new_model": self._create_new_model_llm,  # 新增
}

在前端 frontend.py 中添加选项：

MODEL_OPTIONS = {
    "智谱 GLM-4": "zhipu",
    "本地 Gemma-4": "local",
    "新模型": "new_model",  # 新增
}

调试技巧

# 进入后端容器
docker compose exec backend bash

# 查看实时日志
docker compose logs -f backend

# 检查数据库连接
docker compose exec postgres psql -U postgres -d langgraph_db -c "\dt"

# 测试后端 API
curl http://localhost:8001/

---

🔄 CI/CD 自动化部署

Gitea Workflows

项目包含自动化部署配置 .gitea/workflows/deploy.yml。

触发条件：

• 推送到 main 或 master 分支
• 手动触发（workflow_dispatch）

部署流程：

1. 检出代码
2. 安装 Python 依赖（验证用）
3. 准备环境变量
4. 重新构建并启动前后端（不影响数据库）
5. 健康检查（等待后端就绪）
6. 清理无用 Docker 资源

配置 Secrets：

在 Gitea 仓库设置中添加：

• ZHIPUAI_API_KEY
• VLLM_LOCAL_KEY

---

🐛 故障排查

常见问题

1. PostgreSQL 连接失败

# 检查容器状态
docker compose ps postgres

# 查看日志
docker compose logs postgres

# 测试连接
docker compose exec postgres pg_isready -U postgres

解决方案：

• 确认容器正在运行
• 检查密码是否正确
• 等待健康检查通过（约 10-30 秒）

2. 后端启动失败

# 查看详细日志
docker compose logs backend

# 检查端口占用
lsof -i :8001

常见原因：

• API Key 未配置或错误
• 端口 8001 被占用
• 依赖包缺失

3. 前端无法连接后端（NameResolutionError）

错误信息：

HTTPConnectionPool(host='backend', port=8001): Max retries exceeded with url: /chat 
(Caused by NameResolutionError("HTTPConnection(host='backend', port=8001): Failed to resolve 'backend'"))

原因分析：

• 前端容器和后端容器不在同一个 Docker 网络中
• docker-compose.yml 中的服务名配置错误
• 环境变量 API_URL 配置不正确

解决方案：

1. 检查容器是否在同一网络中：

# 查看所有 Docker 网络
docker network ls

# 检查 ai-network 网络中的容器
docker network inspect docker_ai-network

2. 确认服务名正确：

# 查看运行中的容器
docker compose ps

# 应该看到：ai-backend, ai-frontend, ai-postgres

3. 验证环境变量配置：

# 进入前端容器检查环境变量
docker compose exec frontend env | grep API_URL

# 应该输出：API_URL=http://backend:8001/chat

4. 重启服务：

# 完全停止并重新启动所有服务
docker compose down
docker compose up -d --build

# 查看启动日志
docker compose logs -f

5. 测试网络连通性：

# 从前端容器 ping 后端服务
docker compose exec frontend ping backend

# 从前端容器访问后端 API
docker compose exec frontend curl http://backend:8001/health

重要提示：

• Docker Compose 会自动创建名为 <项目目录>_ai-network 的网络
• 容器间通过服务名（而非容器名）进行通信
• 在 docker-compose.yml 中，服务名是 backend、frontend、postgres
• 确保所有服务都连接到同一个自定义网络（ai-network）

4. 模型初始化失败

# 查看后端启动日志
docker compose logs backend | grep -i "model\|error"

可能原因：

• 智谱 API Key 无效
• vLLM 容器未启动（如使用本地模型）
• 网络连接问题

5. 环境变量未生效

症状：

• 服务启动时提示缺少必需的环境变量
• API Key 为空或使用默认值

解决方案：

1. 检查 .env 文件格式：

# 确保文件末尾没有多余字符（如 EOF）
cat -A .env

# 正确格式应该是每行一个变量，无多余空格或特殊字符

2. 验证环境变量已加载：

# 检查后端容器的环境变量
docker compose exec backend env | grep ZHIPUAI_API_KEY

# 检查前端容器的环境变量
docker compose exec frontend env | grep API_URL

3. 重新构建容器：

# 修改 .env 后需要重新创建容器
docker compose down
docker compose up -d --build

4. 确认 .env 文件位置：

# .env 文件应该在项目根目录（与 docker-compose.yml 的父目录同级）
ls -la .env

# docker-compose.yml 中使用了 context: .. ，所以 .env 应该在上一级目录

---

📊 监控和维护

查看资源使用

# Docker 容器资源使用
docker stats

# 磁盘空间
docker system df

# 清理无用资源
docker system prune -f

日志管理

# 查看所有服务日志
docker compose logs

# 查看特定服务最近 100 行日志
docker compose logs --tail=100 backend

# 实时跟踪日志
docker compose logs -f backend frontend

备份和恢复

# 备份数据库
docker compose exec postgres pg_dump -U postgres langgraph_db > backup.sql

# 恢复数据库
cat backup.sql | docker compose exec -T postgres psql -U postgres langgraph_db

---

🎯 性能优化建议

开发环境

• 使用 docker compose watch 实现热重载（需配置）
• 挂载代码目录而非复制到镜像
• 启用 Python 调试模式

生产环境

• 使用反向代理（Nginx）
• 启用 HTTPS
• 配置日志轮转
• 设置资源限制（CPU、内存）
• 定期备份数据库

---

📞 获取帮助

• 完整文档: README.md
• RAG 示例: rag_example.py
• 报告问题: 提交 Issue 并附上日志

---

祝您部署顺利！ 🎉