일반적인 Geo 오류 문제 해결

Tier: Premium, Ultimate Offering: Self-managed

기본 문제 해결

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

Geo 사이트의 상태 확인.
PostgreSQL 복제 작동 여부 확인.

Geo 사이트의 상태 확인

주 서버에서:

왼쪽 사이드바의 하단에서 Admin을 선택합니다.
Geo > Sites를 선택합니다.

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

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

사이트의 상태가 10분 이상 경과하면 “비정상”으로 표시됩니다. 이 경우, 문제 있는 보조 사이트에서 Rails 콘솔에서 다음을 실행해 보세요:

Geo::MetricsUpdateWorker.new.perform

오류가 발생하면, 이 오류가 작업 완료를 방해하고 있을 가능성이 높습니다. 10분 이상 소요되면, 상태가 이런저런 통계적으로 업데이트되더라도 “비정상” 상태로 계속 남아있을 수 있습니다. 이는 사용량 증가, 시간이 지남에 따른 데이터 증가 또는 누락된 데이터베이스 인덱스와 같은 성능 버그 때문일 수 있습니다.

top 또는 htop과 같은 유틸리티로 시스템 CPU 부하를 모니터링할 수 있습니다. PostgreSQL이 상당한 양의 CPU를 사용하고 있다면, 이는 문제가 있거나 시스템이 과소 제공되고 있다는 것을 나타낼 수 있습니다. 시스템 메모리도 모니터링해야 합니다.

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

상태 업데이트가 성공적으로 이루어지면, Sidekiq에 문제가 있을 수 있습니다. 실행 중인가요? 로그에 오류가 표시되나요? 이 작업은 매분 큐에 넣어야 하며, 작업 중복 제거 무결성 키가 올바르게 지워지지 않으면 실행되지 않을 수 있습니다. 이 작업은 Redis에서 독점적인 잠금을 얻어야 하며, 이를 통해 이러한 작업 중 하나만 실행될 수 있습니다. 주 사이트는 PostgreSQL 데이터베이스에 직접 상태를 업데이트합니다. 보조 사이트는 상태 데이터를 포함하는 HTTP Post 요청을 주 사이트에 전송합니다.

특정 건강 검사가 실패하면 사이트도 “비정상”으로 표시됩니다. 문제 있는 보조 사이트에서 Rails 콘솔에서 다음을 실행하여 실패 원인을 확인할 수 있습니다:

Gitlab::Geo::HealthCheck.new.perform_checks

""(빈 문자열) 또는 "Healthy"를 반환하면, 검사가 성공적으로 완료된 것입니다. 다른 결과를 반환하면, 오류가 발생한 원인을 설명하거나 예외 메시지를 표시해야 합니다.

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

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

헬스 체크 Rake 작업

GitLab 15.7에서 맞춤형 NTP 서버가 도입되었습니다.

