◀ 18.

Laravel メンテナンスモード完全ガイド

▶
編集
この記事の要点
  • php artisan down で Laravel をメンテナンスモード化 / up で復帰
  • --message / --retry / --allow / --secret / --render オプションを使い分け
  • 実体は storage/framework/down ファイル。これが存在する間は 503 を返す
  • カスタム画面は resources/views/errors/503.blade.php を配置
  • CI/CD では down → migrate → up をデプロイスクリプトに組込む

メンテナンスモードとは

Laravel のメンテナンスモードは、デプロイ作業や DB マイグレーション中にユーザーアクセスを一時遮断して 503 Service Unavailable を返す機能です。

基本コマンド

# メンテナンス開始
php artisan down

# メンテナンス解除
php artisan up

# 状態確認 (Laravel 11+)
php artisan about | grep -i maintenance

主要オプション

オプション意味例
--message="..."表示メッセージ (デフォルトビュー用)--message="ただいまメンテナンス中です"
--retry=NRetry-After ヘッダ (秒)--retry=60
--refresh=NHTML meta refresh (秒)--refresh=15
--allow=IP許可 IP (複数可)--allow=192.168.1.1 --allow=10.0.0.0/8
--secret=TOKENバイパストークン (URL パス)--secret=abc123
--render="view"レンダリング済ビューを返す--render="errors::503"
--status=NHTTP ステータスコード--status=503

例: フル装備のメンテナンス開始

php artisan down \
  --message="システムメンテナンスのため一時停止しています" \
  --retry=300 \
  --refresh=60 \
  --secret="bypass-token-2024" \
  --render="errors::503" \
  --status=503

これで:

  • 503 ステータスを返す
  • 5 分後にリトライを推奨 (Retry-After: 300)
  • 60 秒ごとに自動リロード
  • https://your-app.com/bypass-token-2024 にアクセスすると Cookie が付き本人だけ閲覧可能に
  • errors/503.blade.php をレンダリング

secret によるバイパス

運用者だけがサイトを確認したい場合、--secret が最も便利:

php artisan down --secret="abc123xyz"

# ブラウザで以下にアクセス
# https://example.com/abc123xyz
# → Cookie が発行され、以後メンテ画面をバイパスして本物の画面が見える

# 解除
php artisan up

カスタム 503 ビュー

resources/views/errors/503.blade.php を配置すれば自動で使われます:





  
  
  メンテナンス中 | MyApp
  


  

    
メンテナンス中です

    
サービス改善のため一時停止しています。

       しばらく経ってから再度お試しください。

    
復旧予定: 2024年4月1日 12:00 (JST)

--render を使うとメンテナンス時に動的処理を行わずに済みます。

--render と Pre-rendered の違い

Laravel 8+ では、メンテナンスモード中にアプリ全体がブートできない致命的エラーが起きると、デフォルトビューすら表示できません。これを防ぐため --render はメンテ開始時にビューを事前レンダリングし、その HTML を直接返します:

# 推奨: 事前レンダリングして安全に
php artisan down --render="errors::503"

実体ファイル

メンテナンスモードの状態は storage/framework/down ファイルで管理されます:

# down 後に確認
cat storage/framework/down
# {"except":[],"redirect":null,"retry":300,"refresh":60,"secret":"abc","status":503,"template":"..."}

# 手動で削除しても up と同じ
rm storage/framework/down

ゼロダウンタイムデプロイとの組合せ

本番では down → migrate → up がベーシック:

#!/bin/bash
set -e

cd /var/www/myapp

# メンテナンス開始 (運用者は IP でバイパス)
php artisan down --secret="deploy-2024" --retry=60

# コード更新
git pull origin main
composer install --no-dev --optimize-autoloader
npm ci && npm run build

# キャッシュクリア&構築
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

# メンテナンス解除
php artisan up

Envoyer / Deployer / Laravel Forge / Vapor などは内部的にこの流れを自動化しています。

キューワーカーへの影響

メンテナンス中も queue:work はジョブを処理し続けます。デプロイ時はワーカーも止めるのが安全:

# ワーカーに graceful 停止シグナル
php artisan queue:restart

# Supervisor / systemd 経由なら再起動
sudo systemctl restart laravel-worker

FAQ

Q: メンテナンス中に Artisan コマンドは動く？
A: 動きます。storage/framework/down は HTTP リクエストのみ遮断するので、CLI には影響しません。

Q: 特定ルートだけ通したい (Health check 等)
A: Laravel 8+ は app/Http/Middleware/PreventRequestsDuringMaintenance.php の $except に URI を追加。

Q: メンテ中も画像 / CSS は配信したい
A: 静的ファイルは Nginx / Apache が直接配信するので、Laravel を経由しません。デフォルトで配信され続けます。

Q: php artisan up しても 503 のまま
A: OPcache / Nginx の FastCGI キャッシュが原因の可能性。sudo systemctl reload php8.x-fpm + ブラウザ強制リロード。

編集
Post Share
子ページ

子ページはありません

同階層のページ
  1. インストールと設定
  2. クイックスタート & チュートリアル(初心者向け)
  3. クイックスタート & チュートリアル(中級者向け)
  4. ルーティング
  5. Bladeテンプレート(ビュー/レイアウト)
  6. コントローラー
  7. マイグレーションとテーブル定義
  8. データベースの設定
  9. Eloquentモデル (ORM)
  10. SQLとクエリビルダー
  11. バリデーション
  12. .envファイルの設定値へのアクセス
  13. 動作環境による分岐処理
  14. configフォルダ配下の設定値へのアクセス
  15. assetヘルパーを利用したpublicフォルダへのアクセス
  16. storageフォルダへのアクセス
  17. アプリケーション名の変更
  18. メンテナンス
  19. ログイン画面(認証システム)の作成
  20. ログインの必須化
  21. ログインユーザー情報の取得
  22. ルートの認証化
  23. 本番サーバーへのデプロイ方法
  24. 多言語化
  25. csrf_field
  26. ファイルのダウンロード
  27. CSVのアップロードおよび読み込み(maatwebsite/excel)
  28. ページタイトルの設定
  29. コマンド一覧
  30. エラー一覧
  31. SQLの実行ログ出力方法
  32. キャッシュのクリア
  33. Selectの結果の最初もしくは最後に任意の値を追加する方法
  34. ajaxでPOST通信する際の注意点
  35. ソーシャルログインの実装
  36. セッション情報の確認
  37. ログイン、ユーザー登録、パスワードリセット後のリダイレクト先の変更方法
  38. redirectやreturn viewにメッセージを付与する方法
  39. クッキー(cookie)の設定と取得
  40. クラスの再読み込み
  41. csrfの有効時間を変更する方法
  42. ViewComposerを用いてviewに共通の値を付与する方法
  43. View::shareを用いて共通の値を各ビューに渡す方法
  44. ミドルウェアを用いた処理の共通化
  45. Middleware内でAuth::check()などを使用する方法
  46. Controller以外でリダイレクトする方法
  47. セッションの値の取得/保存/更新/削除
  48. $requestの値を変更する方法
  49. 常時SSL化
  50. ページング(ページネーション)をする方法
  51. vue.jsとの連携
  52. Vue.jsと連携するSPA実行環境構築
  53. .envの値をvue.jsで参照する方法
  54. vue.jsを本番環境にリリースする方法
  55. could not find driver（Windows, MySQL編）
2026-05-18 01:50:54 atom 429

人気ページ

最近更新/作成されたページ