gmv-analytics/DOCKER_PREFECT_USAGE.md

Docker + Prefect 使用说明

当前方案包含两条定时任务：

• 08:00 执行数据统计并写入飞书多维表格
• 09:00 推送结果到飞书群

调度配置写在 prefect.yaml 中。 运行容器的职责是启动 Prefect worker，不再使用 --serve 作为主方案。

1. 创建 Docker 镜像

在项目目录执行：

cd /Users/idss/YXT_Project/gmv-analytics
docker build -t gmv-analytics-prefect:0.1.0 .

镜像内容来自：

• Dockerfile
• docker-entrypoint.sh

容器启动后会：

• 加载 .env
• 自动把 PROJECT_MAPPING_FILE 修正为容器内的 /app/店铺映射表.xlsx
• 默认执行 supervisord
• 再由 supervisord.conf 启动：

prefect worker start --pool "gmv-analytics-pool" --type process

2. 启动 Docker 容器

方式 A：直接用 docker run

docker run -d \
  --name prefect-gmv-worker \
  --env-file /Users/idss/YXT_Project/gmv-analytics/.env \
  -e PROJECT_MAPPING_FILE=/app/店铺映射表.xlsx \
  gmv-analytics-prefect:0.1.0

停止容器：

docker stop prefect-gmv-worker
docker rm prefect-gmv-worker

方式 B：用 docker compose

项目里已经有 docker-compose.yaml。

启动：

cd /Users/idss/YXT_Project/gmv-analytics
docker compose up -d --build

开启热加载监听：

cd /Users/idss/YXT_Project/gmv-analytics
docker compose watch

停止：

docker compose down

热加载规则是：

• 修改 .py、.env、Excel 映射表等项目内容：
  • 自动同步到容器
  • 并自动重启服务
• 修改 Dockerfile、pyproject.toml、supervisord.conf、docker-compose.yaml、requirements-docker.txt：
  • 自动触发 rebuild

3. 注册 Prefect 调度

推荐方式是使用 prefect.yaml 注册 deployment：

cd /Users/idss/YXT_Project/gmv-analytics
prefect deploy --all

这会向 .env 中的 PREFECT_API_URL 注册两个 deployment：

• gmv-daily-data-sync-8am
• gmv-daily-notify-9am

前提条件：

• .env 中已经配置好 PREFECT_API_URL
• Prefect API 服务可访问
• 已经有可用的 work pool
  当前 prefect.yaml 默认使用： gmv-analytics-pool

如果还没有 worker，可以在宿主机启动一个：

prefect worker start --pool gmv-analytics-pool --type process

4. 自动执行是怎么发生的

如果你走的是 prefect deploy --all 方案：

1. prefect.yaml 注册两个 deployment
2. Prefect Server/Cloud 按 cron 触发：
   • 08:00：gmv-daily-data-sync-8am
   • 09:00：gmv-daily-notify-9am
3. Prefect worker 拉起执行
4. 代码入口在 prefect_gmv_scheduler.py

如果你走的是 Docker worker 方案：

1. 容器常驻运行 prefect worker start --pool "gmv-analytics-pool" --type process
2. Prefect Server 到点触发 deployment
3. worker 从 gmv-analytics-pool 拉起执行

建议：

• 正式环境优先用 prefect.yaml + prefect deploy --all
• Docker 容器只负责提供 worker 执行环境

5. 单次手动执行

只跑数据同步：

python /Users/idss/YXT_Project/gmv-analytics/prefect_gmv_scheduler.py --mode sync

只跑飞书通知：

python /Users/idss/YXT_Project/gmv-analytics/prefect_gmv_scheduler.py --mode notify

先同步再通知：

python /Users/idss/YXT_Project/gmv-analytics/prefect_gmv_scheduler.py --mode all

如果要在 Docker 里手动执行：

docker run --rm \
  --env-file /Users/idss/YXT_Project/gmv-analytics/.env \
  -e PROJECT_MAPPING_FILE=/app/店铺映射表.xlsx \
  gmv-analytics-prefect:0.1.0 \
  python prefect_gmv_scheduler.py --mode sync

6. Docker 中的日志

现在日志分成两层：

6.1 容器标准输出日志

这是你最先看到的日志来源。

如果用 docker run：

docker logs -f prefect-gmv-worker

如果用 docker compose：

cd /Users/idss/YXT_Project/gmv-analytics
docker compose logs -f

这些日志包含：

• Prefect flow 启动/完成
• 每天数据同步流程
• 飞书接口日志
• 错误堆栈

6.2 容器内本地文件日志

项目已经接了统一日志模块 logging_config.py，所以日志还会写入容器内文件：

• 默认目录：/app/logs
• 默认文件：/app/logs/gmv_sync.log

进入容器查看：

docker exec -it prefect-gmv-worker sh
tail -f /app/logs/gmv_sync.log

如果是 compose：

docker exec -it prefect-gmv-worker sh
tail -f /app/logs/gmv_sync.log

6.3 日志级别

默认是 INFO。
如果要看更细的调试日志，在 .env 里加：

LOG_LEVEL=DEBUG

可选日志配置还有：

LOG_DIR=/app/logs
LOG_FILE_NAME=gmv_sync.log
LOG_MAX_BYTES=10485760
LOG_BACKUP_COUNT=7

7. 现在最推荐的执行方式

如果你要的是“长期稳定自动执行”，建议这样：

1. 构建镜像
2. 准备好 .env
3. 启动 Prefect API
4. 启动 worker
5. 执行：

cd /Users/idss/YXT_Project/gmv-analytics
prefect deploy --all

如果你要的是“容器里运行 worker，由 Prefect Server 统一调度”，直接：

docker compose up -d --build

然后在能连到 Prefect API 的环境里执行：

cd /Users/idss/YXT_Project/gmv-analytics
prefect deploy --all