이 Rake 작업은 primary 또는 secondary 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` Ruby 라이브러리에서 정의된 값 (60 seconds).

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은 객체 저장소에 저장된 객체를 검증하지 않습니다. 객체 저장소를 사용 중인 경우, 모든 “검증됨” 체크가 0 성공을 표시하게 됩니다. 이는 예상되는 결과이며 걱정할 필요가 없습니다.

sudo gitlab-rake geo:status

출력은 다음을 포함합니다:

실패한 항목의 수(실패가 발생한 경우)
“총 수”에 대한 “성공한” 항목의 비율

예시:

http://secondary.example.com/
-----------------------------------------------------
                        GitLab 버전: 14.9.2-ee
                              Geo 역할: 보조
                         건강 상태: 건강함
                  프로젝트 리포지토리: 성공 12345 / 총 12345 (100%)
             프로젝트 위키 리포지토리: 성공 6789 / 총 6789 (100%)
                           첨부파일: 성공 4 / 총 4 (100%)
                      CI 작업 아티팩트: 성공 0 / 총 0 (0%)
        디자인 관리 리포지토리: 성공 1 / 총 1 (100%)
                           LFS 객체: 실패 1 / 성공 2 / 총 3 (67%)
                   병합 요청 차이: 성공 0 / 총 0 (0%)
                         패키지 파일: 실패 1 / 성공 2 / 총 3 (67%)
              Terraform 상태 버전: 실패 1 / 성공 2 / 총 3 (67%)
                  스니펫 리포지토리: 실패 1 / 성공 2 / 총 3 (67%)
               그룹 위키 리포지토리: 성공 4 / 총 4 (100%)
                    파이프라인 아티팩트: 실패 3 / 성공 0 / 총 3 (0%)
                     페이지 배포: 성공 0 / 총 0 (0%)
                  검사된 리포지토리: 실패 5 / 성공 0 / 총 5 (0%)
                패키지 파일 검증됨: 성공 0 / 총 10 (0%)
     Terraform 상태 버전 검증됨: 성공 0 / 총 10 (0%)
         스니펫 리포지토리 검증됨: 성공 99 / 총 100 (99%)
           파이프라인 아티팩트 검증됨: 성공 0 / 총 10 (0%)
         프로젝트 리포지토리 검증됨: 성공 12345 / 총 12345 (100%)
    프로젝트 위키 리포지토리 검증됨: 성공 6789 / 총 6789 (100%)
                         동기화 설정: 전체
              데이터베이스 복제 지연: 0초
       기본에서 본 마지막 이벤트 ID: 12345 (약 2분 전)
               마지막으로 처리된 이벤트 ID: 12345 (약 2분 전)
                마지막 상태 보고서는: 1분 전

각 항목은 최대 세 가지 상태를 가질 수 있습니다. 예를 들어, 프로젝트 리포지토리에 대해 다음과 같은 줄을 볼 수 있습니다:

  프로젝트 리포지토리: 성공 12345 / 총 12345 (100%)
  프로젝트 검증된 리포지토리: 성공 12345 / 총 12345 (100%)
  검사된 리포지토리: 실패 5 / 성공 0 / 총 5 (0%)

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

프로젝트 리포지토리 출력은 기본에서 보조로 동기화된 프로젝트 리포지토리 수를 보여줍니다.
프로젝트 검증된 리포지토리 출력은 이 보조에서 기본과 체크섬이 일치하는 프로젝트 리포지토리 수를 보여줍니다.
검사된 리포지토리 출력은 보조에서 로컬 Git 리포지토리 체크(git fsck)를 통과한 프로젝트 리포지토리 수를 보여줍니다.

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

복제 또는 검증 실패가 발생하는 경우, 이를 해결해보세요.

리포지토리 검사 실패가 있는 경우, 이를 해결해보세요.

Geo 체크 Rake 작업 실행 시 발견된 오류 수정

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

sudo gitlab-rake gitlab:geo:check

Rails는 데이터베이스에 연결할 때 비밀번호를 제공하지 않았습니다.
```
Geo 확인 중 ...

