Geo 문제 해결

Tier: 프리미엄, 얼티메이트 Offering: Self-managed

Geo 설정은 세부 사항에 주의 깊게 관심을 기울여야 하며 때로는 한 단계를 놓치기 쉽습니다.

다음은 문제 해결을 시도하기 위해 수행해야 할 단계 목록입니다:

  1. 기본 문제 해결 수행
  2. PostgreSQL 데이터베이스 복제 오류 해결
  3. 일반 오류 해결
  4. PostgreSQL 이외의 복제 실패 해결

기본 문제 해결

더 고급 문제 해결을 시도하기 전에:

Geo 사이트의 건강 상태 확인

기본 사이트에서:

  1. 왼쪽 사이드바에서 하단에 관리 영역(Admin Area) 을 선택하세요.
  2. Geo > 사이트 를 선택하세요.

우리는 각 보조 사이트에서 다음과 같은 건강 상태 확인을 수행하여 문제가 있는지 확인합니다:

  • 사이트가 실행 중인가요?
  • 보조 사이트의 데이터베이스가 스트리밍 복제로 구성되었나요?
  • 보조 사이트의 추적 데이터베이스가 구성되었나요?
  • 보조 사이트의 추적 데이터베이스에 연결되었나요?
  • 보조 사이트의 추적 데이터베이스가 최신 상태인가요?
  • 보조 사이트의 상태가 10분 이내인가요?

Geo 건강 상태 확인

사이트의 상태가 10분 이상 지연된 경우 “Unhealthy(건강하지 않음)”로 표시됩니다. 이 경우, 영향을 받는 보조 사이트의 Rails 콘솔에서 다음을 실행해 보세요: 

Geo::MetricsUpdateWorker.new.perform

이것이 오류를 발생시키면, 오류로 인해 작업이 완료되지 못할 수 있습니다. 10분 이상 걸린다면 성능 문제가 있을 수 있으며 상태가 최종적으로 업데이트되더라도 UI에서는 항상 “Unhealthy(건강하지 않음)”으로 표시될 수 있습니다.

상태를 성공적으로 업데이트하면, Sidekiq에 문제가 있을 수 있습니다. 실행 중인가요? 로그에 오류가 표시되나요? 이 작업은 매 분마다 대기열로 들어가고 진행 사항이 정확히 추적 데이터베이스에 저장되지 않으면 실행되지 않을 수도 있습니다. Redis에서 배타적 레이스를 이용하여 한 번에 한 가지 작업만 실행되도록 보장합니다. 기본 사이트는 상태를 직접적으로 PostgreSQL 데이터베이스에 업데이트합니다. 보조 사이트는 상태 데이터를 포함하여 HTTP POST 요청을 기본 사이트에 전송합니다.

특정 건강 상태 확인이 실패하면 사이트도 “Unhealthy(건강하지 않음)”로 표시됩니다. 영향을 받는 보조 사이트의 Rails 콘솔에서 다음을 실행하여 실패 사유를 확인할 수 있습니다: 

Gitlab::Geo::HealthCheck.new.perform_checks

반환값이 ""(빈 문자열) 또는 "Healthy"이면 확인에 성공한 것입니다. 다른 값이 반환되면 실패한 부분을 설명하거나 예외 메시지를 표시해야 합니다.

사용자 인터페이스에서 보고된 일반적인 오류 메시지를 해결하는 방법에 대한 자세한 정보는 일반적인 오류 해결을 참조하세요.

사용자 인터페이스가 작동하지 않거나 로그인할 수 없는 경우 Geo 건강 상태 확인을 수동으로 실행하여 이 정보 및 몇 가지 추가 세부 정보를 얻을 수 있습니다.

건강 상태 Rake 작업

  • 사용자 정의 NTP 서버 사용은 GitLab 15.7(https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105514)에서 소개되었습니다.

이 Rake 작업은 기본 또는 보조 Geo 사이트의 Rails 노드에서 실행할 수 있습니다: 

sudo gitlab-rake gitlab:geo:check

예시 출력: 

Geo 확인 중...

GitLab Geo 사용 가능... 예
GitLab Geo 활성화... 예
이 머신의 Geo 노드 이름이 데이터베이스 레코드와 일치합니다... Shanghai이라는 보조 노드 이름을 찾음
GitLab Geo 추적 데이터베이스가 올바르게 구성됨... 예
데이터베이스 복제 활성화됨?... 예
데이터베이스 복제가 작동 중인가요?... 예
GitLab Geo HTTP(S) 연결... 
* 기본 노드에 연결할 수 있습니다... 예
HTTP/HTTPS 저장소 복제가 활성화됨... 예
기계 시계가 동기화되었습니까?... 예
Git 사용자에게 기본 SSH 구성이 있습니까?... 예
OpenSSH가 AuthorizedKeysCommand를 사용하도록 구성되었습니까?... 예
GitLab이 authorized_keys 파일에 쓰기 비활성화되도록 구성되었습니까?... 예
새로운 프로젝트를 해시 저장소에 저장하도록 GitLab이 구성되었습니까?... 예
모든 프로젝트가 해시 저장소에 있습니까?... 예
Geo 확인 중... 완료

환경 변수를 사용하여 사용자 정의 NTP 서버를 지정할 수도 있습니다. 예: 

sudo gitlab-rake gitlab:geo:check NTP_HOST="ntp.ubuntu.com" NTP_TIMEOUT="30"

다음 환경 변수가 지원됩니다.

변수 설명 기본값
NTP_HOST NTP 호스트 pool.ntp.org
NTP_PORT 호스트가 수신 대기하는 NTP 포트 ntp
NTP_TIMEOUT NTP 타임아웃(초) net-ntp 루비 라이브러리에서 정의된 값 (60초)

Rake 작업이 OpenSSH가 AuthorizedKeysCommand를 사용하도록 구성되었습니까 확인을 건너뛴 경우, 다음 출력이 표시됩니다: 

OpenSSH가 AuthorizedKeysCommand를 사용하도록 구성되었습니까... 건너뛰었음
  이유:
  OpenSSH 구성 파일에 액세스할 수 없음
  이를 수정해 보세요:
  이는 SELinux를 사용하는 경우 예상되는 동작입니다. 수동으로 구성을 확인할 수 있습니다.
  자세한 정보는 다음을 참조하세요:
  doc/administration/operations/fast_ssh_key_lookup.md

이 문제가 발생할 수 있는 이유:

  • SELinux를 사용하는 경우
  • SELinux를 사용하지 않고 git 사용자가 제한된 파일 권한으로 인해 OpenSSH 구성 파일에 액세스할 수 없는 경우

후자의 경우, 다음 출력은 root 사용자만이 이 파일을 읽을 수 있다는 것을 보여줍니다: 

sudo stat -c '%G:%U %A %a %n' /etc/ssh/sshd_config

root:root -rw------- 600 /etc/ssh/sshd_config

파일 소유자나 권한을 변경하지 않고 git 사용자가 OpenSSH 구성 파일을 읽을 수 있도록 하려면 acl을 사용하세요: 

sudo setfacl -m u:git:r /etc/ssh/sshd_config

동기화 상태 Rake 작업

현재 동기화 정보는 Geo secondary 사이트의 Rails (Puma, Sidekiq 또는 Geo Log Cursor)를 실행하는 모든 노드에서이 Rake 작업을 수동으로 실행하여 찾을 수 있습니다.

GitLab은 Object Storage에 저장된 객체를 확인하지 않습니다. 객체 저장소를 사용하는 경우 “확인 완료” 확인란에 모두 0이 표시됩니다. 이는 예상된 동작이며 걱정할 것은 없습니다. 

sudo gitlab-rake geo:status

출력에는 다음이 포함됩니다.

  • “실패한” 항목 수 (발생한 실패가 있다면)
  • “성공한” 항목의 “총합”에 대한 “백분율”

예: 

http://secondary.example.com/
-----------------------------------------------------
                        GitLab Version: 14.9.2-ee
                              Geo Role: Secondary
                         Health Status: Healthy
                  Project Repositories: succeeded 12345 / total 12345 (100%)
             Project Wiki Repositories: succeeded 6789 / total 6789 (100%)
                           Attachments: succeeded 4 / total 4 (100%)
                      CI job artifacts: succeeded 0 / total 0 (0%)
        Design management repositories: succeeded 1 / total 1 (100%)
                           LFS Objects: failed 1 / succeeded 2 / total 3 (67%)
                   Merge Request Diffs: succeeded 0 / total 0 (0%)
                         Package Files: failed 1 / succeeded 2 / total 3 (67%)
              Terraform State Versions: failed 1 / succeeded 2 / total 3 (67%)
                  Snippet Repositories: failed 1 / succeeded 2 / total 3 (67%)
               Group Wiki Repositories: succeeded 4 / total 4 (100%)
                    Pipeline Artifacts: failed 3 / succeeded 0 / total 3 (0%)
                     Pages Deployments: succeeded 0 / total 0 (0%)
                  Repositories Checked: failed 5 / succeeded 0 / total 5 (0%)
                Package Files Verified: succeeded 0 / total 10 (0%)
     Terraform State Versions Verified: succeeded 0 / total 10 (0%)
         Snippet Repositories Verified: succeeded 99 / total 100 (99%)
           Pipeline Artifacts Verified: succeeded 0 / total 10 (0%)
         Project Repositories Verified: succeeded 12345 / total 12345 (100%)
    Project Wiki Repositories Verified: succeeded 6789 / total 6789 (100%)
                         Sync Settings: Full
              Database replication lag: 0 seconds
       Last event ID seen from primary: 12345 (약 2분 전)
               Last event ID processed: 12345 (약 2분 전)
                Last status report was: 1 minute ago

각 항목은 최대 세 가지 상태를 가질 수 있습니다. 예를 들어 Project Repositories의 경우 다음과 같이 확인됩니다. 

  Project Repositories: succeeded 12345 / total 12345 (100%)
  Project Repositories Verified: succeeded 12345 / total 12345 (100%)
  Repositories Checked: failed 5 / succeeded 0 / total 5 (0%)

3가지 상태 항목은 다음과 같이 정의됩니다:

  • Project Repositories 출력은 기본에서 보조로 동기화 된 프로젝트 저장소 수를 보여줍니다.
  • Project Verified Repositories 출력은 이 보조의 프로젝트 저장소 중 주요 저장소와 일치하는 저장소 체크섬이 있는지를 보여줍니다.
  • Repositories Checked 출력은 보조에서 로컬 Git 저장소 체크 (git fsck)를 통화해 테스트를 통과한 프로젝트 저장소의 수를 보여줍니다.

실패한 항목에 대한 자세한 내용을 찾으려면 여기를 확인하세요.

복제 또는 확인 실패가 발생하면 이를 해결해 볼 수 있습니다.

저장소 체크 실패가 발생하면 해결해 볼 수 있습니다.

Geo 확인 Rake 작업 실행시 발견된 오류 수정

이 Rake 작업을 실행할 때 노드가 올바르게 구성되지 않았다면 오류 메시지가 표시될 수 있습니다. 

sudo gitlab-rake gitlab:geo:check

  • Rails는 데이터베이스에 연결할 때 암호를 제공하지 않았습니다. 

    Geo 확인 중 ...

GitLab Geo를 사용할 수 있습니다 ... Exception: fe_sendauth: no password supplied
GitLab Geo가 활성화되었습니다 ... Exception: fe_sendauth: no password supplied
...
Geo 확인 완료

    gitlab_rails['db_password']에 postgresql['sql_user_password']의 해시를 생성할 때 사용한 평문 비밀번호가 설정되어 있는지 확인하십시오.

  • Rails가 데이터베이스에 연결할 수 없습니다. 

    Geo 확인 중 ...

