auto_put_ad_mini 生产部署指南

概述

本文档说明如何将 auto_put_ad_mini 部署到海外服务器的 Docker/Kubernetes 环境，实现生产级自动化运行。

核心特性

已实现功能

✅ Docker 容器化

Dockerfile 基于 Python 3.10 slim
多阶段构建，优化镜像大小
健康检查支持

✅ 账户白名单机制

环境变量配置白名单账户
双重安全检查（决策阶段 + 执行阶段）
支持 whitelist.json 配置文件

✅ 海外环境适配

代理配置从环境变量读取
时区支持（UTC/Asia/Shanghai）
移除硬编码本地代理

✅ 定时调度

FastAPI + APScheduler 常驻服务（推荐）
Kubernetes CronJob 支持（备用）
HTTP API 手动触发

✅ 监控和日志

健康检查端点 /health
请求日志中间件
Prometheus metrics 导出（可选）
日志输出到 stdout（Kubernetes 友好）

✅ 安全配置

Kubernetes Secret 管理敏感信息
NetworkPolicy 网络隔离
非 root 用户运行
资源限制和配额

项目结构

auto_put_ad_mini/
├── Dockerfile              # Docker 镜像定义
├── .dockerignore          # Docker 构建排除文件
├── docker-compose.yml     # 本地开发环境
├── requirements.txt       # Python 依赖
├── server.py              # FastAPI + APScheduler 服务器（推荐）
├── execute_once.py        # 单次执行入口
├── schedule.sh            # Cron 脚本（备用）
├── whitelist.json         # 白名单账户配置
├── metrics.py             # Prometheus 指标导出
├── utils/
│   └── log_capture.py     # 并发日志捕获
├── k8s/                   # Kubernetes 部署清单
│   ├── README.md          # K8s 部署详细说明
│   ├── namespace.yaml     # 命名空间
│   ├── deployment.yaml    # Deployment + Service
│   ├── cronjob.yaml       # CronJob（备用）
│   ├── configmap.yaml     # 公开配置
│   ├── secret.yaml        # 敏感信息
│   ├── pvc.yaml           # 持久化存储
│   └── network-policy.yaml # 网络策略
└── DEPLOYMENT.md          # 本文档

快速开始

阶段 1：本地测试

方式 A：Docker Compose（开发环境）

# 1. 进入项目目录
cd /Users/liulidong/project/agent/Agent/examples/auto_put_ad_mini

# 2. 创建 .env 文件（从 .env.example 复制并填入真实值）
cp .env.example .env
vim .env  # 填入实际的 API 密钥和配置

# 3. 构建镜像
docker build -t auto-put-ad-mini:test .

# 4. 启动服务（APScheduler 模式）
docker-compose up -d

# 5. 查看日志
docker-compose logs -f

# 6. 测试健康检查
curl http://localhost:8080/health | jq .

# 7. 手动触发任务
curl -X POST http://localhost:8080/trigger | jq .

# 8. 停止服务
docker-compose down

方式 B：单次执行测试

# 测试单次执行（不启动调度服务）
docker run --rm \
  --env-file .env \
  -e EXECUTION_ENABLED=false \
  -e WHITELIST_ENABLED=true \
  -e WHITELIST_ACCOUNTS=80769799 \
  -v $(pwd)/outputs:/app/outputs \
  auto-put-ad-mini:test \
  python execute_once.py

# 验证输出
ls -lh outputs/reports/
cat outputs/reports/llm_decisions_*.csv | head

阶段 2：推送镜像到仓库

# 1. 登录镜像仓库
docker login your-registry.com

# 2. 打标签
docker tag auto-put-ad-mini:test your-registry.com/auto-put-ad-mini:v1.0.0
docker tag auto-put-ad-mini:test your-registry.com/auto-put-ad-mini:latest

# 3. 推送
docker push your-registry.com/auto-put-ad-mini:v1.0.0
docker push your-registry.com/auto-put-ad-mini:latest

阶段 3：Kubernetes 部署

详细步骤见 k8s/README.md

推荐部署方式：Deployment + APScheduler

# 1. 创建命名空间
kubectl apply -f k8s/namespace.yaml

# 2. 修改 k8s/secret.yaml，填入真实密钥
vim k8s/secret.yaml

# 3. 部署所有资源
kubectl apply -f k8s/pvc.yaml
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/secret.yaml
kubectl apply -f k8s/deployment.yaml

# 4. 验证部署
kubectl get all -n ad-automation
kubectl logs -f -n ad-automation deployment/auto-put-ad-mini

# 5. 端口转发测试
kubectl port-forward -n ad-automation svc/auto-put-ad-mini 8080:8080

# 6. 测试健康检查
curl http://localhost:8080/health | jq .

# 7. 手动触发任务
curl -X POST http://localhost:8080/trigger | jq .

配置说明

环境变量

