GitLab은 일반 유지 관리를 위한 Rake 작업을 제공합니다.

GitLab 및 시스템 정보 수집#

이 명령은 GitLab 설치 및 실행 시스템에 대한 정보를 수집합니다. 도움을 요청하거나 이슈를 보고할 때 유용할 수 있습니다. 멀티 노드 환경에서는 PostgreSQL 소켓 오류를 방지하기 위해 GitLab Rails를 실행하는 노드에서 이 명령을 실행하세요.

• Linux 패키지 설치:

  sudo gitlab-rake gitlab:env:info
  

• 자체 컴파일 설치:

  bundle exec rake gitlab:env:info RAILS_ENV=production
  

출력 예시:

System information
System:         Ubuntu 20.04
Proxy:          no
Current User:   git
Using RVM:      no
Ruby Version:   2.7.6p219
Gem Version:    3.1.6
Bundler Version:2.3.15
Rake Version:   13.0.6
Redis Version:  6.2.7
Sidekiq Version:6.4.2
Go Version:     unknown

GitLab information
Version:        15.5.5-ee
Revision:       5f5109f142d
Directory:      /opt/gitlab/embedded/service/gitlab-rails
DB Adapter:     PostgreSQL
DB Version:     13.8
URL:            https://app.gitaly.gcp.gitlabsandbox.net
HTTP Clone URL: https://app.gitaly.gcp.gitlabsandbox.net/some-group/some-project.git
SSH Clone URL:  git@app.gitaly.gcp.gitlabsandbox.net:some-group/some-project.git
Elasticsearch:  no
Geo:            no
Using LDAP:     no
Using Omniauth: yes
Omniauth Providers:

GitLab Shell
Version:        14.12.0
Repository storage paths:
- default:      /var/opt/gitlab/git-data/repositories
- gitaly:       /var/opt/gitlab/git-data/repositories
GitLab Shell path:              /opt/gitlab/embedded/service/gitlab-shell

Gitaly
- default Address:      unix:/var/opt/gitlab/gitaly/gitaly.socket
- default Version:      15.5.5
- default Git Version:  2.37.1.gl1
- gitaly Address:       tcp://10.128.20.6:2305
- gitaly Version:       15.5.5
- gitaly Git Version:   2.37.1.gl1

GitLab 라이선스 정보 표시#

이 명령은 GitLab 라이선스에 대한 정보와 사용된 좌석 수를 보여줍니다. GitLab Enterprise 설치에서만 사용할 수 있습니다: GitLab Community Edition에는 라이선스를 설치할 수 없습니다.

지원 티켓을 올리거나 라이선스 매개변수를 프로그래밍 방식으로 확인할 때 유용할 수 있습니다.

• Linux 패키지 설치:

  sudo gitlab-rake gitlab:license:info
  

• 자체 컴파일 설치:

  bundle exec rake gitlab:license:info RAILS_ENV=production
  

출력 예시:

Today's Date: 2020-02-29
Current User Count: 30
Max Historical Count: 30
Max Users in License: 40
License valid from: 2019-11-29 to 2020-11-28
Email associated with license: user@example.com

GitLab 구성 확인#

gitlab:check Rake 작업은 다음 Rake 작업을 실행합니다:

• gitlab:gitlab_shell:check
• gitlab:gitaly:check
• gitlab:sidekiq:check
• gitlab:incoming_email:check
• gitlab:ldap:check
• gitlab:app:check
• gitlab:geo:check (Geo를 실행하는 경우에만)

각 구성 요소가 설치 가이드에 따라 설정되었는지 확인하고 발견된 문제에 대한 수정 사항을 제안합니다. 이 명령은 애플리케이션 서버에서 실행해야 하며 Gitaly와 같은 구성 요소 서버에서는 올바르게 작동하지 않습니다.

다음 트러블슈팅 가이드도 참조할 수 있습니다:

• GitLab.
• Linux 패키지 설치.

또한 현재 시크릿을 사용하여 데이터베이스 값을 복호화할 수 있는지 확인해야 합니다.

