# t480 测试服务器部署指南

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

---

## 一、环境信息

| 项目 | 值 |
|---|---|
| 主机 | `sola-t480` (Ubuntu 24.04, kernel 6.17) |
| IP | `192.168.8.145` |
| Docker | 29.1.3 |
| Docker Compose | v2.29.2 |
| Python / Node | 3.12.3 / 24.14.0 |
| 资源 | 31 GB RAM / 250 GB 可用磁盘 |
| 访问端口 | `8001`（8000 已被其他服务占用） |

## 二、部署架构

- **单容器部署**：Python FastAPI 后端同时提供 `/api/*` 和前端 React SPA 静态资源
- **数据持久化**：通过 `data/` 目录挂载保存 SQLite 数据库与 HTML 报告
- **配置挂载**：`config/config.json` 以只读方式挂载到容器内，用于 CLI 注册/更新评测对象
- **前端构建**：使用 t480 系统 Node.js 构建前端，挂载 `frontend/web/dist` 到容器
- **镜像优化**：使用阿里云镜像源（apt/pip）加速下载

## 三、部署步骤

### 3.1 确认本地配置

确保项目根目录已有 `config/config.json`（tutu-api token 等敏感信息）。

### 3.2 同步代码到 t480

```bash
rsync -avz --delete \
  --exclude='.git' \
  --exclude='node_modules' \
  --exclude='frontend/web/dist' \
  --exclude='data' \
  --exclude='.venv' \
  --exclude='__pycache__' \
  --exclude='.pytest_cache' \
  --exclude='.ruff_cache' \
  --exclude='.DS_Store' \
  /Users/sinohuangqb/DevSpace/JkzlItProduct/AgentEvalTool/ \
  sola-t480:~/agenteval/
```

### 3.3 在 t480 上构建前端

```bash
ssh sola-t480
cd ~/agenteval/frontend/web
npm install
npm run build
```

### 3.4 构建并启动容器

```bash
cd ~/agenteval
docker compose -f deploy/t480/docker-compose.yml up -d --build
```

### 3.5 健康检查

```bash
curl http://192.168.8.145:8001/api/health
```

期望返回 `{"status":"ok"}`，并能在浏览器打开 `http://192.168.8.145:8001/` 看到前端页面。

### 3.6 注册/更新评测对象（如需要）

```bash
docker exec -it agenteval agenteval target add \
  --name "社区医院AI客服" \
  --config /app/config/config.json
```

### 3.7 执行评测验证

获取 target-id 与 scenario-id 后：

```bash
docker exec -it agenteval agenteval run start \
  --target-id <target-id> \
  --scenario-id <scenario-id>
```

## 四、日常运维

### 4.1 查看日志

```bash
docker logs -f agenteval
```

### 4.2 重启服务

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

### 4.3 更新版本

```bash
# 1. 同步最新代码
rsync -avz --delete \
  --exclude='.git' \
  --exclude='node_modules' \
  --exclude='frontend/web/dist' \
  --exclude='data' \
  --exclude='.venv' \
  --exclude='__pycache__' \
  --exclude='.pytest_cache' \
  --exclude='.ruff_cache' \
  --exclude='.DS_Store' \
  /Users/sinohuangqb/DevSpace/JkzlItProduct/AgentEvalTool/ \
  sola-t480:~/agenteval/

# 2. 重新构建前端（如有变更）
ssh sola-t480 'cd ~/agenteval/frontend/web && npm install && npm run build'

# 3. 重新构建并启动容器
ssh sola-t480 'cd ~/agenteval && docker compose -f deploy/t480/docker-compose.yml up -d --build'
```

## 五、故障排查

### 5.1 容器无法启动

**检查端口占用**：
```bash
ssh sola-t480 'ss -tln | grep 8001'
```

**检查容器日志**：
```bash
ssh sola-t480 'docker logs agenteval'
```

### 5.2 数据卷问题

**检查数据目录**：
```bash
ssh sola-t480 'ls -la ~/agenteval/data'
```

**检查容器内挂载**：
```bash
ssh sola-t480 'docker exec agenteval ls -la /app/data'
```

### 5.3 前端无法访问

**检查前端构建**：
```bash
ssh sola-t480 'ls -la ~/agenteval/frontend/web/dist'
```

**检查容器内挂载**：
```bash
ssh sola-t480 'docker exec agenteval ls -la /app/frontend/web/dist'
```

## 六、配置文件

### 6.1 Docker Compose 配置

文件位置：`deploy/t480/docker-compose.yml`

关键配置：
- 端口映射：`8001:8000`
- 数据卷挂载：`../../data:/app/data`
- 配置挂载：`../../config/config.json:/app/config/config.json:ro`
- 前端挂载：`../../frontend/web/dist:/app/frontend/web/dist:ro`

### 6.2 Dockerfile 配置

文件位置：`deploy/t480/Dockerfile`

关键特性：
- 基础镜像：`python:3.11.15-slim-bookworm`（t480 已有）
- 使用阿里云镜像源（apt/pip）
- Editable 安装模式（`pip install -e .`）

## 七、注意事项

1. **端口冲突**：t480 上 8000 端口已被 `solafund` 服务占用，使用 8001 端口
2. **镜像加速**：Dockerfile 已配置阿里云镜像源，避免 GFW 导致的下载慢
3. **可编辑安装**：使用 `pip install -e .` 确保数据路径正确指向挂载的 `/app/data`
4. **Token 有效期**：tutu-api token 有效期 30 天，需定期更新 `config/config.json`

## 八、可选：添加反向代理

如果后续需要域名/HTTPS，可在 t480 上再起一个 Nginx/Caddy 容器，将 80/443 反向代理到本机的 `127.0.0.1:8001`。