EC-CUBE 4.2 / 4.3 対応 公式マニュアル

メンテナンス管理プラグイン

EC-CUBEの計画メンテナンス・緊急メンテナンスを柔軟に管理。自動スケジュール制御、事前予告バナー、リアルタイムカウントダウンタイマー、IPホワイトリスト（Cloudflare対応）、URLバイパストークン、操作履歴ログまでを網羅したプロ仕様のメンテナンス拡張プラグインです。

1. プラグイン概要と主な機能

『メンテナンス管理プラグイン (MaintenanceManagement)』は、EC-CUBE標準のメンテナンス機能を大幅に強化し、定期デプロイや商品データ一括更新、深夜帯の計画メンテナンスをスマートに運用するための拡張機能を提供します。

手動切替 & スケジュール自動制御

ワンクリック即時メンテナンス稼働と、開始〜終了日時を指定したCron不要の自動スケジュールに対応。

事前予告バナー (Live Preview)

メンテナンス開始の指定時間前（例: 30分前）から、ショップ最上部に固定告知バナーを自動表示。

リアルタイム カウントダウン

メンテナンス画面にサービス再開予定までの残り時間（日・時・分・秒）を自動カウントダウン表示。

IPホワイトリスト & Cloudflare対応

指定IPやCIDRからのアクセスを許可。CF-Connecting-IPやX-Forwarded-Forの実IP判定に対応。

バイパストークン (Cookie保持)

専用パラメータ付きURLからアクセスすることで、動的IP環境や外部検証者でもメンテナンスを安全に回避。

特定URL除外 & 操作履歴ログ

問い合わせ（/contact）等の除外パス指定や、管理者ごとの操作ログ（直近20件）を常時記録。

2. インストール・有効化

EC-CUBE管理画面の「オーナーズストア」経由、またはCLIコマンドから簡単に導入できます。

1
オーナーズストアからインストール

管理画面 → オーナーズストア → プラグイン一覧 より「MaintenanceManagement」をインストールし、有効化を完了してください。

2
（開発者向け）CLIコマンドでのインストール
# プラグインのインストール
bin/console eccube:plugin:install --code=MaintenanceManagement

# プラグインの有効化（設定・ログ用テーブル自動作成）
bin/console eccube:plugin:enable --code=MaintenanceManagement

# キャッシュクリア
bin/console cache:clear --no-warmup

3. 基本設定とスケジュール自動制御

管理画面 → 設定 → システム設定 → メンテナンス管理 を開き、メンテナンスの実行モードやメッセージを設定します。

1. メンテナンスモードの実行制御

設定項目動作と特徴
今すぐメンテナンスモードを有効にするチェックを入れて保存すると、開始・終了日時の設定に関わらず即座にメンテナンスモードが最優先で稼働します。
スケジュールで自動制御するチェックを入れると、指定した「開始日時」から「終了日時」の間だけ自動的にメンテナンス画面を表示します（Cron等のサーバー設定は不要です）。

2. メッセージのリッチテキスト編集 (Summernote)

「メッセージ」欄にはリッチテキストエディタ（Summernote）を搭載しています。文字の太字・色付け、リンク（<a>）、画像（<img>）、テーブルなどを視覚的に編集し、分かりやすいメンテナンス案内を作成できます。

4. 事前予告バナー設定 (Live Preview)

計画メンテナンスの開始直前、お買い物中のお客様が突然のサービス停止に驚かないよう、サイト最上部に固定の事前告知バナーを自動表示できます。

1
予告バナーを有効化＆表示開始タイミングの設定

「予告バナーを表示する」にチェックを入れ、「予告表示開始タイマー」に開始日時の何分前から表示するか（例: 30 分前、60 分前）を入力します。

2
カラーテーマ選択とリアルタイムプレビュー

プリセット（警告イエロー / 注意レッド / 案内ブルー / ダーク）から選ぶか、カスタムカラーで背景色と文字色を自由調整可能。管理画面上のLive Previewバーで実際の見た目を確認しながら設定できます。

5. ホワイトリストIP・バイパス・除外パス

メンテナンス稼働中であっても、管理者や開発会社、特定ページへのアクセスを安全に許可するための3重の回避仕組みを備えています。

1. 許可するIPアドレス (CIDR & Cloudflare対応)

1行に1つずつ許可したいIPアドレス（例: 203.0.113.10）またはサブネットマスク（例: 198.51.100.0/24）を入力します。
Cloudflare や AWS CloudFront 等のCDN・ロードバランサー配下環境でも、CF-Connecting-IP や X-Forwarded-For ヘッダーを自動解析して正確なクライアントIP判定を行います。

2. バイパストークン（URLアクセストークン）

テレワーク等でIPアドレスが変動する場合でも、設定した秘密トークン付きURLから一度アクセスするだけで、Cookieにトークンが保存され通常通りサイトを閲覧・検証できます。

# バイパス用URLの例
https://your-shop-domain.com/?maintenance_bypass=your_secret_token_123

3. メンテナンス除外URLパス

お問い合わせページ（/contact）やプライバシーポリシー（/help/privacy）など、メンテナンス中も一般公開しておきたいURLパスを1行に1つずつ指定できます。

7. 操作履歴（監査ログ）

プラグイン設定画面の下部には、直近20件の操作ログが自動記録されます。

操作種別記録内容と用途
手動ON / 手動OFF誰がいつメンテナンスモードを手動で切り替えたかを記録。
スケジュール更新自動制御の開始・終了日時の変更内容を記録。
設定更新メッセージやIP制限、バナー設定などの変更履歴と操作元IP・管理者アカウント名を記録。

8. よくある質問・トラブルシューティング

Q. 管理画面（/admin）までメンテナンス画面になってアクセスできなくなることはありますか？
いいえ、管理画面（/%eccube_admin_route%/）は自動的にメンテナンス対象から除外されるため、いつでも管理画面にログインしてメンテナンス解除や設定変更を行えます。
Q. EC-CUBE標準の `.maintenance` ファイルとの違いは何ですか？
標準の .maintenance ファイルはDB接続すら行わない緊急復旧用の仕組みです。本プラグインはデータベースや管理画面が稼働している通常運用時（バージョンアップ作業、商品データ更新、定期メンテナンス等）に、スケジュールやIP制限をかけて安全に作業を行うための機能です。
Q. APIや非同期通信（AJAX）はどう処理されますか？
Accept: application/json リクエストやAJAX通信に対しては、HTMLではなく HTTP 503 Service Unavailable の JSON レスポンスが自動返却されます。

9. サポート・ライセンス

本プラグインに関するご質問、カスタマイズのご要望、不具合のご報告がございましたら、EC-CUBEオーナーズストアのお問い合わせ窓口または開発元（CubeLab）までお気軽にお問い合わせください。

※ EC-CUBE本体のバージョンアップやSymfonyフレームワークの仕様変更に伴う機能改善については、随時アップデートにて対応を予定しております。