gitlab:check를 실행하려면:

• Linux 패키지 설치:

  sudo gitlab-rake gitlab:check
  

• 자체 컴파일 설치:

  bundle exec rake gitlab:check RAILS_ENV=production
  

• Kubernetes 설치:

  kubectl exec -it <toolbox-pod-name> -- sudo gitlab-rake gitlab:check
  

  [!note] Helm 기반 GitLab 설치의 특수한 아키텍처로 인해 출력에는 gitlab-shell, Sidekiq, systemd 관련 파일에 대한 연결 확인에서 거짓 음성이 포함될 수 있습니다. 이렇게 보고된 실패는 예상된 것이며 실제 문제를 나타내지 않으므로 진단 결과를 검토할 때 무시하세요.

출력에서 프로젝트 이름을 생략하려면 gitlab:check에 SANITIZE=true를 사용하세요.

출력 예시:

Checking Environment ...

Git configured for git user? ... yes
Has python2? ... yes
python2 is supported version? ... yes

Checking Environment ... Finished

Checking GitLab Shell ...

GitLab Shell version? ... OK (1.2.0)
Repo base directory exists? ... yes
Repo base directory is a symlink? ... no
Repo base owned by git:git? ... yes
Repo base access is drwxrws---? ... yes
post-receive hook up-to-date? ... yes
post-receive hooks in repos are links: ... yes

Checking GitLab Shell ... Finished

Checking Sidekiq ...

Running? ... yes

Checking Sidekiq ... Finished

Checking GitLab App...

Database config exists? ... yes
Database is SQLite ... no
All migrations up? ... yes
GitLab config exists? ... yes
GitLab config up to date? ... no
Cable config exists? ... yes
Resque config exists? ... yes
Log directory writable? ... yes
Tmp directory writable? ... yes
Init script exists? ... yes
Init script up-to-date? ... yes
Redis version >= 2.0.0? ... yes

Checking GitLab ... Finished

authorized_keys 파일 재빌드#

경우에 따라 authorized_keys 파일을 재빌드해야 합니다. 예를 들어, 업그레이드 후 SSH를 통한 푸시 시 Permission denied (publickey)가 발생하고 gitlab-shell.log 파일에서 404 Key Not Found 오류를 발견하는 경우입니다. authorized_keys를 재빌드하려면:

• Linux 패키지 설치:

  sudo gitlab-rake gitlab:shell:setup
  

• 자체 컴파일 설치:

  cd /home/git/gitlab
  sudo -u git -H bundle exec rake gitlab:shell:setup RAILS_ENV=production
  

출력 예시:

This will rebuild an authorized_keys file.
You will lose any data stored in authorized_keys file.
Do you want to continue (yes/no)? yes

Redis 캐시 지우기#

어떤 이유로 대시보드가 잘못된 정보를 표시하는 경우 Redis 캐시를 지우고 싶을 수 있습니다. 이를 위해:

• Linux 패키지 설치:

  sudo gitlab-rake cache:clear
  

• 자체 컴파일 설치:

  cd /home/git/gitlab
  sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production
  

에셋 사전 컴파일#

버전 업그레이드 중에 CSS가 잘못되거나 아이콘이 누락되는 경우가 있습니다. 이 경우 에셋을 다시 사전 컴파일해 보세요.

이 Rake 작업은 자체 컴파일 설치에만 적용됩니다. Linux 패키지를 실행할 때 이 문제를 트러블슈팅하는 방법에 대해 자세히 읽어보세요. Linux 패키지 안내는 Kubernetes 및 Docker 배포에도 적용될 수 있지만, 일반적으로 컨테이너 기반 설치는 누락된 에셋 문제가 없습니다.

• 자체 컴파일 설치:

  cd /home/git/gitlab
  sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production
  

