跳到主要内容

集群协调 Enterprise

Semaphore 节点之间从不直接通信。它们需要达成一致的所有事情都通过 Redis 进行:谁还活着、哪个任务属于哪个节点、谁来触发计划任务,以及要转发哪些 UI 消息。这些状态中的每一部分都是一小组带过期时间的 Redis 键,因此崩溃的节点不会长时间留下任何残留。持久化数据(任务、模板、日志、运行器)始终存放在数据库中;Redis 只保存协调状态。

所有键都使用固定前缀 ha: 和 tasks:。这些前缀不可配置,因此共享同一台 Redis 服务器的两个 Semaphore 集群必须使用不同的数据库编号(ha.redis.db)。

节点注册表​

每个节点在启动时注册自己,然后每 10 秒刷新一次自己的记录。记录在 30 秒后过期,因此停止刷新的节点最多在半分钟后就会被视为已死亡。正常关闭时,节点会立即删除自己的记录。

键类型用途
ha:node:<node_id>string,JSON单个节点的心跳:node_id、started_at、version、last_beat。在最后一次刷新 30 s 后过期。
ha:nodesset所有已注册节点的 ID。心跳键已过期的成员会被其他节点清理掉。

节点注册表就是集群仪表盘所显示的内容,也是孤儿清理器(见下文)用来判断某个任务的所有者是否仍然存活的依据。

任务队列与运行中的任务​

任务队列是共享的,因此在一个节点上启动的任务可以由任何其他节点分派、监视和完成。Redis 只存储任务 ID 和少量临时字段;任务本身由需要它的节点从数据库加载。

键类型用途
tasks:queuelist等待分派的任务 ID,按顺序排列。
tasks:claim:<task_id>string拥有该任务的节点 ID。与从队列中移除的操作一起原子写入,因此一个任务恰好被一个节点领取。5 分钟后过期;所有者每分钟刷新一次。
tasks:runningset当前正在运行的任务 ID。
tasks:active:<project_id>set某个项目中处于活动状态(等待中或运行中)的任务 ID。用于按项目限制并发数。
tasks:task_projecthashtask_id → project_id,使任何节点都能从数据库加载该任务。
tasks:aliaseshashalias → task_id,用于通过别名寻址的任务。
tasks:runtime:<task_id>hash任务运行期间会变化的字段,例如运行器 ID 和启动任务的用户。
tasks:finalize:<task_id>string由写入远程运行器上所执行任务最终结果的节点获取的锁。5 分钟后过期。

tasks:task_project、tasks:aliases 和 tasks:runtime:* 中的条目在任务结束时被删除,并且作为安全兜底,还会在 7 天后过期。

节点通过单个原子操作从队列中取出任务:它检查任务是否仍在队列中,写入领取记录,将任务从队列中移除,并将其加入运行中集合。如果两个节点同时尝试,只有一个会成功。

**孤儿清理器。**每个节点每分钟检查一次所有者已死亡的运行中任务,即领取记录已过期或所有者的心跳已消失。数据库中已显示为完成的任务会直接从 Redis 中删除。从未交给运行器的任务会被放回队列,以便由存活的节点分派。已经在运行器上执行的任务则保持不动:运行器继续工作,待数据库显示该任务完成后再进行清理。

锁​

锁是用 SET NX 创建的单个键:成功创建该键的节点持有锁。每个锁都有过期时间,长时间持有的锁由其所有者刷新,因此崩溃的节点会自动释放其锁。

键过期时间用途
ha:sched:lock:<schedule_id>:<minute>55 s每个计划任务每分钟一个锁。创建它的节点触发该计划任务;其他节点跳过。
ha:wf:lock:<project_id>:<run_id>30 s,每 10 s 刷新一次同一时刻只有一个节点推进某个给定的工作流运行。
ha:wf:start:<project_id>:<template_id>10 s创建新的工作流运行时的短暂锁,防止两个节点将同一个工作流启动两次。
ha:audit:export:<destination_id>30 s,每 10 s 刷新一次只有一个节点向给定目标导出审计事件。如果 Redis 不可用,则没有节点进行导出,因此事件永远不会被发送两次。

计划任务锁和工作流锁采用失败开放(fail open)策略:如果无法连接 Redis,节点会继续执行而不是跳过工作,数据库中的条件更新会保证结果正确。审计导出租约则采用失败关闭(fail closed)策略,因为重复的导出无法撤销。

发布/订阅频道​

频道用途
ha:ws:broadcast发送给 UI 的 WebSocket 消息。节点将消息投递给自己连接的浏览器,并发布到此频道;其他节点再将其转发给各自的浏览器。
tasks:events任务队列和运行中集合的变化、运行时字段更新以及强制停止请求。节点利用这些事件使其内存中的队列视图保持最新,并停止其他节点要求停止的任务。

消息携带发送节点的 ID,因此节点会忽略自己发出的消息。

运行器缓存键​

ha:runner:* 键属于运行器记录的共享缓存。更多信息请参阅运行器认证缓存。