GitLab Geo를 사용할 수 있습니다 ... Exception: FATAL:  no pg_hba.conf entry for host "1.1.1.1",  user "gitlab", database "gitlabhq_production", SSL on
FATAL:  no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL off
GitLab Geo가 활성화되었습니다 ... Exception: FATAL:  no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL on
FATAL:  no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL off
...
Geo 확인 완료

    postgresql['md5_auth_cidr_addresses']에 레일스 노드의 IP 주소가 포함되어 있는지 그 IP 주소에 서브넷 마스크가 포함되어 있는지 확인하십시오.

  • Rails가 잘못된 암호를 제공했습니다. 

    Geo 확인 중 ...
GitLab Geo를 사용할 수 있습니다 ... Exception: FATAL:  password authentication failed for user "gitlab"
FATAL:  password authentication failed for user "gitlab"
GitLab Geo가 활성화되었습니다 ... Exception: FATAL:  password authentication failed for user "gitlab"
FATAL:  password authentication failed for user "gitlab"
...
Geo 확인 완료

    gitlab_rails['db_password']에 올바른 암호가 설정되어 있는지 확인하십시오.

  • 조회가 보조 노드가 아닙니다로 반환됩니다. 

    Geo 확인 중 ...

GitLab Geo를 사용할 수 있습니다 ... yes
GitLab Geo가 활성화되었습니다 ... yes
GitLab Geo 추적 데이터베이스가 올바르게 구성되었습니다 ... not a secondary node
Database replication enabled? ... not a secondary node
...
Geo 확인 완료

    기본 사이트의 Admin Area > Geo > Sites에서 보조 사이트를 추가했는지 확인하십시오. 또한 기본 사이트의 Admin Area에서 gitlab_rails['geo_node_name']을 입력하였는지 확인하십시오.

  • 조회가 Exception: PG::UndefinedTable: ERROR: relation "geo_nodes" does not exist로 반환됩니다. 

    Geo 확인 중 ...

GitLab Geo를 사용할 수 있습니다 ... no
  해결 방법:
  GitLab Geo 기능이 포함된 새 라이센스를 추가하십시오.
  자세한 정보: https://about.gitlab.com/features/gitlab-geo/
GitLab Geo가 활성화되었습니다 ... Exception: PG::UndefinedTable: ERROR:  relation "geo_nodes" does not exist
LINE 8:                WHERE a.attrelid = '"geo_nodes"'::regclass
                                           ^
:               SELECT a.attname, format_type(a.atttypid, a.atttypmod),
                     pg_get_expr(d.adbin, d.adrelid), a.attnotnull, a.atttypid, a.atttypmod,
                     c.collname, col_description(a.attrelid, a.attnum) AS comment
                FROM pg_attribute a
                LEFT JOIN pg_attrdef d ON a.attrelid = d.adrelid AND a.attnum = d.adnum
                LEFT JOIN pg_type t ON a.atttypid = t.oid
                LEFT JOIN pg_collation c ON a.attcollation = c.oid AND a.attcollation <> t.typcollation
               WHERE a.attrelid = '"geo_nodes"'::regclass
                 AND a.attnum > 0 AND NOT a.attisdropped
               ORDER BY a.attnum
...
Geo 확인 완료

    PostgreSQL 주 버전(9 > 10)으로 업데이트하는 동안이것이 예상 동작입니다. 복제 프로세스를 시작에 따릅니다.

  • Rails는 Geo 추적 데이터베이스에 연결할 필요한 구성이 없는 것으로 보입니다. 

    Geo 확인 중 ...

GitLab Geo를 사용할 수 있습니다 ... yes
GitLab Geo가 활성화되었습니다 ... yes
GitLab Geo 추적 데이터베이스가 올바르게 구성되었습니다 ... no
해결 방법:
Rails에 Geo 추적 데이터베이스에 연결할 필요한 구성이 없는 것으로 보입니다. 추적 데이터베이스가이 노드와 다른 노드에서 실행 중인 경우 구성을 추가해야할 수 있습니다.
...
Geo 확인 완료
메시지: 머신 시계가 동기화되었습니다 … Exception

Rake 작업은 서버 시계가 NTP와 동기화되어 있는지를 확인하려고 합니다. 동기화된 시계는 Geo가 올바르게 작동하기 위해 필요합니다. 예를 들어, 보안을 위해 기본 사이트와 보조 사이트의 서버 시간이 1분 이상 차이 나면 Geo 사이트 간의 요청이 실패합니다. 이 검사 작업이 시간 불일치 외의 이유로 완료되지 않으면 Geo가 작동하지 않을 수 있다는 의미는 아닙니다.

이 검사를 수행하는 Ruby gem은 참조 시간 원본으로 pool.ntp.org를 하드코딩했습니다.

  • Exception 메시지 머신 시계가 동기화됨... Exception: Timeout::Error

    이 문제는 서버가 pool.ntp.org 호스트에 액세스할 수 없을 때 발생합니다.

  • Exception 메시지 머신 시계가 동기화됨... Exception: No route to host - recvfrom(2)

    이 문제는 호스트 이름 pool.ntp.org가 시간 서비스를 제공하지 않는 서버로 해석될 때 발생합니다.

이 경우, GitLab 15.7 이상에서는 환경 변수를 사용하여 사용자 정의 NTP 서버를 지정하십시오.

GitLab 15.6 이전에서는 다음 해결책 중 하나를 사용하십시오:

  • /etc/hosts에 pool.ntp.org 항목 추가하여 요청을 유효한 로컬 시간 서버로 유도합니다. 이렇게 하면 긴 대기 시간과 시간 초과가 해결됩니다.
  • 확인을 유효한 IP 주소로 직접 지정합니다. 이렇게 하면 시간 초과 문제가 해결되지만 위에서 언급한대로 확인이 No route to host 오류로 실패합니다.

Cloud native GitLab 배포는 쿠버네티스의 컨테이너가 호스트 클럭에 액세스할 수 없기 때문에 오류가 발생합니다: 

머신 시계가 동기화됨... Exception: getaddrinfo: Servname not supported for ai_socktype
메시지: ActiveRecord::StatementInvalid: PG::ReadOnlySqlTransaction: ERROR: cannot execute INSERT in a read-only transaction

보조 사이트에서 이 오류가 발생하는 경우, 이는 gitlab-rails 또는 gitlab-rake 명령뿐만 아니라 Puma, Sidekiq 및 Geo Log Cursor 서비스의 모든 사용에 영향을 미칠 가능성이 높습니다. 

ActiveRecord::StatementInvalid: PG::ReadOnlySqlTransaction: ERROR:  cannot execute INSERT in a read-only transaction
/opt/gitlab/embedded/service/gitlab-rails/app/models/application_record.rb:86:in `block in safe_find_or_create_by'
/opt/gitlab/embedded/service/gitlab-rails/app/models/concerns/cross_database_modification.rb:92:in `block in transaction'
/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/database.rb:332:in `block in transaction'
/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/database.rb:331:in `transaction'
/opt/gitlab/embedded/service/gitlab-rails/app/models/concerns/cross_database_modification.rb:83:in `transaction'
/opt/gitlab/embedded/service/gitlab-rails/app/models/application_record.rb:86:in `safe_find_or_create_by'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:21:in `by_name'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `block in populate!'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `map'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `populate!'
/opt/gitlab/embedded/service/gitlab-rails/config/initializers/fill_shards.rb:9:in `<top (required)>'
/opt/gitlab/embedded/service/gitlab-rails/config/environment.rb:7:in `<top (required)>'
/opt/gitlab/embedded/bin/bundle:23:in `load'
/opt/gitlab/embedded/bin/bundle:23:in `<main>'

PostgreSQL 읽기 전용 레플리카 데이터베이스에서 이러한 오류가 발생할 수 있습니다. 

2023-01-17_17:44:54.64268 ERROR:  cannot execute INSERT in a read-only transaction
2023-01-17_17:44:54.64271 STATEMENT:  /*application:web,db_config_name:main*/ INSERT INTO "shards" ("name") VALUES ('storage1') RETURNING "id"

이 상황은 보조 사이트가 아직 자신이 보조 사이트임을 인식하지 못한 초기 구성 중에 발생할 수 있습니다.

이 오류를 해결하려면 단계 3. 보조 사이트 추가를 참조하십시오.

PostgreSQL 복제가 작동하는지 확인

PostgreSQL 복제가 작동하는지 확인하려면 다음을 확인하십시오:

올바른 데이터베이스 노드를 가리키고 있는 사이트는?

주 Geo 사이트가 쓰기 권한이 있는 데이터베이스 노드를 가리키도록 해야 합니다.

기타 보조 사이트는 읽기 전용 데이터베이스 노드만을 가리켜야 합니다.

Geo가 현재 사이트를 올바르게 탐지할 수 있나요?

Geo는 다음과 같은 로직으로 /etc/gitlab/gitlab.rb에서 Puma 또는 Sidekiq 노드의 Geo 사이트 이름을 찾습니다.

  1. “Geo 노드 이름” 가져오기 (설정을 “Geo 사이트 이름”으로 이름 바꾸기에 대한 이슈가 있습니다):
    • Linux 패키지: gitlab_rails['geo_node_name'] 설정 가져오기
    • GitLab 헬름 차트: global.geo.nodeName 설정 가져오기 (참조: GitLab Geo를 사용하는 차트)
  2. 만약 정의되어 있지 않다면, external_url 설정 가져오기

이 이름은 이름이 같은 Geo 사이트를 Geo 사이트 대시보드에서 찾을 때 사용됩니다.

현재 머신에 사이트 이름이 데이터베이스의 사이트와 일치하는지 확인하려면 다음 명령을 실행하세요: 

sudo gitlab-rake gitlab:geo:check

이 명령은 현재 머신의 사이트 이름과 일치하는 데이터베이스 레코드가 주인지 보조인지 보여줍니다. 

이 머신의 Geo 노드 이름이 "Shanghai"라는 이름의 보조 노드와 일치하는 데이터베이스 레코드를 찾았습니다... 예

이 머신의 Geo 노드 이름이 데이터베이스 레코드와 일치하지 않습니다... 아니요
  다음 단계를 시도하세요:
  "https://example.com/"라는 이름으로 Geo 노드 데이터베이스 레코드를 추가하거나 업데이트할 수 있습니다.
  또는 이 머신의 Geo 노드 이름을 기존 데이터베이스 레코드 "London", "Shanghai"의 이름과 일치하도록 설정할 수 있습니다.
  더 많은 정보는 다음을 참조하세요:
  doc/administration/geo/replication/troubleshooting.md#can-geo-detect-the-current-node-correctly

이름 필드 설명에서 권장하는 사이트 이름에 대한 자세한 정보는 Geo 관리 영역 공통 설정을 참조하세요.

OS 로캘 데이터 호환성 확인

여러 Geo 사이트에 다른 운영 체제 또는 다른 운영 체제 버전이 배포되어 있는 경우, Geo 설정을 하기 전에 로캘 데이터의 호환성을 반드시 확인해야 합니다.

Geo는 PostgreSQL과 스트리밍 복제를 사용하여 Geo 사이트 간에 데이터를 복제합니다. PostgreSQL은 텍스트 정렬을 위해 운영 체제의 C 라이브러리에서 제공하는 로캘 데이터를 사용합니다. C 라이브러리의 로캘 데이터가 Geo 사이트 전체에서 호환되지 않으면 부정확한 쿼리 결과로 이어져 보조 사이트에서 잘못된 동작이 발생합니다.

예를 들어, Ubuntu 18.04(이전 버전) 및 RHEL/Centos7(이전 버전)은 이후 버전과 호환되지 않습니다. 자세한 내용은 PostgreSQL 위키를 참조하세요.

모든 Geo 사이트에 걸쳐 PostgreSQL을 실행하는 모든 호스트에서 다음 셸 명령을 실행하세요: 

( echo "1-1"; echo "11" ) | LC_COLLATE=en_US.UTF-8 sort

