본문으로 건너뛰기

클러스터 조정 Enterprise

Semaphore 노드는 서로 직접 통신하지 않습니다. 노드 간에 합의가 필요한 모든 정보는 Redis를 거칩니다. 어떤 노드가 살아 있는지, 어떤 태스크가 어떤 노드에 속하는지, 어떤 노드가 스케줄을 실행하는지, 어떤 UI 메시지를 중계할지 등입니다. 이 상태의 각 요소는 만료 시간이 있는 소수의 Redis 키로 저장되므로, 장애가 발생한 노드가 무언가를 오래 남겨 둘 수 없습니다. 영속적인 데이터(태스크, 템플릿, 로그, runner)는 항상 데이터베이스에 저장되며, Redis는 조정 상태만 보관합니다.

모든 키는 고정된 접두사 ha:와 tasks:를 사용합니다. 이 접두사는 구성으로 변경할 수 없으므로, 하나의 Redis 서버를 공유하는 두 Semaphore 클러스터는 서로 다른 데이터베이스 번호(ha.redis.db)를 사용해야 합니다.

노드 레지스트리​

모든 노드는 시작 시 자신을 등록한 뒤 10초마다 레코드를 갱신합니다. 레코드는 30초 후 만료되므로, 갱신을 멈춘 노드는 늦어도 30초 후에는 죽은 것으로 간주됩니다. 정상 종료 시 노드는 자신의 레코드를 즉시 제거합니다.

키유형용도
ha:node:<node_id>string, JSON노드 하나의 하트비트: node_id, started_at, version, last_beat. 마지막 갱신 후 30초가 지나면 만료됩니다.
ha:nodesset등록된 모든 노드의 ID. 하트비트 키가 만료된 멤버는 다른 노드들이 정리합니다.

노드 레지스트리는 클러스터 대시보드에 표시되는 내용이며, 고아 정리기(아래 참조)가 태스크 소유자가 아직 살아 있는지 판단할 때 참조하는 정보이기도 합니다.

태스크 큐와 실행 중인 태스크​

태스크 큐는 공유되므로, 한 노드에서 시작된 태스크를 다른 어떤 노드든 디스패치하고, 감시하고, 마무리할 수 있습니다. Redis에는 태스크 ID와 몇 가지 임시 필드만 저장되며, 태스크 자체는 필요로 하는 노드가 데이터베이스에서 불러옵니다.

키유형용도
tasks:queuelist디스패치를 기다리는 태스크의 ID(순서대로).
tasks:claim:<task_id>string태스크를 소유한 노드의 ID. 큐에서 제거하는 것과 함께 원자적으로 기록되므로, 태스크는 정확히 하나의 노드만 가져갑니다. 5분 후 만료되며, 소유자가 1분마다 갱신합니다.
tasks:runningset현재 실행 중인 태스크의 ID.
tasks:active:<project_id>set프로젝트에서 활성 상태(대기 중 또는 실행 중)인 태스크의 ID. 프로젝트별 동시 실행 제한에 사용됩니다.
tasks:task_projecthashtask_id → project_id. 어떤 노드든 데이터베이스에서 태스크를 불러올 수 있도록 합니다.
tasks:aliaseshash별칭으로 참조되는 태스크의 alias → task_id.
tasks:runtime:<task_id>hashrunner ID나 태스크를 시작한 사용자처럼 태스크 실행 중에 변경되는 필드.
tasks:finalize:<task_id>string원격 runner에서 실행된 태스크의 최종 결과를 기록하는 노드가 획득하는 잠금. 5분 후 만료됩니다.

tasks:task_project, tasks:aliases, tasks:runtime:*의 항목은 태스크가 끝나면 제거되며, 안전장치로 7일 후에 추가로 만료됩니다.

노드는 단일 원자적 연산으로 큐에서 태스크를 가져갑니다. 태스크가 아직 큐에 있는지 확인하고, 클레임을 기록하고, 큐에서 태스크를 제거하고, 실행 중 세트에 추가합니다. 두 노드가 동시에 시도하면 하나만 성공합니다.

고아 정리기. 모든 노드는 1분에 한 번, 소유자가 죽은 실행 중 태스크, 즉 클레임이 만료되었거나 소유자의 하트비트가 사라진 태스크를 검토합니다. 데이터베이스에 이미 완료된 것으로 표시된 태스크는 Redis에서 그냥 제거됩니다. runner에 한 번도 전달되지 않은 태스크는 살아 있는 노드가 디스패치하도록 큐에 다시 넣습니다. 이미 runner에서 실행 중인 태스크는 그대로 둡니다. runner는 계속 작업하며, 데이터베이스에 완료로 표시되면 태스크가 정리됩니다.

잠금​

잠금은 SET NX로 생성되는 단일 키입니다. 키 생성에 성공한 노드가 잠금을 보유합니다. 모든 잠금에는 만료 시간이 있고, 오래 유지되는 잠금은 소유자가 갱신하므로, 장애가 발생한 노드의 잠금은 자동으로 해제됩니다.

키만료용도
ha:sched:lock:<schedule_id>:<minute>55초스케줄마다, 1분마다 하나의 잠금. 이를 생성한 노드가 스케줄을 실행하고, 나머지 노드는 건너뜁니다.
ha:wf:lock:<project_id>:<run_id>30초, 10초마다 갱신특정 워크플로 실행을 한 번에 하나의 노드만 진행시킵니다.
ha:wf:start:<project_id>:<template_id>10초새 워크플로 실행을 생성하는 동안의 짧은 잠금. 두 노드가 같은 워크플로를 두 번 시작하지 않도록 합니다.
ha:audit:export:<destination_id>30초, 10초마다 갱신특정 대상으로 감사 이벤트를 내보내는 노드는 하나뿐입니다. Redis를 사용할 수 없으면 어떤 노드도 내보내지 않으므로, 이벤트가 두 번 전송되는 일은 없습니다.

스케줄과 워크플로 잠금은 페일 오픈(fail open) 방식입니다. Redis에 연결할 수 없으면 노드는 작업을 건너뛰지 않고 계속 진행하며, 데이터베이스의 조건부 업데이트가 결과의 정확성을 보장합니다. 감사 내보내기 리스는 페일 클로즈(fail closed) 방식입니다. 중복된 내보내기는 되돌릴 수 없기 때문입니다.

Pub/Sub 채널​

채널용도
ha:ws:broadcastUI용 WebSocket 메시지. 노드는 자신에게 연결된 브라우저에 메시지를 전달하고 이 채널에 발행합니다. 다른 노드들은 이를 자신의 브라우저에 중계합니다.
tasks:events태스크 큐와 실행 중 세트의 변경, 런타임 필드 업데이트, 강제 중지 요청. 노드는 이 이벤트를 사용하여 메모리에 있는 큐의 상태를 최신으로 유지하고, 다른 노드가 중지를 요청한 태스크를 중지합니다.

메시지에는 보낸 노드의 ID가 포함되므로, 노드는 자신이 보낸 메시지를 무시합니다.

Runner 캐시 키​

ha:runner:* 키는 runner 레코드의 공유 캐시에 속합니다. 자세한 내용은 Runner 인증 캐시를 참고하세요.