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 페이지 서비스에 연결하기 위해 기본적으로 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 페이지 데몬이 수신할 명시적 주소를 정의하기 위해 GitLab 페이지 listen_proxy 설정에 명시적 IP 및 포트를 설정하십시오: 

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

가끔 502 오류 또는 수 일 후에

systemd 및 tmpfiles.d를 사용하는 시스템에서 페이지를 실행하는 경우, DNS 구성이 손실될 수 있어 페이지를 제공하는 동안 가끔 502 오류가 발생할 수 있습니다. 다음과 유사한 오류로 인한 페이지의 서비스가 중단될 수 있습니다: 

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

GitLab 페이지는 /etc/hosts와 같이 /tmp/gitlab-pages-* 내의 파일을 포함하는 bind mount를 생성합니다. 그러나 systemd는 정기적으로 /tmp/ 디렉토리를 청소할 수 있으므로 DNS 구성이 손실될 수 있습니다.

systemd가 페이지와 관련된 내용을 청소하지 않도록 하려면:

  1. tmpfiles.d에 Pages /tmp 디렉토리를 제거하지 말도록하도록 지시하세요: 

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

  2. GitLab 페이지를 다시 시작하세요: 

    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 페이지를 다시 시작하세요: 

    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 서버에서 페이지 서버로 /etc/gitlab/gitlab-secrets.json 파일을 복사해야 합니다.

네트워크 연결 문제와 같은 GitLab 서버와 페이지 서버 간의 방화벽 구성 또는 닫힌 포트와 같은 다른 이유일 수도 있습니다. 예를 들어, 연결 시간 초과가 있는 경우: 

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 Rails와 GitLab Pages 간의 gitlab-secrets.json 파일이 오래되었을 때 발생할 수 있습니다. 모든 GitLab Pages 인스턴스에서 독립 서버에서 GitLab Pages 실행의 단계 8-10을 따르세요.

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

클라이언트 IP 보존이 활성화된 Network Load Balancer를 사용할 때 요청이 소스 서버로 다시 루프될 때 연결이 타임아웃될 수 있습니다. 이 문제는 여러 서버에서 GitLab 인스턴스를 실행하거나, 핵심 GitLab 애플리케이션과 GitLab Pages를 모두 실행하는 경우 발생할 수 있습니다. 또한, 핵심 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를 통해 무작위 문자열을 가져옵니다. 이를 위해서는 호스트 운영 체제에 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에서 자동으로 앞에 추가됩니다.

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

/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 액세스 제어를 사용할 때 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와 같이 보여야 합니다.

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가 디스크 액세스를 비활성화하도록 구성되어 있는 것을 의미합니다.

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

  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 서버와 GitLab Pages 서버에서 서로 같은 경로에 GitLab Pages 공유 디렉토리를 마운트할 수 있습니다.

GitLab Pages 배포 작업이 “인식되지 않는 공급업체” 오류로 실패함

만약 pages 작업이 성공했지만 deploy 작업이 “인식되지 않는 공급업체” 오류를 반환한다면:

GitLab Pages 파이프라인에서 pages 작업은 성공이지만 deploy 작업에서 오류가 발생했습니다.

인식되지 않는 공급업체라는 오류 메시지는 fog 젬에서 올 수 있는데, GitLab은 객체 저장을 위해 클라우드 공급업체에 연결하는 데 사용합니다.

이를 해결하기 위해:

  1. gitlab.rb 파일을 확인하세요. gitlab_rails['pages_object_store_enabled']가 활성화되어 있지만 버킷 세부 정보가 구성되어 있지 않다면 다음과 같이 하세요:

    • Pages 배포를 위해 객체 저장을 구성하려면 S3 호환 연결 설정 가이드를 따르세요.
    • 그 줄을 주석 처리하여 배포를 로컬에 저장하세요.

  2. gitlab.rb 파일에 한하여 수행한 변경 사항을 저장하고, GitLab을 다시 구성하세요.

404 오류 해당 페이지를 찾을 수 없음

GitLab Pages에서 404 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