GitLab Pagesの管理のトラブルシューティング

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed

このページでは、GitLab Pagesを管理する際に発生する可能性のあるイシューの一覧を示します。

GitLab Pagesログの確認方法

ページデーモンのログは、次のコマンドを実行することで確認できます:

sudo gitlab-ctl tail gitlab-pages

ログファイルは/var/log/gitlab/gitlab-pages/currentにもあります。

詳細については、ログから相関IDを取得するを参照してください。

GitLab Pagesをデバッグする

次のシーケンスチャートは、GitLab Pagesリクエストがどのように処理されるかを示しています。GitLab Pagesサイトのデプロイ方法と、オブジェクトストレージから静的コンテンツを配信する方法について詳しくは、GitLab Pagesアーキテクチャのドキュメントをご覧ください。

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: GitLab Pages Request Flow
    accDescr: Sequence diagram showing how a user request flows through GitLab Pages components to serve static files.

    actor User
    participant PagesNGINX as Pages NGINX
    participant Pages as GitLab Pages
    participant GitlabNGINX as GitLab NGINX
    participant GitlabAPI as GitLab Rails
    participant ObjectStorage as Object Storage

    User->>PagesNGINX: Request to Pages
    activate PagesNGINX
    PagesNGINX->>Pages: Forwarded to Pages
    activate Pages

    Pages->>GitlabNGINX: Fetch domain info
    activate GitlabNGINX
    GitlabNGINX->>GitlabAPI: Forwarded to GitLab API
    activate GitlabAPI
    GitlabAPI->>GitlabNGINX: 200 OK (domain info)
    deactivate GitlabAPI
    GitlabNGINX->>Pages: 200 OK (domain info)
    deactivate GitlabNGINX

    Note right of Pages: Domain information cached in Pages

    Pages->>ObjectStorage: Fetch static files
    activate ObjectStorage
    ObjectStorage->>Pages: 200 OK (files)
    deactivate ObjectStorage

    Pages->>User: 200 OK (static files served)
    deactivate Pages
    deactivate PagesNGINX

エラーログの特定

前のシーケンスチャートに示されている順序でログを確認する必要があります。ドメインに基づいてフィルタリングすると、関連するログを特定するのにも役立ちます。

ログの追跡を開始するには、以下を実行します:

GitLab Pages NGINXログの場合は、以下を実行します:

# View GitLab Pages NGINX error logs
sudo gitlab-ctl tail nginx/gitlab_pages_error.log

# View GitLab Pages NGINX access logs
sudo gitlab-ctl tail nginx/gitlab_pages_access.log

GitLab Pagesログの場合は、以下を実行します: ログから相関IDを特定することから始めます。
```
sudo gitlab-ctl tail gitlab-pages
```

GitLab NGINXログの場合は、以下を実行します:

# View GitLab NGINX error logs
sudo gitlab-ctl tail nginx/gitlab_error.log

# View GitLab NGINX access logs
sudo gitlab-ctl tail nginx/gitlab_access.log

GitLab Railsログの場合は、以下を実行します: これらのログは、correlation_id GitLab Pagesログで特定に基づいてフィルターできます。
```
sudo gitlab-ctl tail gitlab-rails
```

認証コードフロー

次のシーケンスチャートは、保護されたページサイトにアクセスするための、ユーザー、GitLab Pages、GitLab Rails間のOAuth認証フローを示しています。