变量名	说明	默认值	必需
`WHITELIST_ENABLED`	启用账户白名单	true	否
`WHITELIST_ACCOUNTS`	白名单账户ID（逗号分隔）	-	是（启用白名单时）
`EXECUTION_ENABLED`	启用实际执行	false	否
`HTTP_PROXY`	HTTP 代理地址	-	否
`HTTPS_PROXY`	HTTPS 代理地址	-	否
`TZ`	时区	UTC	否
`CRON_SCHEDULE`	定时表达式	0 2 * * *	否
`RUN_ON_STARTUP`	启动时立即执行	false	否
`PORT`	FastAPI 端口	8080	否
`FEISHU_APP_ID`	飞书应用ID	-	是
`FEISHU_APP_SECRET`	飞书应用密钥	-	是
`TENCENT_AD_ACCOUNT_ID`	腾讯广告账户ID	-	是
`ODPS_ACCESS_ID`	ODPS 访问ID	-	是
`ODPS_ACCESS_SECRET`	ODPS 访问密钥	-	是
`OPEN_ROUTER_API_KEY`	OpenRouter API Key	-	是

白名单配置

方式 1：环境变量（推荐）

# .env 或 k8s/secret.yaml
WHITELIST_ENABLED=true
WHITELIST_ACCOUNTS=80769799,71305011,12345678

方式 2：配置文件

编辑 whitelist.json：

{
  "accounts": [80769799, 71305011],
  "description": "生产环境白名单账户列表",
  "last_updated": "2026-04-22"
}

定时调度配置

Cron 表达式格式：分时日月周

示例：

0 2 * * * - 每天凌晨 2 点（UTC）
30 1 * * * - 每天凌晨 1:30（UTC）
0 */6 * * * - 每 6 小时执行一次
0 9 * * 1-5 - 工作日上午 9 点

修改定时：

# Kubernetes ConfigMap
kubectl patch configmap ad-config -n ad-automation \
  --patch '{"data":{"CRON_SCHEDULE":"0 3 * * *"}}'

kubectl rollout restart deployment/auto-put-ad-mini -n ad-automation

监控和运维

健康检查

# 本地
curl http://localhost:8080/health

# Kubernetes
kubectl exec -n ad-automation <pod-name> -- curl -f http://localhost:8080/health

返回示例：

{
  "status": "healthy",
  "timestamp": "2026-04-22T10:00:00Z",
  "scheduler_running": true,
  "latest_report": "llm_decisions_20260422.csv",
  "jobs": [
    {
      "id": "decision_pipeline",
      "name": "广告决策流程",
      "next_run": "2026-04-23T02:00:00Z"
    }
  ]
}

日志查看

Docker：

docker logs -f auto-put-ad-mini

Kubernetes：

# 实时日志
kubectl logs -f -n ad-automation deployment/auto-put-ad-mini

# 最近 100 行
kubectl logs -n ad-automation deployment/auto-put-ad-mini --tail=100

# 查看多个 Pod 日志
kubectl logs -n ad-automation -l app=auto-put-ad-mini --all-containers=true

查看输出文件

Docker：

docker exec -it auto-put-ad-mini ls -lh /app/outputs/reports/
docker exec -it auto-put-ad-mini cat /app/outputs/reports/llm_decisions_*.csv

Kubernetes：

POD_NAME=$(kubectl get pods -n ad-automation -l app=auto-put-ad-mini -o jsonpath='{.items[0].metadata.name}')
kubectl exec -n ad-automation $POD_NAME -- ls -lh /app/outputs/reports/
kubectl exec -n ad-automation $POD_NAME -- cat /app/outputs/reports/llm_decisions_*.csv

Prometheus 监控（可选）

如果启用了 Prometheus metrics：

# 查看 metrics 文件
kubectl exec -n ad-automation $POD_NAME -- cat /app/outputs/metrics.prom

配置 Prometheus 抓取：

scrape_configs:
  - job_name: 'auto-put-ad-mini'
    file_sd_configs:
      - files:
        - /app/outputs/metrics.prom

故障排查

问题 1：容器启动失败

# 查看 Pod 状态
kubectl describe pod <pod-name> -n ad-automation

# 查看事件
kubectl get events -n ad-automation --sort-by='.lastTimestamp'

# 查看日志
kubectl logs <pod-name> -n ad-automation --previous

常见原因：

Secret 未配置或配置错误
PVC 未创建或无法挂载
镜像拉取失败

问题 2：定时任务未执行

# 检查调度器状态
curl http://localhost:8080/health | jq .scheduler_running

# 查看下次执行时间
curl http://localhost:8080/health | jq .jobs

# 手动触发测试
curl -X POST http://localhost:8080/trigger

问题 3：白名单过滤异常

# 查看日志，搜索白名单相关信息
kubectl logs -n ad-automation deployment/auto-put-ad-mini | grep "白名单"