Linux 패키지 설치의 경우, 최적화되지 않은 에셋(JavaScript, CSS)은 업스트림 GitLab 릴리스 시점에 고정됩니다. Linux 패키지 설치에는 최적화된 버전의 에셋이 포함됩니다. 패키지를 설치한 후 프로덕션 머신에서 JavaScript/CSS 코드를 수정하지 않는 한 프로덕션 머신에서 rake gitlab:assets:compile을 다시 실행할 이유가 없습니다. 에셋이 손상된 것으로 의심되는 경우 Linux 패키지를 재설치해야 합니다.

원격 사이트에 대한 TCP 연결 확인#

때로는 GitLab 설치가 프록시 문제를 트러블슈팅하기 위해 다른 머신의 TCP 서비스(예: PostgreSQL 또는 웹 서버)에 연결할 수 있는지 알아야 합니다. 이를 도와주는 Rake 작업이 포함되어 있습니다.

• Linux 패키지 설치:

  sudo gitlab-rake gitlab:tcp_check[example.com,80]
  

• 자체 컴파일 설치:

  cd /home/git/gitlab
  sudo -u git -H bundle exec rake gitlab:tcp_check[example.com,80] RAILS_ENV=production
  

배타적 리스 지우기 (위험)#

GitLab은 공유 리소스에서 동시 작업을 방지하기 위해 공유 잠금 메커니즘인 ExclusiveLease를 사용합니다. 리포지터리에 대한 주기적인 가비지 컬렉션 실행이 그 예입니다.

매우 특정한 상황에서는 배타적 리스에 의해 잠긴 작업이 잠금을 해제하지 않고 실패할 수 있습니다. 만료될 때까지 기다릴 수 없는 경우 이 작업을 실행하여 수동으로 지울 수 있습니다.

모든 배타적 리스를 지우려면:

sudo gitlab-rake gitlab:exclusive_lease:clear

리스 type 또는 리스 type + id를 지정하려면 범위를 지정하세요:

# to clear all leases for repository garbage collection:
sudo gitlab-rake gitlab:exclusive_lease:clear[project_housekeeping:*]

# to clear a lease for repository garbage collection in a specific project: (id=4)
sudo gitlab-rake gitlab:exclusive_lease:clear[project_housekeeping:4]

데이터베이스 마이그레이션 상태 표시#

GitLab을 업그레이드할 때 마이그레이션이 완료되었는지 확인하는 방법은 백그라운드 마이그레이션 설명서를 참조하세요.

특정 마이그레이션의 상태를 확인하려면 다음 Rake 작업을 사용할 수 있습니다:

sudo gitlab-rake db:migrate:status

Geo 보조 사이트의 추적 데이터베이스를 확인하려면 다음 Rake 작업을 사용할 수 있습니다:

sudo gitlab-rake db:migrate:status:geo

각 마이그레이션에 대해 up 또는 down Status가 있는 테이블이 출력됩니다. 예시:

database: gitlabhq_production

 Status   Migration ID    Type     Milestone    Name
--------------------------------------------------
   up     20240701074848  regular  17.2         AddGroupIdToPackagesDebianGroupComponents
   up     20240701153843  regular  17.2         AddWorkItemsDatesSourcesSyncToIssuesTrigger
   up     20240702072515  regular  17.2         AddGroupIdToPackagesDebianGroupArchitectures
   up     20240702133021  regular  17.2         AddWorkspaceTerminationTimeoutsToRemoteDevelopmentAgentConfigs
   up     20240604064938  post     17.2         FinalizeBackfillPartitionIdCiPipelineMessage
   up     20240604111157  post     17.2         AddApprovalPolicyRulesFkOnApprovalGroupRules

GitLab 17.1부터 마이그레이션은 GitLab 릴리스 케이던스에 맞는 순서로 실행됩니다.

불완전한 데이터베이스 마이그레이션 실행#

데이터베이스 마이그레이션은 sudo gitlab-rake db:migrate:status 명령 출력에서 down 상태로 완료되지 않은 상태가 될 수 있습니다.

1. 이러한 마이그레이션을 완료하려면 다음 Rake 작업을 사용합니다:

   sudo gitlab-rake db:migrate
   

