Prefect 产品使用说明

一. 部署地址

环境部署在 k8s环境，支持高并发，高可用，可扩展动态扩容。

UI 地址	API地址	备注
http://192.168.10.107:30420	http://192.168.10.107:30420/api	api地址由集群内部调用

二. Prefect详细说明

1. 什么是 Prefect？

Prefect 是现代开源工作流编排平台，用于构建、调度、监控和运维数据管道（工作流），核心定位是替代传统的 Airflow 等工具，主打 “代码即工作流” 的理念，无需强制使用特定 DSL（领域特定语言），直接用 Python 定义工作流，支持动态、分支、循环等复杂逻辑，适配数据工程、机器学习、自动化运维等场景。

Prefect 分为两个主要版本：

• Prefect Community (开源版)：包含核心引擎、本地 Server、CLI/SDK，免费使用。
• Prefect Cloud (商业版)：托管的控制平面，提供团队协作、RBAC 权限、自动化部署、高级监控等功能。

2. 核心优势

特性	说明	备注
原生 Python 支持	用普通 Python 函数定义任务（Task）和工作流（Flow），学习成本低
动态工作流	突破静态 DAG 限制，支持分支、循环、动态任务生成（如机器学习流水线）
强大的容错能力	内置重试、缓存、失败通知、任务超时控制
灵活部署	支持本地、Docker、K8s、AWS ECS/Fargate、Serverless 等执行环境
可观测性	内置 UI、日志、指标、告警（Slack/Email/Teams 等）
云原生架构	控制平面与执行平面分离，适配混合云 / 多云场景

3. 核心概念Prefect

Prefect 3.x 核心组件： 不官方，用看的懂文字描述

• @task：最小执行单元，封装具体业务逻辑（如数据获取、处理、存储）
• @flow：任务编排容器，定义任务的执行顺序和依赖关系
• 部署（Deployment）：将 Flow 打包并配置运行参数，供 Worker 执行
• Work Pool： 资源池，管理 Worker 的资源类型（Process/Docker/K8s 等）
• Work Queue ： 任务队列，细分 Work Pool 中的任务分发规则
• Worker：执行部署的 Flow 实例的运行时进程。执行器，从 Queue 拉取任务并运行
• Prefect Server：本地 / 远程服务，用于监控、调度 Flow 运行

三. Prefect 架构图

Prefect 采用三层架构，控制平面与执行平面分离，核心结构如下：

┌─────────────────────────────────────────┐
│              用户层（Client Plane）       │  # 客户端交互平面：流程开发/部署入口
│  ┌───────────────┐  ┌────────────────┐  │  - Python SDK：编写 Flow/Task 核心逻辑
│  │  Python SDK   │  │     CLI/UI     │  │  - CLI：部署/调度/运维命令行工具
│  └───────────────┘  └────────────────┘  │  - UI：可视化操作（含 Cloud/自托管控制台）
└───────────────────────┬─────────────────┘
                         │ （提交 Deployment/查询状态/触发流程）
                         ▼
┌─────────────────────────────────────────────────────────────────────┐
│                Control Plane（控制平面，管控核心）                   │  # 中心化管控层：不执行任务，仅做编排/调度/监控
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐         │  - API Server：所有请求统一入口（REST/gRPC）
│  │  API Server │  │  Database   │  │       Scheduler     │         │  - Database：存储元数据（PG/SQLite，3.x 主推PG）
│  └─────────────┘  └─────────────┘  └─────────────────────┘         │  - Scheduler：解析 Deployment 规则生成 Flow Run
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐         │  - UI：控制平面可视化控制台（监控/配置）
│  │     UI      │  │ Notification│  │ RBAC/Auth（可选）   │         │  - 通知引擎：失败/超时触发 Slack/Email/Webhook
│  └─────────────┘  │    Engine   │  └─────────────────────┘         │  - RBAC：3.x 增强版权限控制（团队/角色）
│                   └─────────────┘                                   │ （部署形态：Prefect Cloud 托管 / 自部署 Server）
└───────────────────────┬─────────────────────────────────────────────┘
                         │ （将 Flow Run 分发至指定 Work Pool/Work Queue）
                         ▼