# 检查配置
kubectl get secret ad-secrets -n ad-automation -o jsonpath='{.data.WHITELIST_ACCOUNTS}' | base64 -d

问题 4：代理连接失败

# 检查代理配置
kubectl get configmap ad-config -n ad-automation -o yaml | grep PROXY

# 测试代理连接
kubectl exec -n ad-automation $POD_NAME -- curl -x $HTTP_PROXY https://api.e.qq.com

回滚和恢复

回滚到上一个版本

# Deployment 模式
kubectl rollout undo deployment/auto-put-ad-mini -n ad-automation

# CronJob 模式
kubectl set image cronjob/auto-put-ad-mini \
  decision-engine=your-registry/auto-put-ad-mini:v0.9.0 \
  -n ad-automation

暂停服务

# Deployment 模式
kubectl scale deployment auto-put-ad-mini --replicas=0 -n ad-automation

# CronJob 模式
kubectl patch cronjob auto-put-ad-mini -n ad-automation -p '{"spec":{"suspend":true}}'

恢复服务

# Deployment 模式
kubectl scale deployment auto-put-ad-mini --replicas=1 -n ad-automation

# CronJob 模式
kubectl patch cronjob auto-put-ad-mini -n ad-automation -p '{"spec":{"suspend":false}}'

安全最佳实践

1. Secret 管理

❌ 不要将真实 Secret 提交到 Git
✅ 使用 Kubernetes External Secrets 或 Sealed Secrets
✅ 定期轮换敏感凭据
✅ 限制 Secret 访问权限

2. 网络安全

✅ 启用 NetworkPolicy 限制出入站流量
✅ 仅允许必要的外部连接（腾讯 API、飞书 API）
✅ 使用代理服务访问外部资源

3. 资源隔离

✅ 使用独立命名空间（ad-automation）
✅ 设置 CPU 和内存 limits
✅ 使用 LimitRange 和 ResourceQuota

4. 运行时安全

✅ 非 root 用户运行（UID 1000）
✅ 禁用特权容器
✅ 使用 readOnlyRootFilesystem（输出目录除外）

性能优化

资源配置建议

环境	CPU Request	CPU Limit	Memory Request	Memory Limit
测试	250m	500m	512Mi	1Gi
生产	500m	1	1Gi	2Gi
高负载	1	2	2Gi	4Gi

并发控制

APScheduler max_instances=1 防止任务并发
Kubernetes CronJob concurrencyPolicy: Forbid

日志轮转

# 输出目录定期清理
find /app/outputs -name "cron_*.log" -mtime +30 -delete

升级策略

滚动更新

# 更新镜像
kubectl set image deployment/auto-put-ad-mini \
  decision-engine=your-registry/auto-put-ad-mini:v1.1.0 \
  -n ad-automation

# 查看更新状态
kubectl rollout status deployment/auto-put-ad-mini -n ad-automation

灰度发布

# 创建 Canary Deployment
kubectl apply -f k8s/deployment-canary.yaml

# 验证 Canary 版本
kubectl logs -n ad-automation deployment/auto-put-ad-mini-canary

# 全量发布
kubectl set image deployment/auto-put-ad-mini \
  decision-engine=your-registry/auto-put-ad-mini:v1.1.0 \
  -n ad-automation

# 删除 Canary
kubectl delete deployment auto-put-ad-mini-canary -n ad-automation

附录

A. 两种部署模式对比

特性	Deployment + APScheduler	CronJob
资源占用	常驻 Pod（低）	每次启动新 Pod
启动速度	快（任务触发即执行）	慢（需启动容器）
健康检查	✅ HTTP 端点	❌ 需额外脚本
手动触发	✅ HTTP API	⚠️ 需创建 Job
日志查看	✅ 持续输出	⚠️ 分散在多个 Job
监控集成	✅ Prometheus metrics	⚠️ 需额外配置
适用场景	生产环境、频繁调度	简单定时任务

推荐：生产环境使用 Deployment + APScheduler 模式。

B. 常用命令速查

# 快速重启
kubectl rollout restart deployment/auto-put-ad-mini -n ad-automation

# 查看最近事件
kubectl get events -n ad-automation --sort-by='.lastTimestamp' | tail -20

# 进入 Pod Shell
kubectl exec -it -n ad-automation <pod-name> -- bash

# 复制文件到本地
kubectl cp ad-automation/<pod-name>:/app/outputs/reports/llm_decisions_*.csv ./local-reports/

# 查看资源使用
kubectl top pod -n ad-automation

C. 联系支持

文档问题：查看 k8s/README.md 和本文档
代码问题：查看 CLAUDE.md 和源码注释
配置问题：查看 .env.example 和 k8s/configmap.yaml

文档版本：v1.0.0 最后更新：2026-04-22 维护者：auto_put_ad_mini team

DEPLOYMENT.md 13 KB 히스토리 Raw