GitLab 페이지 관리 문제 해결

Tier: Free, Premium, Ultimate Offering: Self-managed

이 페이지에는 GitLab 페이지를 관리하는 동안 마주칠 수 있는 문제 디렉터리이 포함되어 있습니다.

GitLab 페이지 로그 보는 방법

다음 명령을 실행하여 페이지 데몬 로그를 볼 수 있습니다. 

sudo gitlab-ctl tail gitlab-pages

또한 /var/log/gitlab/gitlab-pages/current에서 로그 파일을 찾을 수 있습니다.

unsupported protocol scheme \"\""

다음 오류가 표시되면: 

{"error":"failed to connect to internal Pages API: Get \"/api/v4/internal/pages/status\": unsupported protocol scheme \"\"","level":"warning","msg":"attempted to connect to the API","time":"2021-06-23T20:03:30Z"}

이는 페이지 서버 설정에서 HTTP(S) 프로토콜 스키마를 설정하지 않았음을 의미합니다. 해결 방법:

  1. /etc/gitlab/gitlab.rb을 편집합니다: 

    gitlab_pages['gitlab_server'] = "https://<your_gitlab_server_public_host_and_port>"
gitlab_pages['internal_gitlab_server'] = "https://<your_gitlab_server_private_host_and_port>" # 선택 사항, gitlab_pages['gitlab_server']가 기본값으로 사용됨

  2. GitLab을 다시 구성합니다: 

    sudo gitlab-ctl reconfigure

IPv6를 통해 듣지 않는 서버에서 GitLab 페이지 프록시에 연결할 때 502 오류

일부 경우에, NGINX가 서버가 IPv6를 통해 듣지 않아도 GitLab 페이지 서비스에 연결하도록 기본 설정되어 있을 수 있습니다. 이것이 발생하는 경우, gitlab_pages_error.log에서 아래와 유사한 로그 항목을 보면 알 수 있습니다: 

2020/02/24 16:32:05 [error] 112654#0: *4982804 connect() failed (111: Connection refused) while connecting to upstream, client: 123.123.123.123, server: ~^(?<group>.*)\.pages\.example\.com$, request: "GET /-/group/project/-/jobs/1234/artifacts/artifact.txt HTTP/1.1", upstream: "http://[::1]:8090//-/group/project/-/jobs/1234/artifacts/artifact.txt", host: "group.example.com"

이를 해결하기 위해 GitLab 페이지 데몬이 수신 대기를 가져올 명시적 IP와 포트를 정의하기 위해 GitLab Pages listen_proxy 설정에 명시적 주소를 정의합니다: 

gitlab_pages['listen_proxy'] = '127.0.0.1:8090'

간헐적인 502 오류 또는 일부 날 후에

systemd 및 tmpfiles.d를 사용하는 시스템에서 Pages를 실행하는 경우, DNS 설정이 손실될 수 있는 /tmp/gitlab-pages- * 내에 바인드 마운트를 만듭니다. 그러나, systemd는 정기적으로 /tmp/ 디렉터리를 청소할 수 있으므로 DNS 구성이 손실될 수 있습니다.

systemd가 Pages 관련 콘텐츠를 청소하지 않도록하기 위해 다음을 수행합니다:

  1. tmpfiles.d에 Pages /tmp 디렉터리를 제거하지 않도록 지시합니다: 

    echo 'x /tmp/gitlab-pages-*' >> /etc/tmpfiles.d/gitlab-pages-jail.conf

  2. GitLab Pages를 다시 시작합니다: 

    sudo gitlab-ctl restart gitlab-pages

GitLab 페이지 접근 불가

GitLab Pages에 액세스할 수 없는 경우(예: 502 Bad Gateway 오류 수신 또는 로그인 루프) 및 페이지 로그에 다음 오류가 표시되면: 

"error":"retrieval context done: context deadline exceeded","host":"root.docs-cit.otenet.gr","level":"error","msg":"could not fetch domain information from a source"

  1. /etc/gitlab/gitlab.rb에 다음을 추가합니다: 

    gitlab_pages['internal_gitlab_server'] = 'http://localhost:8080'

  2. GitLab Pages를 다시 시작합니다: 

    sudo gitlab-ctl restart gitlab-pages

내부 GitLab API에 연결할 수 없음

다음 오류가 표시되면: 

ERRO[0010] Failed to connect to the internal GitLab API after 0.50s  error="failed to connect to internal Pages API: HTTP status: 401"

별도의 서버에서 GitLab Pages를 실행하는 경우 GitLab 13.3로 업그레이드한 후 GitLab 서버에서 Pages 서버로 /etc/gitlab/gitlab-secrets.json 파일을 복사해야 합니다. 해당 섹션에 설명된 대로

기타 이유로는 GitLab 서버와 Pages 서버 간의 네트워크 연결 문제(방화벽 구성 또는 폐쇄된 포트 등)가 포함될 수 있습니다. 예를 들어 연결 시간 제한이 있는 경우: 

