GitLab 백업 문제 해결

GitLab을 백업할 때 다음과 같은 문제가 발생할 수 있습니다.

Secrets 파일을 분실한 경우

비밀 파일을 백업하지 않은 경우, GitLab을 다시 올바르게 작동시키기 위해 여러 단계를 완료해야 합니다.

Secrets 파일은 필요한 중요 정보를 포함하는 열의 암호화 키를 저장하는 데 책임이 있습니다. 키가 분실되면 GitLab은 해당 열을 해독할 수 없어 다음 항목에 대한 액세스를 방해합니다:

CI/CD 변수 및 Runner 인증과 같은 경우, 멈춘 작업(stuck jobs) 또는 500 에러와 같은 예상치 못한 동작을 경험할 수 있습니다.

이 경우, CI/CD 변수 및 Runner 인증에 대한 모든 토큰을 재설정해야 합니다. 이에 대한 자세한 내용은 다음 섹션에서 설명됩니다. 토큰을 재설정한 후에 프로젝트를 방문하고 작업이 다시 실행되기를 기대할 수 있습니다.

경고: 이 섹션의 단계는 위에 나열된 항목에서 잠재적으로 데이터 손실로 이어질 수 있습니다. 프리미엄 또는 얼티밋 고객인 경우, 지원 요청을 열도록 고려하십시오.

모든 값이 해독될 수 있는지 확인

현재 Secrets를 사용하여 해독될 수 없는 값이 데이터베이스에 있는지 Rake 작업을 사용하여 확인할 수 있습니다.

백업 수행

분실된 Secrets 파일을 처리하기 위해 GitLab 데이터를 직접 수정해야 합니다.

경고: 어떠한 변경을 시도하기 전에 완전한 데이터베이스 백업을 만드는 것이 중요합니다.

사용자 이중 인증 (2FA) 비활성화

2FA가 활성화된 사용자는 GitLab에 로그인할 수 없습니다. 이 경우 모두를 위해 2FA를 비활성화해야 합니다. 그 후 사용자는 2FA를 다시 활성화해야 합니다.

CI/CD 변수 재설정

  1. 데이터베이스 콘솔에 들어갑니다:

    Linux 패키지(Omnibus)의 경우: 

    sudo gitlab-rails dbconsole --database main

    자체 컴파일된 설치의 경우: 

    sudo -u git -H bundle exec rails dbconsole -e production --database main

  2. ci_group_variables 및 ci_variables 테이블을 조사합니다: 

    SELECT * FROM public."ci_group_variables";
SELECT * FROM public."ci_variables";

    이러한 변수들을 삭제해야 합니다.

  3. 모든 변수를 삭제합니다: 

    DELETE FROM ci_group_variables;
DELETE FROM ci_variables;

  4. 특정 그룹 또는 프로젝트에서 변수를 삭제하려면 WHERE 문을 사용하여 DELETE를 지정해야 합니다: 

    DELETE FROM ci_group_variables WHERE group_id = <GROUPID>;
DELETE FROM ci_variables WHERE project_id = <PROJECTID>;

변경 사항이 적용되려면 GitLab을 다시 구성하거나 다시 시작해야 할 수 있습니다.

Runner 등록 토큰 재설정

  1. 데이터베이스 콘솔에 들어갑니다:

    Linux 패키지(Omnibus)의 경우: 

    sudo gitlab-rails dbconsole --database main

    자체 컴파일된 설치의 경우: 

    sudo -u git -H bundle exec rails dbconsole -e production --database main

  2. 프로젝트, 그룹 및 전체 인스턴스에 대한 모든 토큰을 지웁니다:

    경고: 최종 UPDATE 작업은 새로운 작업을 수행할 수 없게 합니다. 새로운 runner를 등록해야 합니다. 

    -- 프로젝트 토큰 지우기
