# Docker 本地测试指南

## 🚀 快速开始

### 前提条件

1. **Docker已安装**
   ```bash
   docker --version  # 应该 >= 20.10
   docker-compose --version  # 应该 >= 1.29
   ```

2. **配置文件已准备**
   - `.env` 文件存在（包含数据库配置）
   - 数据库可访问（阿里云RDS）

### 一键测试

```bash
# 运行测试脚本
./docker-test.sh
```

**脚本会自动执行**：
1. ✅ 清理旧容器
2. ✅ 构建Docker镜像
3. ✅ 启动容器
4. ✅ 健康检查
5. ✅ 手动触发测试

---

## 📖 详细步骤

### 步骤1：确认配置文件

检查 `.env` 文件是否包含数据库配置：

```bash
cat .env | grep DB_
```

应该看到：
```
DB_HOST=rm-t4nh1xx6o2a6vj8qu3o.mysql.singapore.rds.aliyuncs.com
DB_PORT=3306
DB_USER=ad_rw
DB_PASSWORD=p82SzuW4kAP3LJXcQGso
DB_NAME=tencent_ad_autoput
```

### 步骤2：构建镜像

```bash
docker-compose build
```

**说明**：
- 首次构建需要5-10分钟（下载依赖）
- 后续构建会使用缓存，更快
- 如需强制重新构建：`docker-compose build --no-cache`

### 步骤3：启动容器

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

**参数说明**：
- `-d`: 后台运行
- 省略 `-d` 会在前台显示日志

### 步骤4：查看日志

```bash
# 实时查看日志
docker-compose logs -f

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

# 只看错误日志
docker-compose logs | grep ERROR
```

### 步骤5：健康检查

```bash
curl http://localhost:8080/health | jq .
```

**预期响应**：
```json
{
  "status": "healthy",
  "timestamp": "2026-04-23T16:00:00Z",
  "scheduler_running": true,
  "latest_report": "llm_decisions_20260423.csv",
  "jobs": [
    {
      "id": "decision_pipeline",
      "name": "广告决策流程",
      "next_run": "2026-04-24T03:00:00Z"
    }
  ]
}
```

### 步骤6：手动触发任务

```bash
curl -X POST http://localhost:8080/trigger
```

**预期响应**：
```json
{
  "status": "triggered",
  "message": "任务已添加到队列"
}
```

### 步骤7：查看执行结果

```bash
# 查看输出文件
ls -lh outputs/reports/

# 查看决策结果（CSV）
cat outputs/reports/llm_decisions_*.csv | head -20

# 查看执行日志
cat outputs/execution_log/execution_*.jsonl | tail -10
```

---

## 🔧 常用操作

### 进入容器调试

```bash
# 进入容器shell
docker exec -it auto_put_ad_mini bash

# 在容器内执行命令
docker exec -it auto_put_ad_mini python -c "from db import get_whitelist_accounts; print(get_whitelist_accounts())"
```

### 查看容器状态

```bash
# 查看运行状态
docker-compose ps

# 查看资源占用
docker stats auto_put_ad_mini

# 查看详细信息
docker inspect auto_put_ad_mini
```

### 重启容器

```bash
# 重启
docker-compose restart

# 停止后重新启动
docker-compose down
docker-compose up -d
```

### 查看网络

```bash
# 查看容器网络
docker network ls

# 查看auto_put_ad_mini网络详情
docker network inspect auto_put_ad_mini_ad_network
```

---

## 🐛 故障排查

### 问题1：容器启动失败

**症状**：`docker-compose up -d` 后容器立即退出

**排查步骤**：
```bash
# 1. 查看日志
docker-compose logs

# 2. 查看容器退出原因
docker-compose ps -a

# 3. 检查配置文件
cat .env | grep -E "DB_|FEISHU_|ODPS_"

# 4. 尝试前台运行查看详细错误
docker-compose up
```

**常见原因**：
- ❌ .env 文件缺失或配置错误
- ❌ 数据库连接失败
- ❌ 依赖安装失败

### 问题2：健康检查失败

**症状**：`curl http://localhost:8080/health` 连接失败

**排查步骤**：
```bash
# 1. 确认容器正在运行
docker-compose ps

# 2. 确认端口映射
docker-compose ps | grep 8080

# 3. 查看容器日志
docker-compose logs --tail=50

# 4. 检查端口是否被占用
lsof -i :8080
```

**解决方法**：
```bash
# 如果8080端口被占用，修改docker-compose.yml
ports:
  - "8081:8080"  # 改用8081端口
```

### 问题3：数据库连接失败

**症状**：日志中出现 "数据库连接失败"