출력은 다음과 같아야 합니다: 

1-1
11

또는 반대 순서일 수도 있습니다: 

11
1-1

모든 호스트에서 출력이 동일하면 호스트는 호환되는 버전의 로캘 데이터를 실행 중이며 Geo 설정을 진행할 수 있습니다.

어떤 호스트에서 출력이 다르면 PostgreSQL 복제가 올바르게 작동하지 않습니다: 데이터베이스 복제본의 인덱스가 손상됩니다. 호환되는 운영 체제 버전을 선택해야 합니다.

디스크상 데이터가 호환되지 않는 운영 체제로 전송되거나 복제를 통해 전송되면 전체 색인을 다시 작성해야 합니다.

이 확인은 Linux 패키지 설치, GitLab 도커 컨테이너, 헬름 차트 배포, 외부 데이터베이스 서비스 등을 혼합해서 사용할 때도 필요합니다.

PostgreSQL 데이터베이스 복제 오류 수정

다음 섹션에서는 거울 복제 출력에서 나타나는 복제 오류 메시지를 수정하는 문제 해결 단계를 설명합니다. 여기에 제시된 지침은 주로 단일 노드 Geo Linux 패키지 배포를 가정하고 있으며, 다른 환경에 맞게 수정해야 할 수도 있습니다.

비활성 복제 슬롯 제거

복제 슬롯은 복제 클라이언트(보조 사이트)가 해당 슬롯에 연결 해제할 때 “비활성”으로 표시됩니다. 비활성 복제 슬롯은 해당 슬롯을 사용하고 있지 않아도 월(WAL) 파일을 유지시킨 채로 두게 되며, 클라이언트가 다시 연결되면 슬롯이 다시 활성화됩니다. 만일 보조 사이트가 재연결할 수 없는 경우 해당 비활성 복제 슬롯을 제거하기 위해 다음 단계를 사용하세요:

  1. Geo 주 사이트의 데이터베이스 노드에서 PostgreSQL 콘솔 세션을 시작하세요: 

    sudo gitlab-psql -d gitlabhq_production

    참고: 복제 슬롯 관리는 수퍼 사용자 권한이 필요하기 때문에 gitlab-rails dbconsole 사용이 불가능합니다.

  2. 복제 슬롯을 보고 모든 비활성 슬롯을 제거하세요: 

    SELECT * FROM pg_replication_slots;

    active가 f인 슬롯은 비활성입니다.

    • 본 슬롯이 활성적이어야 하는 것은 해당 슬롯을 사용하는 보조 사이트가 구성되었기 때문입니다. 복제가 실행되지 않는 이유를 보기 위해 보조 사이트의 PostgreSQL 로그를 확인하세요.

    • 만일 해당 슬롯을 더 이상 사용하지 않거나(예: 더 이상 Geo를 사용하지 않는 경우), 보조 사이트가 다시 연결할 수 없는 경우, PostgreSQL 콘솔 세션에서 다음을 사용하여 제거하세요: 

      SELECT pg_drop_replication_slot('<비활성 슬롯 이름>');

  3. 더 이상 필요하지 않은 경우 그 Geo 사이트를 제거하거나, 더 이상 사용할 수 없는 경우 복제 프로세스를 다시 시작하여 복제 슬롯을 올바르게 다시 만들 수 있습니다.

메시지: 경고: 가장 오래된 xmin이 매우 옛날 데이터입니다 및 pg_wal 크기 증가

복제 슬롯이 비활성화된 경우 해당 슬롯에 해당하는 pg_wal 로그는 영원히 유지되거나 (또는 해당 슬롯이 다시 활성화 될 때까지) 예약됩니다. 이로 인해 지속적인 디스크 사용량 증가 및 다음과 같은 메시지가 PostgreSQL 로그에 반복적으로 나타납니다: 

경고: 가장 오래된 xmin이 매우 옛날 데이터입니다
힌트: 랩어라운드 문제를 피하기 위해 곧 열린 트랜잭션을 완료하세요.
또한 예전에 준비된 트랜잭션을 커밋하거나 롤백하거나 오래된 복제 슬롯을 삭제해야 할 수도 있습니다.

이를 수정하려면 비활성화된 복제 슬롯을 제거하고 복제를 다시 초기화해야 합니다.

메시지: 오류: 최대 복제 슬롯 > 0일 때만 사용할 수 있습니다?

이는 주 데이터베이스에서 max_replication_slots PostgreSQL 변수를 설정해야 한다는 것을 의미합니다. 이 설정의 기본값은 1입니다. 보조 사이트가 더 많은 경우 이 값을 증가해야 할 수 있습니다.

이를 적용하려면 PostgreSQL을 다시 시작해야 합니다. 자세한 내용은 PostgreSQL 복제 설정 가이드를 참조하세요.

메시지: 심각: WAL 스트리밍을 시작할 수 없습니다: 오류: 복제 슬롯 "geo_secondary_my_domain_com"이(가) 없습니다?

이는 PostgreSQL이 해당 이름의 보조 사이트에 대한 복제 슬롯을 보유하지 않을 때 발생합니다.

보조 사이트에서 복제 프로세스를 다시 실행할 수 있습니다.

메시지: 복제 설정 시 “명령이 허용된 실행 시간을 초과했습니다”?

이는 기본 실행 시간 제한(30분) 내에 복제할 데이터가 너무 많아 초기 데이터 집합을 설정하는 동안 발생할 수 있습니다.

gitlab-ctl replicate-geo-database을 다시 실행하되 --backup-timeout에 더 큰 값(예: 21600)을 포함하세요: 

sudo gitlab-ctl \
   replicate-geo-database \
   --host=<primary_node_hostname> \
   --slot-name=<secondary_slot_name> \
   --backup-timeout=21600

기본 30분이 아닌 최대 6시간 동안 초기 복제를 수행하도록 설정합니다. 설치에 따라 필요에 맞게 조정하세요.

메시지: “파일 pg_xlog/xlogtemp.123에 쓸 수 없음: 장치에 여유 공간이 충분하지 않음”

주 데이터베이스에서 사용되지 않는 복제 슬롯이 있는지 확인하세요. 이로 인해 pg_xlog에 대규모 로그 데이터가 축적될 수 있습니다.

비활성 상태의 슬롯을 제거하여 pg_xlog에서 사용된 공간을 줄일 수 있습니다.

메시지: “오류: 복구와 충돌로 인해 명령을 취소함”

이 오류 메시지는 일반적인 사용에서는 드물게 발생하며 시스템은 복구할 수 있는 충분한 유연성을 갖추고 있습니다.

그러나 특정 조건에서 보조에서 일부 데이터베이스 쿼리가 과도하게 오래 실행되어 해당 오류 메시지가 더 자주 발생할 수 있습니다. 이는 일부 쿼리가 복제마다 취소되어 실행되지 못할 수 있는 상황을 초래할 수 있습니다.

이러한 오래 실행되는 쿼리는 향후 제거될 예정입니다만, 현재의 해결책으로는 hot_standby_feedback를 활성화하는 것을 권장합니다. 이는 VACUUM이 최근에 소멸된 행을 제거하지 못하게 하는 주 사이트의 부풀음 가능성을 증가시키므로 주의가 필요합니다. 그러나 GitLab.com에서 성공적으로 사용되었습니다.

hot_standby_feedback를 활성화하려면 보조 사이트의 /etc/gitlab/gitlab.rb에 다음을 추가하세요: 

postgresql['hot_standby_feedback'] = 'on'

그런 다음 GitLab을 재구성하세요: 

sudo gitlab-ctl reconfigure

이 문제를 해결하는 데 도움을 주시려면 이 문제에 의견을 남기십시오.

메시지: 심각: 기본 서버에 연결할 수 없음: "PostgreSQL"의 서버 인증서와 호스트 이름이 일치하지 않음

이는 리눅스 패키지가 자동으로 생성하는 PostgreSQL 인증서에 공통 이름인 PostgreSQL이 포함되어 있지만 복제가 다른 호스트에 연결하고 GitLab이 기본적으로 verify-full SSL 모드를 사용하려고 시도할 때 발생합니다.

이 문제를 해결하려면 다음 중 하나를 선택하실 수 있습니다:

  • replicate-geo-database 명령과 함께 --sslmode=verify-ca 인수를 사용합니다.
  • 이미 복제된 데이터베이스의 경우 /var/opt/gitlab/postgresql/data/gitlab-geo.conf에서 sslmode=verify-full을 sslmode=verify-ca로 변경하고 gitlab-ctl restart postgresql을 실행합니다.
  • 자동으로 생성된 인증서 대신에 호스트 이름이 CN 또는 SAN으로 사용된 사용자 정의 인증서와 함께 PostgreSQL용 SSL 구성을 설정합니다.

메시지: LOG: 주소에서 잘못된 CIDR 마스크

이것은 postgresql['md5_auth_cidr_addresses']에서 잘못된 형식의 주소에서 발생합니다. 

2020-03-20_23:59:57.60499 LOG: 주소 "***"에 잘못된 CIDR 마스크
2020-03-20_23:59:57.60501 CONTEXT: 설정 파일 "/var/opt/gitlab/postgresql/data/pg_hba.conf"의 74번째 줄

이 문제를 해결하려면 /etc/gitlab/gitlab.rb의 postgresql['md5_auth_cidr_addresses']에 있는 IP 주소를 CIDR 형식(예: 10.0.0.1/32)으로 업데이트하세요.

메시지: LOG: 잘못된 IP 마스크 "md5": 이름 또는 서비스를 알 수 없음

이것은 postgresql['md5_auth_cidr_addresses']에 서브넷 마스크 없이 IP 주소를 추가한 경우 발생합니다. 

2020-03-21_00:23:01.97353 LOG:  잘못된 IP 마스크 "md5": 이름 또는 서비스를 알 수 없음
2020-03-21_00:23:01.97354 CONTEXT: 설정 파일 "/var/opt/gitlab/postgresql/data/pg_hba.conf"의 75번째 줄

이 문제를 해결하려면 /etc/gitlab/gitlab.rb에 있는 postgresql['md5_auth_cidr_addresses']에 서브넷 마스크를 추가하여 CIDR 형식(예: 10.0.0.1/32)을 준수하세요.

메시지: gitlab-ctl replicate-geo-database 실행 중 gitlabhq_production 데이터 발견됨

이것은 projects 테이블에서 데이터가 감지된 경우 발생합니다. 하나 이상의 프로젝트가 감지되면 우연한 데이터 손실을 방지하기 위해 작업이 중단됩니다. 이 메시지를 우회하려면 명령에 --force 옵션을 전달하세요.

GitLab 13.4에서 GitLab이 처음 설치될 때 시드 프로젝트가 추가됩니다. 따라서 새로운 지오 보조 사이트에서도 --force를 전달해야 합니다. 데이터베이스 확인 시 시드 프로젝트를 고려하는 이슈가 있습니다.

메시지: FATAL: 익명 공유 메모리 매핑할 수 없음: 메모리를 할당할 수 없음

이 메시지가 표시되면, 이는 보조 사이트의 PostgreSQL이 사용 가능한 메모리보다 높은 메모리를 요청하려고 시도한 것입니다. 이 문제를 추적하는 이슈가 있습니다.

Linux 패키지 설치의 경우 /var/log/gitlab/patroni/current에 있는 Patroni 로그에서 예시 오류 메시지를 확인할 수 있습니다: 

2023-11-21_23:55:18.63727 FATAL:  익명 공유 메모리 매핑할 수 없음: 메모리를 할당할 수 없음
2023-11-21_23:55:18.63729 HINT:  이 오류는 일반적으로 PostgreSQL의 공유 메모리 세그먼트 요청이 사용 가능한 메모리, 스왑 공간 또는 대형 페이지를 초과했을 때 발생합니다. 요청 크기(현재 17035526144 바이트)를 줄이려면 shared_buffers나 max_connections를 줄이는 등 PostgreSQL의 공유 메모리 사용량을 줄입니다.

