기본 문제 해결#

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

• Geo 사이트의 상태 점검.
• PostgreSQL 복제가 작동 중인지 확인.

Geo 사이트 간 요청 추적#

Geo 문제를 해결할 때 보조 사이트에서 기본 사이트로, 또는 그 반대로 요청을 추적해야 할 수 있습니다. GitLab은 서비스 전반의 관련 로그 항목을 연결하기 위해 상관 ID를 사용합니다.

기본적으로 각 사이트는 요청을 받을 때 자체 상관 ID를 생성합니다. 동일한 상관 ID를 사용하여 두 사이트 간의 단일 요청을 추적하려면 각 수신 사이트의 Workhorse가 다른 Geo 사이트의 들어오는 상관 ID를 수락하도록 구성해야 합니다.

모든 Geo 사이트에서:

이 설정을 활성화하면 보조 사이트에서 기본 사이트로 전송된 요청이 로그에서 동일한 상관 ID를 공유하므로 두 사이트 간의 요청을 추적할 수 있습니다.

Geo 사이트 상태 점검#

기본 사이트에서:

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Geo > Sites를 선택합니다.

각 보조 사이트에서 다음 상태 점검을 수행하여 문제가 있는지 식별하는 데 도움을 줍니다:

• 사이트가 실행 중입니까?
• 보조 사이트의 데이터베이스가 스트리밍 복제로 구성되어 있습니까?
• 보조 사이트의 추적 데이터베이스가 구성되어 있습니까?
• 보조 사이트의 추적 데이터베이스가 연결되어 있습니까?
• 보조 사이트의 추적 데이터베이스가 최신 상태입니까?
• 보조 사이트의 상태가 1시간 미만입니까?

사이트 상태가 1시간 이상 된 경우 사이트가 "Unhealthy"로 표시됩니다. 이 경우 영향을 받는 보조 사이트의 Rails 콘솔에서 다음을 실행해 보세요:

Geo::MetricsUpdateWorker.new.perform

오류가 발생하면 해당 오류가 작업 완료를 방해하고 있을 수도 있습니다. 1시간 이상 걸리면 상태가 간헐적으로 또는 지속적으로 "Unhealthy"로 표시될 수 있으며, 상태가 가끔 업데이트되더라도 마찬가지입니다. 이는 사용량 증가, 시간이 지남에 따른 데이터 증가 또는 누락된 데이터베이스 인덱스와 같은 성능 버그로 인해 발생할 수 있습니다.

top 또는 htop과 같은 유틸리티로 시스템 CPU 부하를 모니터링할 수 있습니다. PostgreSQL이 상당한 양의 CPU를 사용하고 있다면 문제가 있거나 시스템이 프로비저닝이 부족한 것일 수 있습니다. 시스템 메모리도 모니터링해야 합니다.

메모리를 늘리는 경우 /etc/gitlab/gitlab.rb 구성에서 PostgreSQL 메모리 관련 설정도 확인해야 합니다.

상태를 성공적으로 업데이트하면 Sidekiq에 문제가 있을 수 있습니다. 실행 중입니까? 로그에 오류가 표시됩니까? 이 작업은 매분 큐에 추가되어야 하며 작업 중복 제거 idempotency 키가 올바르게 지워지지 않은 경우 실행되지 않을 수 있습니다. Redis에서 독점 리스를 사용하여 이러한 작업 중 하나만 한 번에 실행할 수 있도록 합니다. 기본 사이트는 PostgreSQL 데이터베이스에 직접 상태를 업데이트합니다. 보조 사이트는 상태 데이터와 함께 기본 사이트에 HTTP Post 요청을 보냅니다.

특정 상태 점검이 실패하면 사이트도 "Unhealthy"로 표시됩니다. 영향을 받는 보조 사이트의 Rails 콘솔에서 다음을 실행하여 실패를 확인할 수 있습니다:

Gitlab::Geo::HealthCheck.new.perform_checks

"" (빈 문자열) 또는 "Healthy"를 반환하면 점검이 성공한 것입니다. 다른 것을 반환하면 메시지에서 실패 원인이나 예외 메시지가 설명되어야 합니다.

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

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

상태 점검 Rake 작업#

히스토리

• 사용자 지정 NTP 서버 사용이 GitLab 15.7에서 도입되었습니다.

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

sudo gitlab-rake gitlab:geo:check

