この記事の要点

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=N	Retry-After ヘッダ (秒)	--retry=60
--refresh=N	HTML 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=N	HTTP ステータスコード	--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 を配置すれば自動で使われます:

  
  
  
  


  

    
メンテナンス中です
    
サービス改善のため一時停止しています。

       しばらく経ってから再度お試しください。
    
復旧予定: 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 + ブラウザ強制リロード。