**排查步骤**：
```bash
# 1. 在容器内测试连接
docker exec -it auto_put_ad_mini bash
python3 << EOF
from db.connection import test_connection
test_connection()
EOF

# 2. 检查网络连通性
docker exec -it auto_put_ad_mini ping -c 3 rm-t4nh1xx6o2a6vj8qu3o.mysql.singapore.rds.aliyuncs.com

# 3. 检查.env配置
docker exec -it auto_put_ad_mini env | grep DB_
```

**解决方法**：
- 确认数据库白名单允许容器IP访问
- 确认数据库密码正确
- 使用外网地址而非内网地址（Docker环境）

### 问题4：Agent框架找不到

**症状**：`ModuleNotFoundError: No module named 'agent'`

**原因**：Dockerfile中 `COPY ../../agent /app/agent` 路径错误

**解决方法**：
```bash
# 从项目根目录构建
cd /Users/liulidong/project/agent/Agent
docker build -t auto-put-ad-mini:latest -f examples/auto_put_ad_mini/Dockerfile .

# 或者修改Dockerfile，使用相对于构建上下文的正确路径
```

---

## 📊 性能监控

### 查看资源使用

```bash
# 实时监控
docker stats auto_put_ad_mini

# 查看磁盘使用
docker exec -it auto_put_ad_mini du -sh /app/outputs/*
```

### 查看日志大小

```bash
# 查看容器日志大小
docker inspect --format='{{.LogPath}}' auto_put_ad_mini | xargs ls -lh

# 清理日志（如果太大）
truncate -s 0 $(docker inspect --format='{{.LogPath}}' auto_put_ad_mini)
```

---

## 🧹 清理环境

### 停止并删除容器

```bash
docker-compose down
```

### 删除镜像

```bash
docker rmi auto_put_ad_mini-auto_put_ad_mini
```

### 清理所有（包括卷）

```bash
docker-compose down -v  # 删除所有卷（注意：会删除outputs数据）
```

### 清理Docker系统

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

---

## 🎯 测试场景

### 场景1：测试定时任务

```bash
# 1. 修改定时时间为1分钟后
# 在DMS中执行：
# UPDATE system_config SET config_value = '*/1 * * * *' WHERE config_key = 'cron_schedule';

# 2. 重启容器
docker-compose restart

# 3. 查看日志，等待任务执行
docker-compose logs -f
```

### 场景2：测试手动触发

```bash
# 1. 清空outputs目录
rm -rf outputs/reports/*

# 2. 手动触发
curl -X POST http://localhost:8080/trigger

# 3. 等待30秒后查看输出
sleep 30
ls -lh outputs/reports/
```

### 场景3：测试白名单

```bash
# 1. 在DMS中禁用所有账户
# UPDATE account_whitelist SET enabled = FALSE;

# 2. 手动触发
curl -X POST http://localhost:8080/trigger

# 3. 查看日志，应该显示"白名单为空"
docker-compose logs --tail=50

# 4. 恢复白名单
# UPDATE account_whitelist SET enabled = TRUE WHERE account_id = 80769799;
```

---

## 📝 环境变量说明

Docker容器会读取以下环境变量：

| 变量 | 说明 | 示例 |
|------|------|------|
| `DB_HOST` | 数据库主机 | `rm-xxx.mysql.singapore.rds.aliyuncs.com` |
| `DB_PORT` | 数据库端口 | `3306` |
| `DB_USER` | 数据库用户 | `ad_rw` |
| `DB_PASSWORD` | 数据库密码 | `xxx` |
| `DB_NAME` | 数据库名称 | `tencent_ad_autoput` |
| `TZ` | 时区 | `Asia/Shanghai` 或 `UTC` |
| `EXECUTION_ENABLED` | 执行开关（环境变量降级） | `false` |
| `WHITELIST_ENABLED` | 白名单开关（环境变量降级） | `true` |

**优先级**：数据库配置 > 环境变量 > 默认值

---

## ✅ 测试检查清单

- [ ] Docker和docker-compose已安装
- [ ] .env文件已配置数据库信息
- [ ] 构建镜像成功
- [ ] 容器启动成功
- [ ] 健康检查通过
- [ ] 手动触发成功
- [ ] 日志输出正常
- [ ] outputs目录有输出文件
- [ ] 定时任务配置正确（查看next_run）
- [ ] 白名单配置生效
- [ ] 执行开关正确（EXECUTION_ENABLED=false）

---

**测试完成后记得停止容器**：
```bash
docker-compose down
```

**保留输出文件**：
outputs 目录通过volume映射到本地，停止容器不会丢失数据。