GitLab システム管理 - ハンズオンラボ: GitLab のトラブルシューティング

このハンズオンガイドでは、GitLab サービス NGINX、Puma、Gitaly のトラブルシューティング手順を説明します。

完了までの目安時間: 30 分

目的

このラボの目的は、gitlab-ctl コマンドを使って GitLab サーバーをトラブルシューティングする方法を示すことです。このラボ演習では、GitLab の主要なサービスとそれらの相互作用を確認するために、GitLab のアプリケーションアーキテクチャを参照してください。

タスク A. NGINX のトラブルシューティング

GitLab インスタンスのシェルセッションから、NGINX のアクティブなログの 1 つを表示します。
```
sudo gitlab-ctl tail nginx/gitlab_access.log
```
ログには数秒ごとに新しいエントリーが追加されることに注目してください。これらのエントリーのほとんどは、gitlab-runner が HTTP 経由で GitLab インスタンスにチェックインしているものです。
NGINX サービスを停止します。
```
sudo gitlab-ctl stop nginx
```
Web ブラウザーで http://<your_gitlab_instance> に移動してみてください。Web ブラウザーには「This site can’t be reached」または同様のメッセージが表示されるはずです。

nginx/access_log を再度確認します。

sudo gitlab-ctl tail nginx/gitlab_access.log

NGINX を停止した後、クライアントが GitLab に HTTP/HTTPS リクエストを送信できないため、ログは更新されないはずです。

Web サービスがどこでも実行されておらず、リッスンしていないことを確認します。
```
curl -i http://localhost/nginx_status
curl -i http://localhost:80
```
NGINX サービスを再起動します。
```
sudo gitlab-ctl restart nginx
```
クライアント（GitLab Runner など）が再び GitLab と通信できることを確認します。
```
sudo gitlab-ctl tail nginx/gitlab_access.log
```
Web サーバーが稼働してポート 80 でリッスンしていることを確認します。
```
curl -i http://localhost/nginx_status
```

タスク B. Puma のトラブルシューティング

Web ブラウザーで GitLab インスタンスに接続します。プロジェクトや管理者エリアなどをクリックして移動できることを確認します。
GitLab インスタンスのシェルセッションから、Puma を停止します。
```
sudo gitlab-ctl stop puma
```
Web ブラウザーで GitLab を更新します。「502: GitLab is taking too much time to respond」というエラーがすぐに表示されるはずです。NGINX は稼働しているので HTTP リクエストを受け付けられます。しかし、workhorse が Rails アプリケーションに HTTP リクエストを渡そうとしても、それを受け付ける稼働中のサービスがありません。
GitLab Workhorse のログを表示します。
```
sudo gitlab-ctl tail gitlab-workhorse/current
```
出力にはさまざまな 502 および badgateway エラーが表示されます。
Puma のログを表示します。
```
sudo gitlab-ctl tail puma
```
puma/puma_stdout.log に Puma サービスのシャットダウンに関するメッセージが表示されているはずです。puma/puma_stderr.log にエラーが表示されることもあります。
Puma を再起動します。
```
sudo gitlab-ctl restart puma
```
Puma の runit ログを表示します。
```
sudo gitlab-ctl tail puma/current
```
Puma が再起動したことを示す出力が見られるはずです。
puma/puma_stdout.log を表示します。
```
sudo gitlab-ctl tail puma/puma_stdout.log
```
Puma が再び稼働してリソースを消費していることが確認できるはずです。
約 2 分待ってから、Web ブラウザーで GitLab を更新します。アプリケーションが再びアクセス可能になっているはずです。
GitLab Workhorse のログを表示します。
```
sudo gitlab-ctl tail gitlab-workhorse/current
```
最近のエントリーには、Puma へのリクエストが成功していること（つまり Web ブラウザーで GitLab を再読み込みしたとき）が示されているはずです。

タスク C. Gitaly のトラブルシューティング

