root
22cc9b1096
Some checks failed
构建并部署 AI Agent 服务 / deploy (push) Failing after 1s
docs(.gitignore/README/QUICKSTART): 更新文档和忽略配置 - 添加IDE配置、日志和数据文件到.gitignore - 重构QUICKSTART.md，提供Docker Compose和本地开发两种部署方式 - 更新README.md，优化项目介绍和架构说明 - 移除旧的agent.py和backend.py文件 ```
386 lines
6.6 KiB
Markdown
386 lines
6.6 KiB
Markdown
# 快速开始指南
|
||
|
||
详细的启动和部署指南，面向开发者和运维人员。
|
||
|
||
---
|
||
|
||
## 🚀 快速启动（3 步）
|
||
|
||
### 方式一：Docker Compose（推荐 ⭐）
|
||
|
||
适合生产环境，一键启动所有服务。
|
||
|
||
#### 1. 配置环境变量
|
||
|
||
```bash
|
||
cat > .env << EOF
|
||
ZHIPUAI_API_KEY=your_zhipuai_api_key_here
|
||
VLLM_LOCAL_KEY=token-abc123
|
||
EOF
|
||
```
|
||
|
||
#### 2. 启动服务
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
#### 3. 访问应用
|
||
|
||
- **前端**: 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+
|
||
- Docker（用于 PostgreSQL）
|
||
|
||
#### 1. 启动 PostgreSQL
|
||
|
||
```bash
|
||
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. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirement.txt
|
||
```
|
||
|
||
#### 3. 配置环境变量
|
||
|
||
编辑 `.env` 文件：
|
||
|
||
```env
|
||
ZHIPUAI_API_KEY=your_api_key_here
|
||
```
|
||
|
||
#### 4. 启动服务
|
||
|
||
**终端 1 - 后端：**
|
||
```bash
|
||
python backend.py
|
||
```
|
||
|
||
**终端 2 - 前端：**
|
||
```bash
|
||
streamlit run frontend.py
|
||
```
|
||
|
||
浏览器自动打开 http://localhost:8501
|
||
|
||
---
|
||
|
||
## 🐳 Docker 部署详解
|
||
|
||
### 文件说明
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `docker-compose.yml` | 服务编排配置 |
|
||
| `Dockerfile.backend` | 后端镜像构建 |
|
||
| `Dockerfile.frontend` | 前端镜像构建 |
|
||
| `.gitea/workflows/deploy.yml` | CI/CD 自动化部署 |
|
||
|
||
### docker-compose.yml 结构
|
||
|
||
```yaml
|
||
services:
|
||
postgres: # PostgreSQL 数据库
|
||
backend: # FastAPI 后端服务
|
||
frontend: # Streamlit 前端界面
|
||
```
|
||
|
||
**特性：**
|
||
- ✅ PostgreSQL 健康检查，确保数据库就绪后才启动后端
|
||
- ✅ 数据持久化到 Docker volume
|
||
- ✅ 自动重启策略（`restart: unless-stopped`）
|
||
- ✅ 内部网络隔离，外部无法直接访问数据库
|
||
|
||
### 只更新特定服务
|
||
|
||
```bash
|
||
# 只重新构建后端（不影响数据库）
|
||
docker compose up -d --build backend
|
||
|
||
# 只重新启动前端
|
||
docker compose up -d frontend
|
||
```
|
||
|
||
### 数据持久化
|
||
|
||
PostgreSQL 数据存储在命名 volume `pg_data` 中：
|
||
|
||
```bash
|
||
# 查看 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` 中添加：
|
||
|
||
```python
|
||
@tool
|
||
def my_new_tool(param: str) -> str:
|
||
"""
|
||
工具描述（会显示给 LLM）
|
||
|
||
Args:
|
||
param: 参数说明
|
||
|
||
Returns:
|
||
返回值说明
|
||
"""
|
||
# 实现逻辑
|
||
return result
|
||
```
|
||
|
||
工具会自动注册，无需修改其他文件。
|
||
|
||
### 添加新模型
|
||
|
||
在 `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.py` 中添加选项：
|
||
|
||
```python
|
||
MODEL_OPTIONS = {
|
||
"智谱 GLM-4": "zhipu",
|
||
"本地 Gemma-4": "local",
|
||
"新模型": "new_model", # 新增
|
||
}
|
||
```
|
||
|
||
### 调试技巧
|
||
|
||
```bash
|
||
# 进入后端容器
|
||
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 连接失败
|
||
|
||
```bash
|
||
# 检查容器状态
|
||
docker compose ps postgres
|
||
|
||
# 查看日志
|
||
docker compose logs postgres
|
||
|
||
# 测试连接
|
||
docker compose exec postgres pg_isready -U postgres
|
||
```
|
||
|
||
**解决方案：**
|
||
- 确认容器正在运行
|
||
- 检查密码是否正确
|
||
- 等待健康检查通过（约 10-30 秒）
|
||
|
||
#### 2. 后端启动失败
|
||
|
||
```bash
|
||
# 查看详细日志
|
||
docker compose logs backend
|
||
|
||
# 检查端口占用
|
||
lsof -i :8001
|
||
```
|
||
|
||
**常见原因：**
|
||
- API Key 未配置或错误
|
||
- 端口 8001 被占用
|
||
- 依赖包缺失
|
||
|
||
#### 3. 前端无法连接后端
|
||
|
||
```bash
|
||
# 检查后端是否正常运行
|
||
curl http://localhost:8001/
|
||
|
||
# 检查网络连接
|
||
docker compose exec frontend ping backend
|
||
```
|
||
|
||
**解决方案：**
|
||
- 确认后端服务已启动
|
||
- 检查防火墙设置
|
||
- 重启前端服务
|
||
|
||
#### 4. 模型初始化失败
|
||
|
||
```bash
|
||
# 查看后端启动日志
|
||
docker compose logs backend | grep -i "model\|error"
|
||
```
|
||
|
||
**可能原因：**
|
||
- 智谱 API Key 无效
|
||
- vLLM 容器未启动（如使用本地模型）
|
||
- 网络连接问题
|
||
|
||
---
|
||
|
||
## 📊 监控和维护
|
||
|
||
### 查看资源使用
|
||
|
||
```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
|
||
# 备份数据库
|
||
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](README.md)
|
||
- **RAG 示例**: `rag_example.py`
|
||
- **报告问题**: 提交 Issue 并附上日志
|
||
|
||
---
|
||
|
||
**祝您部署顺利！** 🎉
|