GitLab Geo가 사용 가능합니다 ... 예외: fe_sendauth: 비밀번호가 제공되지 않음
GitLab Geo가 활성화되었습니다 ... 예외: fe_sendauth: 비밀번호가 제공되지 않음
...
Geo 확인 중 ... 완료
```
gitlab_rails['db_password']가 postgresql['sql_user_password']의 해시를 생성할 때 사용된 평문 비밀번호로 설정되어 있는지 확인하세요.

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

Geo 확인 중 ...

GitLab Geo가 사용 가능합니다 ... 예외: FATAL:  "1.1.1.1" 호스트에 대한 pg_hba.conf 항목이 없습니다, 사용자 "gitlab", 데이터베이스 "gitlabhq_production", SSL 켜짐
FATAL:  "1.1.1.1" 호스트에 대한 pg_hba.conf 항목이 없습니다, 사용자 "gitlab", 데이터베이스 "gitlabhq_production", SSL 꺼짐
GitLab Geo가 활성화되었습니다 ... 예외: FATAL:  "1.1.1.1" 호스트에 대한 pg_hba.conf 항목이 없습니다, 사용자 "gitlab", 데이터베이스 "gitlabhq_production", SSL 켜짐
FATAL:  "1.1.1.1" 호스트에 대한 pg_hba.conf 항목이 없습니다, 사용자 "gitlab", 데이터베이스 "gitlabhq_production", SSL 꺼짐
...
Geo 확인 중 ... 완료

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

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

Geo 확인 중 ...
GitLab Geo가 사용 가능합니다 ... 예외: FATAL:  사용자 "gitlab"에 대한 비밀번호 인증 실패
FATAL:  사용자 "gitlab"에 대한 비밀번호 인증 실패
GitLab Geo가 활성화되었습니다 ... 예외: FATAL:  사용자 "gitlab"에 대한 비밀번호 인증 실패
FATAL:  사용자 "gitlab"에 대한 비밀번호 인증 실패
...
Geo 확인 중 ... 완료

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

체크 결과 not a secondary node로 반환됩니다.

Geo 확인 중 ...

GitLab Geo가 사용 가능합니다 ... 예
GitLab Geo가 활성화되었습니다 ... 예
GitLab Geo 추적 데이터베이스가 올바르게 구성되어 있습니다 ... not a secondary node
데이터베이스 복제 활성화됨? ... not a secondary node
...
Geo 확인 중 ... 완료

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

체크 결과 Exception: PG::UndefinedTable: ERROR: relation "geo_nodes" does not exist로 반환됩니다.

Geo 확인 중 ...

GitLab Geo가 사용 가능합니다 ... 아니요
  해결 방법 시도:
  GitLab Geo 기능이 포함된 새 라이센스를 추가하세요
  자세한 내용은 다음을 참조하세요:
  https://about.gitlab.com/features/gitlab-geo/
GitLab Geo가 활성화되었습니다 ... 예외: 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가 사용 가능합니다 ... 예
GitLab Geo가 활성화되었습니다 ... 예
GitLab Geo 추적 데이터베이스가 올바르게 구성되어 있습니다 ... 아니요
해결 방법 시도:
Rails는 Geo 추적 데이터베이스에 연결하는 데 필요한 구성이 없는 것으로 보입니다. 추적 데이터베이스가 이 노드가 아닌 노드에서 실행 중이라면 구성을 추가해야 할 수 있습니다.
...
Geo 확인 중 ... 완료
```
- 모든 서비스에 대해 단일 노드에서 보조 사이트를 실행하는 경우 Geo 데이터베이스 복제 - 보조 서버 구성을 따르세요.
- 보조 사이트의 추적 데이터베이스를 별도의 노드에서 실행하는 경우 여러 서버에 대한 Geo - Geo 보조 사이트에서 Geo 추적 데이터베이스 구성을 따르세요.
- 보조 사이트의 추적 데이터베이스가 Patroni 클러스터에서 실행 중인 경우 Geo 데이터베이스 복제 - 추적 PostgreSQL 데이터베이스를 위한 Patroni 클러스터 구성을 따르세요.
- 보조 사이트의 추적 데이터베이스가 외부 데이터베이스에서 실행 중인 경우 Geo 외부 PostgreSQL 인스턴스를 따르세요.
- Geo 체크 작업이 GitLab Rails 앱(Puma, Sidekiq 또는 Geo Log Cursor)을 실행하는 서비스가 아닌 노드에서 실행된 경우, 이 오류는 무시해도 됩니다. Rails를 구성할 필요가 없습니다.

메시지: 머신 시계가 동기화되었습니다 … 예외

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 오류로 검사가 실패합니다.

클라우드 네이티브 GitLab 배포에서는
Kubernetes의 컨테이너가 호스트 시계에 접근할 수 없기 때문에 오류를 생성합니다:

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

메시지: `읽기 전용 트랜잭션에서 INSERT를 실행할 수 없습니다`

이 오류가 보조 사이트에서 발생할 때, gitlab-rails 또는 gitlab-rake 명령과 같은 모든 GitLab Rails의 사용에 영향을 미칠 가능성이 높습니다.
또한 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가 현재 사이트를 정확하게 감지할 수 있는지 확인?

