다음 섹션에서는 복제 오류 메시지를 해결하기 위한 문제 해결 단계를 설명합니다(오류는 geo:check 출력에 Database replication working? ... no로 표시됩니다). 여기에 제시된 지침은 대부분 단일 노드 Geo Linux 패키지 배포를 가정하며, 환경에 따라 조정이 필요할 수 있습니다.

비활성 복제 슬롯 제거#

슬롯에 연결된 복제 클라이언트(보조 사이트)가 연결을 끊으면 복제 슬롯이 '비활성'으로 표시됩니다. 비활성 복제 슬롯은 WAL 파일을 계속 보존합니다. 클라이언트가 다시 연결하면 해당 파일이 전송되고 슬롯이 다시 활성화되기 때문입니다. 보조 사이트가 다시 연결할 수 없다면 다음 단계로 해당 비활성 복제 슬롯을 제거합니다.

1. Geo 기본 사이트의 데이터베이스 노드에서 PostgreSQL 콘솔 세션을 시작합니다.

   sudo gitlab-psql -d gitlabhq_production
   

   [!note] 복제 슬롯 관리에는 슈퍼유저 권한이 필요하므로 gitlab-rails dbconsole을 사용하면 동작하지 않습니다.

2. 복제 슬롯을 확인하고 비활성 상태이면 제거합니다.

   SELECT * FROM pg_replication_slots;
   

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

• 해당 슬롯을 사용하는 보조 사이트가 구성되어 있어 이 슬롯이 활성 상태여야 하는 경우:

  • 보조 사이트의 PostgreSQL 로그에서 복제가 실행되지 않는 이유를 확인합니다.

  • 보조 사이트가 더 이상 다시 연결할 수 없는 경우:

    1. PostgreSQL 콘솔 세션으로 슬롯을 제거합니다.

       SELECT pg_drop_replication_slot('<name_of_inactive_slot>');
       

    2. 복제 프로세스를 다시 시작하면 복제 슬롯이 올바르게 다시 생성됩니다.

• 슬롯을 더 이상 사용하지 않는다면(예를 들어 Geo를 더 이상 활성화하지 않는 경우) 해당 Geo 사이트를 제거하는 단계를 따릅니다.

메시지: WARNING: oldest xmin is far in the past 및 pg_wal 크기 증가#

복제 슬롯이 비활성 상태이면 해당 슬롯의 pg_wal 로그가 영구적으로 (또는 슬롯이 다시 활성화될 때까지) 보존됩니다. 이로 인해 디스크 사용량이 계속 증가하고 PostgreSQL 로그에 다음 메시지가 반복해서 나타납니다.

WARNING: oldest xmin is far in the past
HINT: Close open transactions soon to avoid wraparound problems.
You might also need to commit or roll back old prepared transactions, or drop stale replication slots.

이 문제를 해결하려면 비활성 복제 슬롯을 제거하고 복제를 다시 시작합니다.

메시지: ERROR: replication slots can only be used if max_replication_slots > 0#

이 메시지는 기본 데이터베이스에 max_replication_slots PostgreSQL 변수를 설정해야 한다는 뜻입니다. 이 설정의 기본값은 1입니다. 보조 사이트가 더 많다면 이 값을 늘려야 할 수 있습니다.

변경 사항이 적용되도록 PostgreSQL을 재시작해야 합니다. 자세한 내용은 PostgreSQL 복제 설정 가이드를 참고합니다.

메시지: replication slot "geo_secondary_my_domain_com" does not exist#

이 오류는 PostgreSQL에 해당 이름의 보조 사이트용 복제 슬롯이 없을 때 발생합니다.

FATAL:  could not start WAL streaming: ERROR:  replication slot "geo_secondary_my_domain_com" does not exist

보조 사이트에서 복제 프로세스를 다시 실행하는 방법을 고려합니다.

메시지: 복제 설정 중 Command exceeded allowed execution time#

이 메시지는 보조 사이트에서 복제 프로세스를 시작할 때 나타날 수 있으며, 초기 데이터세트가 너무 커서 기본 타임아웃(30분) 안에 복제할 수 없음을 나타냅니다.

gitlab-ctl replicate-geo-database를 다시 실행하되 --backup-timeout에 더 큰 값을 지정합니다.

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

이렇게 하면 초기 복제에 기본값 30분 대신 최대 6시간이 주어집니다. 설치 환경에 맞게 조정합니다.

메시지: PANIC: could not write to file 'pg_xlog/xlogtemp.123': No space left on device#

기본 데이터베이스에 사용하지 않는 복제 슬롯이 있는지 확인합니다. 이 슬롯 때문에 pg_xlog에 대량의 로그 데이터가 쌓일 수 있습니다.

비활성 슬롯을 제거하면 pg_xlog가 사용하는 공간을 줄일 수 있습니다.

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

이 오류 메시지는 일반적인 사용 환경에서는 드물게 나타나며, 시스템이 스스로 복구할 만큼 복원력을 갖추고 있습니다.

다만 특정 조건에서는 보조 사이트의 일부 데이터베이스 쿼리가 지나치게 오래 실행되어 이 오류 메시지의 빈도가 높아질 수 있습니다. 이 경우 복제할 때마다 쿼리가 취소되어 일부 쿼리가 끝내 완료되지 않는 상황이 생길 수 있습니다.

이처럼 장시간 실행되는 쿼리는 향후 제거될 예정이지만, 임시 해결책으로 hot_standby_feedback 활성화를 권장합니다. 이 설정은 VACUUM 이 최근 삭제된 행을 제거하지 못하게 하므로 기본 사이트에서 블로트가 발생할 가능성이 높아집니다. 다만 GitLab.com의 운영 환경에서 문제없이 사용해 왔습니다.

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

