# 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