Geo는 현재 Puma 또는 Sidekiq 노드의 Geo 사이트 이름을 다음 논리를 통해 /etc/gitlab/gitlab.rb에서 찾습니다:

“Geo 노드 이름” 가져오기 (설정을 “Geo 사이트 이름”으로 변경하는 문제가 있습니다):
- 리눅스 패키지: gitlab_rails['geo_node_name'] 설정 가져오기.
- GitLab Helm 차트: global.geo.nodeName 설정 가져오기 (탐색할 GitLab Geo와 함께하는 차트).
정의되지 않은 경우, external_url 설정을 가져옵니다.

이 이름은 Geo Sites 대시보드에서 동일한 이름의 Geo 사이트를 조회하는 데 사용됩니다.

현재 머신에 데이터베이스의 사이트와 일치하는 사이트 이름이 있는지 확인하려면 체크 작업을 실행하세요:

sudo gitlab-rake gitlab:geo:check

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

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

이 머신의 Geo 노드 이름이 데이터베이스 레코드와 일치하지 않습니다 ... 아니요
  수정해 보세요:
  Geo 노드 데이터베이스 레코드를 추가하거나 업데이트하여 이름을 "https://example.com/"로 설정할 수 있습니다.
  또는 이 머신의 Geo 노드 이름을 기존 데이터베이스 레코드의 이름인 "런던", "상하이"와 일치하도록 설정할 수 있습니다.
  자세한 내용은 다음을 참조하세요:
  doc/administration/geo/replication/troubleshooting/index.md#can-geo-detect-the-current-node-correctly

이름 필드 설명의 권장 사이트 이름에 대한 자세한 내용은 Geo 관리자 영역 일반 설정을 참조하세요.

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

가능한 모든 Geo 노드는 모든 사이트에서 동일한 방법과 운영 체제로 배포되어야 하며, 이는 Geo 실행 요구 사항에 정의되어 있습니다.

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

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

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

일반적인 오류 수정

이 섹션에서는 웹 인터페이스의 관리자 영역에서 보고된 일반적인 오류 메시지와 이를 수정하는 방법을 문서화합니다.

Geo 데이터베이스 구성 파일이 없습니다

GitLab이 database_geo.yml 구성 파일을 찾을 수 없거나 접근 권한이 없습니다.

Linux 패키지 설치에서는 해당 파일이 /var/opt/gitlab/gitlab-rails/etc에 있어야 합니다.

존재하지 않거나 실수로 변경된 경우 sudo gitlab-ctl reconfigure를 실행하여 올바른 상태로 복원합니다.

이 경로가 원격 볼륨에 탑재된 경우, 볼륨 구성에 올바른 권한이 있는지 확인하세요.

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

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

신선한 보조 데이터를 사용하는 것이 가장 안전하며, Geo 보조 사이트 복제를 초기화하는 방법으로 전체 보조를 초기화합니다.

보조 사이트를 초기화하지 않고 재사용하는 것은 위험한데, 보조 사이트가 일부 Geo 이벤트를 놓쳤을 수 있기 때문입니다.

예를 들어, 삭제 이벤트를 놓치면 보조 사이트에 삭제되어야 할 데이터가 영구적으로 남게 됩니다.

마찬가지로, 데이터의 위치를 물리적으로 이동시키는 이벤트를 잃어버리면 한 위치에 데이터가 영구적으로 고아가 되고, 다른 위치에서는 누락됩니다.

이런 이유로 GitLab은 해시된 저장소로 전환했습니다.

이 방법은 데이터를 이동시킬 필요가 없어지기 때문입니다.

사라진 이벤트로 인한 다른 알 수 없는 문제가 있을 수 있습니다.

이런 종류의 위험이 적용되지 않는 경우(예: 테스트 환경에서 발생하는 경우) 또는 Geo 사이트가 추가된 이후에 주요 Postgres 데이터베이스에 모든 Geo 이벤트가 여전히 포함되어 있다는 것을 알고 있는 경우, 이 건강 검사를 우회할 수 있습니다:

