Geo 일반적인 문제 해결

Tier: Premium, Ultimate Offering: Self-managed

기본 문제 해결

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

Geo 사이트의 상태를 확인하세요.
PostgreSQL 복제가 작동하는지 확인하세요.

Geo 사이트의 상태 확인

기본 사이트에서:

왼쪽 사이드바에서 아래쪽으로 이동하여 Admin을 선택합니다.
Geo > Sites을 선택합니다.

각 보조 사이트에서 다음과 같은 상태 점검을 수행하여 문제를 확인하는 데 도움을 줍니다:

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

사이트의 상태가 10분 이상 지속되면 사이트는 “이상”으로 표시됩니다. 이 경우, 영향을 받는 보조 사이트의 Rails 콘솔에서 다음을 실행해 보세요:

Geo::MetricsUpdateWorker.new.perform

만약 에러가 발생하면, 해당 에러는 아마도 작업이 완료되는 것을 막고 있을 것입니다. 10분 이상 걸린다면, 상태가 때때로 업데이트되더라도 상태가 “이상”으로 유지될 수 있습니다. 이는 이용량이 많아지거나 시간이 흐름에 따른 데이터 증가, 또는 데이터베이스 인덱스가 누락된 등의 성능 버그로 인한 것일 수 있습니다.

PostgreSQL이 상당량의 CPU를 사용하고 있다면 시스템 CPU 부하를 모니터링해야 하며, 이는 문제가 있거나 시스템이 부족할 수 있음을 나타낼 수 있습니다. 시스템 메모리 역시 모니터링되어야 합니다.

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

상태가 성공적으로 업데이트되면, 무언가 Sidekiq에 문제가 있을 수 있습니다. Sidekiq는 실행 중인가요? 로그에 오류가 표시되나요? 이 작업은 매분마다 대기열에 추가되어야 하며, 작업의 중복성 격리 키가 올바르게 지워지지 않으면 실행되지 않을 수 있습니다. 이는 Redis에서 전용 레이스를 통해 한 번에 한 작업만 실행될 수 있도록 하는 것입니다. 기본 사이트는 PostgreSQL 데이터베이스에서 상태를 직접 업데이트합니다. 보조 사이트는 상태 데이터를 기본 사이트로 HTTP POST 요청을 보내어 전송하게 됩니다.

일부 상태 확인에서 실패할 경우 사이트는 “이상”으로 표시됩니다. 영향받는 보조 사이트의 Rails 콘솔에서 다음을 실행하여 실패 사실을 확인할 수 있습니다:

Gitlab::Geo::HealthCheck.new.perform_checks

만약 ""(빈 문자열) 또는 "Healthy"가 반환된다면, 확인이 성공했음을 의미합니다. 다른 값이 반환된다면, 메시지에서 실패한 내용을 설명하거나 예외 메시지를 보여줄 것입니다.

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

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

상태 확인 Rake 작업

사용자 지정 NTP 서버의 사용은 GitLab 15.7에서 소개되었습니다.

이 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` 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

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

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

동기화 상태 Rake 작업

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

GitLab은 Object Storage에 저장된 개체를 확인하지 않습니다. Object Storage를 사용하는 경우 “확인된” 체크가 모두 0개임을 볼 수 있습니다. 이는 예상되는 동작이며 걱정할 부분이 아닙니다.

sudo gitlab-rake geo:status

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

어떤 실패가 발생했는지에 대한 “실패” 항목의 개수
“전체”에 상대적인 “성공” 항목의 백분율

예시:

http://secondary.example.com/
-----------------------------------------------------
                        GitLab 버전: 14.9.2-ee
                            Geo 역할: Secondary
                         상태: Healthy
                           프로젝트 저장소: 성공 12345 / 전체 12345 (100%)
                      프로젝트 위키 저장소: 성공 6789 / 전체 6789 (100%)
                              첨부 파일: 성공 4 / 전체 4 (100%)
                         CI 작업 아티팩트: 성공 0 / 전체 0 (0%)
                Design management 저장소: 성공 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가지 상태 항목은 다음과 같이 정의됩니다.

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

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

복제 또는 확인 실패를 발견하면 이를 해결해 보세요.

저장소 확인 실패가 있는 경우 해결해 보세요.

Geo check 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 주소에 서브넷 마스크가 포함되어 있는지 확인하세요: postgresql['md5_auth_cidr_addresses'] = ['1.1.1.1/32'].

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']에 올바른 비밀번호가 설정되어 있는지 확인하세요. 이 비밀번호는 gitlab-ctl pg-password-md5 gitlab을 실행하고 비밀번호를 입력하여 postgresql['sql_user_password']에 해시를 생성할 때 사용된 올바른 비밀번호인지 확인하세요.
검사 결과 보조 노드가 아님을 반환합니다.
```
Geo 확인 중 ...