해결책은 보조 사이트의 PostgreSQL 노드에서 사용 가능한 메모리를 주요 사이트의 PostgreSQL 노드의 메모리 요구 사항과 일치하도록 증가시키는 것입니다.

동기화 오류

모든 업로드 재확인(또는 확인된 SSF 데이터 유형)

  1. 주요 지오 사이트의 GitLab 레일 노드에 SSH로 로그인합니다.
  2. 레일 콘솔을 엽니다.
  3. 모든 업로드를 “확인 대기”로 표시합니다:

경고: 데이터를 변경하는 명령은 올바르게 실행되지 않거나 올바른 조건 하에서 실행되지 않을 경우에 손상을 줄 수 있습니다. 항상 먼저 테스트 환경에서 명령을 실행하고 복원할 수 있는 백업 인스턴스가 준비되어 있어야 합니다. 

   Upload.verification_state_table_class.each_batch do |relation|
     relation.update_all(verification_state: 0)
   end
  1. 이렇게 하면 주요 사이트가 모든 업로드를 체크섬하는 작업이 시작됩니다.
  2. 주요 사이트가 레코드의 체크섬을 성공적으로 만들면 모든 보조 사이트가 체크섬을 재계산하고 그 값을 비교합니다.

동일한 작업을 Geo Self-Service Framework에서 처리하는 모델과 함께 수행할 수 있습니다:

  • LfsObject
  • MergeRequestDiff
  • Packages::PackageFile
  • Terraform::StateVersion
  • SnippetRepository
  • Ci::PipelineArtifact
  • PagesDeployment
  • Upload
  • Ci::JobArtifact
  • Ci::SecureFile

참고: GroupWikiRepository는 확인이 구현되지 않았기 때문에 이전 목록에 없습니다. 관리자 영역 UI에서 이 기능을 구현하기 위한 이슈가 있습니다.

메시지: 동기화 실패 - 저장소 동기화 오류

경고: 대형 저장소가 이 문제의 영향을 받는 경우 재동기화에는 오랜 시간이 소요되며 Geo 사이트, 저장 및 네트워크 시스템에 상당한 부하를 일으킬 수 있습니다.

저장소를 동기화하는 중 일관성 검사 오류가 발생했음을 나타내는 다음 오류 메시지: 

동기화 실패 - 저장소 동기화 오류 [..] fatal: 패키지된 개체의 fsck 오류

이 오류를 유발하는 여러 가지 문제가 있을 수 있습니다. 예를 들어, 이메일 주소와 관련된 문제: 

저장소 동기화 오류: 13:fetch 원격: "error: object <SHA>: badEmail: 유효하지 않은 작성자/커미터 라인 - 잘못된 이메일
   fatal: 패키지된 개체의 fsck 오류
   fatal: fetch-pack: 잘못된 인덱스 팩 출력

이 오류를 유발할 수 있는 다른 문제는 object <SHA>: hasDotgit: '.git'을 포함입니다. 모든 저장소에 걸쳐 하나 이상의 문제가 있을 수 있으므로 구체적인 오류를 확인하세요.

두 번째 동기화 오류는 저장소 확인 문제로 인해 발생할 수도 있습니다: 

저장소 동기화 오류: 13:Received RST_STREAM with error code 2.

이러한 오류는 즉시 실패한 모든 저장소를 동기화하여 확인할 수 있습니다.

일관성 오류를 일으키는 부적절한 개체를 제거하기 위해서는 일반적으로 저장소 히스토리를 다시 작성해야 합니다. 이는 일반적으로 선택할 수 없는 옵션입니다.

이러한 일관성 검사를 무시하려면 Gitaly를 secondary Geo 사이트에서 이러한 git fsck 문제를 무시하도록 다시 구성하세요. 다음 구성 예시:

Gitaly 문서에는 자세한 내용이 포함되어 있으며 다른 Git 검사 오류 및 GitLab 이전 버전에 대해 설명합니다. 

gitaly['configuration'] = {
  git: {
    config: [
      { key: "fsck.duplicateEntries", value: "ignore" },
      { key: "fsck.badFilemode", value: "ignore" },
      { key: "fsck.missingEmail", value: "ignore" },
      { key: "fsck.badEmail", value: "ignore" },
      { key: "fsck.hasDotgit", value: "ignore" },
      { key: "fetch.fsck.duplicateEntries", value: "ignore" },
      { key: "fetch.fsck.badFilemode", value: "ignore" },
      { key: "fetch.fsck.missingEmail", value: "ignore" },
      { key: "fetch.fsck.badEmail", value: "ignore" },
      { key: "fetch.fsck.hasDotgit", value: "ignore" },
      { key: "receive.fsck.duplicateEntries", value: "ignore" },
      { key: "receive.fsck.badFilemode", value: "ignore" },
      { key: "receive.fsck.missingEmail", value: "ignore" },
      { key: "receive.fsck.badEmail", value: "ignore" },
      { key: "receive.fsck.hasDotgit", value: "ignore" },
    ],
  },
}

GitLab 16.1 이상에는 일부 이러한 문제를 해결할 수 있는 향상이 포함되어 있습니다.

Gitaly issue 5625는 문제가 있는 커밋이 포함된 소스 저장소를 Geo가 동기화하도록 보장하는 제안을 합니다.

관련 오류 git 저장소가 아닌 것으로 보입니다

또한 다음과 같은 로그 메시지와 함께 동기화 실패 - 저장소 동기화 오류 오류 메시지를 받을 수 있습니다. 이 오류는 기대되는 Geo 원격이 보조 Geo 사이트의 파일 시스템에있는 .git/config 파일에 존재하지 않음을 나타냅니다: 

{
  "created": "@1603481145.084348757",
  "description": "Error received from peer unix:/var/opt/gitlab/gitaly/gitaly.socket",
  …
  "grpc_message": "exit status 128",
  "grpc_status": 13
}
{  …
  "grpc.request.fullMethod": "/gitaly.RemoteService/FindRemoteRootRef",
  "grpc.request.glProjectPath": "<namespace>/<project>",
  …
  "level": "error",
  "msg": "fatal: 'geo' git 저장소가 아닌 것으로 보입니다
          fatal: 원격 저장소에서 읽을 수 없습니다. …",
}

해결 방법:

  1. 보조 Geo 사이트의 웹 인터페이스에 서명합니다.

  2. .git 폴더를 백업합니다.

  3. 선택 사항. 몇 가지 ID를 검토하여 관련된 프로젝트인지 확인합니다. fatal: 'geo'를 grep 용어로 사용하고 다음 API 호출을 사용합니다: 

    curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<first_failed_geo_sync_ID>"

  4. 레일 콘솔에 들어가 다음을 실행합니다: 

    failed_geo_syncs = Geo::ProjectRegistry.failed.pluck(:id)
failed_geo_syncs.each do |fgs|
  puts Geo::ProjectRegistry.failed.find(fgs).project_id
end

  5. 각 프로젝트의 Geo 관련 속성을 재설정하고 새로운 동기화를 실행하는 다음 명령을 실행합니다: 

    failed_geo_syncs.each do |fgs|
  registry = Geo::ProjectRegistry.failed.find(fgs)
  registry.update(resync_repository: true, force_to_redownload_repository: false, repository_retry_count: 0)
  Geo::RepositorySyncService.new(registry.project).execute
end

    -::-

백필 중 실패

백필(backfill) 중에는 실패한 항목이 백필 대기열의 끝에 다시 시도되기 때문에, 이러한 실패 사항들은 백필이 완료된 후에만 해결됩니다.

동기화 실패 메시지: “검증이 다음으로 실패했습니다: 검증 중 오류: 파일이 체크섬을 생성할 수 없음”

Geo 기본 사이트에 누락된 파일

GitLab 14.5 이전에는, Geo 기본 사이트에서 누락된 특정 데이터 유형은 Geo 보조 사이트에서 “동기화됨”으로 표시되었습니다. 이는 Geo 보조 사이트의 관점에서는 상태가 기본 사이트와 일치하고 보조 사이트에서 더 이상 진행할 수 있는 것이 없다는 것 때문입니다.

보조 사이트는 이러한 파일을 “검증” 기능을 사용하여 정기적으로 다시 동기화 시도했습니다.

  • 파일이 존재하지 않아 검증에 실패합니다.
  • 파일이 “동기화 실패”로 표시됩니다.
  • 동기화가 다시 시도됩니다.
  • 파일이 “동기화 성공”으로 표시됩니다.
  • 파일이 “검증 필요”로 표시됩니다.
  • 파일이 다시 기본 사이트에서 사용 가능해질 때까지 반복합니다.

백그라운드 작업에 의해 레지스트리 항목은 논리적인 루프를 통해 이동하기 때문에 문제 해결이 혼란스러울 수 있습니다. 또한 last_sync_failure와 verification_failure는 “동기화 성공” 후에 검증이 다시 시도되기 전에 비어 있습니다.

동기화 실패가 반복적으로 발생하고 번갈아 증가하면서 성공은 감소하고 그 반대의 경우에는 이는 기본 사이트에서 파일이 누락되었을 가능성이 높습니다. 이를 확인하려면 동일한 파일에 영향을 미치는 File is not checksummable를 위해 보조 사이트의 geo.log를 검색할 수 있습니다.

이 문제를 확인한 후에는 기본 사이트의 파일을 수정해야 합니다. 몇 가지 가능한 원인은:

  • NFS 공유가 마운트 해제됨.
  • 디스크가 손상되었거나 깨졌음.
  • 누군가 실수로 파일이나 디렉토리를 삭제함.
  • GitLab 응용 프로그램의 버그:
    • 파일이 움직여지지 말아야 할 때 파일이 움직입니다.
    • 파일이 움직여져야 할 때 파일이 움직이지 않습니다.
    • 코드에서 잘못된 경로가 생성됨.
  • 비 원자적 백업이 복원됨.
  • 서비스 또는 서버 또는 네트워크 인프라가 사용 중에 중단/재시작됨.

적절한 조치는 때때로 원인에 따라 다를 수 있습니다. 예를 들어, NFS 공유를 다시 마운트할 수 있습니다. 종종 원인이 명확하지 않거나 발견할 가치가 없을 수 있습니다. 정기적인 백업이 있는 경우, 그것을 살펴보고 거기서 파일을 가져오는 것이 빠를 수 있습니다.

일부 경우에는 파일이 낮은 가치로 판명되어 레코드를 삭제하는 것이 좋을 수 있습니다.

Geo 자체는 기본 사이트에서 누락된 파일에 대한 우수한 완화책입니다. 기본 사이트에서 파일이 사라지지만 이미 보조 사이트로 동기화된 경우, 보조 사이트의 파일을 가져올 수 있습니다. 이러한 경우에는 File is not checksummable 오류 메시지가 Geo 보조 사이트에서 발생하지 않으며, 기본 사이트만이 이 오류 메시지를 기록합니다.

이 문제는 원본 GitLab 사이트보다 오랜 시간이 지난 후에 설정된 Geo 보조 사이트에서 더 자주 발생할 수 있습니다. 이러한 경우에는 Geo가 기존 문제를 이미 노출하기 때문입니다.

이 동작은 GitLab 14.6에서 다음과 같은 데이터 유형에만 영향을 미칩니다:

데이터 유형 버전
패키지 레지스트리 13.10
CI 파이프라인 아티팩트 13.11
Terraform 상태 버전 13.12
인프라 레지스트리 (GitLab 15.11부터 Terraform 모듈 레지스트리로 이름 변경) 14.0
외부 MR 차이 14.6
LFS 객체 14.6
페이지 배포 14.6
업로드 14.6
CI 작업 아티팩트 14.6

