ailine/QUICKSTART.md

快速开始指南

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

---

🚀 快速启动（3 步）

方式一：Docker Compose（推荐 ⭐）

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

1. 配置环境变量

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

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

必需配置项：

• ZHIPUAI_API_KEY - 智谱 AI API 密钥（从 智谱开放平台 获取）
• DEEPSEEK_API_KEY - DeepSeek API 密钥（从 DeepSeek 开放平台 获取）
• LLAMACPP_API_KEY - llama.cpp 服务认证 Token（与容器启动参数一致，默认 token-abc123）

可选配置项：

• VLLM_BASE_URL - LLM 服务地址（本地默认：http://127.0.0.1:8081/v1）
• LLAMACPP_EMBEDDING_URL - Embedding 服务地址（本地默认：http://127.0.0.1:8082/v1）
• DB_URI - PostgreSQL 连接字符串（默认已配置远程服务器地址）
• QDRANT_URL - Qdrant 向量数据库地址（默认已配置远程服务器地址）
• LOG_LEVEL - 日志级别（DEBUG/INFO/WARNING/ERROR）
• ENABLE_GRAPH_TRACE - 是否启用图流转追踪（true/false）
• MEMORY_SUMMARIZE_INTERVAL - 对话摘要生成间隔（默认 10）

2. 启动服务

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

3. 访问应用

• 前端: http://127.0.0.1:8501
• 后端 API: http://127.0.0.1:8083
• 健康检查: http://127.0.0.1:8083/health

常用命令

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 查看特定服务日志
docker compose logs -f backend

# 重启特定服务
docker compose restart backend

# 停止所有服务
docker compose down

# 重新构建并启动
docker compose up -d --build

---

方式二：本地开发模式

适合开发和调试。

前置要求

• Python 3.10+

1. 安装依赖

pip install -r requirement.txt

2. 配置环境变量

复制并编辑 .env 文件：

cp .env.docker .env
vim .env

本地开发配置示例：

# API Keys
ZHIPUAI_API_KEY=your_api_key_here
DEEPSEEK_API_KEY=your_deepseek_api_key_here
LLAMACPP_API_KEY=token-abc123

# LLM 服务地址（本地开发）
VLLM_BASE_URL=http://127.0.0.1:8081/v1
LLAMACPP_EMBEDDING_URL=http://127.0.0.1:8082/v1

# 远程数据库和向量存储
DB_URI=postgresql://postgres:your_password_here@115.190.121.151:5432/langgraph_db?sslmode=disable
QDRANT_URL=http://115.190.121.151:6333

# 日志和调试
LOG_LEVEL=INFO
ENABLE_GRAPH_TRACE=true
MEMORY_SUMMARIZE_INTERVAL=10

3. 启动服务

终端 1 - 后端：

python backend/app/backend.py

终端 2 - 前端：

streamlit run frontend/src/frontend_main.py

或者使用启动脚本（推荐）：

./scripts/start.sh both

浏览器自动打开前端页面，访问 http://127.0.0.1:8501

---

🐳 Docker 部署详解

文件说明

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

docker-compose.yml 结构

services:
  backend:      # FastAPI 后端服务（端口 8083）
  frontend:     # Streamlit 前端界面（端口 8501）

特性：

• ✅ 通过环境变量连接远程 PostgreSQL 和 Qdrant
• ✅ 自动重启策略（restart: unless-stopped）
• ✅ 内部网络隔离（ai-network）
• ✅ 文档目录挂载（./data/user_docs）
• ✅ 日志目录挂载（./logs）

只更新特定服务

# 只重新构建后端
docker compose up -d --build backend

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

---

🔧 开发指南

添加新工具

在 backend/app/graph/graph_tools.py 中添加：

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

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

添加新模型

在 backend/app/agent/llm_factory.py 中：

@staticmethod
def create_new_model():
    """创建新模型的 LLM"""
    api_key = os.getenv("NEW_MODEL_API_KEY")
    return ChatOpenAI(
        base_url="https://api.new-model.com/v1",
        api_key=SecretStr(api_key),
        model="model-name",
        temperature=0.1,
        streaming=True,
    )

然后在 CREATORS 字典中注册：

CREATORS = {
    "local": create_local,
    "deepseek": create_deepseek,
    "zhipu": create_zhipu,
    "new_model": create_new_model,  # 新增
}

调试技巧

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

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

# 测试后端 API
curl http://127.0.0.1:8083/health

# 测试对话接口
curl -X POST http://127.0.0.1:8083/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好", "model": "zhipu"}'

---

🔄 CI/CD 自动化部署

Gitea Workflows

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

触发条件：

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

部署流程：

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

配置 Secrets：

在 Gitea 仓库设置中添加：

• ZHIPUAI_API_KEY
• DEEPSEEK_API_KEY
• LLAMACPP_API_KEY

---

🐛 故障排查

常见问题

1. 无法连接远程数据库

# 测试 PostgreSQL 连接
psql -h 115.190.121.151 -U postgres -d langgraph_db -c "SELECT version();"

# 测试 Qdrant 连接
curl http://115.190.121.151:6333/collections

解决方案：

• 确认远程服务器防火墙开放了 5432 和 6333 端口
• 检查网络连接是否正常
• 验证用户名和密码是否正确

2. 后端启动失败

# 查看详细日志
docker compose logs backend

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

常见原因：

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

3. 前端无法连接后端

错误信息：

HTTPConnectionPool(host='backend', port=8083): Max retries exceeded

解决方案：

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

docker network inspect docker_ai-network

2. 验证环境变量配置：

docker compose exec frontend env | grep API_URL

3. 重启服务：

docker compose down
docker compose up -d --build
docker compose logs -f

4. 模型初始化失败

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

可能原因：

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

5. 环境变量未生效

症状：

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

解决方案：

1. 检查 .env 文件格式：

cat -A .env

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

docker compose exec backend env | grep ZHIPUAI_API_KEY
docker compose exec frontend env | grep API_URL

3. 重新构建容器：

docker compose down
docker compose up -d --build

---

📊 监控和维护

查看资源使用

# 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

备份和恢复

# 备份远程数据库
pg_dump -h 115.190.121.151 -U postgres langgraph_db > backup.sql

# 恢复数据库
cat backup.sql | psql -h 115.190.121.151 -U postgres langgraph_db

---

🎯 性能优化建议

开发环境

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

生产环境

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

---

📞 获取帮助

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

---

祝您部署顺利！ 🎉