무결성 검사 Rake 작업
Offering: GitLab Self-Managed
GitLab은 다양한 구성 요소의 무결성을 확인하기 위한 Rake 작업을 제공합니다. Git은 매우 견고하고 데이터 무결성 문제를 방지하려고 하지만, 때로는 문제가 발생할 수 있습니다. 이러한 Rake 작업은 Git 저장소의 무결성을 확인하기 위해 세 가지 방법을 사용합니다.
GitLab은 다양한 구성 요소의 무결성을 확인하기 위한 Rake 작업을 제공합니다. GitLab 구성 확인 Rake 작업도 참조하세요.
저장소 무결성#
Git은 매우 견고하고 데이터 무결성 문제를 방지하려고 하지만, 때로는 문제가 발생할 수 있습니다. 다음 Rake 작업은 GitLab 관리자가 문제 저장소를 진단하여 수정할 수 있도록 도움을 줍니다.
이러한 Rake 작업은 Git 저장소의 무결성을 확인하기 위해 세 가지 방법을 사용합니다.
- Git 저장소 파일 시스템 검사(
git fsck). 이 단계는 저장소에서 객체의 연결성과 유효성을 확인합니다. - 저장소 디렉토리에서
config.lock확인. refs/heads에서 브랜치/참조 잠금 파일 확인.
config.lock 또는 참조 잠금의 존재만으로는 반드시 문제가 있다는 의미가 아닙니다. 잠금 파일은 Git과 GitLab이 저장소에서 작업을 수행할 때 일상적으로 생성되고 제거됩니다. 데이터 무결성 문제를 방지하기 위한 것입니다. 그러나 Git 작업이 중단되면 이러한 잠금이 제대로 정리되지 않을 수 있습니다.
다음 증상은 저장소 무결성 문제를 나타낼 수 있습니다. 사용자가 이러한 증상을 경험하면 아래에 설명된 Rake 작업을 사용하여 문제를 일으키는 저장소를 정확히 파악할 수 있습니다.
- 코드를 push하려고 할 때 오류 수신 -
remote: error: cannot lock ref - GitLab 대시보드를 보거나 특정 프로젝트에 액세스할 때 500 오류.
모든 프로젝트 코드 저장소 확인#
이 작업은 프로젝트 코드 저장소를 순환하여 앞서 설명된 무결성 검사를 실행합니다. 프로젝트가 풀 저장소를 사용하는 경우 해당 저장소도 확인합니다. 다른 유형의 Git 저장소는 확인되지 않습니다.
프로젝트 코드 저장소를 확인하려면:
sudo gitlab-rake gitlab:git:fsck
sudo -u git -H bundle exec rake gitlab:git:fsck RAILS_ENV=production
특정 프로젝트 코드 저장소 확인#
히스토리
- GitLab 18.3에서 도입됨.
PROJECT_IDS 환경 변수를 프로젝트 ID의 쉼표로 구분된 목록으로 설정하여 특정 프로젝트 ID를 가진 프로젝트의 저장소에 대한 검사를 제한합니다.
예를 들어, 프로젝트 ID가 1과 3인 프로젝트의 저장소를 확인하려면:
sudo PROJECT_IDS="1,3" gitlab-rake gitlab:git:fsck
sudo -u git -H PROJECT_IDS="1,3" bundle exec rake gitlab:git:fsck RAILS_ENV=production
저장소 ref의 체크섬#
하나의 Git 저장소를 다른 저장소와 비교하려면 각 저장소의 모든 ref의 체크섬을 계산할 수 있습니다. 두 저장소가 동일한 ref를 가지고 두 저장소 모두 무결성 검사를 통과하면, 두 저장소가 동일하다고 확신할 수 있습니다.
예를 들어, 소스 저장소에 대해 저장소의 백업을 비교하는 데 사용할 수 있습니다.
모든 GitLab 저장소 확인#
이 작업은 GitLab 서버의 모든 저장소를 순환하고 , 형식으로 체크섬을 출력합니다.
- 저장소가 존재하지 않으면 프로젝트 ID는 빈 체크섬입니다.
- 저장소가 존재하지만 비어 있으면 출력 체크섬은
0000000000000000000000000000000000000000입니다. - 존재하지 않는 프로젝트는 건너뜁니다.
모든 GitLab 저장소를 확인하려면:
sudo gitlab-rake gitlab:git:checksum_projects
sudo -u git -H bundle exec rake gitlab:git:checksum_projects RAILS_ENV=production
예를 들어:
- ID#2의 프로젝트가 존재하지 않으면 건너뜁니다.
- ID#4의 프로젝트에 저장소가 없으면 체크섬이 비어 있습니다.
- ID#5의 프로젝트에 빈 저장소가 있으면 체크섬은
0000000000000000000000000000000000000000입니다.
출력은 다음과 같습니다:
1,cfa3f06ba235c13df0bb28e079bcea62c5848af2
3,3f3fb58a8106230e3a6c6b48adc2712fb3b6ef87
4,
5,0000000000000000000000000000000000000000
6,6c6b48adc2712fb3b6ef87cfa3f06ba235c13df0
특정 GitLab 저장소 확인#
선택적으로, 정수의 쉼표로 구분된 목록으로 환경 변수 CHECKSUM_PROJECT_IDS를 설정하여 특정 프로젝트 ID의 체크섬을 계산할 수 있습니다. 예:
sudo CHECKSUM_PROJECT_IDS="1,3" gitlab-rake gitlab:git:checksum_projects
업로드된 파일 무결성#
다양한 유형의 파일을 사용자가 GitLab 설치에 업로드할 수 있습니다. 이러한 무결성 검사는 누락된 파일을 감지할 수 있습니다. 또한 로컬에 저장된 파일의 경우, 체크섬이 업로드 시 데이터베이스에 생성되어 저장되며, 이러한 검사는 현재 파일에 대해 이를 확인합니다.
다음 유형의 파일에 대한 무결성 검사가 지원됩니다:
- CI 아티팩트
- LFS 객체
- 프로젝트 수준 보안 파일 (GitLab 16.1.0에서 도입됨)
- 사용자 업로드
업로드된 파일의 무결성을 확인하려면:
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
sudo -u git -H bundle exec rake gitlab:artifacts:check RAILS_ENV=production
sudo -u git -H bundle exec rake gitlab:ci_secure_files:check RAILS_ENV=production
sudo -u git -H bundle exec rake gitlab:lfs:check RAILS_ENV=production
sudo -u git -H bundle exec rake gitlab:uploads:check RAILS_ENV=production
이러한 작업은 특정 값을 재정의하는 데 사용할 수 있는 일부 환경 변수도 허용합니다:
| 변수 | 유형 | 설명 |
|---|---|---|
BATCH |
integer | 배치 크기를 지정합니다. 기본값은 200. |
ID_FROM |
integer | 시작할 ID를 지정합니다(해당 값 포함). |
ID_TO |
integer | 종료할 ID 값을 지정합니다(해당 값 포함). |
VERBOSE |
boolean | 요약 대신 개별적으로 실패를 나열합니다. |
sudo gitlab-rake gitlab:artifacts:check BATCH=100 ID_FROM=50 ID_TO=250
sudo gitlab-rake gitlab:ci_secure_files:check BATCH=100 ID_FROM=50 ID_TO=250
sudo gitlab-rake gitlab:lfs:check BATCH=100 ID_FROM=50 ID_TO=250
sudo gitlab-rake gitlab:uploads:check BATCH=100 ID_FROM=50 ID_TO=250
출력 예시:
$ sudo gitlab-rake gitlab:uploads:check
Checking integrity of Uploads
- 1..1350: Failures: 0
- 1351..2743: Failures: 0
- 2745..4349: Failures: 2
- 4357..5762: Failures: 1
- 5764..7140: Failures: 2
- 7142..8651: Failures: 0
- 8653..10134: Failures: 0
- 10135..11773: Failures: 0
- 11777..13315: Failures: 0
Done!
상세 출력 예시:
$ sudo gitlab-rake gitlab:uploads:check VERBOSE=1
Checking integrity of Uploads
- 1..1350: Failures: 0
- 1351..2743: Failures: 0
- 2745..4349: Failures: 2
- Upload: 3573: #
- Upload: 3580: #
- 4357..5762: Failures: 1
- Upload: 4636: #
- 5764..7140: Failures: 2
- Upload: 5812: #
- Upload: 5837: #
- 7142..8651: Failures: 0
- 8653..10134: Failures: 0
- 10135..11773: Failures: 0
- 11777..13315: Failures: 0
Done!
LDAP 확인#
LDAP 확인 Rake 작업은 바인드 DN 및 비밀번호 자격 증명(구성된 경우)을 테스트하고 LDAP 사용자의 샘플을 나열합니다. 이 작업은 gitlab:check 작업의 일부로도 실행되지만 독립적으로 실행할 수 있습니다.
자세한 내용은 LDAP Rake 작업 - LDAP 확인을 참조하세요.
현재 시크릿으로 데이터베이스 값을 복호화할 수 있는지 확인#
이 작업은 데이터베이스의 가능한 모든 암호화된 값을 확인하여 현재 시크릿 파일(gitlab-secrets.json)을 사용하여 복호화할 수 있는지 확인합니다.
자동 해결은 아직 구현되지 않았습니다. 복호화할 수 없는 값이 있는 경우 재설정 단계를 따를 수 있으며, 시크릿 파일이 손실된 경우 수행할 작업에 대한 문서를 참조하세요.
데이터베이스 크기에 따라 모든 테이블의 모든 행을 확인하므로 매우 오랜 시간이 걸릴 수 있습니다.
현재 시크릿으로 데이터베이스 값을 복호화할 수 있는지 확인하려면:
sudo gitlab-rake gitlab:doctor:secrets
bundle exec rake gitlab:doctor:secrets RAILS_ENV=production
출력 예시
I, [2020-06-11T17:17:54.951815 #27148] INFO -- : Checking encrypted values in the database
I, [2020-06-11T17:18:12.677708 #27148] INFO -- : - ApplicationSetting failures: 0
I, [2020-06-11T17:18:12.823692 #27148] INFO -- : - User failures: 0
[...] other models possibly containing encrypted data
I, [2020-06-11T17:18:14.938335 #27148] INFO -- : - Group failures: 1
I, [2020-06-11T17:18:15.559162 #27148] INFO -- : - Operations::FeatureFlagsClient failures: 0
I, [2020-06-11T17:18:15.575533 #27148] INFO -- : - ScimOauthAccessToken failures: 0
I, [2020-06-11T17:18:15.575678 #27148] INFO -- : Total: 1 row(s) affected
I, [2020-06-11T17:18:15.575711 #27148] INFO -- : Done!
상세 모드#
복호화할 수 없는 행과 열에 대한 더 자세한 정보를 얻으려면 VERBOSE 환경 변수를 전달할 수 있습니다.
상세 정보와 함께 현재 시크릿으로 데이터베이스 값을 복호화할 수 있는지 확인하려면:
sudo gitlab-rake gitlab:doctor:secrets VERBOSE=1
bundle exec rake gitlab:doctor:secrets RAILS_ENV=production VERBOSE=1
상세 출력 예시
I, [2020-06-11T17:17:54.951815 #27148] INFO -- : Checking encrypted values in the database
I, [2020-06-11T17:18:12.677708 #27148] INFO -- : - ApplicationSetting failures: 0
I, [2020-06-11T17:18:12.823692 #27148] INFO -- : - User failures: 0
[...] other models possibly containing encrypted data
D, [2020-06-11T17:19:53.224344 #27351] DEBUG -- : > Something went wrong for Group[10].runners_token: Validation failed: Route can't be blank
I, [2020-06-11T17:19:53.225178 #27351] INFO -- : - Group failures: 1
D, [2020-06-11T17:19:53.225267 #27351] DEBUG -- : - Group[10]: runners_token
I, [2020-06-11T17:18:15.559162 #27148] INFO -- : - Operations::FeatureFlagsClient failures: 0
I, [2020-06-11T17:18:15.575533 #27148] INFO -- : - ScimOauthAccessToken failures: 0
I, [2020-06-11T17:18:15.575678 #27148] INFO -- : Total: 1 row(s) affected
I, [2020-06-11T17:18:15.575711 #27148] INFO -- : Done!
복구할 수 없는 암호화된 토큰 재설정#
히스토리
- GitLab 16.6에서 도입됨.
이 작업은 위험하며 데이터 손실을 초래할 수 있습니다. 극도의 주의를 기울여 진행하세요. 이 작업을 수행하기 전에 GitLab 내부에 대한 지식이 있어야 합니다.
경우에 따라 암호화된 토큰을 더 이상 복구할 수 없어 문제가 발생할 수 있습니다. 가장 자주, 매우 큰 인스턴스에서 그룹 및 프로젝트의 러너 등록 토큰이 손상될 수 있습니다.
손상된 토큰을 재설정하려면:
-
손상된 암호화된 토큰이 있는 데이터베이스 모델을 식별합니다. 예:
Group및Project. -
손상된 토큰을 식별합니다. 예:
runners_token. -
손상된 토큰을 재설정하려면
VERBOSE=true MODEL_NAMES=Model1,Model2 TOKEN_NAMES=broken_token1,broken_token2와 함께gitlab:doctor:reset_encrypted_tokens를 실행합니다. 예:VERBOSE=true MODEL_NAMES=Project,Group TOKEN_NAMES=runners_token gitlab-rake gitlab:doctor:reset_encrypted_tokensbundle exec rake gitlab:doctor:reset_encrypted_tokens RAILS_ENV=production VERBOSE=true MODEL_NAMES=Project,Group TOKEN_NAMES=runners_token이 작업이 시도할 모든 작업을 볼 수 있습니다:
I, [2023-09-26T16:20:23.230942 #88920] INFO -- : Resetting runners_token on Project, Group if they can not be read I, [2023-09-26T16:20:23.230975 #88920] INFO -- : Executing in DRY RUN mode, no records will actually be updated D, [2023-09-26T16:20:30.151585 #88920] DEBUG -- : > Fix Project[1].runners_token I, [2023-09-26T16:20:30.151617 #88920] INFO -- : Checked 1/9 Projects D, [2023-09-26T16:20:30.151873 #88920] DEBUG -- : > Fix Project[3].runners_token D, [2023-09-26T16:20:30.152975 #88920] DEBUG -- : > Fix Project[10].runners_token I, [2023-09-26T16:20:30.152992 #88920] INFO -- : Checked 11/29 Projects I, [2023-09-26T16:20:30.153230 #88920] INFO -- : Checked 21/29 Projects I, [2023-09-26T16:20:30.153882 #88920] INFO -- : Checked 29 Projects D, [2023-09-26T16:20:30.195929 #88920] DEBUG -- : > Fix Group[22].runners_token I, [2023-09-26T16:20:30.196125 #88920] INFO -- : Checked 1/19 Groups D, [2023-09-26T16:20:30.196192 #88920] DEBUG -- : > Fix Group[25].runners_token D, [2023-09-26T16:20:30.197557 #88920] DEBUG -- : > Fix Group[82].runners_token I, [2023-09-26T16:20:30.197581 #88920] INFO -- : Checked 11/19 Groups I, [2023-09-26T16:20:30.198455 #88920] INFO -- : Checked 19 Groups I, [2023-09-26T16:20:30.198462 #88920] INFO -- : Done!-
이 작업이 올바른 토큰을 재설정한다고 확신하면, dry-run 모드를 비활성화하고 작업을 다시 실행합니다:
DRY_RUN=false VERBOSE=true MODEL_NAMES=Project,Group TOKEN_NAMES=runners_token gitlab-rake gitlab:doctor:reset_encrypted_tokensbundle exec rake gitlab:doctor:reset_encrypted_tokens RAILS_ENV=production DRY_RUN=false VERBOSE=true MODEL_NAMES=Project,Group TOKEN_NAMES=runners_tokengitlab:doctor:reset_encrypted_tokens작업에는 다음과 같은 제한 사항이 있습니다:ApplicationSetting:ci_jwt_signing_key와 같은 비토큰 속성은 재설정되지 않습니다.- 단일 모델 레코드에 복호화할 수 없는 속성이 두 개 이상 있으면 작업이
TypeError: no implicit conversion of nil into String ... block in aes256_gcm_decrypt오류와 함께 실패합니다.
문제 해결#
다음은 앞서 설명한 Rake 작업을 사용하여 발견할 수 있는 문제에 대한 해결책입니다.
댕글링 객체#
gitlab-rake gitlab:git:fsck작업은 다음과 같은 댕글링 객체를 찾을 수 있습니다:dangling blob a12... dangling commit b34... dangling tag c56... dangling tree d78...이를 삭제하려면 하우스키핑 실행을 시도해 보세요.
문제가 지속되면 Rails Console을 통해 가비지 컬렉션을 트리거해 보세요:
p = Project.find_by_path("project-name") Repositories::HousekeepingService.new(p, :gc).execute댕글링 객체가 기본 유예 기간인 2주보다 젊고 자동으로 만료될 때까지 기다리지 않으려면 다음을 실행합니다:
Repositories::HousekeepingService.new(p, :prune).execute누락된 원격 업로드에 대한 참조 삭제#
gitlab-rake gitlab:uploads:check VERBOSE=1은 외부에서 삭제되었지만 참조가 여전히 GitLab 데이터베이스에 존재하는 원격 객체를 감지합니다.오류 메시지가 포함된 출력 예시:
$ sudo gitlab-rake gitlab:uploads:check VERBOSE=1 Checking integrity of Uploads - 100..434: Failures: 2 - Upload: 100: Remote object does not exist - Upload: 101: Remote object does not exist Done!외부에서 삭제된 원격 업로드에 대한 이러한 참조를 삭제하려면 GitLab Rails Console을 열고 실행합니다:
uploads_deleted=0 Upload.find_each do |upload| next if upload.retrieve_uploader.file.exists? uploads_deleted=uploads_deleted + 1 p upload ### allow verification before destroy # p upload.destroy! ### uncomment to actually destroy end p "#{uploads_deleted} remote objects were destroyed."누락된 아티팩트에 대한 참조 삭제#
gitlab-rake gitlab:artifacts:check VERBOSE=1은 아티팩트(또는job.log파일)가:- GitLab 외부에서 삭제되었을 때.
- 참조가 여전히 GitLab 데이터베이스에 있을 때.
이 시나리오가 감지되면 Rake 작업은 오류 메시지를 표시합니다. 예:
Checking integrity of Job artifacts - 1..15: Failures: 2 - Job artifact: 9: # - Job artifact: 15: Remote object does not exist Done!누락된 로컬 및/또는 원격 아티팩트(
job.log파일)에 대한 이러한 참조를 삭제하려면:-
GitLab Rails Console을 엽니다.
-
다음 Ruby 코드를 실행합니다:
artifacts_deleted = 0 ::Ci::JobArtifact.find_each do |artifact| ### Iterate artifacts # next if artifact.file.filename != "job.log" ### Uncomment if only `job.log` files' references are to be processed next if artifact.file.file.exists? ### Skip if the file reference is valid artifacts_deleted += 1 puts "#{artifact.id} #{artifact.file.path} is missing." ### Allow verification before destroy # artifact.destroy! ### Uncomment to actually destroy end puts "Count of identified/destroyed invalid references: #{artifacts_deleted}"
누락된 LFS 객체에 대한 참조 삭제#
gitlab-rake gitlab:lfs:check VERBOSE=1이 데이터베이스에는 있지만 디스크에는 없는 LFS 객체를 감지하면, LFS 문서의 절차를 따라 데이터베이스 항목을 제거합니다.댕글링 객체 스토리지 참조 업데이트#
객체 스토리지에서 로컬 스토리지로 마이그레이션하고 파일이 누락된 경우 댕글링 데이터베이스 참조가 남습니다.
마이그레이션 로그에 다음과 같은 오류가 표시됩니다:
W, [2022-11-28T13:14:09.283833 #10025] WARN -- : Failed to transfer Ci::JobArtifact ID 11 with error: undefined method `body' for nil:NilClass W, [2022-11-28T13:14:09.296911 #10025] WARN -- : Failed to transfer Ci::JobArtifact ID 12 with error: undefined method `body' for nil:NilClass객체 스토리지를 비활성화한 후 누락된 아티팩트에 대한 참조 삭제를 시도하면 다음 오류가 발생합니다:
RuntimeError (Object Storage is not enabled for JobArtifactUploader)이러한 참조를 로컬 스토리지를 가리키도록 업데이트하려면:
-
GitLab Rails Console을 엽니다.
-
다음 Ruby 코드를 실행합니다:
artifacts_updated = 0 ::Ci::JobArtifact.find_each do |artifact| ### Iterate artifacts next if artifact.file_store != 2 ### Skip if file_store already points to local storage artifacts_updated += 1 # artifact.update(file_store: 1) ### Uncomment to actually update end puts "Updated file_store count: #{artifacts_updated}"
누락된 아티팩트에 대한 참조 삭제 스크립트는 이제 정상적으로 작동하여 데이터베이스를 정리합니다.
누락된 보안 파일에 대한 참조 삭제#
VERBOSE=1 gitlab-rake gitlab:ci_secure_files:check는 보안 파일이:- GitLab 외부에서 삭제되었을 때.
- 참조가 여전히 GitLab 데이터베이스에 있을 때.
이 시나리오가 감지되면 Rake 작업은 오류 메시지를 표시합니다. 예:
Checking integrity of CI Secure Files - 1..15: Failures: 2 - Job SecureFile: 9: # - Job SecureFile: 15: Remote object does not exist Done!누락된 로컬 또는 원격 보안 파일에 대한 이러한 참조를 삭제하려면:
-
GitLab Rails Console을 엽니다.
-
다음 Ruby 코드를 실행합니다:
secure_files_deleted = 0 ::Ci::SecureFile.find_each do |secure_file| ### Iterate secure files next if secure_file.file.file.exists? ### Skip if the file reference is valid secure_files_deleted += 1 puts "#{secure_file.id} #{secure_file.file.path} is missing." ### Allow verification before destroy # secure_file.destroy! ### Uncomment to actually destroy end puts "Count of identified/destroyed invalid references: #{secure_files_deleted}"
-