hyperf集群下多服务器定时任务互斥执行需依赖redis分布式锁，通过配置$mutex启用原生支持，结合singleton和合理expires值确保同一任务仅一节点执行，避免重复与数据错乱。
Hyperf 集群下多服务器定时任务互斥执行，核心目标是：同一任务在任意时刻仅由一个节点执行，避免重复处理、数据错乱或资源争抢。这不是靠“选一台机器跑”就能解决的，而是要结合框架能力与分布式协调机制。
用 Hyperf Crontab 内置 mutex 锁（推荐首选）
Hyperf 的 hyperf/crontab 组件原生支持分布式互斥，无需额外引入调度框架，配置简单、耦合低、运维轻量。
-
启用 Redis 分布式锁：确保项目已配置 Redis 连接池（如
default池），并在任务类中声明mutex：
#[Crontab]
class SyncOrderTask extends AbstractCrontab
{
public string $name = 'sync_order';
public string $rule = '0 0 * * *'; // 每天零点
public array $singleton = true; // 同一进程内防重入
public array $mutex = [
'type' => 'redis',
'pool' => 'default',
'expires' => 3600, // 锁过期时间（秒），建议大于任务最大执行时长
];
<pre class="brush:php;toolbar:false;">public function execute(): void { /* 业务逻辑 */ }}
-
关键参数说明：
-
onOneServer = true（隐含在mutex生效时）：自动启用集群级互斥，所有节点竞争同一把 Redis 锁 -
mutexExpires必须合理设置——太短可能任务未完成锁就释放，导致其他节点误入；太长则故障节点无法及时释放锁，影响后续调度 - 锁 key 默认为
crontab:task_name，可自定义，但需保证全局唯一
-
配合 onOneServer + 自定义标识兜底（增强容错）
单纯依赖 Redis 锁在极端网络分区或 Redis 不可用时会降级为“全部跳过”。若业务对可用性要求极高，可叠加轻量级节点仲裁逻辑：
- 在任务执行前，读取 Kubernetes Downward API 或环境变量获取当前 Pod 名/实例 ID
- 结合
onOneServer = true，再加一层“最小实例 ID 优先”策略（如按 Pod 名字典序取最小者执行） - 该方式不替代 Redis 锁，而是作为 Redis 不可用时的 fallback，保障至少有一个节点能尝试执行
避免手动轮子：不用自己写 SETNX 或 try-finally 删锁
有人习惯在 @Scheduled（Spring）或普通方法里手写 Redis 加锁逻辑，但在 Hyperf 中不推荐：
- 易遗漏异常场景：如协程中断、进程崩溃，导致锁未释放，形成死锁
- 无法与 Crontab 生命周期对齐：Hyperf 的
mutex在任务调度器层面统一管理锁的获取、续期、释放，包括自动续期（类似 Redisson 看门狗） - 重复造轮子：Hyperf 已封装好
RedisMutex，底层基于 Lua 原子操作，可靠性远高于应用层拼接
进阶：动态任务 + 数据库锁表（适合规则频繁变更场景）
当定时任务的 cron 表达式、启用状态需要运营后台随时调整时，可结合数据库锁表 + ShedLock 风格机制：
- 设计
crontab_task_lock表，字段含task_name、lock_until、locked_by - 每次执行前，用一条带 WHERE 条件的 UPDATE 尝试更新锁（例如
UPDATE ... SET lock_until = NOW() + INTERVAL 30 MINUTE WHERE task_name = ? AND (lock_until ） - 检查
affectedRows === 1决定是否获得执行权 - 注意：此方案需自行保障事务隔离级别（建议 RR），且不如 Redis 锁响应快，适合分钟级以上、低频变更任务
