❓ 管理者のよくある質問 (FAQ) およびトラブルシューティング

本ドキュメントは、ブログのインストール、デプロイ、および運営段階で発生する可能性のある主なトラブルシューティング解決策と、安全な最新バージョンへのアップグレードガイドを提供します。

---

🗄️ Q1. 最新バージョンへ安全にアップグレード（Upgrade）するか、データを復元する方法を教えてください。

データベースの整合性を維持し、予期しないビルドクラッシュを防ぐため、以下の安全なアップグレード手順を遵守することを強く推奨します。

1. 安全な最新バージョンへのアップグレード検証手順（推奨）

既存のデータベースとのスキーマ不一致やテンプレート変更に伴う衝突を予防するため、本番サーバーに直接適用するのではなく、まず隔離されたテスト環境で安全性を確認してください。（Gitを使用せずファイルを直接ダウンロードして使用するユーザーも同様です）

1. 設定ファイルのバックアップ:
   • 現在の開発フォルダ内にある wrangler.backup.json と .dev.vars ファイルを安全な一時フォルダにコピーして保管します。
   • ※ .dev.vars ファイルは重要な認証情報（パスワード、OAuthキーなど）を含みますが、セキュリティ保護のためGit管理対象外（.gitignore）に指定されています。そのため、コードの更新時や再取得時に紛失しやすいため、必ずバックアップを取ってください。
2. 稼働中のデータバックアップ:
   • 現在稼働しているブログ管理画面の コンテンツバックアップ メニューから、記事全体および設定バックアップファイルをダウンロードします。
3. 隔離されたフォルダに新バージョンをクローン/ダウンロード:
   • 既存のフォルダを上書きせず、完全に新しいディレクトリに最新リリースのソースコードをダウンロードまたはクローンします。
4. 一時テストサーバーのデプロイ:
   • 新しいフォルダに移動し、依存関係のインストール（npm install）を行い、一時的なテスト用データベースを構築してテストデプロイを実行します。
5. バックアップ復元テスト:
   • 新しくデプロイされたテスト用管理画面にアクセスし、ステップ2で取得したバックアップファイルをロードして、データが漏れなく正常に表示され、エラーが発生しないかを徹底的に検証します。
6. 本番サーバーへの正式アップデート適用:
   • テストサーバーですべての機能が正常に動作することを確認した後でのみ、元の開発フォルダに戻り、コードを更新（git pull またはソースコードの上書き）して、各アプリの個別デプロイコマンド（npm run deploy:blog、npm run deploy:admin）を実行し、正式なアップグレードを完了させます。

2. データ紛失時の最終手段

• npm run restore コマンドの使用:
  • インフラ設定やデータベースが深刻に破損し、根本的な復旧が必要な場合にのみ、バックアップしておいた wrangler.backup.json ファイルを基にインフラ全体を再構築する**「最後のデータ復旧手段」**として実行してください。

---

📂 Q2. R2、Supabase、ImageKitへの画像ストレージ変更時に入力すべき必須キーは何ですか？

各外部画像ストレージ使用時に入力漏れのないよう確認すべき必須環境変数および設定のチェックリストです。

ストレージタイプ	必須入力項目 / 設定	説明
Cloudflare R2	IMAGES R2バケットバインディング	wrangler.json 内のR2バケット情報とのマッピングが必要です。
Supabase Storage	supabase_storage_url supabase_storage_key supabase_storage_bucket	API URLおよびService Role Keyが正確である必要があり、Supabase Storage内のバケット権限ポリシーが Public（公開） に設定されていなければ画像が表示されません。
ImageKit.io	imagekit_url_endpoint imagekit_public_key imagekit_private_key	エンドポイントURLの形式を確認し、クロスオリジンリソース共有（CORS）の許可を設定する必要があります。

---

📊 Q3. ダッシュボードの統計グラフがデモデータのみで表示されます。

• 原因: Google Analytics 4 (GA4) APIの環境変数が入力されていない、または無効な場合、ダッシュボードのクラッシュを防ぐためにデモ用のダミーデータが代替表示されます。
• 設定手順: Cloudflare Pages設定に以下の環境変数を入力し、再デプロイを行ってください。
  • GA4_PROPERTY_ID: Google Analytics プロパティ ID
  • GA4_CLIENT_EMAIL: Google Cloud サービスアカウントメールアドレス
  • GA4_PRIVATE_KEY: Google サービスアカウント秘密鍵
• 注意点: .dev.vars ファイルに GA4_PRIVATE_KEY を記述する際、改行コード（\n）の形式が崩れないよう、必ず鍵文字列全体を二重引用符（"）で囲って登録してください。

---

⚡ Q4. 初回setupデプロイ後、管理画面にアクセスできなかったり、一部のデータ同期が不足しているようです。

• 原因: ワンクリックセットアップ時に環境変数の設定が正常に完了していたとしても、一時的なネットワーク接続エラーやシステム上の不具合により、暗号化キーや秘密環境変数（Secrets）の同期が一部抜けてしまったり、データが破損した状態でデプロイが進行することがあります。
• 解決策: 各アプリの .dev.vars 設定値の状態を再度確認した上で、各フォルダに移動し、手動で個別のデプロイコマンド npm run deploy:blog と npm run deploy:admin をそれぞれ 1回実行 してください。ローカルの .dev.vars ファイルに入力された秘密環境変数群が正常に上書きされることで、問題が解決します。

---

🔒 Q5. 管理画面へのアクセス時に「Forbidden (IP Not Allowed)」または403エラーが表示されます。

本ブログのセキュリティ仕様上、デプロイスクリプトの実行時にデプロイを行っているPCのグローバルIPアドレスを自動的に検知し、アクセス許可IP（ALLOWED_IP）としてPages Secretに自動挿入します。

⚠️ 管理者セキュリティ推奨事項

• アカウントの乗っ取りや不正アクセスを防ぐため、外部の公共エリア（カフェ、図書館など）や、信頼性の保証されない 共有PC からの管理画面へのアクセス・投稿作業は、セキュリティ保護のため強く制限することを推奨します。

💡 状況別の対処法

• 状況A. 自宅やオフィスのIPアドレスが変わった場合（ルーターの再起動など）:
  • 既存の作業を行っていた自宅やオフィスのメイン開発PCのターミナルから npm run deploy:admin を1回実行してください。変更後のグローバルIPを自動的に検知して再デプロイが行われ、即座にアクセスが再開されます。
• 状況B. やむを得ず外部の場所から投稿作業を行うため、一時的に開発環境を移動させる場合:
  • 以前取得したバックアップ設定ファイル（wrangler.backup.json など）を持参し、新しいPC環境でワンクリックセットアップを実行して、新規にビルド・デプロイすることでアクセス権限を取得する方法が最も簡単です。
  • ※ 注意: 外部での作業を終え、再び本来の自宅やオフィスに戻ってブログを管理する際には、必ず元のメイン開発PCから npm run deploy:admin を再実行し、アクセス許可IPを本来の固定IPに復元デプロイしてください。

---

🔐 Q6. Better Auth（ソーシャルログイン・会員登録）に関するエラーや、ログインの無限ループが発生します。

• 原因: 認証セキュリティに使用される環境変数が欠落しているか無効な場合、セッション検証に失敗してログイン画面がループし続けます。
• 解決策:
  1. apps/blog/.dev.vars を開き、BETTER_AUTH_SECRET に 最小32文字以上の安全なランダム暗号化文字列 が入力されているか確認します。
  2. 正確に値を設定した後、npm run deploy:blog を実行して秘密キーを同期上書きすれば、認証機能が正常に復旧します。