2. 명령이 완료된 후 sudo gitlab-rake db:migrate:status를 실행하여 모든 마이그레이션이 완료(up 상태)되었는지 확인합니다.

3. puma 및 sidekiq 서비스를 핫 리로드합니다:

   sudo gitlab-ctl hup puma
   sudo gitlab-ctl restart sidekiq
   

GitLab 17.1부터 마이그레이션은 GitLab 릴리스 케이던스에 맞는 순서로 실행됩니다.

데이터베이스 인덱스 재빌드#

히스토리

• GitLab 13.5에서 database_reindexing이라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화됩니다.
• GitLab 13.9에서 GitLab.com에서 활성화되었습니다.
• GitLab 18.0에서 GitLab Self-Managed 및 GitLab Dedicated에서 활성화되었습니다.

데이터베이스 인덱스는 공간을 확보하고 시간이 지남에 따라 정상적인 수준의 인덱스 부풀림을 유지하기 위해 정기적으로 재빌드할 수 있습니다. 재인덱싱은 일반 크론 작업으로도 실행할 수 있습니다. "정상적인" 부풀림 수준은 특정 인덱스에 따라 크게 다르지만 일반적으로 30% 미만이어야 합니다.

데이터베이스 재인덱싱은 다음 작업을 수행합니다:

• 수동으로 대기열에 추가된 PostgreSQL 인덱스를 재인덱싱합니다: 인덱스를 수동으로 재인덱싱을 위한 대기열에 추가할 수 있습니다. PostgreSQL 인덱스를 재인덱싱하면 일반적으로 인덱스 부풀림이 줄어듭니다.
• 인덱스 부풀림 휴리스틱을 사용하여 PostgreSQL 인덱스를 자동으로 재인덱싱합니다: PostgreSQL은 가장 부풀린 인덱스를 식별하는 휴리스틱을 사용합니다. 각 실행에서 최대 2개의 인덱스를 선택하여 재인덱싱합니다.

사전 요구 사항:

• 이 기능에는 PostgreSQL 12 이상이 필요합니다.
• 다음 인덱스 유형은 지원되지 않습니다: 표현식 인덱스 및 제약 조건 제외에 사용되는 인덱스.

재인덱싱 실행#

다음 작업은 각 데이터베이스에서 부풀림이 가장 높은 두 인덱스만 재빌드합니다. 두 개 이상의 인덱스를 재빌드하려면 원하는 모든 인덱스가 재빌드될 때까지 작업을 다시 실행하세요.

1. 재인덱싱 작업을 실행합니다:

   sudo gitlab-rake gitlab:db:reindex
   

2. application_json.log를 확인하여 실행을 검증하거나 트러블슈팅합니다.

Toolbox 차트를 사용하여 이 작업을 실행하는 GitLab의 Cloud Native 설치의 경우, 로그는 팟의 표준 출력에 있습니다.

재인덱싱 설정 사용자 지정#

소규모 인스턴스의 경우 또는 재인덱싱 동작을 조정하려면 Rails 콘솔을 사용하여 이러한 설정을 수정할 수 있습니다:

sudo gitlab-rails console

그런 다음 구성을 사용자 지정합니다:

# Lower minimum index size to 100 MB (default is 1 GB)
Gitlab::Database::Reindexing.minimum_index_size!(100.megabytes)

# Change minimum bloat threshold to 30% (default is 20%, there is no benefit from setting it lower)
Gitlab::Database::Reindexing.minimum_relative_bloat_size!(0.3)

자동화된 재인덱싱#

상당한 데이터베이스 크기의 대규모 인스턴스의 경우 낮은 활동 기간에 실행되도록 예약하여 데이터베이스 재인덱싱을 자동화하세요.

crontab으로 예약#

패키지형 GitLab 설치의 경우 crontab을 사용합니다:

1. crontab을 편집합니다:

   sudo crontab -e
   