GitLab 14.7부터는 기본 사이트에서 누락된 파일은 이제 동기화 실패로 처리됩니다 이로써 Geo가 데이터 손실 위험을 시각적으로 노출시킵니다. 따라서 동기화/검증 루프는 단축됩니다. last_sync_failure는 이제 The file is missing on the Geo primary site로 설정됩니다.

GitLab 관리 객체 저장소 복제 실패

GitLab 14.2에서 14.7까지 문제가 발생하여 GitLab 관리 객체 저장소 복제가 사용될 때 Geo에 영향을 미치며, blob 객체 유형이 동기화에 실패합니다.

GitLab 14.2부터 검증 실패로 인해 동기화 실패가 발생하고 이러한 객체들의 재동기화를 유발합니다.

파일 저장소에 저장된 파일에 대해 검증이 구현되지 않았기 때문에 이로 인해 객체 저장소에 저장된 모든 객체에 대해 일관적으로 실패하는 루프가 발생합니다.

이를 해결하는 방법은 객체를 동기화되었고 검증이 성공했다고 표시하는 것입니다. 그러나 이는 또한 기본 사이트에서 누락된 객체도 표시할 수 있다는 점에 유의하세요.

이를 수행하려면, 레일즈 콘솔에 들어가고 다음을 실행하세요: 

Gitlab::Geo.verification_enabled_replicator_classes.each do |klass|
  updated = klass.registry_class.failed.where(last_sync_failure: "Verification failed with: Error during verification: File is not checksummable").update_all(verification_checksum: '0000000000000000000000000000000000000000', verification_state: 2, verification_failure: nil, verification_retry_at: nil, state: 2, last_sync_failure: nil, retry_at: nil, verification_retry_count: 0, retry_count: 0)
  pp "Updated #{updated} #{klass.replicable_name_plural}"
end

메시지: curl 18 전송이 남은 읽기 데이터를 가진 채로 닫혔으며 fetch-pack: 사이드밴드 패킷을 읽는 동안 예기치 않은 연결 해제가 발생했습니다.

불안정한 네트워크 환경은 Gitaly가 기본 사이트로부터 대량의 저장소 데이터를 가져 오려고 시도할 때 실패할 수 있습니다. 저장소가 사이트 간에 처음부터 복제되어야 하는 경우 더 자주 발생할 수 있습니다.

Geo는 여러 번 재시도하지만 네트워크 속닥거림으로 전송이 계속 중단되는 경우 “rsync”와 같은 대체 방법을 사용하여 git을 우회하고 복제되지 못한 모든 저장소의 초기 사본을 만들 수 있습니다.

각 실패한 저장소를 별도로 전송하고 각 전송 후 일관성을 확인하는 것을 권장합니다. 단일 대상 rsync 지침을 따라 기본 사이트에서 영향을 받는 각 저장소를 보조 사이트로 전송하십시오.

프로젝트 또는 프로젝트 위키 저장소

저장소 확인 실패 찾기

더 많은 정보를 수집하기 위해 보조 Geo 사이트에서 Rails 콘솔 세션을 시작하세요.

경고: 데이터를 변경하는 명령은 올바르게 실행되지 않거나 올바른 조건에서 실행되지 않으면 손해를 입힐 수 있습니다. 명령을 항상 먼저 테스트 환경에서 실행하고 복구할 수 있는 백업 인스턴스를 준비하세요.

확인된 실패 저장소의 수 가져오기 
Geo::ProjectRegistry.verification_failed('repository').count
확인된 실패 저장소 찾기 
Geo::ProjectRegistry.verification_failed('repository')
동기화에 실패한 저장소 찾기 
Geo::ProjectRegistry.sync_failed('repository')

프로젝트 및 프로젝트 위키 저장소 재동기화

다음 변경 사항을 수행하기 위해 보조 Geo 사이트에서 Rails 콘솔 세션을 시작하세요.

경고: 데이터를 변경하는 명령은 올바르게 실행되지 않거나 올바른 조건에서 실행되지 않으면 손해를 입힐 수 있습니다. 명령을 항상 먼저 테스트 환경에서 실행하고 복구할 수 있는 백업 인스턴스를 준비하세요.

모든 저장소를 재동기화 대기열로 지정

이렇게 하면 동기화가 Sidekiq에서 백그라운드로 처리됩니다. 

Geo::ProjectRegistry.update_all(resync_repository: true, resync_wiki: true)
지금 개별 저장소 동기화 
project = Project.find_by_full_path('<group/project>')

Geo::RepositorySyncService.new(project).execute
지금 모든 실패한 저장소 동기화

다음 스크립트는 다음 작업을 수행합니다:

  • 현재 실패한 저장소를 모두 루프 처리합니다.
  • 프로젝트 세부 정보와 마지막 실패 이유를 표시합니다.
  • 저장소를 재동기화하려고 시도합니다.
  • 오류가 발생하면 오류 이유를 보고합니다.
  • 완료되기까지 시간이 걸릴 수 있습니다. 각 저장소 확인이 완료되어야 결과를 보고합니다. 세션이 시간 초과되면 screen 세션을 시작하거나 Rails runner 및 nohup를 사용하여 프로세스가 계속 실행 될 수 있도록 조치하세요. 
Geo::ProjectRegistry.sync_failed('repository').find_each do |p|
   begin
     project = p.project
     puts "#{project.full_path} | id: #{p.project_id} | last error: '#{p.last_repository_sync_failure}'"
     Geo::RepositorySyncService.new(project).execute
   rescue => e
     puts "ID: #{p.project_id} failed: '#{e}'", e.backtrace.join("\n")
   end
end ; nil

Geo 보조 사이트에서 저장소 확인 실패 찾기

모든 프로젝트에 대해 활성화가 되면, 저장소 확인은 Geo 보조 사이트에서도 수행됩니다. 메타데이터는 Geo 추적 데이터베이스에 저장됩니다.

Geo 보조 사이트의 저장소 확인 실패는 반드시 복제 문제를 나타내지는 않습니다. 이러한 실패를 해결하기 위한 일반적인 접근 방식은 다음과 같습니다.

  1. 아래에서 언급된 영향을 받는 저장소를 찾을 때와 기록된 오류를 찾습니다.
  2. 특정 git fsck 오류를 진단해 보세요. 가능한 오류 범위는 넓으니 검색 엔진에 입력해 보세요.
  3. 영향을 받는 저장소의 일반 기능을 테스트합니다. 보조에서 풀을 받고 파일을 보세요.
  4. 기본 사이트의 저장소 사본이 동일한 git fsck 오류를 가지고 있는지 확인하세요. 장애 조치를 계획 중이라면, 기본 사이트와 동일한 정보를 보조 사이트가 가지고 있는 것을 우선 고려하세요. 기본 사이트의 백업을 보유하고 계획된 장애 조치 지침을 따르세요.
  5. 기본 사이트로 푸시하고 변경 사항이 보조 사이트에 복제되는지 확인하세요.
  6. 복제가 자동으로 작동하지 않으면 저장소를 수동으로 동기화해 보세요.

Start a Rails console session 으로 다음 기본적인 문제 해결 단계를 수행하세요.

경고: 데이터를 변경하는 명령은 올바르게 실행되지 않거나 올바른 조건에서 실행되지 않으면 손해를 입힐 수 있습니다. 명령을 항상 테스트 환경에서 실행하고 복구할 준비가 될 수 있는 백업 인스턴스를 가지세요.

repository check 실패한 저장소 수 가져오기 

Geo::ProjectRegistry.where(last_repository_check_failed: true).count

repository check 실패한 저장소 찾기 

Geo::ProjectRegistry.where(last_repository_check_failed: true)

repository check 실패한 저장소 다시 확인하기

이 명령을 실행하면 각 실패한 저장소에 대해 fsck가 실행됩니다.

다른 사이트에서 fsck 레이크 명령어를 사용하여 저장소 확인이 실패한 이유를 이해할 수 있습니다. 

Geo::ProjectRegistry.where(last_repository_check_failed: true).each do |pr|
    RepositoryCheck::SingleRepositoryWorker.new.perform(pr.project_id)
end

PostgreSQL 복제 실패 수정하기

Admin > Geo > Sites 또는 Sync status Rake task에서 복제 실패를 발견하면 다음과 같은 일반적인 단계로 해결할 수 있습니다:

  1. Geo는 실패를 자동으로 재시도합니다. 실패가 새로 발생하고 개수가 적거나 루트 원인이 이미 해결된 것으로 의심된다면 실패가 사라지기를 기다릴 수 있습니다.
  2. 실패가 장기간 발생한 경우 이미 많은 재시도가 진행되었으며 실패 유형에 따라 자동 재시도 간격이 최대 4시간까지 증가했습니다. 루트 원인이 이미 해결되었다고 의심된다면 복제 또는 확인을 수동으로 다시 시도할 수 있습니다.
  3. 실패가 지속되면 다음 섹션을 사용하여 이를 해결할 수 있습니다.

복제 또는 확인을 수동으로 다시 시도

Geo 데이터 유형은 하나 이상의 GitLab 기능에서 관련 정보를 저장하는 데 필요한 특정 데이터 클래스입니다. 이 데이터는 Geo에 의해 보조 사이트로 복제됩니다.

다음과 같은 Geo 데이터 유형이 있습니다:

  • Blob 유형:
    • Ci::JobArtifact
    • Ci::PipelineArtifact
    • Ci::SecureFile
    • LfsObject
    • MergeRequestDiff
    • Packages::PackageFile
    • PagesDeployment
    • Terraform::StateVersion
    • Upload
    • DependencyProxy::Manifest
    • DependencyProxy::Blob
  • 저장소 유형:
    • ContainerRepositoryRegistry
    • DesignManagement::Repository
    • ProjectRepository
    • ProjectWikiRepository
    • SnippetRepository
    • GroupWikiRepository

주요 클래스 유형은 Registry, Model 및 Replicator입니다. 이러한 클래스의 인스턴스가 있는 경우 다른 클래스를 가져올 수 있습니다. Registry와 Model은 대부분 PostgreSQL DB 상태를 관리합니다. Replicator는 복제/확인하는 방법을 알고 있거나 서비스를 호출하여 이를 수행할 수 있습니다: 

model_record = Packages::PackageFile.last
model_record.replicator.registry.replicator.model_record # 이 메서드들이 존재함을 보여주는 것뿐

이 모든 정보를 사용하여 다음을 수행할 수 있습니다:

개별 구성 요소의 수동으로 동기화 및 재확인

UI를 사용하여 자체 서비스 프레임워크에서 관리하는 모든 구성 요소 유형에 대해 개별 항목의 동기화 및 재확인을 강제로 실행할 수 있습니다. 보조 사이트에서 Admin > Geo > Replication으로 이동하세요.

그러나 이것이 도움이 되지 않는 경우 Rails 콘솔을 사용하여 동일한 작업을 수행할 수 있습니다. 다음 섹션에서는 내부 응용 프로그램 명령을 사용하여 개별 레코드의 동기화 또는 확인을 동기적 또는 비동기적으로 유발하는 방법에 대해 설명합니다.

경고: 데이터를 변경하는 명령은 올바르게 실행되지 않거나 올바른 조건에서 실행되지 않으면 손상을 일으킬 수 있습니다. 항상 먼저 테스트 환경에서 명령을 실행하고 복원할 백업 인스턴스를 준비하세요.

Rails 콘솔 세션을 시작하여 다음 기본적인 문제 해결 단계를 활용할 수 있습니다:

  • Blob 유형에 대해

    • 동기화에 실패한 registry 레코드 찾기: 

      Geo::PackageFileRegistry.failed

    • 기본 사이트에서 누락된 registry 레코드 찾기: 

      Geo::PackageFileRegistry.where(last_sync_failure: 'The file is missing on the Geo primary site')

    • ID가 주어지면 패키지 파일을 동기적으로 다시 동기화: 

      model_record = Packages::PackageFile.find(id)
