Agent/examples/auto_put_ad_mini/DOCKER_TEST.md

Docker 本地测试指南

🚀 快速开始

前提条件

1. Docker已安装

   docker --version  # 应该 >= 20.10
   docker-compose --version  # 应该 >= 1.29
   

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

   一键测试

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

脚本会自动执行：

1. ✅ 清理旧容器
2. ✅ 构建Docker镜像
3. ✅ 启动容器
4. ✅ 健康检查
5. ✅ 手动触发测试

---

📖 详细步骤

步骤1：确认配置文件

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

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：构建镜像

docker-compose build

说明：

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

步骤3：启动容器

docker-compose up -d

参数说明：

• -d: 后台运行
• 省略 -d 会在前台显示日志

步骤4：查看日志

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

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

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

步骤5：健康检查

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

预期响应：

{
  "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：手动触发任务

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

预期响应：

{
  "status": "triggered",
  "message": "任务已添加到队列"
}

步骤7：查看执行结果

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

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

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

---

🔧 常用操作

进入容器调试

# 进入容器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())"

查看容器状态

# 查看运行状态
docker-compose ps

# 查看资源占用
docker stats auto_put_ad_mini

# 查看详细信息
docker inspect auto_put_ad_mini

重启容器

# 重启
docker-compose restart

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

查看网络

# 查看容器网络
docker network ls

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

---

🐛 故障排查

问题1：容器启动失败

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

排查步骤：

# 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 连接失败

排查步骤：

# 1. 确认容器正在运行
docker-compose ps

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

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

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

解决方法：

# 如果8080端口被占用，修改docker-compose.yml
ports:
  - "8081:8080"  # 改用8081端口

问题3：数据库连接失败

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

排查步骤：

# 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 路径错误

解决方法：

# 从项目根目录构建
cd /Users/liulidong/project/agent/Agent
docker build -t auto-put-ad-mini:latest -f examples/auto_put_ad_mini/Dockerfile .

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

---

📊 性能监控

查看资源使用

# 实时监控
docker stats auto_put_ad_mini

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

查看日志大小

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

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

---

🧹 清理环境

停止并删除容器

docker-compose down

删除镜像

docker rmi auto_put_ad_mini-auto_put_ad_mini

清理所有（包括卷）

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

清理Docker系统

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

---

🎯 测试场景

场景1：测试定时任务

# 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：测试手动触发

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

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

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

场景3：测试白名单

# 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）

---

测试完成后记得停止容器：

docker-compose down

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