flowchart TD
        A(["Start"])
        A --> B{"What triggers the repository sync?"}
        B --> C["Resync from the admin interface"]
        B --> D["An update event on the repository (for example, git push)"]
        B --> E["Cron worker periodic sync"]
        B --> F["Rails console sync: \n 'replicator.sync'"]
        C --> G["Geo::EventWorker"]
        D --> G
        E --> H["Geo::SyncWorker"]
        F --> I["Geo::FrameworkRepositorySyncService.execute"]
        H --> I
        G --> I

sequenceDiagram
    participant Worker as Geo::EventWorker
    participant Service as Geo::EventService
    participant Scheduler as Geo::RepositoryRegistrySyncWorker
    participant SyncWorker as Geo::SyncWorker
    participant SyncService as Geo::SyncService
    participant Replicator as Geo::ProjectRepositoryReplicator
    participant Registry as Geo::ProjectRepositoryRegistry
    participant FRSS as Geo::FrameworkRepositorySyncService
    participant Primary as Primary Site
Note over Worker,Replicator: Event-driven sync path
Worker->>Service: new(replicable_name, event_name, payload)
Service->>Replicator: new(model_record_id: payload[:model_record_id])
Replicator-->>Service: Geo:ProjectRepositoryReplicator
Service->>Replicator: consume(event_name, **payload)
Replicator->>Registry: find_or_initialize_by(model_foreign_key => model_record_id)
Registry-->>Replicator: Geo::ProjectRepositoryRegistry
Replicator->>Registry: pending!
Registry-->>Replicator: true

Note over Scheduler,Replicator: Background sync path
Scheduler->>SyncWorker: enqueues
SyncWorker->>SyncService: new(replicable_name, model_record_id)
SyncService->>Replicator: new(model_record_id: payload[:model_record_id])
Replicator-->>SyncService: Geo:ProjectRepositoryReplicator
SyncService->>Replicator: sync

Note over Replicator, Primary: Common path
Replicator->>FRSS: execute
FRSS->>Replicator: registry
Replicator->>Registry: find_or_initialize_by(model_foreign_key => model_record_id)
Registry-->>Replicator: Geo::ProjectRepositoryRegistry
Replicator-->>FRSS: Geo::ProjectRepositoryRegistry
FRSS->>Registry: started!
FRSS->>Primary: Fetch repository
Primary->>FRSS: Repository data
FRSS-&gt;&gt;Registry: synced!</code></pre></details></div>

배타적 임대 메커니즘#
배타적 임대 메커니즘은 동일한 저장소에서 동시 동기화 작업을 방지하는 중요한 구성 요소입니다. 임대는 Geo::FrameworkRepositorySyncService가 실행될 때 획득됩니다.
그 목적은:

여러 동기화 잡이 동일한 저장소를 동시에 업데이트하려고 할 때 경쟁 조건을 방지합니다.
각 저장소에 대한 동기화 작업을 직렬화하여 데이터 일관성을 보장합니다.
중복된 이벤트 워커와 pending 상태에 멈춘 동기화로 인한 불필요한 부하를 방지합니다.

임대 타임아웃은 3시간입니다. 임대 키 형식은 geo_sync_ssf_service:{replicable_name}:{model_record_id}입니다.
동기화 작업 중 동작#
동기화 작업이 시작될 때:

서비스가 저장소에 대한 배타적 임대 획득을 시도합니다
다른 프로세스가 이미 임대를 보유하고 있는 경우:

동기화는 로그 메시지 "Cannot obtain an exclusive lease"와 함께 조기에 종료됩니다.
동기화 작업이 수행되지 않습니다.
잡은 나중에 재시도됩니다.


임대가 획득된 경우:

동기화 작업이 진행됩니다.
동기화 완료 후 ensure 블록에서 임대가 해제됩니다.



Mermaid 다이어그램 (18줄)
소스 코드 보기
sequenceDiagram
participant FRSS as FrameworkRepositorySyncService
participant Redis as Redis (Lease Store)
participant Primary as Primary Site
FRSS-&gt;&gt;Redis: Try obtain lease&lt;br/&gt;(geo_sync_ssf_service:type:id, TTL=8h)

alt Lease obtained
    Redis--&gt;&gt;FRSS: Lease granted
    FRSS-&gt;&gt;FRSS: Change state to started
    FRSS-&gt;&gt;Primary: Fetch repository
    Primary--&gt;&gt;FRSS: Repository data
    FRSS-&gt;&gt;FRSS: Change state to synced
    FRSS-&gt;&gt;Redis: Cancel lease
else Lease taken
    Redis--&gt;&gt;FRSS: Lease denied
    Note over FRSS: Sync skipped
end</code></pre></details></div>

고아 임대 키#
고아 임대 키는 동기화 프로세스가 비정상적으로 종료될 때(예: SIGKILL 또는 프로세스 충돌) 발생할 수 있으며, 이는 프로세스가 ensure 블록이 임대를 해제하기 전에 종료됨을 의미합니다. 임대 키가 고아가 되면 해당 저장소에 대한 후속 동기화 시도는 최대 3시간 동안(임대가 만료될 때까지) 차단됩니다.
이 문제를 완화하기 위해 몇 가지 옵션이 있습니다:

자동 만료: 고아 임대는 3시간 후에 자동으로 만료됩니다.
모니터링: geo.log에서 "Cannot obtain an exclusive lease" 메시지와 영향을 받는 잠재적 저장소를 식별하기 위한 lease_key의 geo_sync_ssf_service:{replicable_name}:{model_record_id} 값의 증가를 확인합니다.
수동 해제: 최후의 수단으로, Rails 콘솔을 통해 수동으로 고아 임대를 해제할 수 있습니다(문제 해결 참조)

관련 주제#

Geo 셀프 서비스 프레임워크 - Geo 복제 프레임워크 개요
동기화 및 검증 문제 해결 - 고아 임대 키 해결을 포함한 문제 해결 가이드
이슈 #552408 - 고아 임대 키 문제를 문서화한 원래 이슈