model_record.replicator.send(:download)

    • 레지스트리 ID가 주어지면 패키지 파일을 동기적으로 다시 동기화: 

      registry = Geo::PackageFileRegistry.find(registry_id)
registry.replicator.send(:download)

    • 레지스트리 ID가 주어지면 패키지 파일을 비동기적으로 다시 동기화. GitLab 16.2부터 컴포넌트는 다음과 같이 비동기적으로 복제될 수 있습니다: 

      registry = Geo::PackageFileRegistry.find(registry_id)
registry.replicator.enqueue_sync

    • 레지스트리 ID가 주어지면 패키지 파일을 비동기적으로 다시 확인. GitLab 16.2부터 컴포넌트는 다음과 같이 비동기적으로 확인될 수 있습니다: 

      registry = Geo::PackageFileRegistry.find(registry_id)
registry.replicator.verify_async

  • 저장소 유형에 대해

    • ID가 주어지면 스니펫 저장소를 동기적으로 다시 동기화: 

      model_record = Geo::SnippetRepositoryRegistry.find(id)
model_record.replicator.sync_repository

    • 레지스트리 ID가 주어지면 스니펫 저장소를 동기적으로 다시 동기화: 

      registry = Geo::SnippetRepositoryRegistry.find(registry_id)
registry.replicator.sync_repository

    • 레지스트리 ID가 주어지면 스니펫 저장소를 비동기적으로 다시 동기화. GitLab 16.2부터 컴포넌트는 다음과 같이 비동기적으로 복제될 수 있습니다: 

      registry = Geo::SnippetRepositoryRegistry.find(registry_id)
registry.replicator.enqueue_sync

    • 레지스트리 ID가 주어지면 스니펫 저장소를 비동기적으로 다시 확인. GitLab 16.2부터 컴포넌트는 다음과 같이 비동기적으로 확인될 수 있습니다: 

      registry = Geo::SnippetRepositoryRegistry.find(registry_id)
registry.replicator.verify_async

여러 구성 요소를 다시 동기화하고 다시 확인

참고: 이 기능을 관리자 영역 UI에 구현하는 문제가 있습니다.

경고: 데이터를 변경할 수 있는 명령은 올바르게 실행되지 않거나 올바른 조건에서 실행되지 않으면 손상을 줄 수 있습니다. 항상 명령을 먼저 테스트 환경에서 실행하고 복원할 준비가 된 백업 인스턴스를 보관하세요.

다음 섹션에서는 내부 애플리케이션 명령을 레일즈 콘솔을 사용하여 대량 복제 또는 확인하는 방법을 설명합니다.

모든 구성 요소 다시 확인(또는 확인을 지원하는 모든 SSF 데이터 유형)

GitLab 16.4 및 이전 버전의 경우:

  1. 기본 Geo 사이트의 GitLab 레일스 노드에 SSH로 로그인합니다.
  2. 레일즈 콘솔을 엽니다.

  3. 모든 업로드를 대기 중인 확인으로 표시합니다: 

    Upload.verification_state_table_class.each_batch do |relation|
  relation.update_all(verification_state: 0)
end
  4. 이로 인해 기본이 모든 업로드의 체크섬을 시작합니다.
  5. 기본이 레코드의 체크섬을 성공적으로 체크하면 모든 이차 사본도 체크섬을 다시 계산하고 값들을 비교합니다.

다른 SSF 데이터 유형의 경우 위의 명령에서 Upload를 원하는 모델 클래스로 바꿉니다.

이차 사본에서 blob 파일 확인 수동으로 실행

이 명령은 이차 사본의 모든 패키지 파일을 반복하여 데이터베이스에 저장된 verification_checksum(기본값)을 살펴보고 이 값을 이차 사본에서 계산하여 일치하는 지 확인합니다. 이는 UI에서 아무것도 변경하지 않습니다.

GitLab 14.4 및 이후 버전의 경우: 

# 이차 사이트에서 실행
status = {}

Packages::PackageFile.find_each do |package_file|
  primary_checksum = package_file.verification_checksum
  secondary_checksum = Packages::PackageFile.sha256_hexdigest(package_file.file.path)
  verification_status = (primary_checksum == secondary_checksum)

  status[verification_status.to_s] ||= []
  status[verification_status.to_s] << package_file.id
end

# 각 값을 얼마나 얻는지 계산
status.keys.each {|key| puts "#{key} count: #{status[key].count}"}

# 전체 결과 확인
status

GitLab 14.3 및 이전 버전의 경우: 

# 이차 사이트에서 실행
status = {}

Packages::PackageFile.find_each do |package_file|
  primary_checksum = package_file.verification_checksum
  secondary_checksum = Packages::PackageFile.hexdigest(package_file.file.path)
  verification_status = (primary_checksum == secondary_checksum)

  status[verification_status.to_s] ||= []
  status[verification_status.to_s] << package_file.id
end

# 각 값을 얼마나 얻는지 계산
status.keys.each {|key| puts "#{key} count: #{status[key].count}"}

# 전체 결과 확인
status

기본 Geo 사이트에서 업로드의 확인 실패

기본 Geo 사이트에서 verification_checksum = nil 및 verification_failure = Error during verification: undefined method 'underscore' for NilClass:Class와 함께 일부 업로드의 확인이 실패하는 경우, 이는 고아 업로드 때문일 수 있습니다. 업로드(업로드 모델을 소유하는 부모 레코드)를 소유한 부모 레코드가 어떤 이유로인지 삭제되었지만 업로드 레코드는 여전히 존재하는 경우입니다. 이러한 확인 실패는 잘못된 것입니다.

기본 Geo 사이트의 geo.log 파일에서 이러한 오류를 찾을 수 있습니다.

모델 레코드가 누락되었는지 확인하려면 기본 Geo 사이트에서 다음 Rake 작업을 실행할 수 있습니다: 

sudo gitlab-rake gitlab:uploads:check

이러한 실패를 제거하기 위해 기본 Geo 사이트에서 다음 스크립트를 레일즈 콘솔에서 실행하여 이러한 업로드 레코드를 삭제할 수 있습니다: 

# 확인 오류가 있는 업로드 찾기
# 또는 영향을 받는 자체 ID로 편집
uploads = Geo::UploadState.where(
  verification_checksum: nil,
  verification_state: 3,
  verification_failure: "Error during verification: undefined method  `underscore' for NilClass:Class"
).pluck(:upload_id)

uploads_deleted = 0
begin
    uploads.each do |upload|
    u = Upload.find upload
    rescue => e
        puts "checking upload #{u.id} failed with #{e.message}"
      else
        uploads_deleted=uploads_deleted + 1
        p u                            ### 삭제 전 확인
        # p u.destroy!                 ### 실제로 삭제하려면 주석 제거
  end
end
p "#{uploads_deleted} 원격 개체가 삭제되었습니다."

HTTP 응답 코드 오류

이차 사이트가 Geo 프록시로 502 오류를 반환

이차 사이트용 Geo 프록시가 활성화되어 있고, 이차 사이트 사용자 인터페이스가 502 오류를 반환하는 경우, 기본 사이트에서 프록시된 응답 헤더가 너무 큰 경우가 있습니다.

다음 예제와 같은 NGINX 로그에서 다음과 유사한 오류를 확인하세요: 

2022/01/26 00:02:13 [error] 26641#0: *829148 upstream sent too big header while reading response header from upstream, client: 10.0.2.2, server: geo.staging.gitlab.com, request: "POST /users/sign_in HTTP/2.0", upstream: "http://unix:/var/opt/gitlab/gitlab-workhorse/sockets/socket:/users/sign_in", host: "geo.staging.gitlab.com", referrer: "https://geo.staging.gitlab.com/users/sign_in"

이 문제를 해결하려면:

  1. nginx['proxy_custom_buffer_size'] = '8k'를 /etc/gitlab.rb에 모든 이차 사이트의 웹 노드에 설정합니다.
  2. 이차 사이트에서 sudo gitlab-ctl reconfigure를 사용하여 재구성합니다.

이 오류가 계속 발생하는 경우 위의 단계를 반복하여 버퍼 크기를 더 크게 늘려도 됩니다. 예를 들어 16k로 두 배로 늘려도 됩니다.

Geo 관리 영역에서 건강 상태가 ‘알 수 없음’으로 표시되고 ‘상태 코드 401과 함께 실패한 요청’이 표시됩니다.

로드 밸런서를 사용하는 경우, 로드 밸런서 뒤의 노드들의 /etc/gitlab/gitlab.rb에서 로드 밸런서의 URL이 external_url로 설정되었는지 확인하십시오.

기본 사이트에서 /admin/geo/replication/projects에 액세스할 때 500 에러가 반환됩니다.

기본 Geo 사이트에서 Admin > Geo > Replication (또는 /admin/geo/replication/projects)로 이동하면 500 에러가 표시되는데, 이와 동일한 링크는 보조 사이트에서 정상적으로 작동합니다. 기본 사이트의 production.log에 다음과 유사한 항목이 있습니다. 