2. 원하는 일정에 따라 항목을 추가합니다:

   1. 옵션 1: 조용한 시간대에 매일 실행

   # Run database reindexing every day at 21:12
   # The log will be rotated by the packaged logrotate daemon
   12 21 * * * /opt/gitlab/bin/gitlab-rake gitlab:db:reindex >> /var/log/gitlab/gitlab-rails/cron_reindex.log 2>&1
   

   1. 옵션 2: 주말에만 실행

   # Run database reindexing at 01:00 AM on weekends
   0 1 * * 0,6 /opt/gitlab/bin/gitlab-rake gitlab:db:reindex >> /var/log/gitlab/gitlab-rails/cron_reindex.log 2>&1
   

   1. 옵션 3: 낮은 트래픽 시간대에 자주 실행

   # Run database reindexing every 3 hours during night hours (22:00-07:00)
   0 22,1,4,7 * * * /opt/gitlab/bin/gitlab-rake gitlab:db:reindex >> /var/log/gitlab/gitlab-rails/cron_reindex.log 2>&1
   

Kubernetes 배포의 경우 CronJob 리소스를 사용하여 재인덱싱 작업을 실행하는 유사한 일정을 생성할 수 있습니다.

참고 사항#

• 데이터베이스 인덱스 재빌드는 디스크 집약적인 작업이므로 사용량이 적은 시간대에 수행해야 합니다. 피크 시간대에 작업을 실행하면 부풀림이 증가하고 특정 쿼리가 느리게 수행될 수 있습니다.
• 이 작업에는 복원 중인 인덱스에 대한 여유 디스크 공간이 필요합니다. 생성된 인덱스에는 _ccnew가 추가됩니다. 재인덱싱 작업이 실패하면 작업을 다시 실행하면 임시 인덱스가 정리됩니다.
• 데이터베이스 인덱스 재빌드 완료에 걸리는 시간은 대상 데이터베이스의 크기에 따라 다릅니다. 몇 시간에서 며칠까지 걸릴 수 있습니다.
• 이 작업은 Redis 잠금을 사용하므로 자주 실행되도록 예약해도 안전합니다. 다른 재인덱싱 작업이 이미 실행 중이면 아무것도 하지 않습니다.

데이터베이스 스키마 덤프#

드문 경우지만 모든 데이터베이스 마이그레이션이 완료되더라도 데이터베이스 스키마가 애플리케이션 코드의 예상과 다를 수 있습니다. 이런 경우 GitLab에서 이상한 오류가 발생할 수 있습니다.

데이터베이스 스키마를 덤프하려면:

SCHEMA=/tmp/structure.sql gitlab-rake db:schema:dump

Rake 작업은 데이터베이스 스키마 덤프가 포함된 /tmp/structure.sql 파일을 만듭니다.

차이점이 있는지 확인하려면:

1. gitlab 프로젝트의 db/structure.sql 파일로 이동합니다. GitLab 버전과 일치하는 브랜치를 선택합니다. 예를 들어, GitLab 16.2의 파일: https://gitlab.com/gitlab-org/gitlab/-/blob/16-2-stable-ee/db/structure.sql.
2. /tmp/structure.sql과 버전의 db/structure.sql 파일을 비교합니다.

스키마 불일치에 대한 데이터베이스 확인#

히스토리

• GitLab 15.11에서 도입되었습니다.

이 Rake 작업은 데이터베이스 스키마의 불일치를 확인하고 터미널에 출력합니다. 이 작업은 GitLab 지원의 안내 하에 사용하는 진단 도구입니다. 데이터베이스 불일치가 예상될 수 있으므로 일상적인 확인에는 사용하지 마세요.

gitlab-rake gitlab:db:schema_checker:run

데이터베이스에 대한 정보 및 통계 수집#

히스토리

• GitLab 17.11에서 도입되었습니다.

gitlab:db:sos 명령은 문제를 트러블슈팅하는 데 도움이 되도록 GitLab 데이터베이스에 대한 구성, 성능 및 진단 데이터를 수집합니다. 이 명령을 실행하는 위치는 구성에 따라 다릅니다. GitLab이 설치된 위치(/gitlab)를 기준으로 이 명령을 실행해야 합니다.