error="failed to connect to internal Pages API: Get \"https://gitlab.example.com:3000/api/v4/internal/pages/status\": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)"

Pages가 GitLab API의 인스턴스와 통신할 수 없음

domain_config_source=auto의 기본 값을 사용하고 여러 인스턴스의 GitLab Pages를 실행하는 경우 페이지 콘텐츠를 제공하는 동안 간헐적인 502 오류 응답을 볼 수 있습니다. 페이지 로그에서 다음 경고도 볼 수 있습니다: 

WARN[0010] Pages cannot communicate with an instance of the GitLab API. Please sync your gitlab-secrets.json file https://gitlab.com/gitlab-org/gitlab-pages/-/issues/535#workaround. error="pages endpoint unauthorized"

이는 GitLab Rails와 GitLab Pages 간에 gitlab-secrets.json 파일이 오래된 경우 발생할 수 있습니다. 모든 GitLab Pages 인스턴스에서 별도의 서버에서 GitLab Pages 실행의 단계 8-10을 따릅니다.

AWS 네트워크 로드 밸런서와 GitLab 페이지를 사용할 때 간헐적으로 발생하는 502 오류

커넥션은 클라이언트 IP 보존이 활성화된 상태에서 네트워크 로드 밸런서를 사용할 때 시간 초과될 수 있으며 요청이 소스 서버로 루프백될 수 있습니다. 이는 여러 서버에서 GitLab 인스턴스에 발생할 수 있으며, 이러한 서버에서는 핵심 GitLab 애플리케이션과 GitLab 페이지가 모두 실행됩니다. 또한, 핵심 GitLab 애플리케이션과 GitLab 페이지가 동일한 호스트 또는 컨테이너에서 실행될 때도 발생할 수 있습니다.

AWS는 이 문제를 해결하기 위해 IP 대상 유형을 사용하는 것을 권장합니다.

핵심 GitLab 애플리케이션과 GitLab 페이지가 동일한 호스트 또는 컨테이너에서 실행될 때 클라이언트 IP 보존을 비활성화하면 이 문제를 해결할 수 있습니다.

securecookie: failed to generate random iv 및 Failed to save the session으로 인한 500 오류

이 문제는 아마도 지원 중단된 운영 체제에서 발생한 것으로 보입니다. 페이지 데몬은 securecookie 라이브러리를 사용하여 Go의 crypto/rand를 통해 무작위 문자열을 가져옵니다. 이를 위해서는 호스트 운영 체제에 getrandom 시스템 호출 또는 /dev/urandom이 있어야 합니다. 공식적으로 지원되는 운영 체제로 업그레이드하는 것이 좋습니다.

요청된 스코프가 잘못되었거나 알 수 없는 문제

이 문제는 GitLab 페이지 OAuth 애플리케이션의 권한에서 발생합니다. 이를 해결하려면 다음을 수행하세요:

  1. 왼쪽 사이드바에서 맨 아래쪽에 있는 관리 영역을 선택합니다.
  2. 애플리케이션 > GitLab 페이지를 선택합니다.
  3. 애플리케이션을 편집합니다.
  4. 스코프에서 api 스코프가 선택되었는지 확인합니다.
  5. 변경 사항을 저장합니다.

별도의 페이지 서버를 실행할 때는 주 요 GitLab 서버에서 이 설정을 구성해야 합니다.

와일드카드 DNS 항목을 설정할 수 없는 경우의 해결책

와일드카드 DNS 전제 조건을 충족시키지 못하면 GitLab 페이지를 제한된 방식으로 사용할 수 있습니다:

  1. 페이지를 사용해야 하는 모든 프로젝트를 하나의 그룹 네임스페이스(예: pages)로 이동합니다.
  2. *.-와일드카드 없이 DNS 항목을 구성합니다. 예: pages.example.io.
  3. gitlab.rb 파일에서 pages_external_url http://example.io/을 구성합니다. 여기서 그룹 네임스페이스를 생략합니다. GitLab에서 자동으로 앞에 추가되기 때문입니다.

페이지 데몬이 권한이 거부된 오류로 실패하는 경우

/tmp가 noexec로 마운트되어 있는 경우, 페이지 데몬이 다음과 유사한 오류로 시작하지 못할 수 있습니다: 

{"error":"fork/exec /gitlab-pages: permission denied","level":"fatal","msg":"could not create pages daemon","time":"2021-02-02T21:54:34Z"}

이 경우 /etc/gitlab/gitlab.rb에 다음을 추가하십시오: 

gitlab_pages['env'] = {'TMPDIR' => '<new_tmp_path>'}

추가한 후 sudo gitlab-ctl reconfigure로 재구성하고 sudo gitlab-ctl restart로 GitLab을 다시 시작하세요.

Pages Access Control을 사용할 때 The redirect URI included is not valid.

