hyperf多实例在kubernetes中定时任务重复执行的核心在于多个pod不该同时运行同一任务，需按任务类型选择cronjob或@crontab，并启用ononeserver=true、singleton=true及redis分布式锁。
Hyperf 多实例部署在 Kubernetes 中时，定时任务容易重复执行。核心问题不是“能不能跑”，而是“多个 Pod 该不该同时跑同一任务”。解决思路是：明确任务类型、选对调度层、配好锁机制。
区分任务类型：用 CronJob 还是框架内 Crontab
不是所有定时逻辑都适合写在 Hyperf 的 @Crontab 注解里。
-
基础设施级、无状态、强隔离的任务（如日志归档、指标快照、数据库备份），推荐直接用 Kubernetes
CronJob资源定义。它由 controller-manager 统一调度，天然跨实例唯一，不依赖应用层锁。 -
业务耦合深、需访问容器内服务或上下文的任务（如订单状态补偿、缓存预热、本地协程池清理），才考虑留在 Hyperf 内部用
@Crontab，但必须启用分布式锁。 - 混合场景可拆分：CronJob 负责触发，再通过 HTTP 或消息队列通知 Hyperf 实例执行具体动作，解耦调度与执行。
Hyperf @Crontab 必须开启集群锁
默认情况下，每个 Hyperf Pod 都会独立解析并执行相同 @Crontab 方法，造成 N 倍重复。关键配置在 config/autoload/crontab.php：
-
onOneServer => true：启用集群级互斥，确保整个服务集群中仅一个实例执行该任务。 -
singleton => true：防止单个实例内因协程并发导致重复调用（例如同一秒内多个 timer 触发）。 -
mutexPool => 'redis'和mutexExpires => 120：指定 Redis 连接池和锁过期时间，避免死锁；需确认 Redis 配置已启用且连接稳定。
避免 CronJob 与框架 Crontab 冲突
两者混用时容易出现“双重触发”——比如 CronJob 每天零点调一次接口，而 Hyperf 的 @Crontab(rule="0 0 * * *") 也同时生效。
- 明确分工：要么全交由 CronJob 管理，Hyperf 只暴露执行端点；要么禁用 CronJob，完全由 Hyperf Crontab + 锁控制。
- 若保留双路，务必加幂等校验：任务入口判断当前时间窗口是否已被处理（例如查 Redis key 或 DB 标记），失败直接 return。
- 注意时间基准：Kubernetes CronJob 使用 controller-manager 所在节点时间，Hyperf Crontab 使用各 Pod 所在节点时间。确保所有节点 NTP 同步，否则可能漏跑或早跑。
高可用与可观测性补充建议
定时任务不是“设完就忘”的黑盒，尤其在多实例下更需监控闭环。
- 为每个定时任务添加唯一标识（如注解
@Crontab(name="daily_report")），便于日志检索和 Prometheus 指标打点。 - 在任务逻辑开头记录开始时间、实例 IP/hostname，在结尾记录耗时与结果，写入结构化日志（如 JSON 格式），接入 Loki 或 ELK。
- 对关键任务设置告警：连续 N 次未在预期窗口内完成、执行超时、返回非 0 状态码，均触发企业微信或钉钉通知。