┌─────────────────────────────────────────────────────────────────────┐
│              Execution Plane（执行平面，任务执行层）                 │  # 分布式执行层：实际运行 Flow/Task，与控制平面解耦
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐         │  - Work Pool：3.x 核心，定义执行资源池（Process/Docker/K8s）
│  │  Work Pool  │  │ Work Queue  │  │       Worker        │         │  - Work Queue：Pool 内任务队列（按标签/优先级分组）
│  └─────────────┘  └─────────────┘  └─────────────────────┘         │  - Worker：监听 Queue，拉取任务并创建执行环境
│  ┌─────────────────────────────────────────────────────────────┐   │  - Flow/Task Run：单个流程/任务的执行实例
│  │     Flow Run / Task Run（流程/任务执行实例）                │   │ （执行环境：本地进程/Docker/K8s/Lambda，3.x 废弃 Agent）
│  │     （支持并发/重试/资源隔离，实时上报状态至控制平面）      │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
└─────────────────────────────────────┘

四. 配置本地 Prefect 客户端，连接 Server

1. 本地安装匹配版本的 Prefect

python3 必须 3.12 以上
pip install prefect==3.6.4  # 必须和 Server 版本一致

2. 配置客户端指向 K8s 上的 Prefect Server

# 直接指向 NodePort
prefect config set PREFECT_API_URL=http://192.168.10.107:30420/api

3. 验证连接是否成功

prefect --help  # 查看对应参数了解
prefect config view  # 查看当前配置

五. 使用示例

1. 部署配置

1. 创建 prefect_demo.py

包含任务定义、流程编排、参数化、日志输出（覆盖实际场景核心需求）：

from prefect import flow, task
from prefect.logging import get_run_logger
import random

# ---------------------- 定义任务 ----------------------
@task(name="数据加载任务", retries=2, retry_delay_seconds=3)
def load_data(data_source: str) -> list:
    """模拟加载数据源数据"""
    logger = get_run_logger()
    logger.info(f"开始加载数据源: {data_source}")
    
    # 模拟数据加载（随机生成列表）
    data = [random.randint(1, 100) for _ in range(5)]
    logger.info(f"数据源 {data_source} 加载完成，数据: {data}")
    return data

@task(name="数据处理任务")
def process_data(raw_data: list, multiplier: int) -> list:
    """模拟数据处理（数值乘以指定倍数）"""
    logger = get_run_logger()
    logger.info(f"开始处理数据，倍数: {multiplier}")
    
    processed_data = [num * multiplier for num in raw_data]
    logger.info(f"数据处理完成，结果: {processed_data}")
    return processed_data

# ---------------------- 定义流程 ----------------------
@flow(
    name="数据处理全流程",
    description="Prefect 3.6.4 全流程示例：加载→处理数据",
    log_prints=True  # 允许 print 输出到日志
)
def data_processing_flow(
    data_source: str = "mysql_db",  # 默认数据源
    multiplier: int = 2  # 默认倍数
) -> None:
    """主流程：串联数据加载和处理任务"""
    logger = get_run_logger()
    logger.info("=== 启动数据处理全流程 ===")
    
    # 调用任务（Prefect 3.x 无需显式调用 .submit()，简化语法）
    raw_data = load_data(data_source)
    processed_data = process_data(raw_data, multiplier)
    
    logger.info(f"=== 全流程执行完成！最终结果: {processed_data} ===")
    print(f"流程最终输出：{processed_data}")

# ---------------------- 本地运行入口 ----------------------
if __name__ == "__main__":
    # 方式1：使用默认参数运行
    # data_processing_flow()
    
    # 方式2：自定义参数运行
    data_processing_flow(
        data_source="postgresql_db",
        multiplier=3
    )

查看工作池

# 1. 查看已有工作池
prefect pool ls

# 2. 若不存在 "default-agent-pool"，则创建
prefect pool create "default-worker-pool" --type "prefect-agent"
# --type "prefect-agent"：指定工作池类型为 Agent 类型（适配默认 Agent）

2. 部署流程到 Prefect Server

Prefect 3.6.4 部署流程推荐使用 CLI 方式，步骤如下：

1. 构建部署配置

在代码同级目录执行以下命令，创建部署（指定流程入口、名称、工作池）

prefect deploy prefect_demo.py:data_processing_flow --name "数据处理部署-测试环境" --pool "default-pool" --description "用于测试的数处理流程部署"

2. 验证部署

# 查看所有部署
prefect deployment ls

查看运行状态

# 查看运行状态， 也可查看ID，下边查日志可以看
prefect flow-run ls

2.验证运行结果

1. 查看日志（CLI 方式）

# 查看最新的流程运行日志
prefect flow-run logs <FLOW_RUN_ID>

prefect flow-run logs 99798f5d-dd2a-4ebc-8756-ffd737bb37e5 

2. 可视化查看（UI 方式）

直接访问 Prefect Server 的 UI 地址：