postgresql['hot_standby_feedback'] = 'on'

그런 다음 GitLab을 재구성합니다.

sudo gitlab-ctl reconfigure

이 문제 해결에 도움을 주려면 해당 이슈에 의견을 남기는 방법을 고려합니다.

메시지: server certificate for "PostgreSQL" does not match host name#

다음 오류가 나타나는 경우가 있습니다.

FATAL:  could not connect to the primary server: server certificate for "PostgreSQL" does not match host name

이 문제는 Linux 패키지가 자동으로 생성하는 PostgreSQL 인증서의 Common Name이 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: invalid CIDR mask in address#

이 메시지는 postgresql['md5_auth_cidr_addresses']에 잘못된 형식의 주소가 있을 때 나타납니다.

2020-03-20_23:59:57.60499 LOG:  invalid CIDR mask in address "***"
2020-03-20_23:59:57.60501 CONTEXT:  line 74 of configuration file "/var/opt/gitlab/postgresql/data/pg_hba.conf"

이 문제를 해결하려면 /etc/gitlab/gitlab.rb의 postgresql['md5_auth_cidr_addresses'] 아래 IP 주소를 CIDR 형식(예를 들어 10.0.0.1/32)에 맞게 수정합니다.

메시지: LOG: invalid IP mask "md5": Name or service not known#

이 메시지는 postgresql['md5_auth_cidr_addresses']에 서브넷 마스크 없이 IP 주소를 추가했을 때 나타납니다.

2020-03-21_00:23:01.97353 LOG:  invalid IP mask "md5": Name or service not known
2020-03-21_00:23:01.97354 CONTEXT:  line 75 of configuration file "/var/opt/gitlab/postgresql/data/pg_hba.conf"

이 문제를 해결하려면 /etc/gitlab/gitlab.rb의 postgresql['md5_auth_cidr_addresses'] 아래에 서브넷 마스크를 추가하여 CIDR 형식(예를 들어 10.0.0.1/32)에 맞춥니다.

메시지: Found data in the gitlabhq_production database#

gitlab-ctl replicate-geo-database를 실행할 때 Found data in the gitlabhq_production database! 오류가 나타나면 projects 테이블에서 데이터가 감지된 것입니다. 하나 이상의 프로젝트가 감지되면 실수로 인한 데이터 손실을 막기 위해 작업이 중단됩니다. 이 메시지를 우회하려면 명령에 --force 옵션을 전달합니다.

메시지: FATAL: could not map anonymous shared memory: Cannot allocate memory#

이 메시지가 나타나면 보조 사이트의 PostgreSQL이 사용 가능한 메모리보다 큰 메모리를 요청했다는 뜻입니다. 이 문제는 이슈에서 추적하고 있습니다.

Patroni 로그(Linux 패키지 설치의 경우 /var/log/gitlab/patroni/current)에 나타나는 오류 메시지 예시는 다음과 같습니다.

2023-11-21_23:55:18.63727 FATAL:  could not map anonymous shared memory: Cannot allocate memory
2023-11-21_23:55:18.63729 HINT:  This error usually means that PostgreSQL's request for a shared memory segment exceeded available memory, swap space, or huge pages. To reduce the request size (currently 17035526144 bytes), reduce PostgreSQL's shared memory usage, perhaps by reducing shared_buffers or max_connections.

임시 해결책은 보조 사이트 PostgreSQL 노드의 가용 메모리를 기본 사이트 PostgreSQL 노드의 메모리 요구 사항에 맞게 늘리는 것입니다.

오류: could not open certificate file "/root/.postgresql/postgresql.crt"#

gitlab-ctl replicate-geo-database를 실행하면 다음 오류 중 하나가 나타날 수 있습니다.

could not open certificate file "/root/.postgresql/postgresql.crt": Permission denied

could not open certificate file "/root/.postgresql/postgresql.crt": No such file or directory

이 문제는 gitlab-ctl replicate-geo-database가 root로 실행되고, 이 명령이 내부적으로 호출하는 pg_basebackup 이 SSL CA 인증서를 /root/.postgresql/root.crt에서 찾기 때문에 발생합니다. 이 인증서는 sslmode=verify-ca 또는 sslmode=verify-full을 사용할 때 필요합니다.

이 문제를 해결하려면 다음 단계를 수행합니다.

1. 보조 사이트의 root 사용자용으로도 인증서를 설치합니다. 기본 사이트에서 복사한 것과 동일한 server.crt 파일을 사용합니다.

   install \
      -D \
      -o root \
      -g root \
      -m 0400 \
      -T server.crt /root/.postgresql/root.crt
   

2. 복제 명령을 다시 실행합니다.

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

sudo gitlab-rake gitlab: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 바이트가 스토리지에 성공적으로 저장되었으나 데이터베이스 시스템이 재생하지 못했음을 나타냅니다.

Message: pg_basebackup: initiating base backup, waiting for checkpoint to complete에서 중단#

초기 복제가 Message: pg_basebackup: initiating base backup, waiting for checkpoint to complete에서 멈춘다면, 기본 Geo 사이트가 실제로 사용되지 않고 있다는 뜻입니다. 주로 비운영 GitLab 서버나 새로 설치한 GitLab에서 발생합니다.

임시 해결책은 데이터베이스 쓰기를 발생시키는 것입니다. 예를 들어 기본 사이트에 로그인하여 이슈와 댓글을 몇 개 생성할 수 있습니다.

다른 방법으로는 기본 사이트의 데이터베이스에서 CHECKPOINT; SQL 쿼리를 실행합니다.

sudo gitlab-psql -xc 'CHECKPOINT;'