企业官网建设流程全解析

如何用 prefect flow-run retry 手动重跑 Prefect 中失败的 flow run

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

当一个 flow run 以FAILED或CANCELLED状态结束时，除了等待调度或手动重新触发一次全新的 run，Prefect 3 提供了prefect flow-run retry命令：对同一个 flow run 直接重新执行。重跑后该 flow run 保留原有的 ID 和参数，run_count递增。这篇文章说明如何找到失败的 flow run、执行手动重跑，以及重跑后如何验证结果。以下内容基于 Prefect v3 文档；根据 3.6 版本发布说明，prefect flow-run retry命令是在 3.6.8（2025-12-24 发布）中新增的，低于该版本的 Prefect 没有这条命令。

前提条件

• 已安装 Prefect，且 CLI 能连接到正在运行的 Prefect Server（本地或自托管）。
• 如果要重跑的是通过 deployment 创建的 flow run，重跑后它的状态会变为Scheduled，由 worker 领取执行，因此需要有 worker 在运行。worker 的配置与启动方式见 worker 概念文档。

第一步：找到需要重跑的 flow run

先用prefect flow-run ls按状态筛出失败的 flow run，拿到它的名字或 UUID：

prefect flow-run ls --state FAILED

prefect flow-run ls支持的选项（来自 CLI 参考）：

• --state：按 flow run 的状态名过滤，例如--state Running；
• --state-type：按状态类型过滤，例如--state-type FAILED；
• --flow-name：只看某个 flow 的 run；
• --limit：限制列出数量；
• --output json：以 JSON 输出，便于脚本处理。

注意区分两件事：状态名（name）与状态类型（type）是不同的过滤维度，文档示例中--state Running --state late表示按状态名和状态类型组合过滤。

第二步：执行 retry 命令

命令格式为prefect flow-run retry [OPTIONS] ID_OR_NAME，flow run 可以用 UUID 或名字指定。根据 flow run 的来源，分两种情况。

有 deployment 的 flow run

直接给出 flow run 的名字：

prefect flow-run retry adventurous-crocodile

（adventurous-crocodile是文档中的示例名，请替换为flow-run ls输出里你的 flow run 名字。）

执行后，该 flow run 的状态变为Scheduled，随后由 worker 领取并执行。

没有 deployment 的本地 flow run

通过flow.run等方式在本地创建、没有关联 deployment 的 flow run，必须用--entrypoint指向 flow 代码：

prefect flow-run retry adventurous-crocodile --entrypoint ./flows/my_flow.py:my_flow

--entrypoint的格式是path/to/file.py:flow_function_name，即“包含 flow 的文件路径:flow 函数名”（路径与函数名需替换为你自己的）。提供--entrypoint后，flow 会在当前进程中立即执行，而不是等待 worker。

多个 flow run 同名时

如果多个 flow run 共用同一个名字，用名字无法区分，必须改用 UUID：

prefect flow-run retry a1b2c3d4-e5f6-7890-abcd-ef1234567890

（该 UUID 为文档示例，替换为实际 flow run 的 ID。）

验证重跑结果

• 状态变化：deployment 场景下，重跑后 flow run 状态应变为Scheduled，由 worker 领取执行。可以用prefect flow-run inspect ID查看该 flow run 的详情，加--web可以直接在浏览器中打开该 flow run。

• 等待终态：prefect flow-run watch ID会持续观察该 flow run 直到它到达终态，可选--timeout指定超时秒数：

  prefect flow-run watch a1b2c3d4-e5f6-7890-abcd-ef1234567890 --timeout 300

• 查看日志：prefect flow-run logs ID查看该 flow run 的日志，支持--head/--tail（默认各 20 条，--num-logs可调整）和--reverse（最新日志排在最前）：

  prefect flow-run logs a1b2c3d4-e5f6-7890-abcd-ef1234567890 --tail --reverse

• run_count：文档说明重跑后 flow run 保留原 ID 和参数、run_count递增，可以在inspect的输出中确认次数变化。

• 本地（--entrypoint）场景下，flow 在当前进程中立即执行，进程内的运行结果与日志即为执行反馈；执行结束后同样可用watch/inspect确认最终状态。

边界与限制

• --entrypoint是“没有关联 deployment 的 flow run”的必填项；有 deployment 的 flow run 则无需提供。
• 同名 flow run 必须用 UUID 消歧，用名字会失败或被要求指定 UUID。
• 官方 how-to 指南表述为可重跑 “failed or cancelled” flow run，CLI 参考的措辞是 “failed or completed”，即已完成状态的 flow run 也可以被 retry，两者以命令实际接受的当前状态为准。
• 手动重跑与代码级自动重试是两回事：在 flow/task 上用retries、retry_delay_seconds等参数配置的是异常抛出时的自动重试（见自动重试文档）；prefect flow-run retry是你主动对已结束的一次 flow run 发起的重新执行，二者可以并存、互不替代。

更多细节可参考 手动重跑 flow run 指南和 prefect flow-run 命令参考（其中还包含inspect、ls、cancel、delete、execute等相邻命令）。

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