gmv-analytics/DOCKER_PREFECT_USAGE.md

# Docker + Prefect 使用说明

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

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

调度配置写在 [prefect.yaml](/Users/idss/YXT_Project/gmv-analytics/prefect.yaml) 中。
运行容器的职责是启动 Prefect worker，不再使用 `--serve` 作为主方案。

## 1. 创建 Docker 镜像

在项目目录执行：

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

镜像内容来自：

- [Dockerfile](/Users/idss/YXT_Project/gmv-analytics/Dockerfile)
- [docker-entrypoint.sh](/Users/idss/YXT_Project/gmv-analytics/docker-entrypoint.sh)

容器启动后会：

- 加载 `.env`
- 自动把 `PROJECT_MAPPING_FILE` 修正为容器内的 `/app/店铺映射表.xlsx`
- 默认执行 `supervisord`
- 再由 [supervisord.conf](/Users/idss/YXT_Project/gmv-analytics/supervisord.conf) 启动：

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

## 2. 启动 Docker 容器

### 方式 A：直接用 `docker run`

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

停止容器：

```bash
docker stop prefect-gmv-worker
docker rm prefect-gmv-worker
```

### 方式 B：用 `docker compose`

项目里已经有 [docker-compose.yaml](/Users/idss/YXT_Project/gmv-analytics/docker-compose.yaml)。

启动：

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

开启热加载监听：

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

停止：

```bash
docker compose down
```

热加载规则是：

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

## 3. 注册 Prefect 调度

推荐方式是使用 [prefect.yaml](/Users/idss/YXT_Project/gmv-analytics/prefect.yaml) 注册 deployment：

```bash
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](/Users/idss/YXT_Project/gmv-analytics/prefect.yaml) 默认使用：
  `gmv-analytics-pool`

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

```bash
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](/Users/idss/YXT_Project/gmv-analytics/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. 单次手动执行

只跑数据同步：

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

只跑飞书通知：

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

先同步再通知：

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

如果要在 Docker 里手动执行：

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

```bash
docker logs -f prefect-gmv-worker
```

如果用 `docker compose`：

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

这些日志包含：

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

### 6.2 容器内本地文件日志

项目已经接了统一日志模块 [logging_config.py](/Users/idss/YXT_Project/gmv-analytics/logging_config.py)，所以日志还会写入容器内文件：

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

进入容器查看：

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

如果是 compose：

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

### 6.3 日志级别

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

```bash
LOG_LEVEL=DEBUG
```

可选日志配置还有：

```bash
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. 执行：

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

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

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

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

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