Geo::TrackingBase::SecondaryNotConfigured: Geo secondary database is not configured
  from ee/app/models/geo/tracking_base.rb:26:in `connection'
  [..]
  from ee/app/views/admin/geo/projects/_all.html.haml:1

Geo 기본 사이트에서는 이 오류를 무시해도 됩니다.

GitLab은 기본 사이트에 문자열 레지스트리를 표시하려고 시도하기 때문에 이 문제가 발생하며, 기본 사이트에는 레지스트리가 없습니다(기본 사이트에는 원래 프로젝트만 존재하며, 복제된 프로젝트는 없으므로 추적 데이터베이스도 존재하지 않음).

보조 사이트에서 400 에러인 “요청 헤더 또는 쿠키가 너무 큼”이 반환됩니다.

이 오류는 기본 사이트의 내부 URL이 잘못된 경우 발생할 수 있습니다.

예를 들어 통합 URL을 사용하고 기본 사이트의 내부 URL도 외부 URL과 동일한 경우 발생할 수 있습니다. 이는 보조 사이트가 기본 사이트의 내부 URL로 요청을 프록시하는 경우 루프를 발생시킵니다.

이 문제를 해결하려면 기본 사이트의 내부 URL을 다음과 같이 설정하십시오.

보조 사이트에서 ‘CONNECT’ 후 프록시로부터 HTTP 코드 403을 수신합니다.

Linux 패키지(옴니버스)를 사용하여 GitLab을 설치하고 Gitaly에 대한 no_proxy 사용자 정의 환경 변수를 구성한 경우 이 문제가 발생할 수 있습니다. 영향을 받는 버전:

  • 15.4.6
  • 15.5.0-15.5.6
  • 15.6.0-15.6.3
  • 15.7.0-15.7.1

이는 Linux 패키지 15.4.6 이후에 포함된 cURL 버전에서 발생한 버그 때문입니다. 이 문제는 모든 와일드카드 도메인(.example.com)을 no_proxy 환경 변수 목록에서 맨 마지막 도메인을 제외하고 무시하는 것입니다. 따라서 더 최신 버전으로 업그레이드할 수 없는 경우, 와일드카드 도메인을 목록의 맨 끝으로 이동하여 이 문제를 해결할 수 있습니다.

  1. /etc/gitlab/gitlab.rb를 편집합니다. 

    gitaly['env'] = {
  "no_proxy" => "sever.yourdomain.org, .yourdomain.com",
}

  2. GitLab을 다시 구성합니다. 

    sudo gitlab-ctl reconfigure

no_proxy 목록에는 하나의 와일드카드 도메인만 포함할 수 있습니다.

Geo 관리 영역에서 보조 사이트에 대해 404 에러가 반환됩니다.

때때로 sudo gitlab-rake gitlab:geo:check 명령을 실행하면 보조 사이트의 Rails 노드가 정상임을 나타내지만, 기본 사이트의 웹 인터페이스에서 보조 사이트에 대한 404 Not Found 에러 메시지가 반환됩니다.

이 문제를 해결하려면:

  • sudo gitlab-ctl restart를 사용하여 각 보조 사이트의 Rails, Sidekiq 및 Gitaly 노드를 다시 시작해 보세요.
  • Sidekiq 노드의 /var/log/gitlab/gitlab-rails/geo.log를 확인하여 보조 사이트가 기본 사이트로 상태를 전송할 때 IPv6을 사용하는지 확인합니다. 그렇다면, /etc/hosts 파일에 IPv4를 사용하는 항목을 추가하세요. 또는기본 사이트에서 IPv6를 사용하도록 설정해야 합니다.

Geo 데이터베이스 구성 파일이 누락되었습니다

GitLab은 database_geo.yml 구성 파일을 찾지 못하거나 액세스할 권한이 없을 수 있습니다.

Linux 패키지 설치에서 파일은 /var/opt/gitlab/gitlab-rails/etc에 있어야 합니다. 존재하지 않거나 무심코 변경 사항이 있는 경우 sudo gitlab-ctl reconfigure를 실행하여 올바른 상태로 복원하십시오.

이 경로가 원격 볼륨에 장착된 경우 볼륨 구성이 올바른 권한을 갖고 있는지 확인하십시오.

기존 추적 데이터베이스를 재사용할 수 없습니다

Geo는 기존 추적 데이터베이스를 재사용할 수 없습니다.

가장 안전한 방법은 새 이차 사이트를 사용하거나 전체 이차를 재설정하는 것입니다. Geo 이차 사이트 복제 재설정을 따라하십시오.

이차 사이트를 재설정하지 않은 채 재사용하면 위험합니다. 왜냐하면 이차 사이트에서 일부 Geo 이벤트를 놓칠 수 있기 때문입니다. 예를 들어, 누락된 삭제 이벤트는 지워져야 할 데이터가 이차 사이트에 영구적으로 남아있게 만듭니다. 마찬가지로 데이터의 위치를 물리적으로 옮기는 이벤트를 놓친 것은 데이터를 한 위치에 영구적으로 유랑시키고 다른 위치에서 누락되게 만들며, 이를 다시 검증할 때까지 누락된 상태로 유지됩니다. 이것이 GitLab이 데이터 이동이 불필요하게 만들어서 변경해 버렸기 때문입니다. 누락된 이벤트로 인한 기타 알려지지 않은 문제가 있을 수 있습니다.

이러한 위험이 해당되지 않는 경우(예: 테스트 환경)나 Geo 사이트가 추가된 이후 메인 포스트그레스 데이터베이스가 모든 Geo 이벤트를 아직 포함하고 있는지 알고 있다면 이 건강 검사를 우회할 수 있습니다:

  1. 마지막으로 처리된 이벤트 시간을 얻으십시오. 이차 사이트의 Rails 콘솔에서 다음을 실행하십시오: 

     Geo::EventLogState.last.created_at.utc
  2. 출력을 복사하십시오. 예를 들어 2024-02-21 23:50:50.676918 UTC와 같습니다.

  3. 이차 사이트의 생성 시간을 업데이트하여 이전처럼 보이도록 만드십시오. 주 사이트의 Rails 콘솔에서 다음을 실행하십시오: 

     GeoNode.secondary_nodes.last.update_column(:created_at, DateTime.parse('2024-02-21 23:50:50.676918 UTC') - 1.second)

    이 명령은 영향을 받는 이차 사이트가 마지막으로 생성된 사이트라고 가정합니다.

  4. Admin > Geo > Sites에서 이차 사이트의 상태를 업데이트하십시오. 이차 사이트의 Rails 콘솔에서 다음을 실행하십시오: 

     Geo::MetricsUpdateWorker.new.perform
  5. 이차 사이트는 정상적으로 표시되어야 합니다. 그렇지 않은 경우 이차 사이트에서 gitlab-rake gitlab:geo:check를 실행하거나 이차 사이트를 다시 추가한 이후 Rails를 다시 시작해 보십시오.
  6. 누락된 또는 오래된 데이터를 동기화하려면 Admin > Geo > Sites로 이동하십시오.
  7. 이차 사이트 아래에서 Replication Details를 선택하십시오.
  8. 각 데이터 유형에 대해 모두 다시 확인을 선택하십시오.

Geo 사이트에 기록 가능한 데이터베이스가 있으므로 이는 주 사이트와의 복제가 구성되지 않았음을 나타내는 것입니다

이 오류 메시지는 이차 사이트에서 데이터베이스 복제가 중단된 것을 나타냅니다. Geo는 액세스할 수 있을 것으로 기대하는 데이터베이스 복제에 문제가 있다는 것을 보통 의미합니다. 보통 다음 중 하나입니다:

  • 지원되지 않는 복제 방법이 사용됨(예: 논리적 복제).
  • Geo 데이터베이스 복제를 올바르게 설정하는 지침을 지켜주지 않았음.
  • 데이터베이스 연결 세부 정보가 잘못됨, 즉 /etc/gitlab/gitlab.rb 파일에서 잘못된 사용자를 지정했음.

Geo 이차 사이트는 두 개의 별도 PostgreSQL 인스턴스가 필요합니다:

  • 주 사이트의 읽기 전용 레플리카.
  • 복제 메타데이터를 보유하는 일반적인 기록 가능한 인스턴스. 즉, Geo 추적 데이터베이스입니다.

이 오류 메시지는 이차 사이트의 레플리카 데이터베이스가 잘못 구성되어 있고 복제가 중지되었음을 나타냅니다.

데이터베이스를 복원하고 복제를 재개하려면 다음 중 하나를 수행할 수 있습니다:

새 이차를 처음부터 설정하는 경우, 또한 Geo 클러스터에서 이전 사이트를 제거해야 합니다.

Geo 사이트에서 주 사이트로부터 데이터베이스를 복제하는 것으로 보이지 않습니다

데이터베이스가 올바르게 복제되지 못하는 가장 일반적인 문제점은:

  • 이차 사이트가 주 사이트에 도달할 수 없음. 자격 증명 및 방화벽 규칙을 확인하십시오.
  • SSL 인증서 문제. /etc/gitlab/gitlab-secrets.json을 주 사이트에서 복사했는지 확인하십시오.
  • 데이터베이스 저장 디스크가 가득 참.
  • 데이터베이스 복제 슬롯이 잘못 구성됨.
  • 데이터베이스가 복제 슬롯을 사용하고 있지 않거나 다른 대안을 사용하지 않아 WAL 파일이 정리되지 못하여 따라잡을 수 없음.

지원되는 구성에 대한 Geo 데이터베이스 복제 지침을 따르십시오.

Geo 데이터베이스 버전(…)이(가) 최신 마이그레이션(…)과(와) 일치하지 않습니다.

Linux 패키지 설치를 사용하는 경우, 업그레이드 중에 오류가 발생했을 수 있습니다. 다음을 수행할 수 있습니다:

  • sudo gitlab-ctl reconfigure를 실행합니다.
  • 루트로 실행하여 수동으로 데이터베이스 마이그레이션을 트리거합니다: sudo gitlab-rake db:migrate:geo (secondary 사이트에서).

GitLab은 저장소의 100% 이상이 동기화되었다고 표시합니다.

프로젝트 레지스트리에 고아 레코드가 있을 수 있어 발생할 수 있습니다. 정기적으로 레지스트리 워커를 사용하여 정리되므로 몇 시간이 지나면 자체적으로 수정될 수 있습니다.

external_url의 값이 변경된 후 secondary 사이트에서 UI에 “Unhealthy”가 표시됩니다.

기본 사이트의 /etc/gitlab/gitlab.rb에서 external_url의 값을 업데이트하거나 프로토콜을 http에서 https로 변경한 경우, secondary 사이트가 Unhealthy로 표시될 수 있습니다. 또한 geo.log에서 다음 오류를 찾을 수 있습니다: 

"class": "Geo::NodeStatusRequestService",
...
"message": "Failed to Net::HTTP::Post to primary url: http://primary-site.gitlab.tld/api/v4/geo/status",
  "error": "Failed to open TCP connection to <PRIMARY_IP_ADDRESS>:80 (Connection refused - connect(2) for "<PRIMARY_ID_ADDRESS>" port 80)"

이 경우, 변경된 URL을 모든 사이트에서 업데이트하고 변경 내용을 저장하세요.

  1. 왼쪽 사이드바에서 맨 아래에서 관리자 영역(Admin Area)을 선택합니다.
  2. Geo > 사이트(Sites)을 선택합니다.
  3. URL을 변경하고 변경 사항을 저장합니다.

백업 중 메시지: ERROR: canceling statement due to conflict with recovery

Geo secondary에서 백업을 실행하는 것은 지원되지 않습니다.

Geo secondary에서 백업을 실행하는 경우 다음과 같은 오류 메시지가 발생할 수 있습니다: 

PostgreSQL 데이터베이스 gitlabhq_production을 덤프하는 중...
pg_dump: error: Dumping the contents of table "notes" failed: PQgetResult() failed.
pg_dump: error: Error message from server: ERROR:  canceling statement due to conflict with recovery
DETAIL:  User query might have needed to see row versions that must be removed.
pg_dump: error: The command was: COPY public.notes (id, note, [...], last_edited_at) TO stdout;

Geo secondary에서 GitLab 업그레이드 중 자동으로 데이터베이스 백업을 방지하려면 다음 빈 파일을 만듭니다: 

sudo touch /etc/gitlab/skip-auto-backup

장애 조치(failover) 중 또는 secondary를 primary 사이트로 승격(promote)할 때 오류 수정하기

다음은 장애 조치(failover) 중 또는 secondary를 primary 사이트로 승격(promote)할 때 발생할 수 있는 가능한 오류 메시지와 이를 해결하기 위한 전략입니다.

메시지: ActiveRecord::RecordInvalid: Validation failed: Name has already been taken

secondary 사이트를 승격(promote)하는 중에 다음과 같은 오류 메시지가 발생할 수 있습니다. (secondary 사이트 승격(promote) 참조) 

gitlab-rake geo:set_secondary_as_primary 실행 중...

rake 중지됨!
ActiveRecord::RecordInvalid: Validation failed: Name has already been taken
/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:236:in `block (3 levels) in <top (required)>'
/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:221:in `block (2 levels) in <top (required)>'
/opt/gitlab/embedded/bin/bundle:23:in `load'
/opt/gitlab/embedded/bin/bundle:23:in `<main>'
Tasks: TOP => geo:set_secondary_as_primary
(전체 추적은 --trace 옵션으로 실행하여 확인할 수 있습니다.)
무사히 이 노드를 승격(promote)했습니다!

gitlab-rake geo:set_secondary_as_primary 또는 gitlab-ctl promote-to-primary-node를 실행하는 중에 이 메시지가 표시되면:

  • 레일즈 콘솔로 이동하여 다음을 실행합니다: 

    Rails.application.load_tasks; nil
Gitlab::Geo.expire_cache!
Rake::Task['geo:set_secondary_as_primary'].invoke

  • 안전하다면 GitLab 12.6.3 이상으로 업그레이드합니다. 예를 들어, 장애 조치(failover)가 테스트였을 경우. 캐싱 관련 버그가 수정되었습니다.

메시지: NoMethodError: undefined method secondary?’ for nil:NilClass`

secondary 사이트를 승격(promote)하는 중에 다음과 같은 오류 메시지가 발생할 수 있습니다. (secondary 사이트 승격(promote) 참조) 

sudo gitlab-rake geo:set_secondary_as_primary 실행 중

