Rails 콘솔 세션에서 다음을 사용하여 그룹 임포트 시도에 대한 실패 또는 오류 메시지를 찾을 수 있습니다:

# Get relevant import records
import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import).last

# Alternative lookup by user
import = BulkImport.where(user_id: User.find(...)).last

# Get list of import entities. Each entity represents either a group or a project
entities = import.entities

# Get a list of entity failures
entities.map(&:failures).flatten

# Alternative failure lookup by status
entities.where(status: [-1]).pluck(:destination_name, :destination_namespace, :status)

API 엔드포인트를 사용하여 관련된 실패와 함께 모든 마이그레이션된 엔티티를 볼 수도 있습니다.

마이그레이션이 느리거나 시간 초과#

마이그레이션 중 매우 느린 마이그레이션이나 시간 초과를 경험하는 경우 다음 전략을 사용하여 마이그레이션 기간을 줄입니다.

대상 인스턴스에 Sidekiq 워커 추가#

GitLab Self-Managed 인스턴스로 마이그레이션하는 경우 마이그레이션 속도를 높이기 위해 대상 인스턴스에 Sidekiq 워커를 추가할 수 있습니다. Sidekiq 워커 수를 늘릴 때는 다음을 고려해야 합니다:

• 단일 다이렉트 트랜스퍼 마이그레이션은 대상 인스턴스에서 사용 가능한 Sidekiq 워커 수와 상관없이 한 번에 5개의 그룹 또는 프로젝트를 마이그레이션합니다.
• 대상 인스턴스는 더 많은 동시 작업을 처리할 용량이 있어야 합니다. 그런 경우 Sidekiq 워커를 추가하면 각 그룹 또는 프로젝트를 임포트하는 데 걸리는 시간을 줄일 수 있습니다.

대상 인스턴스에 Sidekiq 워커를 추가하는 방법에 대한 자세한 내용은 임포트를 위한 Sidekiq 구성을 참조하세요.

별도의 마이그레이션 시작#

소스 인스턴스에 5개의 그룹을 병렬로 내보낼 리소스가 없는 경우 지연 및 잠재적인 시간 초과가 발생할 수 있습니다. 소스 인스턴스의 리소스가 부족하면 대상 인스턴스는 내보낸 데이터가 사용 가능해질 때까지 기다려야 합니다.

병렬 내보내기로 인한 지연을 줄이려면 모든 그룹과 프로젝트를 동시에 대신 각 그룹에 대해 별도의 마이그레이션을 시작하세요. GitLab UI는 최상위 그룹만 마이그레이션할 수 있으므로 서브그룹의 프로젝트를 마이그레이션하려면 API를 사용해야 할 수 있습니다.

오래된 임포트#

소스 또는 대상 인스턴스의 문제로 인해 마이그레이션이 중단되거나 timeout 상태로 완료될 수 있습니다. 이러한 문제를 해결하려면 소스와 대상 인스턴스 모두의 로그를 검사합니다.

소스 인스턴스#

소스 인스턴스에서 오래된 임포트는 종종 과도한 메모리 사용으로 인해 발생하며, 이로 인해 Sidekiq 프로세스가 재시작되고 내보내기 작업이 중단될 수 있습니다. 대상 인스턴스는 마이그레이션이 결국 시간 초과될 때까지 내보내기 파일을 기다릴 수 있습니다.

그룹 또는 프로젝트 관계가 성공적으로 내보내졌는지 확인하려면 다음 명령을 실행합니다:

curl --request GET --location "https://example.gitlab.com/api/v4/projects/:ID/export_relations/status" \
--header "PRIVATE-TOKEN: <your_access_token>"

의 상태가 1이 아닌 경우 관계가 성공적으로 내보내지지 않았으며 문제가 소스 인스턴스에 있습니다.

다음 명령을 실행하여 중단된 내보내기 작업을 검색할 수도 있습니다. Sidekiq 로그는 재시작 후 교체될 수 있으므로 교체된 로그도 확인하세요.

grep `BulkImports::RelationBatchExportWorker` sidekiq.log | grep "interrupted_count"