출력 예시:

Checking Geo ...

GitLab Geo is available ... yes
GitLab Geo is enabled ... yes
This machine's Geo node name matches a database record ... yes, found a secondary node named "Shanghai"
GitLab Geo tracking database is correctly configured ... yes
Database replication enabled? ... yes
Database replication working? ... yes
GitLab Geo HTTP(S) connectivity ...
* Can connect to the primary node ... yes
HTTP/HTTPS repository cloning is enabled ... yes
Machine clock is synchronized ... yes
Git user has default SSH configuration? ... yes
OpenSSH configured to use AuthorizedKeysCommand ... yes
GitLab configured to disable writing to authorized_keys file ... yes
GitLab configured to store new projects in hashed storage? ... yes
All projects are in hashed storage? ... yes
Container Registry replication enabled ... yes
Container Registry Geo events ... last event at 2024-01-15 10:30:00 UTC

Checking Geo ... Finished

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

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

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

Rake 작업이 OpenSSH configured to use AuthorizedKeysCommand 점검을 건너뛰면 다음 출력이 표시됩니다:

OpenSSH configured to use AuthorizedKeysCommand ... skipped
  Reason:
  Cannot access OpenSSH configuration file
  Try fixing it:
  This is expected if you are using SELinux. You may want to check configuration manually
  For more information see:
  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 보조 사이트의 Rails(Puma, Sidekiq, 또는 Geo Log Cursor)를 실행하는 모든 노드에서 이 Rake 작업을 실행하여 수동으로 찾을 수 있습니다.

GitLab은 객체 스토리지에 저장된 객체를 검증하지 않습니다. 객체 스토리지를 사용하는 경우 "verified" 점검이 모두 0 성공을 표시합니다. 이는 예상된 동작이며 우려할 사항이 아닙니다.

sudo gitlab-rake gitlab:geo:status

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

• 오류가 발생한 경우 "failed" 항목의 수
• "total"에 대한 "succeeded" 항목의 비율

예시:

                        Geo Site Information
--------------------------------------------
                                      Name: example-us-east-2
                                       URL: https://gitlab.example.com
                                  Geo Role: Secondary
                             Health Status: Healthy
                This Node's GitLab Version: 17.7.0-ee

                     Replication Information
--------------------------------------------
                             Sync Settings: Full
                  Database replication lag: 0 seconds
           Last event ID seen from primary: 12345 (about 2 minutes ago)
                   Last event ID processed: 12345 (about 2 minutes ago)
                    Last status report was: 1 minute ago

                          Replication Status
--------------------------------------------
                    Lfs Objects replicated: succeeded 111 / total 111 (100%)
            Merge Request Diffs replicated: succeeded 28 / total 28 (100%)
                  Package Files replicated: succeeded 90 / total 90 (100%)
       Terraform State Versions replicated: succeeded 65 / total 65 (100%)
           Snippet Repositories replicated: succeeded 63 / total 63 (100%)
        Group Wiki Repositories replicated: succeeded 14 / total 14 (100%)
             Pipeline Artifacts replicated: succeeded 112 / total 112 (100%)
              Pages Deployments replicated: succeeded 55 / total 55 (100%)
                        Uploads replicated: succeeded 2 / total 2 (100%)
                  Job Artifacts replicated: succeeded 32 / total 32 (100%)
                Ci Secure Files replicated: succeeded 44 / total 44 (100%)
         Dependency Proxy Blobs replicated: succeeded 15 / total 15 (100%)
     Dependency Proxy Manifests replicated: succeeded 2 / total 2 (100%)
      Project Wiki Repositories replicated: succeeded 2 / total 2 (100%)
 Design Management Repositories replicated: succeeded 1 / total 1 (100%)
           Project Repositories replicated: succeeded 2 / total 2 (100%)

                         Verification Status