rake 중지됨!
NoMethodError: undefined method `secondary?' for nil:NilClass
/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:232:in `block (3 levels) in <top (required)>'
/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:221:in `block (2 levels) in <top (required)>'
/opt/gitlab/embedded/bin/bundle:23:in `load'
/opt/gitlab/embedded/bin/bundle:23:in `<main>'
Tasks: TOP => geo:set_secondary_as_primary
(전체 추적은 --trace 옵션으로 실행하여 확인할 수 있습니다.)

이 명령은 secondary 사이트에서만 실행되어야 하며, 만약 이 명령을 주(primary) 사이트에서 실행하면 이 오류 메시지가 표시됩니다.

만료된 artifact

어떤 이유로든 Geo secondary 사이트에 artifact가 primary site보다 더 많이 있는 경우, Rake task를 사용하여 고아 artifact 파일을 정리할 수 있습니다.

Geo secondary 사이트에서 이 명령은 또한 디스크에 있는 고아 파일과 관련된 모든 Geo 레지스트리 레코드를 정리합니다.

로그인 오류 수정

메시지: 포함된 리디렉션 URI가 유효하지 않습니다

primary 사이트의 웹 인터페이스에 로그인할 수 있지만 secondary 웹 인터페이스에 로그인하려고 하면 이 오류 메시지를 받는다면 Geo 사이트의 URL이 외부 URL과 일치하는지 확인해야 합니다.

primary 사이트에서:

  1. 왼쪽 사이드바에서 맨 아래쪽에 있는 관리 영역(Admin Area)을 선택합니다.
  2. Geo > 사이트를 선택합니다.
  3. 영향을 받는 secondary 사이트를 찾아 편집(Edit)합니다.
  4. URL 필드가 secondary 사이트의 Rails 노드의 /etc/gitlab/gitlab.rb에서 찾은 값인 external_url "https://gitlab.example.com"와 일치하는지 확인합니다.

SAML을 사용하여 secondary 사이트에 인증하는 경우 항상 primary 사이트로 이동함

이 문제는 GitLab 15.1로 업그레이드할 때 일반적으로 발생합니다. 이 문제를 해결하려면 단일 사인온(Single Sign-On)으로 Geo에서 인스턴스 전체 SAML 구성을 참조하세요.

클라이언트 오류 수정

LFS HTTP(S) 클라이언트 요청에서의 권한 오류

버전 2.4.2 이전의 Git LFS를 실행 중이라면 문제가 발생할 수 있습니다. 이러한 권한 문제는 이 인증 문제에서 설명한 대로 secondary에서 primary 사이트로 리디렉트된 요청이 인증 헤더를 제대로 보내지 않은 것을 원인으로 합니다. 이는 무한한 인증 <-> 리디렉션 루프 또는 인증 오류 메시지로 이어질 수 있습니다.

Error: Geo secondary에서 SSH로 푸시할 때 Net::ReadTimeout

Geo secondary 사이트에서 SSH로 대형 리포지토리를 푸시하면 시간 초과 오류가 발생할 수 있습니다. 이는 Rails가 push를 primary로 프록시하고 기본 60초의 타임아웃을 가지기 때문인데, 이 Geo 이슈에서 설명한 대로입니다.

현재의 임시 방편은:

  • Geo 프록시가 사용되지 않으면 Workhorse가 요청을 primary에 프록시하거나(primary로 리디렉션) HTTP를 통해 푸시합니다.
  • 직접 primary로 푸시합니다.

예상 로그 (gitlab-shell.log): 

Failed to contact primary https://primary.domain.com/namespace/push_test.git\\nError: Net::ReadTimeout\",\"result\":null}" code=500 method=POST pid=5483 url="http://127.0.0.1:3000/api/v4/geo/proxy_git_push_ssh/push"

Geo 사이트 간의 OAuth 권한 부여 복구

Geo 사이트를 업그레이드하는 동안, 인증에 OAuth만 사용하는 secondary 사이트에 로그인할 수 없을 수 있습니다. 이 경우 primary 사이트에서 Rails 콘솔 세션을 시작하고 다음 단계를 수행합니다:

  1. 영향을 받는 노드를 찾기 위해 먼저 모든 Geo 노드를 나열합니다: 

    GeoNode.all

  2. ID를 지정하여 영향을 받는 Geo 노드를 복구합니다: 

    GeoNode.find(<id>).repair

부분 장애 복구

secondary Geo 사이트로의 부분 장애는 일시적인/일시적인 문제의 결과일 수 있습니다. 따라서 먼저 프로모트 명령을 다시 실행하려고 시도해보세요.

  1. secondary 사이트의 모든 Sidekiq, PostgreSQL, Gitaly, Rails 노드로 SSH로 연결하고 다음 명령 중 하나를 실행합니다:

    • secondary 사이트를 primary로 프로모트하려면: 

      sudo gitlab-ctl geo promote

    • 어떠한 추가 확인도 없이 secondary 사이트를 primary로 프로모트하려면: 

      sudo gitlab-ctl geo promote --force
  2. 이전에 secondary 사이트에 사용했던 URL로 새로 프로모트된 primary 사이트에 연결할 수 있는지 확인합니다.
  3. 성공적이라면, secondary 사이트가 이제 primary 사이트로 프로모트되었습니다.

만약 위 단계가 성공적이 아니라면, 다음 단계로 진행합니다:

  1. secondary 사이트의 모든 Sidekiq, PostgreSQL, Gitaly, Rails 노드로 SSH로 연결하고 다음 작업을 수행합니다:

    • 다음 내용과 같은 /etc/gitlab/gitlab-cluster.json 파일을 생성합니다: 

      {
  "primary": true,
  "secondary": false
}

    • 변경 사항이 적용되도록 GitLab을 다시 구성합니다: 

      sudo gitlab-ctl reconfigure
  2. 이전에 secondary 사이트에 사용했던 URL로 새로 프로모트된 primary 사이트에 연결할 수 있는지 확인합니다.
  3. 성공적이라면, secondary 사이트가 이제 primary 사이트로 프로모트되었습니다.

데이터베이스 복제 지연의 원인 조사

sudo gitlab-rake geo:status의 출력에서 데이터베이스 복제 지연(Database replication lag)이 지속적으로 높은 것으로 나타나면, 데이터베이스 복제의 기본 노드에서 데이터베이스 복제 프로세스의 다른 부분의 지연 상태를 확인할 수 있습니다. 이러한 값들은 write_lag, flush_lag, replay_lag로 알려져 있습니다. 더 많은 정보는 공식 PostgreSQL 문서를 참조하세요.

기본 Geo 노드에서 다음 명령을 실행하여 관련 출력을 제공합니다: 

gitlab-psql -xc 'SELECT write_lag,flush_lag,replay_lag FROM pg_stat_replication;'
-[ RECORD 1 ]---------------
write_lag  | 00:00:00.072392
flush_lag  | 00:00:00.108168
replay_lag | 00:00:00.108283

이 값들 중 하나 이상이 현저히 높으면, 이는 문제를 나타내고 추가적으로 조사해야 합니다. 원인을 결정하는 과정에서 다음을 고려하세요:

  • write_lag는 기본에서 WAL 바이트를 보냈지만 보조로 아직 플러시되거나 적용되지 않은 시간을 나타냅니다.
  • 높은 write_lag 값은 기본과 보조 노드 간에 네트워크 성능이 저하되었거나 네트워크 속도가 충분하지 않을 수 있음을 나타낼 수 있습니다.
  • 높은 flush_lag 값은 보조 노드의 저장 장치와의 디스크 I/O 성능이 저하되었거나 최적이 아님을 나타낼 수 있습니다.
  • 높은 replay_lag 값은 PostgreSQL에서 오랜 시간 동안 실행 중인 트랜잭션 또는 필요한 리소스(CPU와 같은) 포화를 나타낼 수 있습니다.
  • write_lag와 flush_lag 사이의 시간 차이는 WAL 바이트가 기본 저장 시스템에 전송되었지만 플러시되지 않았음을 나타냅니다. 이 데이터는 아마도 완전히 영속적인 저장소에 기록되지 않았으며 아마도 어떤 종류의 휘발성 쓰기 캐시에 보관 중일 것입니다.
  • flush_lag와 replay_lag의 차이는 저장소에 성공적으로 영속화된 WAL 바이트지만 데이터베이스 시스템에서 재생되지 못한 것입니다.

Geo secondary 사이트 복제 재설정

secondary 사이트가 손상된 상태로 있고 복제 상태를 재설정하려면, 처음부터 다시 시작할 수 있는 몇 가지 단계가 도움이 될 수 있습니다:

  1. Sidekiq와 Geo LogCursor를 중지합니다.

    Sidekiq를 우아하게 중지할 수 있지만, 새로운 작업을 받지 않도록 하고 현재 작업 처리가 완료될 때까지 기다릴 수 있습니다.

    첫 번째 단계에 SIGTSTP kill 시그널을 보내고, 모든 작업이 처리를 완료할 때 SIGTERM을 보냅니다. 그렇지 않으면 gitlab-ctl stop 명령을 사용합니다. 

    gitlab-ctl status sidekiq
# run: sidekiq: (pid 10180) <- 이것은 사용할 PID입니다
kill -TSTP 10180 # 올바른 PID로 변경합니다

gitlab-ctl stop sidekiq
gitlab-ctl stop geo-logcursor

    Sidekiq 작업 처리가 완료되는지 확인하려면 Sidekiq 로그를 확인할 수 있습니다: 

    gitlab-ctl tail sidekiq

  2. 저장소 저장 폴더의 이름을 변경하고 새로운 폴더를 만듭니다. 가능한 고아 상태의 디렉토리와 파일에 대해 걱정할 필요가 없다면, 이 단계를 건너뛸 수 있습니다. 

    mv /var/opt/gitlab/git-data/repositories /var/opt/gitlab/git-data/repositories.old
mkdir -p /var/opt/gitlab/git-data/repositories
chown git:git /var/opt/gitlab/git-data/repositories

    참고: 더 이상 필요하지 않다는 것을 확인한 후에는 /var/opt/gitlab/git-data/repositories.old를 나중에 제거하는 것이 좋습니다. 이렇게 하면 디스크 공간을 절약할 수 있습니다.

  3. 선택 사항. 다른 데이터 폴더의 이름 변경 및 새로운 폴더 생성.

    경고: 여전히 primary 사이트에서 제거된 파일이 secondary 사이트에 남아있을 수 있습니다. 이 단계를 건너뛴다면 이러한 파일들은 Geo secondary 사이트에서 제거되지 않습니다.

    업로드된 모든 콘텐츠(파일 첨부, 아바타, 또는 LFS 객체와 같은)는 다음 경로 중 하나의 하위 폴더에 저장됩니다:

    • /var/opt/gitlab/gitlab-rails/shared
    • /var/opt/gitlab/gitlab-rails/uploads

    이들 모두의 이름을 변경하려면 다음을 수행합니다: 

    gitlab-ctl stop

mv /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-rails/shared.old
mkdir -p /var/opt/gitlab/gitlab-rails/shared

mv /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/uploads.old
mkdir -p /var/opt/gitlab/gitlab-rails/uploads

gitlab-ctl start postgresql
gitlab-ctl start geo-postgresql

    폴더를 다시 생성하고 권한과 소유권이 올바른지 확인하도록 다시 구성합니다: 

    gitlab-ctl reconfigure

  4. 추적 데이터베이스를 재설정합니다.

    경고: 선택 사항 3 단계를 건너뛴 경우, geo-postgresql 및 postgresql 서비스가 실행 중인지 확인하십시오. 

    gitlab-rake db:drop:geo DISABLE_DATABASE_ENVIRONMENT_CHECK=1   # secondary 앱 노드에서
gitlab-ctl reconfigure     # 추적 데이터베이스 노드에서
gitlab-rake db:migrate:geo # secondary 앱 노드에서

  5. 이전에 중지된 서비스를 다시 시작합니다. 

    gitlab-ctl start