마지막 처리된 이벤트 시간을 가져옵니다. 보조 사이트의 Rails 콘솔에서 다음을 실행합니다:
```
Geo::EventLogState.last.created_at.utc  
```
출력을 복사합니다. 예: 2024-02-21 23:50:50.676918 UTC.
보조 사이트의 생성 시간을 업데이트하여 더 오래되게 만듭니다. 주요 사이트의 Rails 콘솔에서 다음을 실행합니다:
```
GeoNode.secondary_nodes.last.update_column(:created_at, DateTime.parse('2024-02-21 23:50:50.676918 UTC') - 1.second)  
```
이 명령은 영향을 받는 보조 사이트가 마지막으로 생성된 것이라고 가정합니다.
관리자 > Geo > 사이트에서 보조 사이트의 상태를 업데이트합니다. 보조 사이트의 Rails 콘솔에서 다음을 실행합니다:
```
Geo::MetricsUpdateWorker.new.perform  
```
보조 사이트가 정상으로 나타나야 합니다. 그렇지 않으면 보조 사이트에서 gitlab-rake gitlab:geo:check를 실행하거나, 보조 사이트를 다시 추가한 이후에 초기화하지 않았다면 Rails를 다시 시작해 보세요.
누락되거나 오래된 데이터를 다시 동기화하려면 관리자 > Geo > 사이트로 이동합니다.
보조 사이트 아래에서 복제 세부 정보를 선택합니다.
모든 데이터 유형에 대해 모두 재검증을 선택합니다.

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

이 오류 메시지는 보조 사이트의 데이터베이스 복제본에 문제가 있음을 나타내며, Geo는 접근할 수 있어야 합니다.

쓰기 가능한 보조 사이트 데이터베이스는 데이터베이스가 주요 사이트와의 복제를 위해 구성되지 않았음을 나타냅니다.

보통 다음을 의미합니다:

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

Geo 보조 사이트는 두 개의 분리된 PostgreSQL 인스턴스가 필요합니다:

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

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

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

전혀 새로운 보조 사이트를 처음부터 설정하면 Geo 클러스터에서 기존 사이트를 제거해야 합니다.

Geo 사이트가 기본 사이트에서 데이터베이스를 복제하지 않는 경우

데이터베이스의 올바른 복제를 방해하는 가장 일반적인 문제는 다음과 같습니다:

Secondary 사이트가 primary 사이트에 도달할 수 없습니다. 자격 증명과 방화벽 규칙을 확인하세요.
SSL 인증서 문제. primary 사이트에서 /etc/gitlab/gitlab-secrets.json을 복사했는지 확인하세요.
데이터베이스 저장 디스크가 가득 찼습니다.
데이터베이스 복제 슬롯이 잘못 구성되었습니다.
데이터베이스가 복제 슬롯이나 다른 대안을 사용하지 않으며 WAL 파일이 삭제되었기 때문에 따라잡을 수 없습니다.

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

Geo 데이터베이스 버전 (…)이 최신 마이그레이션 (…)과 일치하지 않음

Linux 패키지 설치를 사용하는 경우, 업그레이드 중 실패한 것이 있을 수 있습니다. 다음을 수행할 수 있습니다:

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

GitLab이 100% 이상의 리포지토리가 동기화되었다고 표시함

이는 프로젝트 레지스트리에 고아 레코드가 있을 경우 발생할 수 있습니다. 이러한 레코드는 정기적으로 레지스트리 작업자를 사용하여 정리되므로, 스스로 수정될 때까지 잠시 기다리세요.

UI에서 “Unhealthy” 상태를 표시하는 Secondary 사이트

기본 사이트의 /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을 업데이트하세요:

왼쪽 사이드바에서 아래쪽에서 Admin을 선택합니다.
Geo > Sites를 선택합니다.
URL을 변경하고 변경 내용을 저장합니다.

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

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

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

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 secondary에서 GitLab 업그레이드 중 자동으로 백업이 생성되는 것을 방지하기 위해, 다음과 같은 빈 파일을 생성하세요:

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

객체 검증 중 기본 사이트의 CPU 사용량이 높음

