Pumaが停止しないときは?8.1.1への更新とSolid Queue・クラスタ構成の確認方法

RailsのデプロイでGracefully shutting down workers...から停止が進まない場合、Pumaのバージョンとプラグイン構成を確認してみてください。2026年11月15日16時59分(日本時間)公開のPuma 8.1.1には、クラスタモードで子プロセスの終了待ちが続く不具合の修正が含まれます。Solid QueueのPumaプラグインを標準のforkモードで使う構成が、その具体例です。

Webサーバーが処理を終え、つながったワーカープロセスを順番に終了する概念イラスト
サーバーの正常な停止を表したAI生成の概念イラストです。Pumaの実画面ではありません。

この記事では公式リリース情報と実装をもとに、対象の見分け方、依存関係を絞った更新、停止後の確認を整理します。個別のアプリで動作確認した結果ではありません。

目次

ログだけで決めず、4つの条件を照合する

修正PRによると、この問題はPuma 8.1.0の変更によって表面化しました。Puma自身のワーカーが終了した後、親プロセスがプラグインの子プロセスを待ちます。しかし、その子を止めるafter_stoppedフックは待機が終わるまで実行されず、停止処理が進まなくなります。8.1.1はこの待ち合わせを解消します。

  • 稼働中のPumaが8.1.0か。
  • スレッドだけの構成ではなく、ワーカーをforkするクラスタモードか。
  • 子プロセスを持ち、after_stoppedで止めるプラグインや独自フックがあるか。
  • 問題が出た停止経路はcontrol appへのstop要求か、SIGINTか。

PRではTailwind、Dart Sass、Inertia SSRのプラグインも同じ形式の例として挙げられています。ただし、導入しているだけで原因が確定するわけではありません。処理の長いリクエスト、別の終了フック、サービス管理側のタイムアウトも切り分けます。

RubyとアプリのPumaを確認する

対象アプリのディレクトリで、本番と同じ実行環境を使って確認します。

ruby --version
bundle exec puma --version

8.1.1のgem仕様はRuby 3.0以上を要求します。これはアプリ側のサポート方針や依存要件とは別の最低条件です。また、Pumaのクラスタモードはforkを利用するため、ネイティブWindowsとJRubyでは非対応です。開発用PCの環境だけで判断せず、実際に稼働するOSとRuby実装を確認してください。ワーカー数とWEB_CONCURRENCYの関係はクラスタモードの公式資料で確認できます。

8.1.0から依存関係を絞って更新する

以下は、現在8.1.0を使い、Gemfileの指定が8.1.1を許容しているアプリ向けの例です。

bundle update puma --patch --strict --conservative
bundle exec puma --version

Bundlerの説明では、--patch --strictでパッチ系列を越える更新を制限し、--conservativeで間接依存の変更を抑えます。ただし、Gemfileの完全固定、ほかのgemとの競合、設定済みの公開直後バージョンの待機期間を無視する指定ではありません。更新できない場合は解決結果を読み、全gemの一括更新へ広げる前に原因を確認します。

変更されたGemfile.lockをレビューし、既存のアプリテストを通してから通常の配布手順で反映します。Puma 7や8.0に対するstrictなパッチ更新では8.1へ進みません。別系列からの移行では依存指定の見直しとPuma 8の移行資料の確認が必要です。待受アドレスやフックの互換性も含めて判断してください。

同じ停止経路で確認する

pumactl stopは常に同じ動きをするわけではありません。control URLがあればstop要求を送り、PIDだけの場合はSIGTERMを送ります。今回の停止待ちはcontrol appのstopとSIGINT経路の問題で、直接のSIGTERM経路はこの待ち合わせの影響を受けません。制御CLIの実装でも経路の違いを確認できます。

既存の設定が確認対象のテストサーバーを正しく指している場合、次のように状態確認と停止を行えます。

bundle exec pumactl -F config/puma.rb status
bundle exec pumactl -F config/puma.rb stop

設定パスと実行環境は実際の構成に合わせます。2行目はサーバーを停止するため、検証環境か調整済みのメンテナンス手順で実施してください。コマンドの成功表示は要求の送信確認であり、親プロセスの終了完了とは別です。実際の終了、プラグインの終了処理、子プロセスの残存を確認します。シグナルの公式説明は処理を終えて終了しようとする動作を示しており、更新すれば即座に全処理が消えるという意味ではありません。

サービス管理側とアプリの応答まで確認する

systemd管理なら、既存のデプロイ手順に従います。実際のユニット名がpuma.serviceの場合の例です。

sudo systemctl status puma.service
sudo systemctl restart puma.service
sudo systemctl status puma.service

ユニット名は環境に合わせて変更してください。ソケットアクティベーションを使わない通常の再起動では、新しいPumaが起動する間に待受が閉じます。利用している場合はsocketユニットも確認します。新しいbundleで稼働したことをログで確かめ、ヘルスチェックとキュー処理も確認してください。シェル上のバージョン表示だけでは、古い稼働プロセスの置換は証明できません。

まだ止まらない場合は、バージョン、ワーカー設定、停止経路、該当ログを残して調査します。終了フックのない独自の子プロセスまでPumaが自動で止める修正ではありません。詳細はリリースノートとsystemdの公式運用資料を参照してください。

この記事を書いた人

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows/Office(Teams・Excel)からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

コメント

コメントする

目次