• 스케일 아웃된 GitLab: Puma 또는 Sidekiq 서버에서.
• 클라우드 네이티브 설치: toolbox 팟에서.
• 기타 모든 구성: GitLab 서버에서.

필요에 따라 명령을 수정합니다:

• 기본 경로 - 기본 파일 경로(/var/opt/gitlab/gitlab-rails/tmp/sos.zip)로 명령을 실행하려면 gitlab-rake gitlab:db:sos를 실행합니다.
• 사용자 지정 경로 - 파일 경로를 변경하려면 gitlab-rake gitlab:db:sos["/absolute/custom/path/to/file.zip"]를 실행합니다.
• Zsh 사용자 - Zsh 구성을 수정하지 않은 경우 전체 명령에 따옴표를 추가해야 합니다: gitlab-rake "gitlab:db:sos[/absolute/custom/path/to/file.zip]"

Rake 작업은 5분간 실행됩니다. 지정한 경로에 압축 폴더를 만듭니다. 압축 폴더에는 많은 수의 파일이 포함됩니다.

선택적 쿼리 통계 데이터 활성화#

gitlab:db:sos Rake 작업은 pg_stat_statements 확장을 사용하여 느린 쿼리 트러블슈팅을 위한 데이터도 수집할 수 있습니다.

이 확장을 활성화하는 것은 선택 사항이며 PostgreSQL 및 GitLab을 재시작해야 합니다. 이 데이터는 느린 데이터베이스 쿼리로 인한 GitLab 성능 문제를 트러블슈팅할 때 필요할 가능성이 높습니다.

사전 요구 사항:

• 확장을 활성화하거나 비활성화하려면 수퍼유저 권한이 있는 PostgreSQL 사용자여야 합니다.

1. 데이터베이스 콘솔에서 실행합니다:

   CREATE EXTENSION pg_stat_statements;
   

2. 확장이 작동하는지 확인합니다:

   SELECT extname FROM pg_extension WHERE extname = 'pg_stat_statements';
   SELECT * FROM pg_stat_statements LIMIT 10;
   

CI/CD 중복 태그에 대한 데이터베이스 확인#

히스토리

• GitLab 17.10에서 도입되었습니다.

이 Rake 작업은 ci 데이터베이스의 tags 테이블에서 중복 태그를 확인합니다. 이 문제는 오랜 기간에 걸쳐 여러 주요 업그레이드를 거친 인스턴스에 영향을 줄 수 있습니다. 다음 명령을 실행하여 중복 태그를 검색한 후, 중복 태그를 참조하는 태그 할당을 대신 원래 태그를 사용하도록 다시 씁니다.

sudo gitlab-rake gitlab:db:deduplicate_tags

드라이 런 모드로 이 명령을 실행하려면 환경 변수 DRY_RUN=true를 설정합니다.

PostgreSQL 콜레이션 버전 불일치 감지#

히스토리

• GitLab 18.2에서 도입되었습니다.
• GitLab 18.3에서 손상에 대한 사전 정의된 인덱스 세트의 스팟 확인이 도입되었습니다.
• GitLab 18.4에서 MAX_TABLE_SIZE 사용자 지정 및 PgBouncer 우회 옵션이 도입되었습니다.

PostgreSQL 콜레이션 검사기는:

• 인덱스 손상을 유발할 수 있는 데이터베이스와 운영 체제 간의 콜레이션 버전 불일치를 감지합니다. PostgreSQL은 문자열 콜레이션(정렬 및 비교 규칙)에 운영 체제의 glibc 라이브러리를 사용합니다.
• 사전 정의된 인덱스 세트에 대한 손상 스팟 확인(중복 감지)을 수행합니다. 이러한 인덱스는 콜레이션 불일치로 인한 손상 문제에 취약한 것으로 알려져 있습니다.

