タイトル: メンテナンス
SEOタイトル: Laravel メンテナンスモード完全ガイド
この本文には実行可能なタグ等が含まれるため、安全のためHTMLソースとして表示しています。本文データは変更していません。
<table border="1" cellpadding="6" cellspacing="0" style="border-collapse:collapse;background:#fffbea;border:1px solid #f4c430;margin:1em 0;width:100%"><tr><td style="background:#f4c430;color:#000;font-weight:bold;padding:8px">この記事の要点</td></tr><tr><td style="padding:10px"><ul><li><strong><code>php artisan down</code></strong> で Laravel をメンテナンスモード化 / <code>up</code> で復帰</li><li><code>--message</code> / <code>--retry</code> / <code>--allow</code> / <code>--secret</code> / <code>--render</code> オプションを使い分け</li><li>実体は <code>storage/framework/down</code> ファイル。これが存在する間は 503 を返す</li><li>カスタム画面は <code>resources/views/errors/503.blade.php</code> を配置</li><li>CI/CD では <code>down</code> → <code>migrate</code> → <code>up</code> をデプロイスクリプトに組込む</li></ul></td></tr></table>
<h2>メンテナンスモードとは</h2>
<p>Laravel のメンテナンスモードは、デプロイ作業や DB マイグレーション中に<strong>ユーザーアクセスを一時遮断</strong>して 503 Service Unavailable を返す機能です。</p>
<h2>基本コマンド</h2>
<pre style="background:#1e293b;color:#e2e8f0;padding:1em;border-radius:6px;overflow-x:auto;line-height:1.5"><code class="language-bash"># メンテナンス開始
php artisan down
# メンテナンス解除
php artisan up
# 状態確認 (Laravel 11+)
php artisan about | grep -i maintenance</code></pre>
<h2>主要オプション</h2>
<table border="1" cellpadding="6" cellspacing="0" style="border-collapse:collapse;width:100%">
<thead><tr style="background:#e3f2fd"><th>オプション</th><th>意味</th><th>例</th></tr></thead>
<tbody>
<tr><td><code>--message="..."</code></td><td>表示メッセージ (デフォルトビュー用)</td><td><code>--message="ただいまメンテナンス中です"</code></td></tr>
<tr><td><code>--retry=N</code></td><td>Retry-After ヘッダ (秒)</td><td><code>--retry=60</code></td></tr>
<tr><td><code>--refresh=N</code></td><td>HTML meta refresh (秒)</td><td><code>--refresh=15</code></td></tr>
<tr><td><code>--allow=IP</code></td><td>許可 IP (複数可)</td><td><code>--allow=192.168.1.1 --allow=10.0.0.0/8</code></td></tr>
<tr><td><code>--secret=TOKEN</code></td><td>バイパストークン (URL パス)</td><td><code>--secret=abc123</code></td></tr>
<tr><td><code>--render="view"</code></td><td>レンダリング済ビューを返す</td><td><code>--render="errors::503"</code></td></tr>
<tr><td><code>--status=N</code></td><td>HTTP ステータスコード</td><td><code>--status=503</code></td></tr>
</tbody>
</table>
<h2>例: フル装備のメンテナンス開始</h2>
<pre style="background:#1e293b;color:#e2e8f0;padding:1em;border-radius:6px;overflow-x:auto;line-height:1.5"><code class="language-bash">php artisan down \
--message="システムメンテナンスのため一時停止しています" \
--retry=300 \
--refresh=60 \
--secret="bypass-token-2024" \
--render="errors::503" \
--status=503</code></pre>
<p>これで:</p>
<ul>
<li>503 ステータスを返す</li>
<li>5 分後にリトライを推奨 (<code>Retry-After: 300</code>)</li>
<li>60 秒ごとに自動リロード</li>
<li><code>https://your-app.com/bypass-token-2024</code> にアクセスすると Cookie が付き<strong>本人だけ閲覧可能</strong>に</li>
<li><code>errors/503.blade.php</code> をレンダリング</li>
</ul>
<h2>secret によるバイパス</h2>
<p>運用者だけがサイトを確認したい場合、<code>--secret</code> が最も便利:</p>
<pre style="background:#1e293b;color:#e2e8f0;padding:1em;border-radius:6px;overflow-x:auto;line-height:1.5"><code class="language-bash">php artisan down --secret="abc123xyz"
# ブラウザで以下にアクセス
# https://example.com/abc123xyz
# → Cookie が発行され、以後メンテ画面をバイパスして本物の画面が見える
# 解除
php artisan up</code></pre>
<h2>カスタム 503 ビュー</h2>
<p><code>resources/views/errors/503.blade.php</code> を配置すれば自動で使われます:</p>
<pre style="background:#1e293b;color:#e2e8f0;padding:1em;border-radius:6px;overflow-x:auto;line-height:1.5"><code class="language-html"><!-- 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></code></pre>
<p><code>--render</code> を使うとメンテナンス時に動的処理を行わずに済みます。</p>
<h2>--render と Pre-rendered の違い</h2>
<p>Laravel 8+ では、メンテナンスモード中に<strong>アプリ全体がブートできない致命的エラー</strong>が起きると、デフォルトビューすら表示できません。これを防ぐため <code>--render</code> はメンテ開始時にビューを<strong>事前レンダリング</strong>し、その HTML を直接返します:</p>
<pre style="background:#1e293b;color:#e2e8f0;padding:1em;border-radius:6px;overflow-x:auto;line-height:1.5"><code class="language-bash"># 推奨: 事前レンダリングして安全に
php artisan down --render="errors::503"</code></pre>
<h2>実体ファイル</h2>
<p>メンテナンスモードの状態は <code>storage/framework/down</code> ファイルで管理されます:</p>
<pre style="background:#1e293b;color:#e2e8f0;padding:1em;border-radius:6px;overflow-x:auto;line-height:1.5"><code class="language-bash"># down 後に確認
cat storage/framework/down
# {"except":[],"redirect":null,"retry":300,"refresh":60,"secret":"abc","status":503,"template":"..."}
# 手動で削除しても up と同じ
rm storage/framework/down</code></pre>
<h2>ゼロダウンタイムデプロイとの組合せ</h2>
<p>本番では <code>down</code> → <code>migrate</code> → <code>up</code> がベーシック:</p>
<pre style="background:#1e293b;color:#e2e8f0;padding:1em;border-radius:6px;overflow-x:auto;line-height:1.5"><code class="language-bash">#!/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</code></pre>
<p>Envoyer / Deployer / Laravel Forge / Vapor などは内部的にこの流れを自動化しています。</p>
<h2>キューワーカーへの影響</h2>
<p>メンテナンス中も <code>queue:work</code> はジョブを処理し続けます。デプロイ時はワーカーも止めるのが安全:</p>
<pre style="background:#1e293b;color:#e2e8f0;padding:1em;border-radius:6px;overflow-x:auto;line-height:1.5"><code class="language-bash"># ワーカーに graceful 停止シグナル
php artisan queue:restart
# Supervisor / systemd 経由なら再起動
sudo systemctl restart laravel-worker</code></pre>
<h2>FAQ</h2>
<p><strong>Q: メンテナンス中に Artisan コマンドは動く？</strong><br />
A: 動きます。<code>storage/framework/down</code> は HTTP リクエストのみ遮断するので、CLI には影響しません。</p>
<p><strong>Q: 特定ルートだけ通したい (Health check 等)</strong><br />
A: Laravel 8+ は <code>app/Http/Middleware/PreventRequestsDuringMaintenance.php</code> の <code>$except</code> に URI を追加。</p>
<p><strong>Q: メンテ中も画像 / CSS は配信したい</strong><br />
A: 静的ファイルは Nginx / Apache が直接配信するので、Laravel を経由しません。デフォルトで配信され続けます。</p>
<p><strong>Q: <code>php artisan up</code> しても 503 のまま</strong><br />
A: OPcache / Nginx の FastCGI キャッシュが原因の可能性。<code>sudo systemctl reload php8.x-fpm</code> + ブラウザ強制リロード。</p>