plaintext

http://192.168.10.107:30420

在 UI 中可查看：

• 流程部署列表
• 流程运行状态（成功 / 失败）
• 任务执行日志
• 流程执行时序图

 

六. K8S使用示例

官网一般只有纯净的服务镜像，依赖推荐自行安装。

构建 k8s work 镜像

Dockerfile

# 基础镜像（替换为你的原始基础镜像，若没有则用官方镜像）
FROM prefecthq/prefect:3.6.4-python3.11

# 安装 Kubernetes Worker 必需依赖
RUN pip install --no-cache-dir \
    prefect==3.6.4 \
    prefect-kubernetes>=0.3.0 \
    minio -i https://pypi.tuna.tsinghua.edu.cn/simple

# 验证依赖安装（可选，构建时检查）
RUN python -c "import prefect_kubernetes; print('prefect-kubernetes 安装成功，版本：', prefect_kubernetes.__version__)"

# 保持与原 Deployment 一致的默认命令（可选）
CMD ["prefect", "worker", "start", "--pool", "k8s-pool", "--work-queue", "default"]

 执行构建

docker build -t prefect-spirit-ai:v1.0.2 .

 

 

安装本地开发依赖

 

pip install "prefect[kubernetes]"
pip install -U "prefect[kubernetes]"
prefect block register -m prefect_kubernetes
# 指定版本，备用
pip install prefect==3.6.4 whenever==0.9.1 prefect-kubernetes>=0.3.0

部署 

编写 K8s Job YAML 文件

创建 job.yaml（指定 flowauto 命名空间， Job）

job.yml

apiVersion: batch/v1
kind: Job
metadata:
  name: prefect-demo-job
  namespace: default
spec:
  template:
    spec:
      containers:
      - name: demo-container
        image: busybox:latest
        command: ["/bin/sh", "-c", "echo '✅ Running from YAML!' && sleep 3"]
      restartPolicy: Never
  backoffLimit: 1
  ttlSecondsAfterFinished: 300

1：修改代码适配环境（1 分钟）

创建 k8s_job_flow.py

from prefect import flow, get_run_logger
from prefect_kubernetes.credentials import KubernetesCredentials
from prefect_kubernetes.flows import run_namespaced_job
from prefect_kubernetes.jobs import KubernetesJob

# 1. 加载之前保存的 K8s 凭证块（k8s-creds）
k8s_creds = KubernetesCredentials.load("k8s-creds")

# 2. 从 YAML 文件创建 KubernetesJob 对象
job = KubernetesJob.from_yaml_file(
    credentials=k8s_creds,
    manifest_path="job.yaml",  # 指向你的 YAML 文件路径
)

# 3. 保存 Job 块（可在 UI 中复用）
job.save("my-k8s-job", overwrite=True)

# 4. 定义核心 Flow
@flow
def kubernetes_orchestrator():
    logger = get_run_logger()
    # 运行 K8s Job，日志输出到 Prefect 日志器
    run_namespaced_job(
        kubernetes_credentials=k8s_creds,
        job=job,
        namespace="default",
        print_func=logger.info  # 将 Job 日志转发到 Prefect 日志
    )

# 5. 运行 Flow
if __name__ == "__main__":
    kubernetes_orchestrator()

2：部署 Flow 到 k8s-pool

# 部署 Flow 到你的 K8s Work Pool
prefect deploy k8s_job_flow.py:kubernetes_orchestrator --pool k8s-pool --name k8s-job-deployment

 

3：触发 Flow 运行

# 触发 Flow 执行（调度 K8s Job）
prefect deployment run k8s-job-orchestrator/k8s-job-deployment

4：验证结果

方式 1：查看 K8s Job/Pod 状态

# 1. 查看 flowauto 命名空间下的 Job
kubectl get jobs -n flowauto

查看日志

# 2. 查看 Job 对应的 Pod 日志
kubectl logs -n flowauto $(kubectl get pods -n flowauto -l job-name=prefect-test-job -o name | cut -d/ -f2)

方式 2：查看 Prefect Flow 日志（UI/CLI）

# 查看 Flow Run 日志（替换为实际 Flow Run ID，可从 UI 复制）
prefect flow-run logs <flow-run-id>
# 或直接在 Prefect UI 查看：Flow Runs → k8s-job-orchestrator → Logs

Prefect 日志：

🚀 开始调度 K8s Job...
✅ Prefect 调度的 K8s Job 运行成功！
🎉 K8s Job 调度完成！

UI 界面查看，验证，至此完成。