421 lines
8.0 KiB
Markdown
421 lines
8.0 KiB
Markdown
# 快速开始指南
|
||
|
||
详细的启动和部署指南，面向开发者和运维人员。
|
||
|
||
---
|
||
|
||
## 🚀 快速启动（3 步）
|
||
|
||
### 方式一：Docker Compose（推荐 ⭐）
|
||
|
||
适合生产环境，一键启动所有服务。
|
||
|
||
#### 1. 配置环境变量
|
||
|
||
```bash
|
||
# 复制 Docker 部署模板
|
||
cp .env.docker .env
|
||
|
||
# 编辑 .env 文件，填入真实的 API Key
|
||
vim .env # 或使用你喜欢的编辑器
|
||
```
|
||
|
||
**必需配置项**：
|
||
- `ZHIPUAI_API_KEY` - 智谱 AI API 密钥（从 [智谱开放平台](https://open.bigmodel.cn/) 获取）
|
||
- `LLAMACPP_API_KEY` - llama.cpp 服务认证 Token（与容器启动参数一致，默认 `token-abc123`）
|
||
|
||
**可选配置项**：
|
||
- `VLLM_BASE_URL` - LLM 服务地址（默认已配置为 `http://localhost:8081/v1`）
|
||
- `VLLM_EMBEDDING_URL` - Embedding 服务地址（默认已配置为 `http://localhost:8082/v1`）
|
||
- `DB_URI` - PostgreSQL 连接字符串（默认已配置，使用远程服务器地址）
|
||
- `QDRANT_URL` - Qdrant 向量数据库地址（默认已配置，使用远程服务器地址）
|
||
|
||
**注意**：Docker Compose 部署时，`API_URL` 由 `docker-compose.yml` 自动注入，无需在 `.env` 中配置。
|
||
|
||
#### 2. 启动服务
|
||
|
||
```bash
|
||
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
|
||
|
||
#### 常用命令
|
||
|
||
```bash
|
||
# 查看服务状态
|
||
docker compose ps
|
||
|
||
# 查看日志
|
||
docker compose logs -f
|
||
|
||
# 重启特定服务
|
||
docker compose restart backend
|
||
|
||
# 停止所有服务
|
||
docker compose down
|
||
```
|
||
|
||
---
|
||
|
||
### 方式二：本地开发模式
|
||
|
||
适合开发和调试。
|
||
|
||
#### 前置要求
|
||
|
||
- Python 3.10+
|
||
|
||
#### 1. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirement.txt
|
||
```
|
||
|
||
#### 2. 配置环境变量
|
||
|
||
复制并编辑 `.env` 文件：
|
||
|
||
```
|
||
# 基于 Docker 模板创建
|
||
cp .env.docker .env
|
||
vim .env
|
||
```
|
||
|
||
**本地开发需要修改以下配置**：
|
||
|
||
``env
|
||
ZHIPUAI_API_KEY=your_api_key_here
|
||
LLAMACPP_API_KEY=token-abc123
|
||
|
||
# 本地开发时，llama.cpp 服务在 localhost
|
||
VLLM_BASE_URL=http://localhost:8081/v1
|
||
VLLM_EMBEDDING_URL=http://localhost:8082/v1
|
||
|
||
# 数据库和向量存储使用远程服务器
|
||
DB_URI=postgresql://postgres:mysecretpassword@115.190.121.151:5432/langgraph_db?sslmode=disable
|
||
QDRANT_URL=http://115.190.121.151:6333
|
||
|
||
# 本地开发时，后端也在 localhost
|
||
API_URL=http://localhost:8003/chat
|
||
```
|
||
|
||
#### 3. 启动服务
|
||
|
||
**终端 1 - 后端：**
|
||
```bash
|
||
python app/backend.py
|
||
```
|
||
|
||
**终端 2 - 前端：**
|
||
```bash
|
||
cd frontend && streamlit run app.py
|
||
```
|
||
|
||
浏览器自动打开前端页面（如果配置了 Nginx，访问 `http://your-domain.com`；否则访问 http://localhost:8501）
|
||
|
||
---
|
||
|
||
## 🐳 Docker 部署详解
|
||
|
||
### 文件说明
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `docker-compose.yml` | 服务编排配置（仅包含 backend 和 frontend） |
|
||
| `Dockerfile.backend` | 后端镜像构建 |
|
||
| `Dockerfile.frontend` | 前端镜像构建 |
|
||
| `.gitea/workflows/deploy.yml` | CI/CD 自动化部署 |
|
||
|
||
### docker-compose.yml 结构
|
||
|
||
```yaml
|
||
services:
|
||
backend: # FastAPI 后端服务（连接远程 PostgreSQL 和 Qdrant）
|
||
frontend: # Streamlit 前端界面
|
||
```
|
||
|
||
**特性：**
|
||
- ✅ 通过环境变量连接远程 PostgreSQL 和 Qdrant
|
||
- ✅ 自动重启策略（`restart: unless-stopped`）
|
||
- ✅ 内部网络隔离
|
||
|
||
### 只更新特定服务
|
||
|
||
```bash
|
||
# 只重新构建后端
|
||
docker compose up -d --build backend
|
||
|
||
# 只重新启动前端
|
||
docker compose up -d frontend
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 开发指南
|
||
|
||
### 添加新工具
|
||
|
||
在 `app/tools.py` 中添加：
|
||
|
||
```python
|
||
@tool
|
||
def my_new_tool(param: str) -> str:
|
||
"""
|
||
工具描述（会显示给 LLM）
|
||
|
||
Args:
|
||
param: 参数说明
|
||
|
||
Returns:
|
||
返回值说明
|
||
"""
|
||
# 实现逻辑
|
||
return result
|
||
```
|
||
|
||
工具会自动注册，无需修改其他文件。
|
||
|
||
### 添加新模型
|
||
|
||
在 `app/agent.py` 中：
|
||
|
||
```python
|
||
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/app.py` 中添加选项：
|
||
|
||
```python
|
||
MODEL_OPTIONS = {
|
||
"智谱 GLM-4": "zhipu",
|
||
"本地 Gemma-4": "local",
|
||
"新模型": "new_model", # 新增
|
||
}
|
||
```
|
||
|
||
### 调试技巧
|
||
|
||
```bash
|
||
# 进入后端容器
|
||
docker compose exec backend bash
|
||
|
||
# 查看实时日志
|
||
docker compose logs -f backend
|
||
|
||
# 测试后端 API
|
||
curl http://localhost:8001/health
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 CI/CD 自动化部署
|
||
|
||
### Gitea Workflows
|
||
|
||
项目包含自动化部署配置 `.gitea/workflows/deploy.yml`。
|
||
|
||
**触发条件：**
|
||
- 推送到 `main` 或 `master` 分支
|
||
- 手动触发（workflow_dispatch）
|
||
|
||
**部署流程：**
|
||
1. 检出代码
|
||
2. 准备环境变量
|
||
3. 重新构建并启动前后端（不影响远程数据库）
|
||
4. 健康检查（等待后端就绪）
|
||
5. 清理无用 Docker 资源
|
||
|
||
**配置 Secrets：**
|
||
|
||
在 Gitea 仓库设置中添加：
|
||
- `ZHIPUAI_API_KEY`
|
||
- `VLLM_LOCAL_KEY`
|
||
|
||
---
|
||
|
||
## 🐛 故障排查
|
||
|
||
### 常见问题
|
||
|
||
#### 1. 无法连接远程数据库
|
||
|
||
```bash
|
||
# 测试 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. 后端启动失败
|
||
|
||
```bash
|
||
# 查看详细日志
|
||
docker compose logs backend
|
||
|
||
# 检查端口占用
|
||
lsof -i :8001
|
||
```
|
||
|
||
**常见原因：**
|
||
- API Key 未配置或错误
|
||
- 端口 8001 被占用
|
||
- 依赖包缺失
|
||
|
||
#### 3. 前端无法连接后端
|
||
|
||
**错误信息：**
|
||
```
|
||
HTTPConnectionPool(host='backend', port=8001): Max retries exceeded
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
1. **检查容器是否在同一网络中：**
|
||
```bash
|
||
docker network inspect docker_ai-network
|
||
```
|
||
|
||
2. **验证环境变量配置：**
|
||
```bash
|
||
docker compose exec frontend env | grep API_URL
|
||
```
|
||
|
||
3. **重启服务：**
|
||
```bash
|
||
docker compose down
|
||
docker compose up -d --build
|
||
docker compose logs -f
|
||
```
|
||
|
||
#### 4. 模型初始化失败
|
||
|
||
```bash
|
||
# 查看后端启动日志
|
||
docker compose logs backend | grep -i "model\|error"
|
||
```
|
||
|
||
**可能原因：**
|
||
- 智谱 API Key 无效
|
||
- vLLM 容器未启动（如使用本地模型）
|
||
- 网络连接问题
|
||
|
||
#### 5. 环境变量未生效
|
||
|
||
**症状：**
|
||
- 服务启动时提示缺少必需的环境变量
|
||
- API Key 为空或使用默认值
|
||
|
||
**解决方案：**
|
||
|
||
1. **检查 .env 文件格式：**
|
||
```bash
|
||
cat -A .env
|
||
```
|
||
|
||
2. **验证环境变量已加载：**
|
||
```bash
|
||
docker compose exec backend env | grep ZHIPUAI_API_KEY
|
||
docker compose exec frontend env | grep API_URL
|
||
```
|
||
|
||
3. **重新构建容器：**
|
||
```bash
|
||
docker compose down
|
||
docker compose up -d --build
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 监控和维护
|
||
|
||
### 查看资源使用
|
||
|
||
```bash
|
||
# Docker 容器资源使用
|
||
docker stats
|
||
|
||
# 磁盘空间
|
||
docker system df
|
||
|
||
# 清理无用资源
|
||
docker system prune -f
|
||
```
|
||
|
||
### 日志管理
|
||
|
||
```bash
|
||
# 查看所有服务日志
|
||
docker compose logs
|
||
|
||
# 查看特定服务最近 100 行日志
|
||
docker compose logs --tail=100 backend
|
||
|
||
# 实时跟踪日志
|
||
docker compose logs -f backend frontend
|
||
```
|
||
|
||
### 备份和恢复
|
||
|
||
```bash
|
||
# 备份远程数据库
|
||
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](README.md)
|
||
- **报告问题**: 提交 Issue 并附上日志
|
||
|
||
---
|
||
|
||
**祝您部署顺利！** 🎉
|