231 lines
4.5 KiB
Markdown
231 lines
4.5 KiB
Markdown
# AgentEvalTool 部署文档
|
||
|
||
**版本**: v1.0
|
||
**日期**: 2026-07-09
|
||
**状态**: 已发布
|
||
**作者**: AgentEval Team
|
||
|
||
---
|
||
|
||
## 一、概述
|
||
|
||
本文档提供 AgentEvalTool 的部署指南，包括 Docker 容器化部署和裸机部署两种方式。
|
||
|
||
## 二、部署方式
|
||
|
||
### 2.1 Docker 容器化部署（推荐）
|
||
|
||
Docker 部署是推荐的生产环境部署方式，提供以下优势：
|
||
- 环境隔离
|
||
- 易于扩展
|
||
- 版本管理
|
||
- 快速部署
|
||
|
||
**部署文档**：
|
||
- [t480 服务器部署指南](t480-v1.0.md) - 针对 t480 测试服务器的具体部署步骤
|
||
- [volcengine-102 正式线部署指南](volcengine-102-v1.0.md) - 版本化发布、备份、迁移、健康检查与回滚
|
||
|
||
### 2.2 裸机部署
|
||
|
||
裸机部署适用于开发环境或特殊需求场景。
|
||
|
||
**前置要求**：
|
||
- Python 3.10+
|
||
- Node.js 18+（用于构建前端）
|
||
- Git
|
||
|
||
**部署步骤**：
|
||
|
||
1. **克隆代码**
|
||
```bash
|
||
git clone <repository-url>
|
||
cd AgentEvalTool
|
||
```
|
||
|
||
2. **安装后端依赖**
|
||
```bash
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
3. **构建前端**
|
||
```bash
|
||
cd frontend/web
|
||
npm install
|
||
npm run build
|
||
cd ../..
|
||
```
|
||
|
||
4. **配置**
|
||
```bash
|
||
# 创建配置文件
|
||
mkdir -p config
|
||
cp config.example.json config/config.json
|
||
# 编辑 config/config.json，填入 tutu-api 配置
|
||
```
|
||
|
||
5. **启动服务**
|
||
```bash
|
||
agenteval server start --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
6. **验证**
|
||
```bash
|
||
curl http://localhost:8000/api/health
|
||
# 期望返回：{"status":"ok"}
|
||
```
|
||
|
||
## 三、配置说明
|
||
|
||
### 3.1 配置文件
|
||
|
||
配置文件位于 `config/config.json`，包含 tutu-api 连接参数：
|
||
|
||
```json
|
||
{
|
||
"base_url": "https://api.example.com",
|
||
"token": "jwt-token",
|
||
"tenant": "tenant-id",
|
||
"chat_channel_id": "channel-id",
|
||
"chat_contact_id": "contact-id"
|
||
}
|
||
```
|
||
|
||
**注意**：
|
||
- `token` 有效期为 30 天，需定期更新
|
||
- 配置文件包含敏感信息，不要提交到版本控制
|
||
|
||
### 3.2 数据目录
|
||
|
||
数据存储在 `data/` 目录：
|
||
- `data/agenteval.db`: SQLite 数据库
|
||
- `data/scenarios/`: 场景 YAML 文件
|
||
- `data/reports/`: 生成的报告文件
|
||
|
||
**备份建议**：定期备份 `data/` 目录。
|
||
|
||
## 四、环境要求
|
||
|
||
### 4.1 硬件要求
|
||
|
||
- **最低配置**：2 CPU, 4GB RAM, 10GB 磁盘
|
||
- **推荐配置**：4 CPU, 8GB RAM, 20GB 磁盘
|
||
|
||
### 4.2 软件要求
|
||
|
||
- **操作系统**：Linux (Ubuntu 20.04+), macOS, Windows (WSL2)
|
||
- **Docker**：20.10+（容器化部署）
|
||
- **Docker Compose**：2.0+（容器化部署）
|
||
|
||
### 4.3 网络要求
|
||
|
||
- 能够访问 tutu-api 服务
|
||
- 如需外部访问，需开放 8000 端口（或自定义端口）
|
||
|
||
## 五、运维指南
|
||
|
||
### 5.1 日志查看
|
||
|
||
**Docker 部署**：
|
||
```bash
|
||
docker logs -f agenteval
|
||
```
|
||
|
||
**裸机部署**：
|
||
日志输出到标准输出，可使用 systemd 或 supervisor 管理。
|
||
|
||
### 5.2 服务重启
|
||
|
||
**Docker 部署**：
|
||
```bash
|
||
docker compose -f deploy/t480/docker-compose.yml restart
|
||
```
|
||
|
||
**裸机部署**：
|
||
```bash
|
||
# 停止服务
|
||
pkill -f "agenteval server"
|
||
|
||
# 启动服务
|
||
agenteval server start --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
### 5.3 版本更新
|
||
|
||
**Docker 部署**：
|
||
```bash
|
||
# 拉取最新代码
|
||
git pull
|
||
|
||
# 重新构建并启动
|
||
docker compose -f deploy/t480/docker-compose.yml up -d --build
|
||
```
|
||
|
||
**裸机部署**：
|
||
```bash
|
||
# 拉取最新代码
|
||
git pull
|
||
|
||
# 更新依赖
|
||
pip install -e ".[dev]"
|
||
|
||
# 重新构建前端
|
||
cd frontend/web && npm install && npm run build && cd ../..
|
||
|
||
# 重启服务
|
||
pkill -f "agenteval server"
|
||
agenteval server start --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
## 六、故障排查
|
||
|
||
### 6.1 服务无法启动
|
||
|
||
**检查端口占用**：
|
||
```bash
|
||
ss -tln | grep 8000
|
||
```
|
||
|
||
**检查日志**：
|
||
```bash
|
||
docker logs agenteval
|
||
```
|
||
|
||
### 6.2 数据库连接失败
|
||
|
||
**检查数据目录权限**：
|
||
```bash
|
||
ls -la data/
|
||
```
|
||
|
||
**检查数据库文件**：
|
||
```bash
|
||
file data/agenteval.db
|
||
```
|
||
|
||
### 6.3 前端无法访问
|
||
|
||
**检查前端构建**：
|
||
```bash
|
||
ls -la frontend/web/dist/
|
||
```
|
||
|
||
**检查静态文件挂载**（Docker）：
|
||
```bash
|
||
docker exec agenteval ls -la /app/frontend/web/dist/
|
||
```
|
||
|
||
## 七、安全建议
|
||
|
||
1. **配置文件安全**：不要将 `config/config.json` 提交到版本控制
|
||
2. **网络隔离**：生产环境建议使用反向代理（Nginx/Caddy）并配置 HTTPS
|
||
3. **定期备份**：定期备份 `data/` 目录
|
||
4. **Token 管理**：定期更新 tutu-api token（30 天有效期）
|
||
5. **访问控制**：如需外部访问，配置身份验证和访问控制
|
||
|
||
## 八、支持
|
||
|
||
如有部署问题，请：
|
||
1. 查看本文档的故障排查章节
|
||
2. 检查日志输出
|
||
3. 联系 AgentEval Team
|