prefect 缓存失效主因是 cache_key_fn 非纯函数、本地内存缓存误判、部署环境缓存后端配置错误；需确保 key 稳定可复现、启用持久化 orion、校验 api url 与数据库路径。
缓存失效时 Prefect 任务反复重跑，怎么锁定原因
Prefect 默认不缓存任务结果，哪怕 cache_key_fn 写了也常因参数或环境变化导致缓存未命中。最常见的是：函数签名没变，但输入参数里混入了 datetime.now()、uuid.uuid4() 这类每次调用都不同的值，缓存 key 就永远不一致。
-
cache_key_fn返回的 key 必须是纯函数：相同输入 → 相同输出；含随机/时间/全局状态的逻辑必须提前剥离 - 检查
cache_expiration是否设得太短（比如timedelta(minutes=1)），本地调试时容易误判为“没缓存” - 用
logger.info(f"Cache key: {cache_key}")在cache_key_fn里打日志，直接比对两次运行的 key 字符串是否完全一致 - 注意 Prefect 2.10+ 对
Pandas DataFrame的默认哈希行为：空 DataFrame 和含 NaN 的 DataFrame 可能生成相同 hash，建议显式用df.values.tobytes() + df.index.tobytes()构造 key
在本地开发时让缓存真正生效，而不是假装生效
Prefect 的本地运行模式（flow.run() 或 CLI prefect flow run）和部署后行为不同：本地不会自动启用持久化缓存后端，默认只走内存缓存，进程一退出就清空。所以你看到“Hit cache”日志，很可能只是同一 Python 进程内的临时命中。
- 本地调试务必启动
prefect orion start（或prefect server start），并确保 flow 用serve()或deploy()注册到该实例，否则缓存不跨进程、不跨重启 - 确认
prefect config set PREFECT_API_URL="http://127.0.0.1:4200/api"已设置，避免 CLI 误连云端托管服务 - 检查 Orion 数据库路径：
PREFECT_ORION_DATABASE_CONNECTION_URL默认是 SQLite 文件，若路径权限不对或磁盘满，缓存写入静默失败，日志里只有Failed to store cache而无堆栈
cache_key_fn 怎么写才稳定又不拖慢执行
缓存 key 生成本身不能成为性能瓶颈，尤其当任务输入是大对象（如 GB 级 pd.DataFrame）时，全量序列化算 hash 很容易卡住。Prefect 不强制要求 key 是 hash，只要可哈希、可比较、语义稳定即可。
- 避免用
pickle.dumps(obj)或json.dumps(obj, sort_keys=True)直接序列化整个输入——DataFrame 的 index 名、列顺序微调都会导致 key 突变 - 推荐组合策略：
f"{input_path}_{hashlib.md5(df.columns.tobytes()).hexdigest()[:8]}_{len(df)}"，只取关键可判定字段 - 如果任务依赖外部文件，key 应包含
os.path.getmtime(input_path)而非文件内容 hash（除非内容极小），否则每次读文件都得先计算 hash - 函数内不要调用
time.time()或random.random()，Prefect 会警告 “non-deterministic cache key”，但不会报错，而是拒绝缓存
部署后缓存突然不工作，优先查这三处配置
Flow 在本地缓存正常，一上 Kubernetes 或 Docker 部署就失效，大概率不是代码问题，而是环境隔离导致缓存后端不可达或配置错位。
立即学习“Python免费学习笔记（深入）”；
- K8s Job 中未挂载持久卷给 Orion SQLite DB，或者
PREFECT_ORION_DATABASE_CONNECTION_URL指向了sqlite:///tmp/orion.db—— 容器重启即丢失 - Docker 镜像里没装
psycopg2却配置了 PostgreSQL 缓存后端，Prefect 启动时静默降级为内存缓存，日志无提示 - Agent 运行时未继承 flow 所在环境的
PREFECT_API_URL，导致 task 运行时连的是默认https://api.prefect.cloud/，而你的缓存存在本地 Orion 里
缓存机制本身不复杂，难在它依赖的每个环节——key 生成、序列化、存储后端、网络连通性、权限——只要一个链路断掉，就退化成无缓存执行，而且 Prefect 很少明确告诉你哪一环坏了。