Sidekiq 재시작이 문제를 일으키는 경우:

• 내보내기 작업에 대해 별도의 Sidekiq 프로세스를 구성합니다. 자세한 내용은 임포트를 위한 Sidekiq 구성을 참조하세요. 문제가 지속되면 Sidekiq 동시성을 줄여 동시에 처리되는 작업 수를 제한합니다.

• Sidekiq 메모리 한도 늘리기: 인스턴스에 사용 가능한 메모리가 있다면 Sidekiq 프로세스의 최대 RSS 한도를 늘립니다. 예를 들어 한도를 2GB에서 3GB로 늘려 빈번한 재시작을 방지할 수 있습니다.

• 최대 중단 횟수 늘리기: 작업이 실패하기 전에 더 많은 중단을 허용하려면 BulkImports::RelationBatchExportWorker의 최대 중단 횟수를 늘릴 수 있습니다:

  1. 한도를 20으로 늘리기 위해 다음 구성을 추가합니다(기본값은 3):

     sidekiq_options max_retries_after_interruption: 20
     

  2. 변경 사항이 적용되도록 Sidekiq을 재시작합니다.

이제 새 마이그레이션을 트리거하거나 프로젝트 관계 내보내기 API를 사용하여 수동으로 내보내기를 트리거할 수 있습니다. 관계가 성공적으로 내보내지고 있는지 확인하려면 내보내기 상태를 확인합니다.

예를 들어 특정 프로젝트의 내보내기를 트리거하려면 다음 명령을 실행합니다:

curl --request POST --location "https://example.gitlab.com/api/v4/projects/:ID/export_relations" \
--header "PRIVATE-TOKEN: <your_access_token>" \
--form 'batched="true"'

대상 인스턴스#

드문 경우에 대상 인스턴스가 그룹 또는 프로젝트를 성공적으로 마이그레이션하지 못할 수 있습니다. 자세한 내용은 이슈 498720을 참조하세요.

이 문제를 해결하려면 임포트 API를 사용하여 실패한 그룹 또는 프로젝트를 마이그레이션합니다. 이 API를 사용하면 특정 그룹과 프로젝트를 개별적으로 마이그레이션할 수 있습니다.

오류: 404 Group Not Found#

숫자만으로 구성된 경로(예: 5000)를 가진 그룹을 임포트하려고 하면 GitLab은 경로 대신 ID로 그룹을 찾으려고 합니다. 이로 인해 GitLab 15.4 이하에서 404 Group Not Found 오류가 발생합니다.

이 문제를 해결하려면 다음 중 하나를 사용하여 소스 그룹 경로를 비숫자 문자를 포함하도록 변경해야 합니다:

• GitLab UI:

  1. 상단 바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. 고급을 확장합니다.
  4. 그룹 URL 변경 아래에서 그룹 URL을 비숫자 문자를 포함하도록 변경합니다.

• 그룹 API.

기타 404 오류#

그룹을 임포트할 때 다른 404 오류를 받을 수 있습니다. 예:

"exception_message": "Unsuccessful response 404 from [FILTERED] Bo...",
"exception_class": "BulkImports::NetworkError",

이 오류는 소스 인스턴스에서 전송하는 문제를 나타냅니다. 이 문제를 해결하려면 소스 인스턴스의 사전 요건을 충족했는지 확인하세요.

일치하지 않는 그룹 또는 프로젝트 경로 이름#

소스 그룹 또는 프로젝트 경로가 이름 지정 규칙을 준수하지 않는 경우 경로가 유효하도록 정규화됩니다. 예를 들어 Destination-Project-Path는 destination-project-path로 정규화됩니다.

오류: command exited with error code 15 and Unable to save [FILTERED] into [FILTERED]#

다이렉트 트랜스퍼를 사용하여 프로젝트를 마이그레이션할 때 로그에서 command exited with error code 15 and Unable to save [FILTERED] into [FILTERED] 오류를 받을 수 있습니다. 이 오류를 받으면 안전하게 무시할 수 있습니다. GitLab이 종료된 명령을 재시도합니다.

