🔑 CLI環境におけるCloudflare WranglerログインおよびAPIトークン設定詳細説明書

本プロジェクトは、1回のコマンド実行だけでCloudflareのデータベース、ストレージ、ビルドパイプラインを自動構築するセットアップスクリプトを提供しています。

このスクリプトは内部的にCloudflareのコマンドラインツールである wrangler CLIを使用します。通常のローカル開発PC環境では、Webブラウザを介した対話型ログイン（npx wrangler login）が即座に実行されますが、**ブラウザを開くことができない完全なCLI環境（例：リモートSSH Linuxサーバー、ヘッドレス仮想マシン、CI/CDデプロイパイプライン）**では、ログインセッションを対話式に確立できない制約が発生します。

本マニュアルでは、この環境の制約を克服するため、Cloudflare APIトークンを活用してWranglerの非対話型認証セッションを安全に構築する方法を詳しく解説します。

📂 1. ドメイン設定の前後に伴う必須最小限の権限区分

APIトークンを発行する前に、現在のインフラデプロイ段階を把握することが重要です。不要なセキュリティリスクを抑えるため、カスタムドメインの接続状況に応じて必要な権限を分離して適用します。

🔌 1-1. 初期デプロイ段階 (カスタムドメイン連携前)

プロジェクトを初めてデプロイし、Cloudflare Pagesが提供するデフォルトドメインである *.pages.dev アドレスのみを使用する場合、ブラウザ経由の一般的なログイン状態と同様に、Zone（ドメイン）レベルの権限は一切不要です。 オ직 アカウント（Account）レベルの主要なリソース権限のみで、セットアップスクリプトの実行とD1のマイグレーションが問題なく動作します。

必須最小限の権限リスト:
- D1 — 編集 (Edit) (D1 DBの作成、スキーマイグレーションの実行、クエリ動作用)
- Workers KV ストレージ (Workers KV Storage) — 編集 (Edit) (ブログメディアアップロード用のKVネームスペース制御用)
- Cloudflare Pages — 編集 (Edit) (モノレポのブログおよび管理画面プロジェクトデプロイ用)
- Workers スクリプト (Workers Scripts) — 編集 (Edit) (WorkersスクリプトおよびCLI設定制御用)

🌐 1-2. カスタムドメイン連携およびCDNエッジキャッシュ使用段階 (今後の設定)

ブログに個人ドメインを接続し、パフォーマンス向上のためにエッジCDNキャッシュを強制的にクリア（Purge）する機能などを有効にする場合に、初めて Zoneレベルの権限が要求されます。

追加必須権限:
- Zone: キャッシュパージ (Cache Purge) — 編集 (Edit) (デプロイ完了時やコンテンツ更新時にCDNエッジサーバーのキャッシュを即座に削除するために必要)
セキュリティのベストプラクティス: トークンのスコープを制限する際、Zone Resourcesを「All Zones（すべてのゾーン）」にせず、使用している特定固有のドメイン（Zone）にスコープを限定してトークンを発行するのが安全です。
注意: カスタムドメインの設定方法およびキャッシュ制御メカニズムの詳細は、今後別途発行される 「カスタムドメイン設定に関する詳細説明書」 で詳しく解説する予定であるため、初期構築段階の現在は該当設定を省略して進めても問題ありません。

🛠️ 2. Cloudflare API トークンの生成手順

非対話型ログインを可能にするトークンは、Cloudflareダッシュボードで以下の手順に従って簡単に生成できます。

Cloudflareダッシュボードにログイン:
- Cloudflare Dashboardにアクセスしてログインします。
トークン作成メニューへの移動:
- 画面右上のプロフィールアイコンをクリックし、「マイプロフィール」 (My Profile) を選択します。
- 左側メニューから 「API トークン」 (API Tokens) を選択します。
- 右側の 「トークンを作成する」 (Create Token) ボタンをクリックします。
カスタムトークンの設定:
- テンプレート一覧の一番下にある 「カスタムトークン」 (Create Custom Token) 領域の 「始める」 (Get Started) をクリックします。
権限 (Permissions) の割り当て:
- トークン名 (Token Name): 判別しやすい名前を入力 (例: sveltekit-blog-cli-token)
- Permissions (アクセス許可):
  - アカウント (Account) -> D1 -> 編集 (Edit)
  - アカウント (Account) -> Workers KV ストレージ (Workers KV Storage) -> 編集 (Edit)
  - アカウント (Account) -> Cloudflare Pages -> 編集 (Edit)
  - アカウント (Account) -> Workers スクリプト (Workers Scripts) -> 編集 (Edit)