UPDATE projects SET runners_token = null, runners_token_encrypted = null;
-- 그룹 토큰 지우기
UPDATE namespaces SET runners_token = null, runners_token_encrypted = null;
-- 인스턴스 토큰 지우기
UPDATE application_settings SET runners_registration_token_encrypted = null;
-- JWT 인증에 사용되는 키 지우기
-- 이는 $CI_JWT_TOKEN 작업 변수를 망가뜨릴 수 있습니다:
-- https://gitlab.com/gitlab-org/gitlab/-/issues/325965
UPDATE application_settings SET encrypted_ci_jwt_signing_key = null;
-- Runner 토큰 지우기
UPDATE ci_runners SET token = null, token_encrypted = null;

보류 중인 파이프라인 작업 재설정

  1. 데이터베이스 콘솔에 들어갑니다:

    Linux 패키지(Omnibus)의 경우: 

    sudo gitlab-rails dbconsole --database main

    자체 컴파일된 설치의 경우: 

    sudo -u git -H bundle exec rails dbconsole -e production --database main

  2. 보류 중인 작업에 대한 모든 토큰을 지웁니다:

    GitLab 15.3 이전: 

    -- 빌드 토큰 지우기
UPDATE ci_builds SET token = null, token_encrypted = null;

    GitLab 15.4 이상: 

    -- 빌드 토큰 지우기
UPDATE ci_builds SET token_encrypted = null;

나머지 기능에 대해서도 유사한 전략을 적용할 수 있습니다. 해독할 수 없는 데이터를 삭제함으로써 GitLab을 다시 작동시키고 분실된 데이터를 수동으로 대체할 수 있습니다.

통합 및 웹훅 수정

Secrets를 분실한 경우, 통합 설정 및 웹훅 설정 페이지에서 500 에러 메시지가 표시될 수 있습니다. 분실된 Secrets는 이전에 구성된 통합 또는 웹훅이 있는 프로젝트의 저장소에 액세스하려고 할 때도 500 에러를 생성할 수 있습니다.

해결 방법은 영향을 받는 테이블(암호화된 열을 포함하는)을 잘라내는 것입니다. 이렇게 하면 구성된 모든 통합, 웹훅 및 관련된 메타데이터가 삭제됩니다. 데이터를 삭제하기 전에 Secrets가 원인인지 확인해야 합니다.

  1. 데이터베이스 콘솔에 들어갑니다:

    Linux 패키지(Omnibus)의 경우: 

    sudo gitlab-rails dbconsole --database main

    자체 컴파일된 설치의 경우: 

    sudo -u git -H bundle exec rails dbconsole -e production --database main

  2. 다음 테이블을 잘라냅니다: 

    -- 웹훅 테이블 잘라내기
TRUNCATE integrations, chat_names, issue_tracker_data, jira_tracker_data, slack_integrations, web_hooks, zentao_tracker_data, web_hook_logs CASCADE;

컨테이너 레지스트리가 복원되지 않음

환경의 컨테이너 레지스트리를 사용하는 백업을 새로 설치한 환경으로 복원하면 컨테이너 레지스트리가 복원되지 않습니다.

컨테이너 레지스트리도 복원하려면 백업을 복원하기 전에 새 환경에서 활성화해야 합니다.

백업에서 복원 후 컨테이너 레지스트리 푸시 실패

컨테이너 레지스트리를 사용하는 경우, 리눅스 패키지(Omnibus) 인스턴스에서 백업을 복원한 후 레지스트리 데이터를 복원하면 레지스트리로의 푸시가 실패할 수 있습니다.

이러한 실패는 레지스트리 로그에서 권한 문제를 언급하며 다음과 유사합니다: 

level=error
msg="response completed with error"
err.code=unknown
err.detail="filesystem: mkdir /var/opt/gitlab/gitlab-rails/shared/registry/docker/registry/v2/repositories/...: permission denied"
err.message="unknown error"

