Hyperf定时任务在集群下默认重复执行，必须启用RedisTaskMutex等分布式锁机制才能保证单实例执行；需正确配置mutex参数、Redis连接池、锁续期看门狗，并防范kill-9、Redis脑裂、手动删锁等静默失效场景。
Hyperf 的定时任务在集群部署下默认会重复执行，必须显式启用分布式锁机制才能保证「同一时刻仅一个实例执行」——这不是可选项，是生产环境的硬性前提。
为什么 hyperf/crontab 默认不防并发
Hyperf 的 Crontab 进程各自独立扫描规则、触发回调，彼此无协调。哪怕你只配了一个 */1 * * * * *（每秒执行），5 台机器就会每秒跑 5 次。
- 框架不会自动加锁：除非你主动配置
mutex或继承带锁逻辑的策略类 -
mutex配置项默认为null，即关闭互斥 - 即使开了
RedisTaskMutex，若 Redis 不可用或锁 key 冲突，它也不会阻塞或降级，而是静默跳过
如何正确启用 RedisTaskMutex
这是 Hyperf 官方推荐的开箱即用方案，但需确认三点是否到位：
- 确保
config/autoload/crontab.php中已开启mutex配置：'mutex' => [ 'type' => 'redis', 'params' => [ 'pool' => 'default', 'key' => 'crontab:mutex:%s', 'ttl' => 30, ], ], -
key模板里的%s会被替换成任务名，所以不同任务锁隔离；但若多个任务共用同一name，它们会互相阻塞 -
ttl建议设为任务平均耗时的 2–3 倍（比如任务通常跑 8 秒，ttl设为 30），太短会导致锁提前释放，太长则故障恢复慢 - 必须确保
hyperf/redis已安装且default连接池配置正确，否则锁初始化失败，日志里只会打印 warning，任务照常执行
自定义策略类时锁续期容易漏掉看门狗
如果你像文档里那样手写 DistributedCrontabStrategy，只用 SET key value NX EX 30 是不够的——没有续期，30 秒一到锁就丢，不管任务是否还在跑。
- 必须启用看门狗：
leaseTime参数得传-1或省略，不能写死成正数（如lock(30, TimeUnit.SECONDS)） - 全局配置
lockWatchdogTimeout（单位毫秒）必须在config/autoload/redis.php或启动前注入，例如：'options' => [ 'lockWatchdogTimeout' => 120000, ], - 续期脚本必须原子：用
PEXPIRE而非EXPIRE，避免毫秒级精度丢失；Lua 脚本里要先校验 value 是否匹配，防止误删别人锁 - 别在
@Transactional方法里调unlock()：事务未提交，看门狗线程会终止，锁残留且无告警
锁失效的三个静默陷阱
就算你把参数全配对了，以下情况仍会导致锁“看似生效，实则失效”，且没有任何报错：
- Worker 进程被
kill -9：看门狗协程直接消失，锁只能等lockWatchdogTimeout后自动过期（比如设了 2 分钟，就得等满 120 秒） - Redis 集群脑裂，客户端连到只读从节点：所有
PEXPIRE返回 0，续期失败，但业务逻辑照常执行，锁形同虚设 - 运维手动
DEL lock:crontab:xxx：看门狗还在发续期请求，每次返回 0，最终放弃续期，但业务不感知，继续跑完——此时已失去互斥保障
这些场景无法靠单点锁参数规避，得靠架构层兜底：比如任务执行前查 DB 标记位 + 最终一致性补偿，或者用 ZooKeeper 锁替代（强一致但性能低）。真正高可用，从来不是加一行 mutex 就能解决的事。
