GitLab Pages 관리 문제 해결

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

이 페이지에는 GitLab Pages를 관리할 때 발생할 수 있는 문제 목록이 포함되어 있습니다.

GitLab Pages 로그 보기

다음 명령어를 실행하여 Pages 데몬 로그를 확인할 수 있습니다:

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"}

이는 Pages 서버 설정에서 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

GitLab Pages 프록시에 연결할 때 502 오류 (서버가 IPv6에서 수신 대기하지 않음)

일부 경우, NGINX는 서버가 IPv6에서 수신 대기하지 않더라도 GitLab Pages 서비스에 연결하기 위해 기본적으로 IPv6를 사용할 수 있습니다. 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 Pages listen_proxy 설정에 대해 명시적인 IP와 포트를 설정하여 GitLab Pages 데몬이 수신해야 하는 명시적 주소를 정의합니다:

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

간헐적인 502 오류 또는 며칠 후

systemd를 사용하는 시스템에서 Pages를 실행하면 tmpfiles.d를 통해 간헐적인 502 오류가 발생할 수 있으며, 오류는 다음과 유사합니다:

dial tcp: lookup gitlab.example.com on [::1]:53: dial udp [::1]:53: connect: no route to host"

GitLab Pages는 /tmp/gitlab-pages-* 내부에 /etc/hosts와 같은 파일을 포함하는 bind mount를 생성합니다. 그러나 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 Pages에 액세스할 수 없음

GitLab Pages에 액세스할 수 없는 경우(예: 502 Bad Gateway 오류가 발생하거나 로그인 루프가 발생하는 경우)

Pages 로그에 다음 오류가 표시됩니다:

"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 서버에서 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 인스턴스를 실행하면 Pages 콘텐츠를 제공할 때 간헐적인 502 오류 응답이 발생할 수 있습니다.

Pages 로그에서 다음 경고를 볼 수 있습니다:

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-secrets.json 파일이 GitLab Rails와 GitLab Pages 간에 오래된 경우 발생할 수 있습니다.

별도의 서버에서 GitLab Pages 실행하기 가이드의 8-10단계를 모든 GitLab Pages 인스턴스에서 따라야 합니다.

AWS 네트워크 로드 밸런서와 GitLab Pages를 사용할 때 간헐적인 502 오류

클라이언트 IP 보존이 활성화된 상태에서 네트워크 로드 밸런서를 사용할 때 연결이 시간 초과되며, 요청이 원본 서버로 루프백될 때 이러한 문제가 발생할 수 있습니다.

이것은 핵심 GitLab 애플리케이션과 GitLab Pages 모두를 실행하는 여러 서버를 가진 GitLab 인스턴스에서 발생할 수 있습니다.

하나의 컨테이너가 핵심 GitLab 애플리케이션과 GitLab Pages를 동시에 실행하는 경우에도 발생할 수 있습니다.

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

핵심 GitLab 애플리케이션과 GitLab Pages가 동일한 호스트 또는 컨테이너에서 실행되는 경우, 클라이언트 IP 보존을 끄면 이 문제가 해결될 수 있습니다.

securecookie: failed to generate random iv 및 Failed to save the session와 관련된 500 오류

이 문제는 대부분 구식 운영 체제에서 발생합니다.

Pages 데몬은 securecookie 라이브러리를 사용하여 crypto/rand in Go를 통해 랜덤 문자열을 가져옵니다.

이것은 호스트 운영 체제에서 getrandom 시스템 호출 또는 /dev/urandom이 사용 가능해야 합니다.

공식적으로 지원되는 운영 체제로 업그레이드하는 것이 권장됩니다.

요청된 범위가 유효하지 않거나, 잘못되었거나, 알 수 없습니다.

이 문제는 GitLab Pages OAuth 애플리케이션의 권한에서 발생합니다. 이를 수정하려면:

  1. 왼쪽 사이드바에서 하단의 Admin을 선택합니다.

  2. Applications > GitLab Pages를 선택합니다.

  3. 애플리케이션을 수정합니다.

  4. Scopes에서 api 범위가 선택되어 있는지 확인합니다.

  5. 변경 사항을 저장합니다.

별도의 Pages 서버를 실행하고 있는 경우, 이러한 설정을 주요 GitLab 서버에서 구성해야 합니다.

와일드카드 DNS 항목을 설정할 수 없는 경우의 우회 방법

