Prefect 高可用部署实战：从单节点到零停机

Prefect 高可用部署实战：从单节点到零停机

【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefect

凌晨两点，跑 ETL 的单台机器磁盘写满，整条链路全断。这篇文章带你走一遍 Prefect 高可用部署的完整路径：PostgreSQL、Docker Compose 起 Server、多 Worker 调度、重试缓存、告警与容灾演练，最后给上线检查清单。

核心概念 30 秒

Prefect 3.x 把运行时拆成三个角色。Server 是大脑：存元数据、做调度、提供 UI。Work Pool 是一份"资源池"定义，声明任务跑在什么基础设施上、占多少资源。Worker 是计算节点上的长驻进程，注册到某个池子里排队干活。

记住一条主线：Server 和 Worker 都是无状态的，状态全部落在数据库里，所以它们都能横向复制。

选型决策

Prefect 给两种部署形态，先定这个，后面所有操作才有的放矢：

结论：稳定频率、单机可恢复的场景用serve；跑 7x24 或任务量上来，必须切 Work Pool，本文后续分层全部基于 Work Pool 展开。同一条 flow 别用两种方式同时部署，那只会让排障复杂度翻倍。

基础层：Python 环境与 PostgreSQL

🔧 这一层只做两件事：装一个干净的 Python 环境，把数据库连接串指对。

用 uv 搭建环境

这段建虚拟环境并安装 Prefect，全程不超过一分钟：

# 创建虚拟环境 uv venv --python 3.11 source .venv/bin/activate # 安装 Prefect uv add prefect

装完验证三件事：

• prefect version输出的大版本与 Server 一致
• 客户端PREFECT_API_URL指向负载均衡地址，别指单节点
• Python 用 3.9 以上，生产固定 3.11 或 3.12

PostgreSQL 连接串怎么配

生产只用 PostgreSQL，SQLite 留给本地调试。连接串通过环境变量注入，示例如下：

# 设置数据库连接串 export PREFECT_API_DATABASE_CONNECTION_URL="postgresql+asyncpg://prefect:<your-password>@<pg-host>:5432/prefect"

三条红线：密码只放环境变量或密钥管理，别写进代码和镜像；多实例部署时所有实例必须连同一个主库；主从复制和自动故障转移在数据库层做，Prefect 只负责连。官方安装文档：安装指南。

服务层：Docker Compose 拉起 Server

这段把 Server 容器化，最小生产配置如下：

services: prefect-server: image: prefecthq/prefect:3-latest environment: - PREFECT_API_DATABASE_CONNECTION_URL=postgresql+asyncpg://prefect:<your-password>@<pg-host>:5432/prefect - PREFECT_SERVER_API_HOST=0.0.0.0 command: prefect server start ports: - "4200:4200" restart: always

多节点部署时同一份 compose 起两个以上实例，前置负载均衡器做分发和故障摘除，健康检查挂/api/health端点。端口固定 4200，LB 之后客户端一律走 LB 地址。完整含 Redis 的编排参考：Docker Compose 指南。

调度层：Work Pool 与多 Worker

这一层决定任务"在哪里跑"。先建池，再在多台节点上起 Worker，丢一台节点不影响整体：

Work Pool 资源限制设置

这段创建 Kubernetes 池并给任务划资源上限：

# 创建 k8s 工作池 prefect work-pool create k8s-pool --type kubernetes # 限制单任务资源 prefect work-pool set k8s-pool job_variables.cpu_request=1 prefect work-pool set k8s-pool job_variables.memory_request=2Gi

资源限制必须写：不限的池子会让一个大任务把节点资源吃光，拖垮同池其他运行。

启动多个 Worker

Worker 是纯无状态进程，数量按"峰值并发 ÷ 单 Worker 容量 + 1 台冗余"来定：

# 节点 1 启动 Worker prefect worker start --pool k8s-pool --name worker-01 # 节点 2 启动 Worker prefect worker start --pool k8s-pool --name worker-02

每个 Worker 用 systemd 或 Kubernetes Deployment 包一层自动重启，进程崩了必须自己活过来。池的管理细节见：Work Pool 管理。

任务层：重试、缓存与超时

架构兜不住单个任务的手抖。三个参数缺一不可：retries管瞬态故障，cache_key_fn管重复计算的浪费，timeout管卡死任务。只看装饰器关键参数：

@task( retries=3, # 失败重试3次 retry_delay_seconds=60, # 重试间隔60秒 cache_key_fn=task_input_hash, # 按输入缓存 timeout=300 # 任务超时上限 ) def extract_data(source: str): pass

两个判断标准：timeout必须大于正常耗时的最大值，小于重试总预算；cache_key_fn只用在输入确定、结果可复用的任务上。不设超时的后果是——一个卡死任务占着池子并发位，整条队列跟着停摆。重试机制完整参考：任务重试。

可观测性：监控面板与 Slack 告警

📊 UI 地址：http://<your-server-ip>:4200。面板上看三类东西：Flow Run 状态流转（Pending/Running/Failed）、在线 Worker 数量、数据库连接数。异常必须有人第一时间知道，用 Automations 把"任务失败"推送到 Slack：

配置四步：

1. 打开 Automations 页面
2. 触发条件选 Flow Run 状态
3. 状态设为 Failed
4. 动作选发送 Slack 消息

配完必须触发一次真实失败验证通路，告警到不了人等于没有。触发器与动作的完整写法见：创建 Automation。

容灾：数据库备份与恢复

🚨 要备的东西只有一个：元数据库。flow 定义、运行历史、部署配置全在里头，代码在 Git 里不在库里。备份与恢复一共四条命令：

# 导出元数据 pg_dump -U prefect prefect > backup_$(date +%F).sql # 恢复演练 psql -U prefect -d prefect_test -f backup_20250101.sql

备份挂 cron 每天跑，恢复演练每季度做一次——备份坏掉的那份，往往是你最想要它的那份。

生产上线检查清单

• PostgreSQL 主从已配置，连接串走 asyncpg 驱动
• 至少 2 个 Server 实例，前置 LB，健康检查生效
• 工作池至少 2 个 Worker，分布在不同节点
• Worker 已接入自动重启（systemd 或 k8s）
• Automations 告警通道收到过真实测试消息
• 备份 cron 连续 7 天 exit 0
• 最近一次恢复演练成功，耗时已知

升级路径

【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefect