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가 실행될 때 획득합니다.
목적은 다음과 같습니다.

여러 동기화 job 이 동시에 같은 리포지터리를 업데이트하려 할 때 발생하는 경합 상태를 방지합니다.
리포지터리별로 동기화 작업을 직렬화해 데이터 일관성을 보장합니다.
중복된 이벤트 워커와 pending 상태에 멈춘 동기화에서 오는 불필요한 부하를 막습니다.

임대의 타임아웃은 3시간입니다. 임대 키 형식은 geo_sync_ssf_service:{replicable_name}:{model_record_id} 입니다.
동기화 작업 중 동작#
동기화 작업이 시작되면 다음과 같이 진행됩니다.

서비스가 해당 리포지터리에 대한 배타적 임대를 획득하려고 시도합니다
다른 프로세스가 이미 임대를 보유하고 있는 경우

"Cannot obtain an exclusive lease" 로그 메시지를 남기고 동기화가 조기에 종료됩니다.
동기화 작업은 수행되지 않습니다.
해당 job은 나중에 재시도됩니다.


임대를 획득한 경우

동기화 작업이 진행됩니다.
동기화가 끝난 뒤 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 - 고아 임대 키 문제를 최초로 문서화한 이슈