詳細については、GitLab OAuth認可コードフローを参照してください。

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
   accTitle: GitLab Pages OAuth Flow
   accDescr: Sequence diagram showing the OAuth authentication flow between User, GitLab Pages, and GitLab Rails for accessing protected pages sites.

   actor User
   participant PagesService as GitLab Pages
   participant GitlabApp as GitLab Rails

   User->>PagesService: GET Request for site
   activate PagesService
   PagesService-->>User: 302 Redirect to project subdomain https://projects.gitlab.io/auth?state=state1
   deactivate PagesService
   Note left of User: Cookie state1

   User->>PagesService: GET https://projects.gitlab.io/auth?state=state1
   activate PagesService
   PagesService-->>User: 302 Redirect to gitlab.com/oauth/authorize?state=state1
   deactivate PagesService

   User->>GitlabApp: GET oauth/authorize?state=state1
   activate GitlabApp
   GitlabApp-->>User: 200 OK (authorization form)
   deactivate GitlabApp

   User->>GitlabApp: POST authorization form
   activate GitlabApp
   GitlabApp-->>User: 302 Redirect to oauth/redirect
   deactivate GitlabApp

   User->>GitlabApp: GET oauth/redirect?state=state1
   activate GitlabApp
   GitlabApp-->>User: 200 OK (with auth code)
   deactivate GitlabApp

   User->>PagesService: GET https://projects.gitlab.io/auth?code=code1&state=state1
   activate PagesService
   PagesService->>GitlabApp: POST oauth/token with code=code1
   activate GitlabApp
   GitlabApp-->>PagesService: 200 OK (access token)
   deactivate GitlabApp
   PagesService-->>User: 302 Redirect to https://[namespace].gitlab.io/auth?code=code2&state=state1
   deactivate PagesService

   User->>PagesService: GET https://[namespace].gitlab.io/auth?code=code2&state=state1
   activate PagesService
   PagesService-->>User: 302 Redirect to site
   deactivate PagesService

   User->>PagesService: GET Request for site
   activate PagesService
   PagesService-->>User: 200 OK (site content)
   deactivate PagesService

エラー: `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)プロトコルスキームを設定していないことを意味します。解決策:

/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>" # optional, gitlab_pages['gitlab_server'] is used as default

GitLabを再設定します:
```
sudo gitlab-ctl reconfigure
```

サーバーがIPv6経由でリッスンしない場合にGitLab Pagesプロキシへの接続時に発生する502エラー

サーバーがIPv6経由でリッスンしない場合でも、NGINXがデフォルトでIPv6を使用してGitLab Pagesサービスに接続する場合があります。これが発生しているかどうかは、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と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のようなファイルを含めます。ただし、systemdは/tmp/ディレクトリを定期的にクリーンするため、DNS設定が失われる可能性があります。

systemdがページ関連のコンテンツをクリーンしないようにするには:

tmpfiles.dに、ページの/tmpディレクトリを削除しないように指示します:
```
echo 'x /tmp/gitlab-pages-*' >> /etc/tmpfiles.d/gitlab-pages-jail.conf
```
GitLab Pagesを再起動します:
```
sudo gitlab-ctl restart gitlab-pages
```

GitLab Pagesにアクセスできません

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"

次の内容を/etc/gitlab/gitlab.rbに追加します:

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

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を別のサーバーで実行している場合は、/etc/gitlab/gitlab-secrets.jsonファイルをGitLab server（GitLabサーバー）からPages server（ページサーバー）にコピーする必要があります。

その他の理由としては、ファイアウォール設定や閉じられたポートなど、GitLab server（GitLabサーバー）とPages server（ページサーバー）間のネットワーク接続のイシューが考えられます。たとえば、接続タイムアウトが発生した場合:

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エラー応答が表示されることがあります。また、ページログに次の警告が表示されることがあります:

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保持が有効になっているネットワークロードバランサーを使用し、リクエストがソースサーバーにループバックされる場合、接続タイムアウトが発生します。これは、コア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エラー

この問題は、オペレーティングシステムが古くなっていることが原因である可能性が最も高いです。ページデーモンはsecurecookieライブラリを使用して、Goのcrypto/rand経由でランダムな文字列を取得します。これには、ホストOSでgetrandomシステム呼び出しまたは/dev/urandomが利用可能である必要があります。公式にサポートされているオペレーティングシステムにアップグレードすることをお勧めします。

リクエストされたスコープが無効、不正な形式、または不明です

この問題は、GitLab Pages OAuthアプリケーションの権限に起因します。解決策:

左側のサイドバーの下部で、管理者を選択します。
アプリケーション > GitLab Pagesを選択します。
アプリケーションを編集します。
スコープで、apiスコープが選択されていることを確認します。
変更を保存します。

別のページサーバーを実行している場合、この設定はメインのGitLabサーバーで構成する必要があります。

ワイルドカードDNSエントリを設定できない場合の回避策

ワイルドカードDNSの前提条件を満たせない場合でも、制限された方法でGitLab Pagesを使用できます:

Pagesで使用する必要があるすべてのプロジェクトを、たとえばpagesのように、単一のグループネームスペースに移動します。
*.-ワイルドカードなしでDNSエントリを構成します(例: pages.example.io)。
pages_external_url http://example.io/ファイルをgitlab.rbで構成します。グループネームスペースはGitLabによって自動的に先頭に追加されるため、ここでは省略します。

パーミッションが拒否されたエラーでページデーモンが失敗する

/tmpがnoexecでマウントされている場合、ページデーモンは次のようなエラーで起動に失敗します:

{"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を再起動します。

ページアクセス制御の使用時に`The redirect URI included is not valid.`

pages_external_urlが途中で更新された場合、このエラーが表示されることがあります。以下を確認します:

システムOAuthアプリケーションを確認します:
1. 左側のサイドバーの下部で、管理者を選択します。
2. アプリケーション、新しいアプリケーションを追加の順に選択します。
3. Callback URL/Redirect URI（コールバックURL/リダイレクトURI）が、pages_external_urlを使用するように構成されているプロトコル(HTTPまたはHTTPS)を使用していることを確認します。
Redirect URIのドメインおよびパスコンポーネントが有効です。それらはprojects.<pages_external_url>/authのように見えるはずです。

500エラー`cannot serve from disk`

ページから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がディスクアクセスを無効にするように構成されていることを意味します。

ディスクアクセスを有効にするには:

/etc/gitlab/gitlab.rbでGitLab Pagesのディスクアクセスを有効にします:
```
gitlab_pages['enable_disk'] = true
```
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共有ディレクトリを同じパスにマウントすることもできます。

エラー`is not a recognized provider`でGitLab Pagesデプロイジョブが失敗する

ページジョブは成功したが、デプロイジョブがエラー"認識されたプロバイダーではありません"を出す場合:

エラーメッセージis not a recognized providerは、GitLabがオブジェクトストレージのクラウドプロバイダーに接続するために使用するfog gemから発生している可能性があります。

それを修正するには、次の手順に従ってください:

gitlab.rbファイルを確認してください。gitlab_rails['pages_object_store_enabled']が有効になっているが、バケットの詳細が構成されていない場合は、次のいずれかを行います:
- S3互換接続設定ガイドに従って、Pagesデプロイのオブジェクトストレージを構成します。
- その行をコメントアウトして、デプロイをローカルに保存します。
gitlab.rbファイルに加えた変更を保存し、GitLabを再構成します。

404エラー`The page you're looking for could not be found`

