GitLab 페이지 관리 문제 해결

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

이 페이지에는 GitLab 페이지를 관리하는 중에 마주칠 수 있는 문제 목록이 포함되어 있습니다.

GitLab 페이지 로그 보는 방법

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

sudo gitlab-ctl tail gitlab-pages

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

지원되지 않는 프로토콜 스킴 ""

다음과 같은 오류가 표시되면: 

{"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 오류

일부 경우에, GitLab 페이지 서비스에 연결하기 위해 NGINX가 기본적으로 IPv6를 사용하는 경우가 있습니다. 이 경우 아래의 로그 항목과 유사한 내용을 볼 수 있다면 발생합니다. 

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 페이지 listen_proxy 설정에 명시적인 IP와 포트를 설정하여 GitLab 페이지 데몬이 수신해야 하는 명시적 주소를 정의합니다: 

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

간헐적인 502 오류 또는 몇 일 후에 발생하는 오류

systemd 및 tmpfiles.d를 사용하는 시스템에서 Pages를 실행하는 경우, DNS 구성이 손실될 수 있어 systemd가 정기적으로 /tmp/ 디렉토리를 정리할 수 있어 발생하는 간헐적인 502 오류에 마주칠 수 있습니다. 이를 해결하기 위해 다음과 같은 해결 방법이 있습니다:

  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 페이지에 액세스할 수 없는 경우(예: 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 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)"

페이지는 GitLab API의 인스턴스와 통신할 수 없습니다.

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

WARN[0010] 페이지는 GitLab API의 인스턴스와 통신할 수 없습니다. gitlab-secrets.json 파일을 동기화하십시오. 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 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 라이브러리를 사용하여 Go의 crypto/rand를 통해 무작위 문자열을 얻습니다. 이를 위해 호스트 OS에서 getrandom 시스템 호출 또는 /dev/urandom이 사용 가능해야 합니다. 공식으로 지원되는 운영 체제로 업그레이드하는 것이 권장됩니다.

요청된 범위가 잘못되었거나 알 수 없습니다.

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

  1. 왼쪽 사이드바에서 맨 아래에서 관리 영역을 선택합니다.
  2. 응용 프로그램 > GitLab Pages를 선택합니다.
  3. 응용 프로그램을 편집합니다.
  4. 범위에서 api 범위가 선택되었는지 확인합니다.
  5. 변경 내용을 저장하세요.

별도 페이지 서버를 실행하는 경우, 이 설정은 주 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 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와 같아야 합니다.

500 오류 디스크에서 서비스할 수 없음

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 14.0 이상으로 업그레이드한 후 GitLab Pages가 작동하지 않는 경우

GitLab 14.0에서는 수동 개입이 필요할 수 있는 GitLab Pages에 대한 여러 변경 사항이 소개되었습니다.

  1. 먼저 이 마이그레이션 가이드를 따르십시오.
  2. GitLab 14.3 이상으로 업그레이드해 보십시오. 일부 문제가 GitLab 14.1, 14.2 및 14.3에서 수정되었습니다.
  3. 작동하지 않는 경우 GitLab Pages 로그를 확인하고 거기서 오류를 확인한 후 이 페이지에서 해당 오류를 검색하십시오.

경고: GitLab 14.0에서 14.2에서는 일시적으로 레거시 저장소와 구성 메커니즘을 활성화할 수 있습니다.

그렇게 하려면:

  1. 이 마이그레이션 피드백 이슈에서 보이는 문제를 설명합니다.

  2. /etc/gitlab/gitlab.rb 파일을 편집합니다. 

    gitlab_pages['use_legacy_storage'] = true

  3. GitLab 다시 구성.

GitLab Pages 배포 작업이 “인식되지 않는 제공 업체” 오류로 실패하는 경우

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

Pages Deploy Failure

“인식되지 않는 제공 업체” 오류 메시지는 GitLab이 객체 저장소에 연결하기 위해 사용하는 fog 젬에서 올 수 있습니다.

해결 방법:

  1. gitlab_rails['pages_object_store_enabled']가 활성화되어 있지만 버킷 세부 정보가 구성되지 않은 경우 gitlab.rb 파일을 확인하십시오.

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

  2. gitlab.rb 파일에 대한 변경 사항을 저장한 후 GitLab 다시 구성합니다.

404 오류 찾을 수 없는 페이지

GitLab Pages로부터 404 Page Not Found 응답을 받는 경우:

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

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