タイトル: メンテナンス
SEOタイトル: Laravel メンテナンスモード完全ガイド
| この記事の要点 |
|
メンテナンスモードとは
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 を配置すれば自動で使われます:
<!-- resources/views/errors/503.blade.php -->
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="60">
<title>メンテナンス中 | MyApp</title>
<style>
body { font-family: sans-serif; text-align: center; padding: 4em; background: #f8fafc; }
h1 { color: #334155; }
.card { max-width: 480px; margin: auto; background: white; padding: 2em; border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.08); }
</style>
</head>
<body>
<div class="card">
<h1>メンテナンス中です</h1>
<p>サービス改善のため一時停止しています。<br>
しばらく経ってから再度お試しください。</p>
<p>復旧予定: 2024年4月1日 12:00 (JST)</p>
</div>
</body>
</html>--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 upEnvoyer / Deployer / Laravel Forge / Vapor などは内部的にこの流れを自動化しています。
キューワーカーへの影響
メンテナンス中も queue:work はジョブを処理し続けます。デプロイ時はワーカーも止めるのが安全:
# ワーカーに graceful 停止シグナル
php artisan queue:restart
# Supervisor / systemd 経由なら再起動
sudo systemctl restart laravel-workerFAQ
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 + ブラウザ強制リロード。