GitLab Pagesから404 Page Not Found応答を受け取った場合:

.gitlab-ci.ymlにジョブpages:が含まれているか確認してください。
現在のプロジェクトのパイプラインをチェックして、ジョブpages:deployが実行されていることを確認します。

pages:deployジョブがないと、GitLab Pagesサイトへの更新は公開されません。

namespace_in_pathが有効になっている別のページサーバーを使用している場合は、UIに誤ったURLが表示される場合の404エラーを参照してください。

404エラー: ページのUIに誤ったURLが表示される場合、ページが見つかりません

別のGitLab Pagesサーバーでnamespace_in_pathを構成して有効にした場合、404 Page not foundエラーが発生する可能性があります。

このエラーは、GitLab PagesサーバーまたはメインGitLabサーバーでnamespace_in_path設定が誤って構成されているか、見つからない場合に発生します。

グローバル設定 namespace_in_pathは、GitLab PagesサイトのURL構造を決定します。GitLabサーバーとGitLab Pagesサーバーの両方で、この設定に同じ値を使用する必要があります。

このエラーを解決するには:

/etc/gitlab/gitlab.rbファイルを開きます:
1. GitLabサーバーの設定が以下であることを確認します:
```
gitlab_pages['namespace_in_path'] = true
```
2. GitLab Pagesサーバーの設定が同じであることを確認します:
```
   gitlab_pages['namespace_in_path'] = true
```
ファイルを保存します。
変更を有効にするには、両方のサーバーでGitLabを再構成します。

503エラー`Client authentication failed due to unknown client`

ページが登録済みのOAuthアプリケーションであり、アクセス制御が有効になっている場合、このエラーは、/etc/gitlab/gitlab-secrets.jsonに格納されている認証トークンが無効になったことを示します:

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

解決するには、次のようにします:

シークレットファイルをバックアップします:

sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.$(date +\%Y\%m\%d)

/etc/gitlab/gitlab-secrets.jsonを編集し、gitlab_pagesセクションを削除します。
GitLabを再構成し、OAuthトークンを再生成します:
```
sudo gitlab-ctl reconfigure
```