スコープの制限:
- アカウントリソース (Account Resources): 含める (Include) -> 自身の Cloudflare アカウントを選択 (権限範囲を自身のアカウント内部のみに絞り、セキュリティ脅威を隔離します。)
生成完了と保管:
- 「サマリーに進む」 (Continue to summary) を押した後、「トークンを作成」 (Create Token) をクリックして生成された固有のトークン値（英数字と記号で構成された長いキー文字列）を安全な場所にコピーして保管します。 (この値は一度画面を閉じると再確認できないため、紛失した場合は再発行する必要があります。)

💻 3. 発行されたAPIトークンの適用および環境変数の設定方法

対話型のブラウザログインウィンドウを開くことができないため、システム環境変数に発行されたトークン値を挿入して、Wranglerが自動的にこれを読み込んで認証を確立するように誘導する必要があります。

3-1. OS環境別のターミナル環境変数コマンド

セットアップスクリプトを実行するターミナルコンソール画面に、OSの種類に応じて以下のコマンドを入力します。

Linux / macOS / Git Bash (Bash/Zsh Shell):

export CLOUDFLARE_API_TOKEN="発行された_トークン_値"

Windows Command Prompt (CMD):

set CLOUDFLARE_API_TOKEN=発行された_トークン_値

Windows PowerShell:

$env:CLOUDFLARE_API_TOKEN="発行된_トークン_値"

[!NOTE]
💻 macOS環境での実行および検証に関するご案内

本ガイドは、Windows 10/11 および Linux(Ubuntu 22.04 LTS) の物理コンソール環境で、コマンドラインの起動およびトークン連携の有効性を事前にテスト・検証済みです。

ただし、作成者個人の検証用ハードウェアの都合上、macOS（実際のMac環境）での動作確認は実施できていません。Node.js CLIのクロスプラットフォーム動作の原則に基づき、macOSでもZsh/Bashターミナルを介して同様に export コマンドで問題なく正常に稼働すると想定されます。

3-2. ローカル開発環境ファイルおよびCI/CDの連携

ローカル開発環境 (.dev.vars):
ターミナルを開くたびに環境変数を入力するのが手間な場合は、apps/blog/.dev.vars および apps/admin/.dev.vars ファイルに以下のように登録しておくと、ローカルで wrangler dev を起動する際に自動的にトークンが読み込まれバインドされます。
```
CLOUDFLARE_API_TOKEN="発行された_トークン_値"
```
CI/CDパイプライン (GitHub Actions):
GitHubリポジトリの Settings -> Secrets and variables -> Actions -> Repository secrets メニューに進み、CLOUDFLARE_API_TOKEN という名前で発行されたトークンを追加した後、YAMLワークフローファイルで以下のように呼び出して使用できます。
```
- name: Build and Deploy SvelteKit Apps
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
  run: npm run deploy:blog
```

🔍 4. トークンの認証状態の検証とデバッグ

トークン環境変数がシステムセッション上に正しく挿入され、バインドされているかを確認するためのデバッグコマンドです。

4-1. wrangler whoami

ターミナルで以下のコマンドを実行します。

npx wrangler whoami

検証成功時: 現在トークンが所属しているアカウント情報（Account Name、Account ID）およびD1、KVなどの制御権限のバインディングリストがコンソールに出力されます。
ログインセッションのクリア (wrangler logout):
以前にブラウザログイン方式で確立した古いセッションデータが残っており、環境変数と干渉している可能性がある場合は、先にログアウトコマンドを実行してローカルに保存されている古い認証セッションを完全に初期化してから、環境変数を再適用することをお勧めします。
```
npx wrangler logout
```

⚠️ 5. よくある質問と解決策 (Troubleshooting)

🚨 1. Authentication Error (Code: 10000)

原因: セットアップスクリプト実行中に Cloudflare の認証失敗エラーが表示される状態です。
解決策: 挿入した CLOUDFLARE_API_TOKEN の文字列にタイポや不要なスペースが含まれていないか確認してください。また、ダッシュボードでトークンを発行した際に指定した Account Resources スコープが、現在接続しているアカウントと一致しているか再確認してください。

🚨 2. Forbidden (アクセス拒否エラー)

原因: D1のマイグレーションは成功するものの、PagesのデプロイやKVリソースの生成時にアクセス拒否エラーが発生する場合です。
解決策: 作成したトークンのアクセス許可（Permissions）リストに Cloudflare Pages -> Edit や Workers KV Storage -> Edit など、必要なアクセス権が不足していないかダッシュボードで確認し、権限を修正・追加した後に再度環境変数の設定を試みてください。

CLI環境におけるCloudflare WranglerログインおよびAPIトークン設定詳細説明書