--------------------------------------------
                      Lfs Objects verified: succeeded 111 / total 111 (100%)
              Merge Request Diffs verified: succeeded 28 / total 28 (100%)
                    Package Files verified: succeeded 90 / total 90 (100%)
         Terraform State Versions verified: succeeded 65 / total 65 (100%)
             Snippet Repositories verified: succeeded 63 / total 63 (100%)
          Group Wiki Repositories verified: succeeded 14 / total 14 (100%)
               Pipeline Artifacts verified: succeeded 112 / total 112 (100%)
                Pages Deployments verified: succeeded 55 / total 55 (100%)
                          Uploads verified: succeeded 2 / total 2 (100%)
                    Job Artifacts verified: succeeded 32 / total 32 (100%)
                  Ci Secure Files verified: succeeded 44 / total 44 (100%)
           Dependency Proxy Blobs verified: succeeded 15 / total 15 (100%)
       Dependency Proxy Manifests verified: succeeded 2 / total 2 (100%)
        Project Wiki Repositories verified: succeeded 2 / total 2 (100%)
   Design Management Repositories verified: succeeded 1 / total 1 (100%)
             Project Repositories verified: succeeded 2 / total 2 (100%)

모든 객체가 복제 및 검증되며, Geo 용어집에 정의되어 있습니다. 각 데이터 유형을 복제하고 검증하는 데 사용하는 방법에 대한 자세한 내용은 지원되는 Geo 데이터 유형을 참조하세요.

실패한 항목에 대한 자세한 내용을 찾으려면 gitlab-rails/geo.log 파일을 확인하세요.

복제 또는 검증 실패가 발견되면 이를 해결해 볼 수 있습니다.

Geo 점검 Rake 작업 실행 시 발견된 오류 수정#

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

sudo gitlab-rake gitlab:geo:check

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

  Checking Geo ...
  
  GitLab Geo is available ... Exception: fe_sendauth: no password supplied
  GitLab Geo is enabled ... Exception: fe_sendauth: no password supplied
  ...
  Checking Geo ... Finished
  

  postgresql['sql_user_password']의 해시를 생성할 때 사용한 일반 텍스트 비밀번호로 gitlab_rails['db_password']가 설정되어 있는지 확인합니다.

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

  Checking Geo ...
  
  GitLab Geo is available ... 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 is enabled ... 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
  ...
  Checking Geo ... Finished
  

  Rails 노드의 IP 주소가 postgresql['md5_auth_cidr_addresses']에 포함되어 있는지 확인합니다. 또한 IP 주소에 서브넷 마스크를 포함했는지 확인합니다: postgresql['md5_auth_cidr_addresses'] = ['1.1.1.1/32'].

• Rails가 잘못된 비밀번호를 제공했습니다.

  Checking Geo ...
  GitLab Geo is available ... Exception: FATAL:  password authentication failed for user "gitlab"
  FATAL:  password authentication failed for user "gitlab"
  GitLab Geo is enabled ... Exception: FATAL:  password authentication failed for user "gitlab"
  FATAL:  password authentication failed for user "gitlab"
  ...
  Checking Geo ... Finished
  

  gitlab-ctl pg-password-md5 gitlab을 실행하고 비밀번호를 입력하여 postgresql['sql_user_password']의 해시를 생성할 때 사용한 gitlab_rails['db_password']에 올바른 비밀번호가 설정되어 있는지 확인합니다.

• 점검이 not a secondary node를 반환합니다.

  Checking Geo ...
  
  GitLab Geo is available ... yes
  GitLab Geo is enabled ... yes
  GitLab Geo tracking database is correctly configured ... not a secondary node
  Database replication enabled? ... not a secondary node
  ...
  Checking Geo ... Finished
  

  기본 사이트의 웹 인터페이스에서 Admin 영역의 Geo > Sites 아래에 보조 사이트를 추가했는지 확인합니다. 또한 기본 사이트의 Admin 영역에 보조 사이트를 추가할 때 gitlab_rails['geo_node_name']을 입력했는지 확인합니다.

• 점검이 Exception: PG::UndefinedTable: ERROR: relation "geo_nodes" does not exist를 반환합니다.

  Checking Geo ...
  
  GitLab Geo is available ... no
    Try fixing it:
    Add a new license that includes the GitLab Geo feature
    For more information see:
    https://about.gitlab.com/features/gitlab-geo/
  GitLab Geo is enabled ... 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
  ...
  Checking Geo ... Finished
  

  PostgreSQL 주요 버전(9 > 10)을 업그레이드할 때 이 오류가 예상됩니다. 복제 프로세스 시작을 따르세요.