Web ブラウザーで GitLab インスタンスに接続します。
Menu > Projects > Your Projects に移動します。
New Project を選択します。
Create blank project を選択します。
プロジェクトに Test project という名前を付けます。プロジェクトの公開範囲を Public に設定し、Initialize repository with a README が選択されていることを確認します。その他の設定はそのままにします。
Create project を選択します。プロジェクトのランディングページにリダイレクトされます。
GitLab Runner サーバーに SSH 接続します。
```
ssh -i <SSH_HOST_KEY> root@<GITLAB_runner_host>
```
Git がまだインストールされていない場合は、ダウンロードします。
```
sudo apt-get install -y git
```
GitLab の Test project に戻り、ページの右側にある Clone を選択します。
Clone with HTTP の隣にある Copy URL を選択します。
GitLab Runner サーバーで、リポジトリをクローンします。
```
git clone <URL_copied_from_previous_step>
```
プロジェクトが正しくクローンされたことを確認します。
```
cd ~/test-project
ls -a
git status
```
exit を入力して、GitLab Runner サーバーの SSH セッションを終了します。
GitLab Omnibus インスタンスで SSH セッションを開きます。
```
ssh -i <SSH_HOST_KEY> root@<GITLAB_OMNIBUS_HOST>
```
Gitaly が稼働していることを確認します。
```
sudo gitlab-ctl status gitaly
```
Gitaly のログを表示します。
```
sudo gitlab-ctl tail gitaly
```
Test Project に関連する最近の gRPC リクエストが多数表示されるはずです（出力を grep するとリファレンスがより明確に見えます。例: sudo gitlab-ctl tail gitaly | grep test-project）。
Gitaly サービスを停止します。
```
sudo gitlab-ctl stop gitaly
```
Gitaly（および Gitaly のみ）が停止していることを確認します。
```
sudo gitlab-ctl status
```
Web ブラウザーで Test Project に戻ります。プロジェクトページで、プロジェクトタイトルの下にある main と表示されているドロップダウンを選択します。通常であれば、切り替える Git ブランチを選択できます。今はエラーが表示され、ブランチリストが読み込まれません。
左サイドバーで Repository > Files を選択します。GitLab がリポジトリファイルを取得できないため、404 エラーが表示されることに注目してください。
戻るボタンを選択して、プロジェクトのランディングページに戻ります。その後ページを更新します。
追加のエラーに注目してください。エラーの 1 つは「An error occurred while fetching folder content」と表示されている場合があります。Gitaly が稼働してリクエストを処理していないため、GitLab はデフォルトブランチの HEAD をチェックアウトできません。
GitLab インスタンスの SSH セッションに戻ります。Gitaly の最近のログエントリーを確認します。
```
sudo gitlab-ctl tail gitaly/current
```
ログ出力に多数のエラーがあることに注目してください。
exit を入力して、GitLab インスタンスサーバーの SSH セッションを終了します。
GitLab Runner サーバーに再度 SSH 接続します。
```
ssh -i <SSH_HOST_KEY> root@<GITLAB_RUNNER_HOST>
```
クローンした Test Project に移動します。
```
cd ~/test-project
```
GitLab インスタンス上のリモートリポジトリから新しい変更を取得しようとします。
```
git fetch
```
出力にエラー 503 が表示されることがあり、これは Gitaly に到達できず、リクエストを処理できないことを示しています。
exit を入力して、GitLab Runner サーバーの SSH セッションを終了します。
GitLab Omnibus インスタンスで SSH セッションを再開します。
```
ssh -i <SSH_HOST_KEY> root@<GITLAB_OMNIBUS_HOST>
```
Gitaly サービスを再起動します。
```
sudo gitlab-ctl start gitaly
```
Gitaly のログを確認します。
```
sudo gitlab-ctl tail gitaly/current
```
出力には gRPC リクエストの成功が表示されるはずです。
Web ブラウザーで Test Project に戻ります。ページを更新します。リポジトリ内を移動したり、ファイルを表示したり、ブランチをチェックアウトしたりできるようになっているはずです。
ランナーサーバーに再度 SSH 接続して、git fetch をテストします。コマンドはエラーなしで実行されるはずです（GitLab 内のファイルが変更されていないため、出力はおそらく何もありません）。

タスク D. gitlabsos ユーティリティを実行する

gitlabsos プロジェクトページに移動します。プロジェクトの概要と README に目を通し、ユーティリティの目的と使い方を学びます。
SSH 経由で GitLab Omnibus インスタンスに接続します。

gitlabsos ユーティリティをクローンします。

/opt/gitlab/embedded/bin/git clone --recursive https://gitlab.com/gitlab-com/support/toolbox/gitlabsos.git

gitlabsos を実行します。
```
cd gitlabsos
sudo ./gitlabsos.rb
```
スクリプトの実行には数分かかる場合があります。
スクリプトが完了したら、生成されたレポートファイルとその内容を確認します。
```
ls
tar -tvf gitlabsos.<GITLAB_FQDN>.<timestamp>.tar.gz
```
GitLab Support がトラブルシューティングを支援するためにこのレポートを求めることがあります。

ラボガイド完了

このラボ演習は完了しました。本コースのその他のラボガイドを確認できます。

ご提案はありますか？

GitLab システム管理ハンズオンガイドへの変更を提案したい場合は、マージリクエストでお寄せください。

最終更新 May 6, 2026: Merge pull request #100 from kyama0/fix/upload-images-tolerate-upstream-missing (70970e1a)

ページのソースコードを見る - ページの編集 - please contribute.