pages_external_url이 어느 시점에서 업데이트된 경우 이 오류가 발생할 수 있습니다. 다음을 확인하세요:

  1. 시스템 OAuth 애플리케이션을 확인합니다:

    1. 왼쪽 사이드바에서 맨 아래쪽에 있는 관리 영역을 선택합니다.
    2. 애플리케이션을 선택한 다음 새 애플리케이션 추가를 선택합니다.
    3. Callback URL/Redirect URI가 pages_external_url에서 구성된 프로토콜(HTTP 또는 HTTPS)을 사용하는지 확인합니다.

  2. Redirect URI의 도메인 및 경로 컴포넌트가 유효한지 확인합니다. 다음과 같이 보여야 합니다: projects.<pages_external_url>/auth.

cannot serve from disk로 인한 500 오류

Pages에서 500 응답을 받고 다음과 유사한 오류에 직면하면: 

ERRO[0145] cannot serve from disk                        error="gitlab: disk access is disabled via enable-disk=false" project_id=27 source_path="file:///shared/pages/@hashed/67/06/670671cd97404156226e507973f2ab8330d3022ca96e0c93bdbdb320c41adcaf/pages_deployments/14/artifacts.zip" source_type=zip

이는 GitLab Rails가 GitLab Pages에게 디스크의 위치에서 콘텐츠를 제공하도록 지시하지만, GitLab Pages가 디스크 액세스를 비활성화하도록 구성된 경우입니다.

디스크 액세스를 활성화하려면:

  1. /etc/gitlab/gitlab.rb에서 GitLab Pages의 디스크 액세스를 활성화합니다: 

    gitlab_pages['enable_disk'] = true

  2. GitLab을 재구성합니다.

httprange: new resource 403 오류

다음과 유사한 오류가 표시된다면: 

{"error":"httprange: new resource 403: \"403 Forbidden\"","host":"root.pages.example.com","level":"error","msg":"vfs.Root","path":"/pages1/","time":"2021-06-10T08:45:19Z"}

그리고 별도의 서버에서 파일을 NFS를 통해 동기화하는 페이지를 실행 중이라면, 공유 페이지 디렉터리가 주 요 GitLab 서버와 GitLab Pages 서버의 다른 경로에 마운트되어 있을 수 있습니다.

이 경우 객체 리포지터리를 구성하고 기존 페이지 데이터를 마이그레이션하는 것이 매우 권장됩니다.

또는 GitLab Pages 공유 디렉터리를 두 서버에서 동일한 경로로 마운트할 수 있습니다.

GitLab Pages가 GitLab 14.0 이상으로 업그레이드된 후 작동하지 않는 문제

GitLab 14.0은 GitLab Pages에 몇 가지 변경 사항을 도입하여 매뉴얼 개입이 필요할 수 있습니다.

  1. 먼저 마이그레이션 가이드를 따르세요.
  2. GitLab 14.3 이상으로 업그레이드를 시도하세요. 일부 문제는 GitLab 14.1, 14.2 및 14.3에서 수정되었습니다.
  3. 작동하지 않는 경우 GitLab Pages 로그를 참조하고 거기서 오류가 발견된 경우 해당 오류를 이 페이지에서 검색하세요.
caution
GitLab 14.0-14.2에서는 일시적으로 레거시 리포지터리 및 구성 메커니즘을 활성화할 수 있습니다.

다음을 수행하세요:

  1. 마이그레이션 피드백 이슈에 보고하는 문제를 설명하세요.

  2. /etc/gitlab/gitlab.rb 파일을 편집하세요: 

    gitlab_pages['use_legacy_storage'] = true
  3. GitLab을 재구성하세요.

GitLab Pages 배포 작업이 “is not a recognized provider” 오류로 실패하는 경우

pages 작업은 성공하지만 deploy 작업에서 “is not a recognized provider” 오류가 발생하는 경우:

Pages Deploy Failure

오류 메시지 is not a recognized provider는 GitLab이 객체 리포지터리에 연결하기 위해 사용하는 fog 젬에서 올 수 있습니다.

해결 방법:

  1. gitlab.rb 파일을 확인하세요. gitlab_rails['pages_object_store_enabled']가 활성화되어 있지만 버킷 세부 정보가 구성되지 않은 경우 다음 중 하나를 수행하세요:

    • S3 호환 연결 설정 가이드를 따라 페이지 배포용 객체 리포지터리를 구성합니다.
    • 해당 줄을 주석 처리하여 배포를 로컬로 저장합니다.

  2. gitlab.rb 파일에 적용한 변경 사항을 저장한 다음, GitLab을 재구성하세요.

404 오류 “찾을 수 없는 페이지”

GitLab Pages에서 404 Page Not Found 응답을받는 경우:

  1. .gitlab-ci.yml 파일이 작업 pages:를 포함하는지 확인하세요.
  2. 현재 프로젝트의 파이프라인을 확인하여 작업 pages:deploy가 실행되는지 확인하세요.

pages:deploy 작업이 없으면 GitLab Pages 사이트의 업데이트가 공개되지 않습니다.