오류: Batch export [batch_number] from source instance failed#

대상 인스턴스에서 다음 오류가 발생할 수 있습니다:

Batch export [batch_number] from source instance failed: [source instance error]

이 오류는 소스 인스턴스가 일부 레코드를 내보내지 못할 때 발생합니다. 가장 일반적인 이유는 다음과 같습니다:

• 디스크 공간 부족
• 메모리 부족으로 인한 Sidekiq 작업의 여러 번 중단
• 데이터베이스 명령문 시간 초과

이 문제를 해결하려면:

1. 소스 인스턴스의 문제를 식별하고 수정합니다.
2. 대상 인스턴스에서 부분적으로 임포트된 프로젝트 또는 그룹을 삭제하고 새 임포트를 시작합니다.

내보내지 못한 관계 및 배치에 대한 자세한 내용은 소스 인스턴스에서 프로젝트와 그룹의 내보내기 상태 API 엔드포인트를 사용합니다.

오류: duplicate key value violates unique constraint#

레코드를 임포트할 때 다음 오류가 발생할 수 있습니다:

PG::UniqueViolation: ERROR:  duplicate key value violates unique constraint

이 오류는 다음 경우에 발생할 수 있습니다:

• 임포트를 처리하는 Sidekiq 워커가 높은 메모리 또는 CPU 사용으로 인해 재시작됩니다. Sidekiq 임포트 중 리소스 문제를 줄이려면:
  • 임포트를 위한 Sidekiq 구성을 최적화합니다.
  • bulk_import_concurrent_pipeline_batch_limit 애플리케이션 설정에서 동시 작업 수를 제한합니다.
• 다른 소스 그룹의 그룹 또는 프로젝트를 단일 대상 그룹으로 통합하는 경우. 다른 소스 그룹의 에픽이 동일한 내부 ID(단일 그룹 내에서만 고유)를 가지는 경우, 이를 단일 대상 그룹으로 임포트하면 충돌이 발생합니다. 이 충돌은 index_issues_on_namespace_id_iid_unique 또는 index_epics_on_group_id_and_iid를 참조하는 PG::UniqueViolation: ERROR: duplicate key value violates unique constraint 오류를 일으킵니다.

오류: Import::BulkImports::FileDownloadStrategy::ServiceError Invalid content type#

GitLab 인스턴스 간 다이렉트 트랜스퍼를 사용할 때 다음 오류가 발생할 수 있습니다:

Import::BulkImports::FileDownloadStrategy::ServiceError Invalid content type

이 오류는 인스턴스 간 네트워크 트래픽 라우팅 방식과 관련이 있습니다. application/gzip 이외의 콘텐츠 유형이 반환되면 네트워크 요청이 GitLab Workhorse를 우회하고 있을 수 있습니다.

이 문제를 해결하려면:

• Ingress가 Puma로 직접 가는 대신 포트 8181에서 GitLab Workhorse를 통해 트래픽을 라우팅하도록 구성되어 있는지 확인합니다.
• 오브젝트 스토리지에 대해 프록시 다운로드를 활성화하는 것을 고려합니다.

(imported-xx-datetime)이 추가된 마일스톤 제목#

그룹을 임포트할 때 그룹 및 프로젝트 마일스톤 제목이 대상 네임스페이스의 기존 제목과 충돌하면 임포트된 마일스톤의 제목에 고유한 접미사가 추가됩니다. 예: 18.0 (imported-3d-1770206299).

이러한 마일스톤을 식별하려면 대상 인스턴스의 log/importer.log 파일에서 다음을 검색합니다:

Updating milestone title - source title used by existing group or project milestone

로그 항목에는 다음이 포함됩니다:

• importable_id: 임포트되는 그룹의 ID.
• milestone_title: 이름이 변경되는 마일스톤의 제목.
• existing_group_id 또는 existing_project_id: 기존 마일스톤을 포함하는 그룹 또는 프로젝트의 ID.

이 정보를 사용하여 마일스톤을 찾고 제목을 원하는 것으로 업데이트할 수 있습니다.