GitLab Geo 사용 가능 ... yes
GitLab Geo 활성화됨 ... yes
GitLab Geo 추적 데이터베이스가 올바르게 구성되었습니다 ... not a secondary node
데이터베이스 복제 활성화됨? ... not a secondary node
...
Geo 확인 중 ... 완료
```
웹 인터페이스에서 기본 사이트의 관리자 > Geo > 사이트에 보조 사이트를 추가했는지 확인하세요. 또한, 기본 사이트의 관리자 영역에서 보조 사이트를 추가할 때 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 주 버전을 실행하기 시작하려면 이것은 예상 동작입니다. 관련 문서를 참조하여 업데이트해 주세요.

Rails에 Geo 추적 데이터베이스에 연결하기 위한 구성이 없어 보입니다.
```
Geo 확인 중 ...

GitLab Geo 사용 가능 ... yes
GitLab Geo 활성화됨 ... yes
GitLab Geo 추적 데이터베이스가 올바르게 구성되었습니다 ... no
해결하려면 다음을 시도하십시오:
Rails가 Geo 추적 데이터베이스에 연결하기 위한 필요한 구성을 갖추지 못한 것으로 보입니다. 추적 데이터베이스가 본 노드가 아닌 다른 노드에서 실행 중인 경우 구성을 추가해야 할 수 있습니다.
...
Geo 확인 중 ... 완료
```
- 보조 사이트의 모든 서비스를 단일 노드에서 실행 중인 경우 Geo 데이터베이스 복제 - 보조 서버 구성을 따르세요.
- 보조 사이트의 추적 데이터베이스를 고유한 노드에서 실행 중인 경우 다중 서버용 Geo - 보조 사이트의 Geo 추적 데이터베이스 구성을 따르세요.
- 보조 사이트의 추적 데이터베이스를 Patroni 클러스터에서 실행 중인 경우 Geo 데이터베이스 복제 - 추적 PostgreSQL 데이터베이스용 Patroni 클러스터 구성를 따르세요.
- 보조 사이트의 추적 데이터베이스를 외부 데이터베이스에서 실행 중인 경우 외부 PostgreSQL 인스턴스를 사용하는 Geo를 따르세요.
- 만약 gitlab-rails 앱 (퓨마, Sidekiq 또는 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 오류로 확인이 실패합니다.

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

머신 시계가 동기화되었습니다 ... Exception: getaddrinfo: Servname not supported for ai_socktype

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

이 오류가 복제본 사이트에서 발생하면 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:  cinsert할 수 없음
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는 /etc/gitlab/gitlab.rb에서 다음 로직으로 현재 Puma 또는 Sidekiq 노드의 Geo 사이트 이름을 찾습니다:

“Geo 노드 이름”을 가져옵니다 (설정을 “Geo 사이트 이름”으로 이름을 바꾸기 위한 이슈가 있습니다):
- Linux 패키지: gitlab_rails['geo_node_name'] 설정 가져오기
- GitLab Helm 차트: global.geo.nodeName 설정 가져오기 (GitLab Geo를 사용하는 차트 참조)
정의되지 않았다면 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/index.md#can-geo-detect-the-current-node-correctly

이름 필드의 권장 사이트 이름에 대한 자세한 정보는 관리 영역 공통 설정(../../../../administration/geo_sites.md#common-settings)의 이름 필드 설명을 참조하세요.

OS 로캘 데이터 호환성 확인

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

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

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

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

일반 오류 수정

이 섹션은 관리자 영역에서 보고된 일반 오류 메시지와 해당 오류를 수정하는 방법에 대한 문서입니다.

Geo 데이터베이스 구성 파일이 누락됨

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

리눅스 패키지 설치에서 해당 파일은 /var/opt/gitlab/gitlab-rails/etc에 있어야 합니다. 파일이 없거나 의도치 않게 변경된 경우 sudo gitlab-ctl reconfigure를 실행하여 올바른 상태로 복원해야 합니다.

이 경로가 원격 볼륨에 마운트된 경우 볼륨 구성이 올바른 권한을 갖도록 확인하세요.

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

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

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

보조를 재설정하지 않고 보조 사이트를 재사용하는 것은 위험합니다. 예를 들어, 누락된 삭제 이벤트는 보조 사이트에서 영구적으로 삭제해야 할 데이터를 계속 갖게 합니다. 마찬가지로, 데이터 위치를 물리적으로 이동하는 이벤트를 놓친 경우, 데이터가 다른 위치에서 영구적으로 고아 상태가 될 수 있으며, 검증되기 전까지 다른 위치에 누락될 수 있습니다. 이는 데이터 이동이 필요하지 않도록 해시 저장소로 전환한 대신 GitLab이하는 일입니다. 데이터가 누락됨으로 인한 기타 알 수 없는 문제가 있을 수 있습니다.

이러한 위험이 해당되지 않는 경우(예: 테스트 환경이거나 Geo 사이트가 추가된 이후 메인 Postgres 데이터베이스에 모든 Geo 이벤트가 여전히 있는 경우), 이 health check를 우회할 수 있습니다:

마지막 처리된 이벤트 시간을 가져옵니다. 보조 사이트에서 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는 해당 데이터베이스에 액세스할 수 있어야 합니다. 쓰기 가능한 보조 사이트 데이터베이스는 복제가 설정되지 않은 것을 나타냅니다.

데이터베이스 연결 세부 정보를 검토해보세요. 예를 들어 /etc/gitlab/gitlab.rb 파일에서 올바른 사용자를 지정했는지 확인하세요.

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

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

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

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

Geo 보조 사이트 복제 재설정.
리눅스 패키지를 사용하여 새 Geo 보조를 설정(../../setup/index.md#using-linux-package-installations).

새로운 보조를 처음부터 설정했다면, 반드시 Geo 클러스터에서 이전 사이트를 제거해야 합니다.

Geo 사이트가 주 사이트로부터 데이터베이스를 복제하는 것으로 보이지 않음

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

보조 사이트가 주 사이트에 도달할 수 없습니다. 자격 증명 및 방화벽 규칙을 확인하세요.
SSL 인증서 문제. /etc/gitlab/gitlab-secrets.json을 주 사이트에서 복사했는지 확인하세요.
데이터베이스 저장 디스크가 가득 찼습니다.
데이터베이스 복제 슬롯이 잘못 구성되었습니다.
데이터베이스가 복제 슬롯을 사용하지 않거나 다른 대체품을 사용하지 않아 WAL 파일이 삭제되어 따라 잡히지 못할 수 있습니다.

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

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

만약 Linux 패키지 설치를 사용 중이라면, 업그레이드 중에 문제가 발생했을 수 있습니다. 다음을 실행할 수 있습니다:

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

GitLab이 저장소의 100% 이상이 동기화되었다고 표시됨

프로젝트 레지스트리에서 고아 레코드가 원인일 수 있습니다. 이는 주기적으로 레지스트리 워커를 통해 정리되므로 시간을 주어 스스로 해결하도록 합니다.

보조 사이트에서 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 <PRIMARY_IP_ADDRESS>:80 (Connection refused - connect(2) for \"<PRIMARY_ID_ADDRESS>\" port 80)"

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

왼쪽 사이드바에서 아래쪽에 있는 관리자를 선택합니다.
Geo > 사이트를 선택합니다.
URL을 변경하고 변경 사항을 저장합니다.

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

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

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

PostgreSQL 데이터베이스 gitlabhq_production를 덤프하는 중...
pg_dump: error: 테이블 "notes"의 내용을 덤프하는 데 실패했습니다: PQgetResult()가 실패했습니다.
pg_dump: error: 서버에서의 오류 메시지: ERROR:  canceling statement due to conflict with recovery
DETAIL:  사용자 쿼리가 제거해야 하는 행 버전을 보아야 할 수 있습니다.
pg_dump: error: 명령은 다음과 같습니다: COPY public.notes (id, note, [...], last_edited_at) TO stdout;

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

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

객체 확인 중 기본 사이트에서 고 CPU 사용률

GitLab 16.11에서 17.2로 이동하는 동안 누락된 PostgreSQL 인덱스로 인해 고 CPU 사용률과 느린 아티팩트 확인 진행률이 발생합니다. 게다가, Geo 보조 사이트가 불량으로 표시될 수 있습니다. Issue 471727에서 이러한 동작을 자세히 설명하고 있습니다.

이 문제가 발생하는지 여부를 확인하려면, 해당 사항 확인 단계를 따릅니다.

문제가 있는 경우, 임시 방편 단계를 따라 수동으로 인덱스를 생성합니다. 인덱스를 생성하면 PostgreSQL이 완료될 때까지 약간 더 많은 리소스를 사용합니다. 그 후에 CPU 사용률은 여전히 높을 수 있지만, 쿼리가 훨씬 빨리 완료되고 보조 사이트 상태가 올바르게 업데이트될 것입니다.

보조에서 Geo Rake check 작업 실행 시 `end of file reached` 오류

보조 사이트에서 health check Rake task를 실행할 때 다음과 같은 오류가 발생할 수 있습니다:

기본 노드에 연결할 수 있음... 아니요
이유:
end of file reached

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

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 check Rake 작업을 실행할 때 발견된 오류 수정

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

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

PostgreSQL 복제가 작동하는지 확인

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

Geo가 현재 사이트를 올바르게 감지하는지?

OS 로캘 데이터 호환성 확인

일반 오류 수정

Geo 데이터베이스 구성 파일이 누락됨

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

Geo 사이트에 쓰기 가능한 데이터베이스

Geo 사이트가 주 사이트로부터 데이터베이스를 복제하는 것으로 보이지 않음

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

GitLab이 저장소의 100% 이상이 동기화되었다고 표시됨

보조 사이트에서 UI에 “Unhealthy” 표시

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

객체 확인 중 기본 사이트에서 고 CPU 사용률

보조에서 Geo Rake check 작업 실행 시 `end of file reached` 오류

도움말

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

도움받기

Geo 일반적인 문제 해결

기본 문제 해결

Geo 사이트의 상태 확인

상태 확인 Rake 작업

동기화 상태 Rake 작업

Geo check Rake 작업을 실행할 때 발견된 오류 수정

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

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

PostgreSQL 복제가 작동하는지 확인

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

Geo가 현재 사이트를 올바르게 감지하는지?

OS 로캘 데이터 호환성 확인

일반 오류 수정

Geo 데이터베이스 구성 파일이 누락됨

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

Geo 사이트에 쓰기 가능한 데이터베이스

Geo 사이트가 주 사이트로부터 데이터베이스를 복제하는 것으로 보이지 않음

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

GitLab이 저장소의 100% 이상이 동기화되었다고 표시됨

보조 사이트에서 UI에 “Unhealthy” 표시

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

객체 확인 중 기본 사이트에서 고 CPU 사용률

보조에서 Geo Rake check 작업 실행 시 end of file reached 오류

도움말

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

도움받기

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

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

보조에서 Geo Rake check 작업 실행 시 `end of file reached` 오류