• Rails에 Geo 추적 데이터베이스에 연결하는 데 필요한 구성이 없는 것 같습니다.

  Checking Geo ...
  
  GitLab Geo is available ... yes
  GitLab Geo is enabled ... yes
  GitLab Geo tracking database is correctly configured ... no
  Try fixing it:
  Rails does not appear to have the configuration necessary to connect to the Geo tracking database. If the tracking database is running on a node other than this one, then you may need to add configuration.
  ...
  Checking Geo ... Finished
  

  • 모든 서비스에 대해 단일 노드로 보조 사이트를 실행하는 경우 Geo 데이터베이스 복제 - 보조 서버 구성을 따르세요.
  • 보조 사이트의 추적 데이터베이스를 자체 노드에서 실행하는 경우 여러 서버용 Geo - Geo 보조 사이트에서 Geo 추적 데이터베이스 구성을 따르세요.
  • 보조 사이트의 추적 데이터베이스를 Patroni 클러스터에서 실행하는 경우 Geo 데이터베이스 복제 - 추적 PostgreSQL 데이터베이스를 위한 Patroni 클러스터 구성을 따르세요.
  • 보조 사이트의 추적 데이터베이스를 외부 데이터베이스에서 실행하는 경우 외부 PostgreSQL 인스턴스가 있는 Geo를 따르세요.
  • GitLab Rails 앱(Puma, Sidekiq, 또는 Geo Log Cursor)을 실행하는 서비스가 실행되지 않는 노드에서 Geo 점검 작업이 실행된 경우 이 오류는 무시할 수 있습니다. 해당 노드는 Rails를 구성할 필요가 없습니다.

메시지: Container Registry Geo events ... none found#

Container Registry Geo events ... none found가 표시되고 컨테이너 레지스트리 복제 이벤트가 있어야 한다고 예상하는 경우, 기본 사이트의 레지스트리 알림 구성이 컨테이너 레지스트리 복제 구성 가이드에 맞게 설정되어 있는지 확인합니다.

메시지: Machine clock is synchronized ... Exception#

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

점검을 수행하는 Ruby gem은 pool.ntp.org를 참조 시간 소스로 하드코딩합니다.

• 예외 메시지 Machine clock is synchronized ... Exception: Timeout::Error

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

• 예외 메시지 Machine clock is synchronized ... 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 배포는 Kubernetes의 컨테이너가 호스트 시계에 액세스할 수 없기 때문에 오류를 생성합니다:

Machine clock is synchronized ... Exception: getaddrinfo: Servname not supported for ai_socktype

메시지: cannot execute INSERT in a read-only transaction#

이 오류가 보조 사이트에서 발생하면 gitlab-rails 또는 gitlab-rake 명령뿐만 아니라 Puma, Sidekiq, Geo Log Cursor 서비스 등 GitLab Rails의 모든 사용에 영향을 미칩니다.

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단계. 보조 사이트 추가를 따르세요.

• Geo 보조 사이트 업그레이드 중. gitlab_rails['auto_migrate']가 true로 설정되어 GitLab이 복제본 데이터베이스에서 데이터베이스 마이그레이션을 시도하는데, 이는 필요하지 않습니다. 오류를 해결하려면:

  1. 보조 사이트의 GitLab Rails 노드에 root로 SSH 접속합니다.

  2. /etc/gitlab/gitlab.rb를 편집하고 이 설정을 주석 처리하거나 false로 설정합니다:

     gitlab_rails['auto_migrate'] = false
     

  3. GitLab을 재구성합니다:

     sudo gitlab-ctl reconfigure
     

PostgreSQL 복제가 작동 중인지 확인#

PostgreSQL 복제가 작동 중인지 확인하려면 다음을 확인합니다:

• 사이트가 올바른 데이터베이스 노드를 가리키는지 확인.
• Geo가 현재 사이트를 올바르게 감지할 수 있는지 확인.

여전히 문제가 있는 경우 고급 복제 문제 해결을 참조하세요.

사이트가 올바른 데이터베이스 노드를 가리키고 있습니까?#

기본 Geo 사이트가 쓰기 권한이 있는 데이터베이스 노드를 가리키는지 확인해야 합니다.

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

Geo가 현재 사이트를 올바르게 감지할 수 있습니까?#

Geo는 다음 로직을 사용하여 /etc/gitlab/gitlab.rb에서 현재 Puma 또는 Sidekiq 노드의 Geo 사이트 이름을 찾습니다:

1. "Geo 노드 이름"을 가져옵니다 (설정을 "Geo 사이트 이름"으로 이름 변경하는 이슈가 있습니다):
   • Linux 패키지: gitlab_rails['geo_node_name'] 설정을 가져옵니다.
   • GitLab Helm 차트: global.geo.nodeName 설정을 가져옵니다(GitLab Geo가 있는 차트 참조).
2. 정의되지 않은 경우 external_url 설정을 가져옵니다.

이 이름은 Geo Sites 대시보드에서 동일한 Name을 가진 Geo 사이트를 찾는 데 사용됩니다.

현재 머신의 사이트 이름이 데이터베이스의 사이트와 일치하는지 확인하려면 점검 작업을 실행합니다:

sudo gitlab-rake gitlab:geo:check

현재 머신의 사이트 이름과 일치하는 데이터베이스 레코드가 기본 또는 보조 사이트인지 여부가 표시됩니다.

This machine's Geo node name matches a database record ... yes, found a secondary node named "Shanghai"

This machine's Geo node name matches a database record ... no
  Try fixing it:
  You could add or update a Geo node database record, setting the name to "https://example.com/".
  Or you could set this machine's Geo node name to match the name of an existing database record: "London", "Shanghai"
  For more information see:
  doc/administration/geo/replication/troubleshooting/_index.md#can-geo-detect-the-current-node-correctly

Name 필드 설명에 권장 사이트 이름에 대한 자세한 내용은 Geo Admin 영역 공통 설정을 참조하세요.

OS 로케일 데이터 호환성 확인#

가능하면 모든 사이트의 모든 Geo 노드는 Geo 실행 요구사항에 정의된 것과 동일한 방법 및 운영 체제로 배포해야 합니다.

Geo 사이트 간에 서로 다른 운영 체제 또는 다른 운영 체제 버전이 배포된 경우 Geo를 설정하기 전에 반드시 로케일 데이터 호환성 점검을 수행해야 합니다. GitLab 배포 방법이 혼합된 경우 glibc도 확인해야 합니다. Linux 패키지 설치, GitLab Docker 컨테이너, Helm 차트 배포 또는 외부 데이터베이스 서비스 간에 로케일이 다를 수 있습니다. glibc 버전 호환성을 확인하는 방법을 포함하여 PostgreSQL의 운영 체제 업그레이드 문서를 참조하세요.

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

예를 들어 Ubuntu 18.04(이하)와 RHEL/CentOS 7(이하)은 이후 릴리스와 호환되지 않습니다. 자세한 내용은 PostgreSQL 위키를 참조하세요.

일반 오류 수정#

이 섹션은 웹 인터페이스의 Admin 영역에서 보고되는 일반 오류 메시지와 이를 수정하는 방법을 설명합니다.

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

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

새로운 보조 사이트를 사용하거나 Geo 보조 사이트 복제 초기화를 따라 전체 보조 사이트를 초기화하는 것이 가장 안전합니다.

보조 사이트를 초기화하지 않고 재사용하는 것은 보조 사이트가 일부 Geo 이벤트를 놓쳤을 수 있어 위험합니다. 예를 들어 놓친 삭제 이벤트는 보조 사이트에 삭제되어야 하는 데이터가 영구적으로 남아 있게 됩니다. 마찬가지로 데이터의 위치를 물리적으로 이동하는 이벤트를 잃으면 데이터가 한 위치에서 영구적으로 고아가 되고 재검증될 때까지 다른 위치에서 누락됩니다. 이것이 GitLab이 데이터 이동을 불필요하게 만드는 해시 스토리지로 전환한 이유입니다. 손실된 이벤트로 인한 다른 알려지지 않은 문제가 있을 수 있습니다.

