# Docker 一键部署文档

## 快速开始

### 1. 配置环境变量

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

`.env` 文件内容：
```bash
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. 一键启动

```bash
docker-compose up -d
```

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

### 3. 查看状态

```bash
docker-compose ps
```

---

## 服务访问

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

---

## 常用命令

### 启动服务

```bash
docker-compose up -d
```

### 停止服务

```bash
docker-compose down
```

### 重启服务

```bash
# 重启所有服务
docker-compose restart

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

### 查看日志

```bash
# 所有服务
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
```

### 重新构建

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

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

### 更新镜像

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

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

---

## 数据持久化

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

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

### 备份数据

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

### 恢复数据

```bash
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 |

### 服务器准备

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

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

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

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

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

---

## 故障排查

### 服务无法启动

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

# 检查环境变量
cat .env

# 检查容器状态
docker-compose ps
```

### 前端无法访问 API

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

**原因**：ALB 没有暴露 8000 端口

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

### 端口冲突

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

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

### 构建失败

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

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

### 磁盘空间不足

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

# 查看磁盘使用
docker system df
```

---

## 性能优化

### 资源限制

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

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

### 日志轮转

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

---

## 监控

### 查看资源使用

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

### 健康检查

```bash
# 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`