와일드카드 DNS 필수 조건을 충족할 수 없는 경우, GitLab Pages를 제한된 방식으로 사용할 수 있습니다:

  1. 이동하여 Pages와 함께 사용할 필요가 있는 모든 프로젝트를 하나의 그룹 네임스페이스, 예를 들어 pages로 이동합니다.

  2. *.-와일드카드 없이 DNS 항목을 구성합니다. 예: pages.example.io.

  3. gitlab.rb 파일에 pages_external_url http://example.io/를 구성합니다. 여기서는 그룹 네임스페이스를 생략하십시오. 왜냐하면 GitLab에 의해 자동으로 추가되기 때문입니다.

Pages 데몬이 권한 거부 오류로 실패합니다.

/tmp가 noexec로 마운트된 경우, Pages 데몬은 다음과 같은 오류와 함께 시작하지 못합니다:

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

이 경우, TMPDIR을 noexec로 마운트되지 않은 위치로 변경합니다. /etc/gitlab/gitlab.rb에 다음 내용을 추가합니다:

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

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

Pages 접근 제어를 사용할 때 The redirect URI included is not valid.

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

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

    1. 왼쪽 사이드바에서 하단의 Admin을 선택합니다.

    2. Applications를 선택한 다음 Add new application을 선택합니다.

    3. Callback URL/Redirect URI가 pages_external_url에 구성된 프로토콜(HTTP 또는 HTTPS)을 사용하는지 확인합니다.

  2. Redirect URI의 도메인 및 경로 구성 요소가 유효한지 확인합니다: projects.<pages_external_url>/auth와 같아야 합니다.

500 오류 cannot serve from disk

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를 통해 파일을 동기화하는 별도의 서버에서 Pages를 실행하는 경우,

공유 페이지 디렉토리가 메인 GitLab 서버와 GitLab Pages 서버에서 다른 경로에 마운트되었을 수 있습니다.

이 경우, 오브젝트 스토리지 구성 및 기존 페이지 데이터를 이를 마이그레이션하는 것이 강력히 권장됩니다.

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

GitLab Pages 배포 작업이 “알려지지 않은 제공업체” 오류로 실패함

pages 작업은 성공하지만 deploy 작업이 “알려지지 않은 제공업체” 오류를 반환하는 경우:

GitLab Pages 파이프라인이 pages 작업에 대한 성공을 보여주지만 deploy 작업에 대한 오류를 보여줍니다.

오류 메시지 is not a recognized provider는 GitLab이 오브젝트 스토리지의 클라우드 제공업체에 연결하기 위해 사용하는 fog gem에서 발생할 수 있습니다.

이를 해결하려면:

  1. gitlab.rb 파일을 확인합니다. gitlab_rails['pages_object_store_enabled']가 활성화되어 있지만 버킷 세부사항이 구성되지 않은 경우:

    • S3 호환 연결 설정 가이드를 따라 Pages 배포를 위한 오브젝트 스토리지를 구성합니다.
    • 해당 줄의 주석을 달아 배포를 로컬에 저장합니다.

  2. gitlab.rb 파일에 변경한 내용을 저장한 후, GitLab 재구성을 수행합니다.

404 오류 찾고 있는 페이지를 찾을 수 없습니다

GitLab Pages에서 404 Page Not Found 응답을 받으면:

  1. .gitlab-ci.yml에 작업 pages:가 포함되어 있는지 확인합니다.
  2. 현재 프로젝트의 파이프라인에서 작업 pages:deploy가 실행되고 있는지 확인합니다.

pages:deploy 작업이 없으면 GitLab Pages 사이트에 대한 업데이트가 게시되지 않습니다.

503 오류 알 수 없는 클라이언트로 인해 클라이언트 인증에 실패했습니다

Pages가 등록된 OAuth 애플리케이션이고 액세스 제어가 활성화된 경우, 이 오류는 /etc/gitlab/gitlab-secrets.json에 저장된 인증 토큰이 유효하지 않게 되었음을 나타냅니다:

Client authentication failed due to unknown client, no client authentication included,
or unsupported authentication method.

이를 해결하려면:

  1. 비밀 파일을 백업합니다:

    sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.$(date +\%Y\%m\%d)
  2. /etc/gitlab/gitlab-secrets.json를 편집하고 gitlab_pages 섹션을 제거합니다.

  3. GitLab을 재구성하고 OAuth 토큰을 재생성합니다:

    sudo gitlab-ctl reconfigure