이러한 종류의 위험이 적용되지 않는 경우(예: 테스트 환경에서, 또는 Geo 사이트가 추가된 이후 기본 Postgres 데이터베이스에 모든 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. 모든 데이터 유형에 대해 Reverify all을 선택합니다.

Geo 사이트에 쓰기 가능한 데이터베이스가 있습니다#

이 오류 메시지는 Geo가 액세스해야 하는 보조 사이트의 데이터베이스 복제본 문제를 나타냅니다. 쓰기 가능한 보조 사이트 데이터베이스는 데이터베이스가 기본 사이트와의 복제를 위해 구성되지 않았음을 나타냅니다. 일반적으로 다음 중 하나를 의미합니다:

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

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

• 기본 사이트의 읽기 전용 복제본.
• 복제 메타데이터를 보관하는 일반 쓰기 가능 인스턴스. 즉, Geo 추적 데이터베이스.

이 오류 메시지는 보조 사이트의 복제본 데이터베이스가 잘못 구성되어 복제가 중지되었음을 나타냅니다.

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

• Geo 보조 사이트 복제 초기화.
• Linux 패키지를 사용하여 새 Geo 보조 사이트 설정.

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

Geo 사이트가 기본 사이트에서 데이터베이스를 복제하지 않는 것 같습니다#

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

• 보조 사이트가 기본 사이트에 도달할 수 없습니다. 자격 증명과 방화벽 규칙을 확인합니다.
• SSL 인증서 문제. 기본 사이트에서 /etc/gitlab/gitlab-secrets.json을 복사했는지 확인합니다.
• 데이터베이스 스토리지 디스크가 가득 찼습니다.
• 데이터베이스 복제 슬롯이 잘못 구성되었습니다.
• 데이터베이스가 복제 슬롯이나 다른 대안을 사용하지 않고 WAL 파일이 제거되어 따라잡을 수 없습니다.

지원되는 구성에 대한 Geo 데이터베이스 복제 지침을 따르고 있는지 확인합니다.

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

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

• sudo gitlab-ctl reconfigure를 실행합니다.
• 보조 사이트의 root로 sudo gitlab-rake db:migrate:geo를 실행하여 수동으로 데이터베이스 마이그레이션을 트리거합니다.

GitLab이 100% 이상의 리포지토리가 동기화되었음을 나타냅니다#

이는 프로젝트 레지스트리의 고아 레코드로 인해 발생할 수 있습니다. 레지스트리 워커를 사용하여 주기적으로 정리되므로 스스로 수정될 시간을 주세요.

기본 사이트의 체크섬 실패#

Geo 기본 검증 정보 화면에서 식별된 체크섬 실패는 누락된 파일 또는 일치하지 않는 체크섬으로 인해 발생할 수 있습니다. gitlab-rails/geo.log 파일에서 "Repository cannot be checksummed because it does not exist" 또는 "File is not checksummable - file does not exist at: <path>"와 같은 오류 메시지를 찾을 수 있습니다. 오류 메시지에는 누락된 파일을 식별하는 데 도움이 되는 파일 경로가 포함됩니다.

실패한 항목에 대한 추가 정보를 얻으려면 무결성 점검 Rake 작업을 실행합니다:

sudo gitlab-rake gitlab:artifacts:check
sudo gitlab-rake gitlab:ci_secure_files:check
sudo gitlab-rake gitlab:lfs:check
sudo gitlab-rake gitlab:uploads:check

개별 오류에 대한 자세한 정보를 보려면 VERBOSE=1 변수를 사용합니다.

보조 사이트가 UI에서 Unhealthy로 표시됩니다#

기본 사이트의 /etc/gitlab/gitlab.rb에서 external_url 값을 업데이트하거나 프로토콜을 http에서 https로 변경한 경우 보조 사이트가 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 :80 (Connection refused - connect(2) for \"\" port 80)"

이 경우 모든 사이트에서 변경된 URL을 업데이트해야 합니다:

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Geo > Sites를 선택합니다.
3. URL을 변경하고 저장합니다.

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

Geo 보조 사이트에서 백업 실행은 지원되지 않습니다.

보조 사이트에서 백업을 실행하면 다음 오류 메시지가 발생할 수 있습니다:

Dumping PostgreSQL database 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 보조 사이트에서 GitLab 업그레이드 중에 데이터베이스 백업이 자동으로 생성되지 않도록 하려면 다음 빈 파일을 생성합니다:

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

객체 검증 중 기본 사이트에서 높은 CPU 사용량#

GitLab 16.11부터 GitLab 17.2까지 누락된 PostgreSQL 인덱스로 인해 높은 CPU 사용량과 느린 아티팩트 검증 진행이 발생합니다. 또한 Geo 보조 사이트가 비정상으로 보고될 수 있습니다. 이슈 471727에서 동작에 대해 자세히 설명합니다.

이 문제가 발생하는지 확인하려면 영향을 받는지 확인하는 단계를 따르세요.

영향을 받는 경우 해결 방법의 단계를 따라 수동으로 인덱스를 생성합니다. 인덱스를 생성하면 완료될 때까지 PostgreSQL이 약간 더 많은 리소스를 소비합니다. 그 후에도 검증이 계속되는 동안 CPU 사용량이 높게 유지될 수 있지만 쿼리가 훨씬 빠르게 완료되고 보조 사이트 상태가 올바르게 업데이트되어야 합니다.

검증 실패: Verification timed out after (...)#

GitLab 16.11부터 Geo는 동일한 artifact_id에 대해 중복 JobArtifactRegistry 항목을 생성할 수 있으며, 이로 인해 기본 사이트와 보조 사이트 간의 동기화 실패가 발생할 수 있습니다. 이 문제는 UploadRegistry 및 PackageFileRegistry 항목에도 영향을 미칠 수 있습니다.

이 문제가 발생하는지 확인하고 중복 항목을 제거하려면:

1. 보조 사이트에서 Rails 콘솔을 엽니다.

2. 중복이 있는 모델 레코드 ID의 수를 가져옵니다:

   artifact_ids = Geo::JobArtifactRegistry.group(:artifact_id).having('COUNT(*) > 1').pluck(:artifact_id); artifact_ids.size
   upload_ids = Geo::UploadRegistry.group(:file_id).having('COUNT(*) > 1').pluck(:file_id); upload_ids.size
   package_file_ids = Geo::PackageFileRegistry.group(:package_file_id).having('COUNT(*) > 1').pluck(:package_file_id); package_file_ids.size
   

3. ID를 출력합니다:

   puts 'BEGIN Artifact IDs', artifact_ids, 'END Artifact IDs'
   puts 'BEGIN Upload IDs', upload_ids, 'END Upload IDs'
   puts 'BEGIN Package File IDs', package_file_ids, 'END Package File IDs'
   

   출력이 비어 있으면 영향을 받지 않은 것입니다. 그렇지 않으면 나중에 연결이 끊어질 경우를 대비하여 터미널 출력을 텍스트 파일로 저장합니다.

4. 모든 중복을 삭제합니다:

   Geo::JobArtifactRegistry.where(artifact_id: artifact_ids).delete_all
   Geo::UploadRegistry.where(file_id: upload_ids).delete_all
   Geo::PackageFileRegistry.where(package_file_id: package_file_ids).delete_all
   

5. 백그라운드 작업이 레지스트리 행을 다시 생성하고 재동기화될 때까지 기다립니다.

수정에 대한 피드백을 얻으려면 이슈 479852를 팔로우합니다.

보조 사이트에서 Geo Rake 점검 작업 실행 시 end of file reached 오류#

보조 사이트에서 상태 점검 Rake 작업을 실행할 때 다음 오류가 발생할 수 있습니다:

Can connect to the primary node ... no
Reason:
end of file reached

기본 사이트에 잘못된 URL이 설정에 지정된 경우 발생할 수 있습니다. 문제를 해결하려면 Rails 콘솔에서 다음 명령을 실행합니다:

primary = Gitlab::Geo.primary_node
primary.internal_uri
Gitlab::HTTP.get(primary.internal_uri, allow_local_requests: true, limit: 10)

이전 출력에서 internal_uri의 값이 올바른지 확인합니다. 기본 사이트의 URL이 올바르지 않은 경우 /etc/gitlab/gitlab.rb와 Admin > Geo > Sites에서 다시 확인합니다.

Geo 메트릭 수집로 인한 과도한 데이터베이스 IO#

빈번한 Geo 메트릭 수집으로 인해 데이터베이스 부하가 높은 경우 geo_metrics_update_worker 작업의 빈도를 줄일 수 있습니다. 이 조정은 메트릭 수집이 데이터베이스 성능에 크게 영향을 미치는 대규모 GitLab 인스턴스에서 데이터베이스 부담을 완화하는 데 도움이 될 수 있습니다.

간격을 늘리면 Geo 메트릭이 덜 자주 업데이트됩니다. 이로 인해 메트릭이 더 오랜 기간 동안 최신 상태가 아닐 수 있으며, 이는 실시간으로 Geo 복제를 모니터링하는 능력에 영향을 미칠 수 있습니다. 메트릭이 10분 이상 최신 상태가 아닌 경우 사이트는 Admin 영역에서 "Unhealthy"로 표시됩니다.

다음 예시에서는 작업을 30분마다 실행하도록 설정합니다. 필요에 따라 cron 스케줄을 조정합니다.