이 문제는 복원이 비권한 사용자 git로 실행되어 복원 프로세스 중에 레지스트리 파일에 올바른 소유권을 할당할 수 없는 것에서 발생합니다 (이슈 #62759).

다시 레지스트리를 작동시키려면 다음과 같이 합니다: 

sudo chown -R registry:registry /var/opt/gitlab/gitlab-rails/shared/registry/docker

레지스트리의 기본 파일 시스템 위치를 변경한 경우에는 /var/opt/gitlab/gitlab-rails/shared/registry/docker 대신 사용자 지정 위치에서 chown을 실행하십시오.

Gzip 오류로 인해 백업이 완료되지 않음

백업을 실행하는 동안 Gzip 오류 메시지를 받을 수 있습니다: 

sudo /opt/gitlab/bin/gitlab-backup create
...
덤프 중 ...
...
gzip: stdout: Input/output error

백업 실패

이런 경우 다음을 점검합니다:

  • Gzip 작업에 충분한 디스크 공간이 있는지 확인합니다. 백업 작성 중에 무료 디스크 공간이 인스턴스 크기의 절반을 필요로 할 수 있습니다.
  • NFS를 사용하는 경우, timeout 마운트 옵션이 설정되어 있는지 확인합니다. 기본값은 600이며, 더 작은 값으로 변경하면 이 오류가 발생합니다.

파일 이름이 너무 깁니다` 에러로 인해 백업이 실패

백업 중에 파일 이름이 너무 깁니다 오류가 발생할 수 있습니다 (이슈 #354984). 예를 들어: 

Problem: <class 'OSError: [Errno 36] File name too long:

이 문제로 인해 백업 스크립트가 완료되지 않습니다. 이 문제를 해결하려면 문제를 야기하는 파일 이름을 줄여야 합니다. 파일 확장자를 포함하여 최대 246자까지 허용됩니다.

경고: 이 섹션의 단계는 잠재적으로 데이터 손실로 이어질 수 있습니다. 모든 단계는 엄격하게 순서대로 따라야 합니다. 프리미엄 또는 얼티밋 고객이라면 지원 요청을 고려해 보십시오.

오류 해결을 위해 파일 이름을 줄이는 단계는 다음과 같습니다:

  • 데이터베이스에 추적되지 않은 원격 업로드 파일 정리
  • 데이터베이스에서 파일 이름을 줄임
  • 백업 작업을 다시 실행

원격 업로드 파일 정리

부모 리소스가 삭제된 후에도 객체 저장소 업로드가 남아있는 알려진 문제가 있습니다. 이 문제는 해결되었습니다.

이러한 파일을 수정하려면 데이터베이스 테이블의 uploads에 추적되지 않는 모든 원격 업로드 파일을 정리해야 합니다.

  1. 데이터베이스를 덤프하여 GitLab 데이터베이스에 존재하지 않는 모든 원격 업로드 파일을 나타냅니다: 

    bundle exec rake gitlab:cleanup:remote_upload_files RAILS_ENV=production

  2. 이러한 파일을 삭제하고 모든 비참조된 업로드 파일을 제거하려면 다음을 실행하십시오:

    경고: 다음 조치는 되돌릴 수 없습니다. 

    bundle exec rake gitlab:cleanup:remote_upload_files RAILS_ENV=production DRY_RUN=false

데이터베이스에서 파일 이름을 줄이기

문제를 일으키는 데이터베이스에서 파일 이름을 줄여야 합니다. 데이터베이스에 저장된 파일 이름은 다음과 같이 찾을 수 있습니다:

  • uploads 테이블.
  • 찾은 참조. 다른 데이터베이스 테이블 및 열에서 찾은 참조.
  • 파일 시스템.

업로드 테이블에서 파일 이름을 줄입니다:

  1. 데이터베이스 콘솔에 입력하십시오:

    리눅스 패키지(Omnibus)의 경우: 

    sudo gitlab-rails dbconsole --database main

    직접 컴파일한 설치의 경우: 

    sudo -u git -H bundle exec rails dbconsole -e production --database main

  2. 246자보다 긴 파일 이름을 가진 uploads 레코드를 선택합니다: 이 쿼리는 0부터 10000까지 배치로 246자 이상인 uploads 레코드를 선택합니다. 이를 통해 테이블이 엄청나게 많은 레코드를 가질 수 있는 대규모 GitLab 인스턴스에서 성능을 향상시킵니다. 

       CREATE TEMP TABLE uploads_with_long_filenames AS
   SELECT ROW_NUMBER() OVER(ORDER BY id) row_id, id, path
   FROM uploads AS u
   WHERE LENGTH((regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1]) > 246;

   CREATE INDEX ON uploads_with_long_filenames(row_id);

   SELECT
      u.id,
      u.path,
      -- 현재 파일 이름
      (regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1] AS current_filename,
      -- 새 파일 이름
      CONCAT(
         LEFT(SPLIT_PART((regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1], '.', 1), 242),
         COALESCE(SUBSTRING((regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1] FROM '\.(?:.(?!\.))+$'))
      ) AS new_filename,
      -- 새 경로
      CONCAT(
         COALESCE((regexp_match(u.path, '(.*\/).*'))[1], ''),
         CONCAT(
            LEFT(SPLIT_PART((regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1], '.', 1), 242),
            COALESCE(SUBSTRING((regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1] FROM '\.(?:.(?!\.))+$'))
         )
      ) AS new_path
   FROM uploads_with_long_filenames AS u
   WHERE u.row_id > 0 AND u.row_id <= 10000;

    출력 예: 

       -[ RECORD 1 ]----+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
   id               | 34
   path             | public/@hashed/loremipsumdolorsitametconsecteturadipiscingelitseddoeiusmodtemporincididuntutlaboreetdoloremagnaaliquaauctorelitsedvulputatemisitloremipsumdolorsitametconsecteturadipiscingelitseddoeiusmodtemporincididuntutlaboreetdoloremagnaaliquaauctorelitsedvulputatemisit.txt
   current_filename | loremipsumdolorsitametconsecteturadipiscingelitseddoeiusmodtemporincididuntutlaboreetdoloremagnaaliquaauctorelitsedvulputatemisitloremipsumdolorsitametconsecteturadipiscingelitseddoeiusmodtemporincididuntutlaboreetdoloremagnaaliquaauctorelitsedvulputatemisit.txt
   new_filename     | loremipsumdolorsitametconsecteturadipiscingelitseddoeiusmodtemporincididuntutlaboreetdoloremagnaaliquaauctorelitsedvulputatemisitloremipsumdolorsitametconsecteturadipiscingelitseddoeiusmodtemporincididuntutlaboreetdoloremagnaaliquaauctorelits.txt
   new_path         | public/@hashed/loremipsumdolorsitametconsecteturadipiscingelitseddoeiusmodtemporincididuntutlaboreetdoloremagnaaliquaauctorelitsedvulputatemisitloremipsumdolorsitametconsecteturadipiscingelitseddoeiusmodtemporincididuntutlaboreetdoloremagnaaliquaauctorelits.txt

    여기서:

    • current_filename: 246자보다 긴 파일 이름입니다.
    • new_filename: 246자로 줄인 새 파일 이름입니다.

    배치 결과를 확인한 후에는 다음에 레코드의 마지막까지 반복하여 batch size (row_id)를 변경해야 합니다.

  3. 긴 파일 이름을 가진 레코드를 새로운 줄인 파일 이름으로 변경합니다. 다음 쿼리는 업데이트를 롤백하여 안전하게 결과를 확인할 수 있도록 합니다: 

    CREATE TEMP TABLE uploads_with_long_filenames AS
SELECT ROW_NUMBER() OVER(ORDER BY id) row_id, path, id
FROM uploads AS u
WHERE LENGTH((regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1]) > 246;

CREATE INDEX ON uploads_with_long_filenames(row_id);

BEGIN;
WITH updated_uploads AS (
   UPDATE uploads
   SET
      path =
      CONCAT(
         COALESCE((regexp_match(updatable_uploads.path, '(.*\/).*'))[1], ''),
         CONCAT(
            LEFT(SPLIT_PART((regexp_match(updatable_uploads.path, '[^\\/:*?"<>|\r\n]+$'))[1], '.', 1), 242),
            COALESCE(SUBSTRING((regexp_match(updatable_uploads.path, '[^\\/:*?"<>|\r\n]+$'))[1] FROM '\.(?:.(?!\.))+$'))
         )
      )
   FROM
      uploads_with_long_filenames AS updatable_uploads
   WHERE
      uploads.id = updatable_uploads.id
   AND updatable_uploads.row_id > 0 AND updatable_uploads.row_id  <= 10000
   RETURNING uploads.*
)
SELECT id, path FROM updated_uploads;
ROLLBACK;

    배치 업데이트 결과를 확인한 후에는 다음에 레코드의 마지막까지 반복하여 batch size (row_id)를 변경해야 합니다.

  4. 이전 쿼리의 새 파일 이름이 예상대로 맞는지 확인합니다. 이전 단계에서 찾은 레코드를 246 문자로 줄이려면 다음을 실행합니다:

    경고: 다음 조치는 되돌릴 수 없습니다. 

    CREATE TEMP TABLE uploads_with_long_filenames AS
SELECT ROW_NUMBER() OVER(ORDER BY id) row_id, path, id
FROM uploads AS u
WHERE LENGTH((regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1]) > 246;

CREATE INDEX ON uploads_with_long_filenames(row_id);

UPDATE uploads
SET
path =
   CONCAT(
      COALESCE((regexp_match(updatable_uploads.path, '(.*\/).*'))[1], ''),
      CONCAT(
         LEFT(SPLIT_PART((regexp_match(updatable_uploads.path, '[^\\/:*?"<>|\r\n]+$'))[1], '.', 1), 242),
         COALESCE(SUBSTRING((regexp_match(updatable_uploads.path, '[^\\/:*?"<>|\r\n]+$'))[1] FROM '\.(?:.(?!\.))+$'))
      )
   )
FROM
uploads_with_long_filenames AS updatable_uploads
WHERE
uploads.id = updatable_uploads.id
AND updatable_uploads.row_id > 0 AND updatable_uploads.row_id  <= 10000;

    배치 업데이트 완료 후에는 다음에 레코드의 마지막까지 반복하여 batch size (updatable_uploads.row_id)를 변경해야 합니다.

파일 시스템의 파일 이름을 줄입니다. uploads 테이블을 쿼리하여 받은 새 파일 이름으로 파일 시스템에서 파일 이름을 수동으로 바꿔야 합니다.

백업 작업 다시 실행하기

이전 단계를 모두 따른 후, 백업 작업을 다시 실행하세요.

pg_stat_statements가 이전에 활성화된 경우 데이터베이스 백업 복원 실패

PostgreSQL 데이터베이스의 GitLab 백업에는 이전에 데이터베이스에서 활성화된 확장 기능을 활성화하는 데 필요한 모든 SQL 문이 포함됩니다.

pg_stat_statements 확장 기능은 PostgreSQL 사용자 중 슈퍼유저 역할을 가진 사용자만 활성화 또는 비활성화할 수 있습니다. 복원 프로세스는 제한된 권한을 가진 데이터베이스 사용자를 사용하므로 다음 SQL 문을 실행할 수 없습니다. 

DROP EXTENSION IF EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements WITH SCHEMA public;

pg_stats_statements 확장 기능이 없는 PostgreSQL 인스턴스에서 백업을 복원하려고 하면 다음 오류 메시지가 표시됩니다. 

ERROR: permission denied to create extension "pg_stat_statements"
HINT: Must be superuser to create this extension.
ERROR: extension "pg_stat_statements" does not exist

pg_stats_statements 확장 기능이 활성화된 인스턴스에서 복원을 시도하면 정리 단계에서 다음과 유사한 오류 메시지로 실패합니다. 

rake aborted!
ActiveRecord::StatementInvalid: PG::InsufficientPrivilege: ERROR: must be owner of view pg_stat_statements
/opt/gitlab/embedded/service/gitlab-rails/lib/tasks/gitlab/db.rake:42:in `block (4 levels) in <top (required)>'
/opt/gitlab/embedded/service/gitlab-rails/lib/tasks/gitlab/db.rake:41:in `each'
/opt/gitlab/embedded/service/gitlab-rails/lib/tasks/gitlab/db.rake:41:in `block (3 levels) in <top (required)>'
/opt/gitlab/embedded/service/gitlab-rails/lib/tasks/gitlab/backup.rake:71:in `block (3 levels) in <top (required)>'
/opt/gitlab/embedded/bin/bundle:23:in `load'
/opt/gitlab/embedded/bin/bundle:23:in `<main>'
Caused by:
PG::InsufficientPrivilege: ERROR: must be owner of view pg_stat_statements
/opt/gitlab/embedded/service/gitlab-rails/lib/tasks/gitlab/db.rake:42:in `block (4 levels) in <top (required)>'
/opt/gitlab/embedded/service/gitlab-rails/lib/tasks/gitlab/db.rake:41:in `each'
/opt/gitlab/embedded/service/gitlab-rails/lib/tasks/gitlab/db.rake:41:in `block (3 levels) in <top (required)>'
/opt/gitlab/embedded/service/gitlab-rails/lib/tasks/gitlab/backup.rake:71:in `block (3 levels) in <top (required)>'
/opt/gitlab/embedded/bin/bundle:23:in `load'
/opt/gitlab/embedded/bin/bundle:23:in `<main>'
Tasks: TOP => gitlab:db:drop_tables
(See full trace by running task with --trace)

덤프 파일에 pg_stat_statements 포함 방지

백업 번들의 일부인 PostgreSQL 덤프 파일에 확장 기능이 포함되지 않도록 하려면 public 스키마 이외의 다른 스키마에서 확장 기능을 활성화하세요. 

CREATE SCHEMA adm;
CREATE EXTENSION pg_stat_statements SCHEMA adm;

확장 기능이 이전에 public 스키마에서 활성화된 경우 새 스키마로 이동하세요. 

CREATE SCHEMA adm;
ALTER EXTENSION pg_stat_statements SET SCHEMA adm;

스키마를 변경한 후 pg_stat_statements 데이터를 조회하려면 새 스키마 이름으로 뷰 이름에 접두사를 붙이세요. 

SELECT * FROM adm.pg_stat_statements limit 0;

public 스키마에서 활성화되어 있어야 하는 타사 모니터링 솔루션과 호환되게 하려면 search_path에 포함하세요. 

set search_path to public,adm;

기존 덤프 파일 수정하여 pg_stat_statements 참조 제거

기존 백업 파일을 수정하려면 다음과 같은 변경을 수행하세요:

  1. 백업에서 다음 파일을 추출하세요: db/database.sql.gz.
  2. 파일을 압축 해제하거나 압축 처리할 수 있는 편집기를 사용하세요.

  3. 다음 또는 유사한 줄을 제거하세요: 

    CREATE EXTENSION IF NOT EXISTS pg_stat_statements WITH SCHEMA public;

    COMMENT ON EXTENSION pg_stat_statements IS 'track planning and execution statistics of all SQL statements executed';
  4. 변경 사항을 저장하고 파일을 다시 압축하세요.
  5. 수정된 db/database.sql.gz로 백업 파일을 업데이트하세요.