AgentEvalTool/docs/deployment

AgentEvalTool 部署文档

版本: v1.0
日期: 2026-07-09
状态: 已发布
作者: AgentEval Team

---

一、概述

本文档提供 AgentEvalTool 的部署指南，包括 Docker 容器化部署和裸机部署两种方式。

二、部署方式

2.1 Docker 容器化部署（推荐）

Docker 部署是推荐的生产环境部署方式，提供以下优势：

• 环境隔离
• 易于扩展
• 版本管理
• 快速部署

部署文档：

• t480 服务器部署指南 - 针对 t480 测试服务器的具体部署步骤
• volcengine-102 正式线部署指南 - 版本化发布、备份、迁移、健康检查与回滚

2.2 裸机部署

裸机部署适用于开发环境或特殊需求场景。

前置要求：

• Python 3.10+
• Node.js 18+（用于构建前端）
• Git

部署步骤：

1. 克隆代码

   git clone <repository-url>
   cd AgentEvalTool
   

2. 安装后端依赖

   pip install -e ".[dev]"
   

3. 构建前端

   cd frontend/web
   npm install
   npm run build
   cd ../..
   

4. 配置

   # 创建配置文件
   mkdir -p config
   cp config.example.json config/config.json
   # 编辑 config/config.json，填入 tutu-api 配置
   

5. 启动服务

   agenteval server start --host 0.0.0.0 --port 8000
   

6. 验证

   curl http://localhost:8000/api/health
   # 期望返回：{"status":"ok"}
   

三、配置说明

3.1 配置文件

配置文件位于 config/config.json，包含 tutu-api 连接参数：

{
  "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 部署：

docker logs -f agenteval

裸机部署： 日志输出到标准输出，可使用 systemd 或 supervisor 管理。

5.2 服务重启

Docker 部署：

docker compose -f deploy/t480/docker-compose.yml restart

裸机部署：

# 停止服务
pkill -f "agenteval server"

# 启动服务
agenteval server start --host 0.0.0.0 --port 8000

5.3 版本更新

Docker 部署：

# 拉取最新代码
git pull

# 重新构建并启动
docker compose -f deploy/t480/docker-compose.yml up -d --build

裸机部署：

# 拉取最新代码
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 服务无法启动

检查端口占用：

ss -tln | grep 8000

检查日志：

docker logs agenteval

6.2 数据库连接失败

检查数据目录权限：

ls -la data/

检查数据库文件：

file data/agenteval.db

6.3 前端无法访问

检查前端构建：

ls -la frontend/web/dist/

检查静态文件挂载（Docker）：

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