Agent/DEPLOY.md

Docker 一键部署文档

快速开始

1. 配置环境变量

cp .env.example .env
vim .env  # 填写 OPEN_ROUTER_API_KEY

.env 文件内容：

OPEN_ROUTER_API_KEY=your-api-key-here
MODEL=anthropic/claude-sonnet-4.6
TEMPERATURE=0.3
MAX_ITERATIONS=30
MAX_CONCURRENT_TASKS=3

2. 一键启动

docker-compose up -d

首次启动会自动构建镜像（需要几分钟），后续启动秒级完成。

3. 查看状态

docker-compose ps

---

服务访问

服务	地址	说明
前端	http://localhost:3000	可视化界面
API 服务	http://localhost:8000	可视化 API
Agent 服务	http://localhost:8080	内容寻找 API

---

常用命令

启动服务

docker-compose up -d

停止服务

docker-compose down

重启服务

# 重启所有服务
docker-compose restart

# 重启指定服务
docker-compose restart content-finder

查看日志

# 所有服务
docker-compose logs -f

# 指定服务
docker-compose logs -f content-finder
docker-compose logs -f api-server
docker-compose logs -f frontend

# 查看最近 100 行
docker-compose logs --tail 100 content-finder

重新构建

# 代码更新后重新构建
docker-compose build

# 构建并启动
docker-compose up -d --build

更新镜像

# 拉取最新基础镜像
docker-compose pull

# 重新构建
docker-compose build --no-cache
docker-compose up -d

---

数据持久化

数据存储在宿主机目录，容器重启不会丢失：

• traces：/home/data/traces → Agent 执行轨迹
• output：/home/data/output → 输出文件

备份数据

tar -czf backup-$(date +%Y%m%d).tar.gz /home/data/traces /home/data/output

恢复数据

tar -xzf backup-20260317.tar.gz -C /

---

生产环境部署

ALB 配置

监听器

端口	协议	目标	说明
80	HTTP	宿主机:3000	前端（可重定向到 HTTPS）
443	HTTPS	宿主机:3000	前端（SSL 终止）
8000	HTTP/HTTPS	宿主机:8000	API 服务

重要：前端代码会访问 window.location.hostname:8000，所以 ALB 必须暴露 8000 端口。

健康检查

服务	路径	端口	间隔	超时
frontend	/	3000	5s	3s
api-server	/health	8000	5s	3s
content-finder	/health	8080	5s	3s

服务器准备

# 1. 安装 Docker 和 Docker Compose
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# 2. 创建持久化目录
mkdir -p /home/data/traces
mkdir -p /home/data/output

# 3. 克隆代码
git clone <your-repo>
cd Agent

# 4. 配置环境变量
cp .env.example .env
vim .env

# 5. 启动服务
docker-compose up -d

---

故障排查

服务无法启动

# 查看日志
docker-compose logs content-finder

# 检查环境变量
cat .env

# 检查容器状态
docker-compose ps

前端无法访问 API

问题：前端访问 yourdomain.com:8000 失败

原因：ALB 没有暴露 8000 端口

解决：在 ALB 配置中添加 8000 端口监听器

端口冲突

# 检查端口占用
netstat -tlnp | grep 3000
netstat -tlnp | grep 8000
netstat -tlnp | grep 8080

# 停止占用端口的进程
sudo kill -9 <PID>

构建失败

# 清理缓存重新构建
docker-compose build --no-cache

# 查看构建日志
docker-compose build --progress=plain

磁盘空间不足

# 清理未使用的镜像和容器
docker system prune -a

# 查看磁盘使用
docker system df

---

性能优化

资源限制

编辑 docker-compose.yml 添加资源限制：

services:
  content-finder:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

日志轮转

# 限制日志大小
docker-compose logs --tail 1000 > logs.txt
docker-compose logs --since 1h > recent-logs.txt

---

监控

查看资源使用

docker stats agent-content-finder agent-api-server agent-frontend

健康检查

# content-finder
curl http://localhost:8080/health

# api-server
curl http://localhost:8000/health

# frontend
curl http://localhost:3000

---

架构说明

[用户浏览器]
    ↓
[ALB - 80/443/8000]
    ↓
[宿主机]
    ├─ :3000 → agent-frontend (nginx)
    ├─ :8000 → agent-api-server (FastAPI)
    └─ :8080 → agent-content-finder (FastAPI)
         ↓
    [/home/data/traces] (执行轨迹)
    [/home/data/output]  (输出文件)

服务说明

• frontend：React 应用，nginx 托管静态文件
• api-server：可视化 API，读取 .trace 数据
• content-finder：内容寻找 Agent，写入 .trace 和 .output 数据

数据流

1. 用户访问前端 (port 3000)
2. 前端调用 API (port 8000)
3. API 读取 .trace 数据
4. content-finder 执行任务，写入 .trace 和 .output