GitLab 16.11에서 GitLab 17.2까지, 누락된 PostgreSQL 인덱스가 높은 CPU 사용량과 느린 아티팩트 검증 진행 속도를 유발합니다. 또한, Geo secondary 사이트가 비정상으로 보고될 수 있습니다. 문제 471727에서는 이러한 동작을 자세히 설명합니다.

이 문제로 영향을 받고 있는지 확인하려면 영향을 받는지 확인하는 단계를 따르세요.

영향을 받는 경우, 우회 방법에서 인덱스를 수동으로 생성하는 단계를 따르세요. 인덱스를 생성하면 PostgreSQL이 완료될 때까지 약간 더 많은 리소스를 소비하게 됩니다. 이후 CPU 사용량이 높게 유지되더라도 쿼리는 훨씬 더 빠르게 완료되어야 하며, secondary 사이트 상태는 올바르게 업데이트되어야 합니다.

`end of file reached` 오류가 발생했을 때 Geo Rake 체크 작업 실행 중 보조 사이트에서

보조 사이트에서 헬스 체크 Rake 작업을 실행할 때 다음 오류가 발생할 수 있습니다:

기본 노드에 연결할 수 없습니다 ... 아니오
이유:
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와 관리자 > Geo > 사이트에서 다시 확인하세요.

일반적인 Geo 오류 문제 해결

기본 문제 해결

Geo 사이트의 상태 확인

헬스 체크 Rake 작업

동기화 상태 Rake 작업

Geo 체크 Rake 작업 실행 시 발견된 오류 수정

메시지: 머신 시계가 동기화되었습니다 … 예외

메시지: `읽기 전용 트랜잭션에서 INSERT를 실행할 수 없습니다`

PostgreSQL 복제 작동 여부 확인

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

Geo가 현재 사이트를 정확하게 감지할 수 있는지 확인?

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

일반적인 오류 수정

Geo 데이터베이스 구성 파일이 없습니다

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

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

Geo 사이트가 기본 사이트에서 데이터베이스를 복제하지 않는 경우

Geo 데이터베이스 버전 (…)이 최신 마이그레이션 (…)과 일치하지 않음

GitLab이 100% 이상의 리포지토리가 동기화되었다고 표시함

UI에서 “Unhealthy” 상태를 표시하는 Secondary 사이트

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

객체 검증 중 기본 사이트의 CPU 사용량이 높음

`end of file reached` 오류가 발생했을 때 Geo Rake 체크 작업 실행 중 보조 사이트에서

도움말

기능 사용 가능성과 제품 평가판

도움받기

일반적인 Geo 오류 문제 해결

기본 문제 해결

Geo 사이트의 상태 확인

헬스 체크 Rake 작업

동기화 상태 Rake 작업

Geo 체크 Rake 작업 실행 시 발견된 오류 수정

메시지: 머신 시계가 동기화되었습니다 … 예외

메시지: 읽기 전용 트랜잭션에서 INSERT를 실행할 수 없습니다

PostgreSQL 복제 작동 여부 확인

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

Geo가 현재 사이트를 정확하게 감지할 수 있는지 확인?

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

일반적인 오류 수정

Geo 데이터베이스 구성 파일이 없습니다

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

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

Geo 사이트가 기본 사이트에서 데이터베이스를 복제하지 않는 경우

Geo 데이터베이스 버전 (…)이 최신 마이그레이션 (…)과 일치하지 않음

GitLab이 100% 이상의 리포지토리가 동기화되었다고 표시함

UI에서 “Unhealthy” 상태를 표시하는 Secondary 사이트

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

객체 검증 중 기본 사이트의 CPU 사용량이 높음

end of file reached 오류가 발생했을 때 Geo Rake 체크 작업 실행 중 보조 사이트에서

도움말

기능 사용 가능성과 제품 평가판

도움받기

메시지: `읽기 전용 트랜잭션에서 INSERT를 실행할 수 없습니다`

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

`end of file reached` 오류가 발생했을 때 Geo Rake 체크 작업 실행 중 보조 사이트에서