기반이 되는 glibc 라이브러리를 변경하는 운영 체제 업그레이드 후에 이 작업을 실행합니다.

사전 요구 사항:

• PostgreSQL 13 이상.

모든 데이터베이스에서 PostgreSQL 콜레이션 불일치 및 관련 인덱스 손상을 확인하려면:

sudo gitlab-rake gitlab:db:collation_checker

특정 데이터베이스를 확인하려면:

# Check main database
sudo gitlab-rake gitlab:db:collation_checker:main

# Check CI database
sudo gitlab-rake gitlab:db:collation_checker:ci

테이블 크기 한도 조정#

기본적으로 1GB보다 큰 테이블은 데이터베이스 성능에 영향을 줄 수 있는 오래 실행되는 쿼리를 방지하기 위해 건너뜁니다. MAX_TABLE_SIZE 환경 변수를 설정하여 테이블 크기 임계값을 조정할 수 있습니다.

# Set custom table size limit (in bytes)
# to increase the max table size threshold to 10 GB
MAX_TABLE_SIZE=10737418240 sudo gitlab-rake gitlab:db:collation_checker:main

오래 실행되는 쿼리를 위한 PgBouncer 우회#

트러블슈팅 섹션의 명령문 시간 초과 오류 해결을 참조하세요.

출력 예시#

문제가 발견되지 않은 경우:

Checking for PostgreSQL collation mismatches on main database...
No collation mismatches detected on main.
Found 8 indexes to corruption spot check.
No corrupted indexes detected.

불일치가 감지되면 작업은 영향받은 인덱스를 수정하기 위한 수정 단계를 제공합니다.

불일치가 있는 출력 예시:

Checking for PostgreSQL collation mismatches on main database...
⚠️ COLLATION MISMATCHES DETECTED on main database!
2 collation(s) have version mismatches:
  - en_US.utf8: stored=428.1, actual=513.1
  - es_ES.utf8: stored=428.1, actual=513.1

Found 8 indexes to corruption spot check.
Affected indexes that need to be rebuilt:
  - index_projects_on_name (btree) on table projects
    • Issues detected: duplicates
    • Affected columns: name
    • Type: UNIQUE
    • Needs deduplication: Yes

REMEDIATION STEPS:
1. Put GitLab into maintenance mode
2. Run the following SQL commands:

# Step 1: Check for duplicate entries in unique indexes
SELECT name, COUNT(*), ARRAY_AGG(id) FROM projects GROUP BY name HAVING COUNT(*) > 1 LIMIT 1;

# If duplicates exist, you may need to use gitlab:db:deduplicate_tags or similar tasks
# to fix duplicate entries before rebuilding unique indexes.

# Step 2: Rebuild affected indexes
# Option A: Rebuild individual indexes with minimal downtime:
REINDEX INDEX CONCURRENTLY index_projects_on_name;

# Option B: Alternatively, rebuild all indexes at once (requires downtime):
REINDEX DATABASE main;

# Step 3: Refresh collation versions
ALTER DATABASE main REFRESH COLLATION VERSION;

3. Take GitLab out of maintenance mode

PostgreSQL 콜레이션 문제와 그것이 데이터베이스 인덱스에 미치는 영향에 대한 자세한 내용은 PostgreSQL OS 업그레이드 설명서를 참조하세요.

손상된 데이터베이스 인덱스 복구#

히스토리

• GitLab 18.2에서 도입되었습니다.
• GitLab 18.4에서 PgBouncer 우회 옵션이 도입되었습니다.

인덱스 복구 도구는 데이터 무결성 문제를 유발할 수 있는 손상되거나 누락된 데이터베이스 인덱스를 수정합니다. 이 도구는 콜레이션 불일치 또는 기타 손상 문제의 영향을 받는 특정 문제 인덱스를 처리합니다. 이 도구는:

• 고유 인덱스가 손상된 경우 데이터를 중복 제거합니다.
• 데이터 무결성을 유지하기 위해 참조를 업데이트합니다.
• 올바른 구성으로 인덱스를 재빌드하거나 생성합니다.

인덱스를 복구하기 전에 드라이 런 모드로 도구를 실행하여 잠재적인 변경 사항을 분석합니다:

sudo DRY_RUN=true gitlab-rake gitlab:db:repair_index

다음 예시 출력은 변경 사항을 보여줍니다:

INFO -- : DRY RUN: Analysis only, no changes will be made.
INFO -- : Running Index repair on database main...
INFO -- : Processing index 'index_merge_request_diff_commit_users_on_name_and_email'...
INFO -- : Index is unique. Checking for duplicate data...
INFO -- : No duplicates found in 'merge_request_diff_commit_users' for columns: name,email.
INFO -- : Index exists. Reindexing...
INFO -- : Index reindexed successfully.

모든 데이터베이스에서 알려진 모든 문제 인덱스를 복구하려면:

sudo gitlab-rake gitlab:db:repair_index

명령은 각 데이터베이스를 처리하고 인덱스를 복구합니다. 예를 들어:

INFO -- : Running Index repair on database main...
INFO -- : Processing index 'index_merge_request_diff_commit_users_on_name_and_email'...
INFO -- : Index is unique. Checking for duplicate data...
INFO -- : No duplicates found in 'merge_request_diff_commit_users' for columns: name,email.
INFO -- : Index does not exist. Creating new index...
INFO -- : Index created successfully.
INFO -- : Index repair completed for database main.

특정 데이터베이스의 인덱스를 복구하려면:

# Repair indexes in main database
sudo gitlab-rake gitlab:db:repair_index:main

# Repair indexes in CI database
sudo gitlab-rake gitlab:db:repair_index:ci

오래 실행되는 쿼리를 위한 PgBouncer 우회#

트러블슈팅 섹션의 명령문 시간 초과 오류 해결을 참조하세요.

트러블슈팅#

어드바이저리 잠금 연결 정보#

db:migrate Rake 작업을 실행한 후 다음과 같은 출력이 표시될 수 있습니다:

main: == [advisory_lock_connection] object_id: 173580, pg_backend_pid: 5532
main: == [advisory_lock_connection] object_id: 173580, pg_backend_pid: 5532

반환된 메시지는 정보 제공용이며 무시할 수 있습니다.

gitlab:env:info Rake 작업 실행 시 PostgreSQL 소켓 오류#

Gitaly 또는 다른 비 Rails 노드에서 sudo gitlab-rake gitlab:env:info를 실행한 후 다음 오류가 표시될 수 있습니다:

PG::ConnectionBad: could not connect to server: No such file or directory
Is the server running locally and accepting
connections on Unix domain socket "/var/opt/gitlab/postgresql/.s.PGSQL.5432"?

이는 멀티 노드 환경에서 gitlab:env:info Rake 작업이 GitLab Rails를 실행하는 노드에서만 실행되어야 하기 때문입니다.

명령문 시간 초과 오류 해결#

GitLab 인스턴스가 PgBouncer를 사용하고 데이터베이스 유지 관리 작업(콜레이션 검사기 또는 인덱스 복구 등) 중에 명령문 시간 초과가 발생하는 경우 직접 PostgreSQL 연결을 사용하여 PgBouncer를 우회합니다.

# Example with direct connection
GITLAB_BACKUP_PGUSER=postgres GITLAB_BACKUP_PGHOST=localhost sudo gitlab-rake gitlab:db:collation_checker

GITLAB_BACKUP_PGUSER=postgres GITLAB_BACKUP_PGHOST=localhost sudo gitlab-rake gitlab:db:repair_index

지원되는 환경 변수:

• GITLAB_BACKUP_PGHOST
• GITLAB_BACKUP_PGUSER
• GITLAB_BACKUP_PGPORT
• GITLAB_BACKUP_PGPASSWORD

PgBouncer 우회 및 지원되는 환경 변수의 전체 목록에 대한 자세한 내용은 PgBouncer 우회 절차를 참조하세요.