cloudflare-manager

Cloudflare Manager

Workers、KV Storage、R2 バケット、Pages、DNS レコード、ルーティングのデプロイと設定を可能にする、包括的な Cloudflare サービス管理スキルです。API 認証情報を自動的に検証し、デプロイ URL を抽出して、問題解決に役立つエラーメッセージを提供します。

初期設定

このスキルを初めて使用する前に、次の手順を実行してください。

1. 依存関係をインストールする

   cd ~/.claude/skills/cloudflare-manager
   bun install
   

2. API キーを設定する

   プロジェクトのルートに .env ファイルを作成します。

   CLOUDFLARE_API_KEY=your_api_token_here
   CLOUDFLARE_ACCOUNT_ID=your_account_id  # Optional, auto-detected
   

   API トークンの取得方法：

   • https://dash.cloudflare.com/profile/api-tokens にアクセスします
   • 「Create Token」をクリックします
   • 「Edit Cloudflare Workers」テンプレートを使用します（またはカスタムトークンを作成します）
   • 必要な権限：
     • Account > Workers Scripts > Edit
     • Account > Workers KV Storage > Edit
     • Account > Workers R2 Storage > Edit
     • Account > Cloudflare Pages > Edit
     • Zone > DNS > Edit（カスタムドメインを使用する場合）

3. 認証情報を検証する

   検証を実行して API キーを確認し、権限をチェックします。

   cd ~/.claude/skills/cloudflare-manager
   bun scripts/validate-api-key.ts
   

   期待される出力：

   ✅ API key is valid!
   ℹ️  Token Status: active
   ℹ️  Account: Your Account Name (abc123...)
   
   🔑 Granted Permissions:
     ✅ Workers Scripts: Edit
     ✅ Workers KV Storage: Edit
     ✅ Workers R2 Storage: Edit
   

   検証に関するトラブルシューティング：

   • 検証が 401/403 で失敗する場合：.env の API トークンが正しいことを確認してください
   • 検証がネットワークエラーで失敗する場合：インターネット接続を確認してください
   • --no-cache フラグを使用して最新の検証を強制します：bun scripts/validate-api-key.ts --no-cache

現在の API 権限

bun scripts/validate-api-key.ts を実行すると、このセクションに現在の権限が反映されます。

例

例 1：新しい Worker API のデプロイ

ユーザーのリクエスト：

"Set up a Cloudflare worker for handling API requests and give me the URL"

ワークフロー：

1. .env に API 認証情報があることを検証します
2. Worker スクリプトをデプロイします：

   bun scripts/workers.ts deploy api-handler ./worker.js
   

3. レスポンスから Cloudflare が生成した URL を抽出します
4. URL を返します：https://api-handler.username.workers.dev

期待される出力：

✅ Worker deployed successfully!
📍 URL: https://api-handler.username.workers.dev
🆔 Worker ID: abc123def456

所要時間： 2～5 秒

---

例 2：アプリケーションスタック全体（Worker + KV + R2）

ユーザーのリクエスト：

"Set up a complete Cloudflare application with worker, key-value storage, and file storage"

ワークフロー：

1. セッションのキャッシュ用に KV 名前空間を作成します：

   bun scripts/kv-storage.ts create-namespace app-sessions
   # Returns: namespace-id-123
   

2. ユーザーアップロード用に R2 バケットを作成します：

   bun scripts/r2-storage.ts create-bucket app-uploads
   # Returns: Bucket created: app-uploads
   

3. バインディングを設定して Worker をデプロイします：

   bun scripts/workers.ts deploy app-api ./worker.js \
     --kv-binding SESSION_STORE=namespace-id-123 \
     --r2-binding UPLOADS=app-uploads
   

4. カスタムドメインのルートを設定します：

   bun scripts/dns-routes.ts create-route example.com \
     "api.example.com/*" app-api
   

期待される出力：

✅ KV namespace created: app-sessions (namespace-id-123)
✅ R2 bucket created: app-uploads
✅ Worker deployed: https://app-api.username.workers.dev
✅ Route configured: api.example.com/* → app-api

所要時間： 合計 8～12 秒

---

例 3：静的サイトを Pages にデプロイ

ユーザーのリクエスト：

"Deploy my static site to Cloudflare Pages"

ワークフロー：

1. Pages プロジェクトを作成します（存在しない場合）：

   bun scripts/pages.ts deploy my-site ./dist
   

2. ファイルを使って初回デプロイを行うには、Wrangler を使用します：

   npx wrangler pages deploy ./dist --project-name=my-site
   

3. 環境変数を設定します：

   bun scripts/pages.ts set-env my-site API_URL https://api.example.com
   bun scripts/pages.ts set-env my-site DEBUG false --env production
   

期待される出力：

✅ Pages project created: my-site
📍 URL: https://my-site.pages.dev
🚀 Deploying files... (via Wrangler)
✅ Deployment complete!
✅ Environment variables set

所要時間： 15～30 秒（サイトのサイズによって異なります）

---

クイックスタートガイド

Worker コンテナをデプロイする

新しい Worker コンテナのサンドボックスをデプロイするには：

# Using the skill
bun scripts/workers.ts deploy worker-name ./worker-script.js

実行内容：

• 新しい Worker コンテナを作成します
• JavaScript/TypeScript コードをデプロイします
• Cloudflare が生成した URL（例：https://worker-name.username.workers.dev）を自動的に抽出して返します
• Worker ID と設定を返します

会話例：

User: "Set up and deploy a new cloudflare worker container sandbox named 'api-handler' and return the URL"
Claude: [Deploys worker using bun scripts/workers.ts deploy api-handler ./worker.js]
       Returns URL: https://api-handler.username.workers.dev

終了コード：

• 0：成功 — Worker がデプロイされ、URL が返されました
• 1：失敗 — 詳細についてはエラーメッセージを確認してください

パフォーマンス：デプロイは通常 2～5 秒で完了します

よくある落とし穴

⚠️ 特に重大な問題 — 問題が発生した場合は、まず次の点を確認してください。

1. API トークンのスコープ（最もよくある失敗の原因）

問題：権限が不十分、またはスコープが正しく設定されていない API トークンは、403 エラーを出しながら失敗し、デバッグが非常に困難になります。

回避方法：

• https://dash.cloudflare.com/profile/api-tokens でトークンを作成する際は、**「Edit Cloudflare Workers」**テンプレートを使用してください。「Read All」や、適切な権限のないカスタムスコープは使用しないでください
• 最低限必要なスコープ：
  • Account > Workers Scripts > Edit
  • Account > Workers KV Storage > Edit
  • Account > Workers R2 Storage > Edit
  • Zone > DNS > Edit（カスタムドメインを使用する場合のみ）
• トークンの作成後、すぐに検証してください：

  bun scripts/validate-api-key.ts
  

  これにより、保有している権限を正確に確認できます。トークンを作成または更新するたびに、必ず実行してください。

簡単な診断：

# If you see "Insufficient permissions", stop and fix the token:
bun scripts/validate-api-key.ts
# If any required permission shows ❌, update token at:
# https://dash.cloudflare.com/profile/api-tokens

---

2. Wrangler OAuth のポート競合

問題：wrangler login は OAuth コールバックにポート 8976 を使用します。別の wrangler dev または wrangler pages dev プロセスがすでに実行中の場合、ログインフローは何も通知せずに失敗します。ブラウザーのタブは開きますが、OAuth リダイレクトを受信できません。

回避方法：

• wrangler login を実行する前に、ほかの Wrangler プロセスをすべて終了します：

  pkill -f wrangler
  

• 次に、ログインを実行します：

  wrangler login
  

• ログインが完了してから wrangler dev または Pages を起動してください

原因：Wrangler は OAuth コールバックをキューに入れません。ポート 8976 のバインドに成功した最初のプロセスがコールバックを受信します。それが開発サーバーの場合、ログイン試行は何も通知せずに失敗します。

---

3. デプロイのタイムアウト（大規模プロジェクト）

問題：プロジェクトの規模が大きすぎる場合や、ネットワーク接続が不安定な場合、Workers と Pages のデプロイはタイムアウトします。Cloudflare の負荷がピークに達しているときにも、タイムアウトが発生します。

回避方法：

• Worker スクリプト：1MB 未満に保ちます（小さいほどコールドスタートが速くなります）
• Pages のデプロイ：
  • ファイル数が 1000 を超えるプロジェクトでは、5～10 分かかることがあります
  • .cloudflare/ の除外パターンを使って、node_modules、ビルドキャッシュなどを除外します
  • 大規模なデプロイでは、Wrangler CLI を直接使用します：

    npx wrangler pages deploy ./dist --project-name=my-app
    

• ネットワーク：安定した接続からデプロイします。再試行では指数バックオフが使用され、自動的に成功するはずです
• 保留状態から進まない場合：

  bun scripts/pages.ts list-deployments my-app  # Check status
  # If truly stuck, delete and recreate the project
  

---

リファレンス：トラブルシューティングガイド

特定のエラーメッセージに対する詳しい解決方法については、以下のトラブルシューティングセクションを参照してください。

KV ストレージの作成と使用

KV 名前空間を作成してデータを保存するには：

# Create namespace
bun scripts/kv-storage.ts create-namespace user-sessions
# Returns: Namespace ID (e.g., abc123def456)
# Save this ID for binding to workers

# Write key-value pair
bun scripts/kv-storage.ts write <namespace-id> "session:user123" '{"userId":"123","token":"abc"}'

# Read value
bun scripts/kv-storage.ts read <namespace-id> "session:user123"
# Returns: {"userId":"123","token":"abc"}

# List all keys (useful for debugging)
bun scripts/kv-storage.ts list-keys <namespace-id>

# Delete a key
bun scripts/kv-storage.ts delete <namespace-id> "session:user123"

重要：KV ストレージでは結果整合性が使用されます。書き込み内容がグローバルに反映されるまで、最大 60 秒かかることがあります。すぐに読み取るには、データを書き込んだのと同じエッジロケーションを使用してください。

R2 バケットの作成とファイルのアップロード

R2 バケットを作成してオブジェクトを管理するには：

# Create bucket
bun scripts/r2-storage.ts create-bucket media-assets

# Upload file
bun scripts/r2-storage.ts upload media-assets ./images/logo.png logo.png

# List objects
bun scripts/r2-storage.ts list-objects media-assets

# Download object
bun scripts/r2-storage.ts download media-assets logo.png ./downloaded-logo.png

Cloudflare Pages へのデプロイ

静的サイトまたはアプリケーションを Pages にデプロイするには：

# Create Pages project (or get existing project info)
bun scripts/pages.ts deploy my-app ./dist
# Returns: https://my-app.pages.dev

# Set environment variable
bun scripts/pages.ts set-env my-app API_URL https://api.example.com

# Set environment variable for specific environment
bun scripts/pages.ts set-env my-app DEBUG true --env preview

# Get deployment URL
bun scripts/pages.ts get-url my-app

自動抽出される URL：Pages スクリプトは、デプロイのレスポンスから Cloudflare が生成した URL（例：https://my-app.pages.dev）を自動的に抽出して返します。

注：API はプロジェクトの構成を作成しますが、実際にファイルをアップロードするには Wrangler CLI が必要です：

npx wrangler pages deploy ./dist --project-name=my-app

この方法が機能する理由：スキルは Pages プロジェクトを作成または検証して、URL を返します。ファイルを使った初回デプロイでは、複雑なマルチパートアップロード処理を Wrangler が行います。

DNS とルートの設定

DNS レコードを作成して Worker のルートを設定するには：

# Create DNS A record
bun scripts/dns-routes.ts create-dns example.com A api 192.168.1.1

# Route pattern to worker
bun scripts/dns-routes.ts create-route example.com "*.example.com/api/*" api-handler

一般的なワークフロー

複数サービスのセットアップ

Worker、KV ストレージ、R2 バケットを含むアプリケーション全体をセットアップするには：

1. キャッシュ用の KV 名前空間を作成

   bun scripts/kv-storage.ts create-namespace app-cache
   

2. メディア用の R2 バケットを作成

   bun scripts/r2-storage.ts create-bucket app-media
   

3. バインディングを設定して Worker をデプロイ

   bun scripts/workers.ts deploy app-worker ./worker.js --kv-binding app-cache --r2-binding app-media
   

4. ルートを設定

   bun scripts/dns-routes.ts create-route example.com "example.com/*" app-worker
   

Worker の設定を更新

既存の Worker のコードまたはバインディングを更新するには：

# Update worker code
bun scripts/workers.ts update worker-name ./new-worker-script.js

# Get worker details
bun scripts/workers.ts get worker-name

# List all workers
bun scripts/workers.ts list

KV の一括操作

KV ストレージで一括操作を実行するには：

# Bulk write from JSON file
bun scripts/kv-storage.ts bulk-write namespace-name ./data.json

# Delete multiple keys
bun scripts/kv-storage.ts bulk-delete namespace-name key1 key2 key3

エラー処理

API キーがない場合

.env ファイルが存在しない場合、または CLOUDFLARE_API_KEY が設定されていない場合：

Error: CLOUDFLARE_API_KEY not found in environment

Solution: Create .env file in project root:
  echo "CLOUDFLARE_API_KEY=your_token_here" > .env

権限が無効な場合

API トークンに必要な権限がない場合：

Error: Insufficient permissions for Workers deployment

Required: Workers Scripts: Edit
Current: Workers Scripts: Read

Solution: Update token permissions at:
  https://dash.cloudflare.com/profile/api-tokens

API のレート制限

リクエストが多すぎる場合：

Error: Rate limit exceeded (429)

Solution: Retry automatically with exponential backoff (3 attempts)

ネットワークの問題

API に接続できない場合：

Error: Failed to connect to Cloudflare API

Solution: Check internet connection and retry

ベストプラクティス

セキュリティ：

• .env ファイルは絶対にコミットせず、必ず .gitignore に追加してください
• API キーではなく、トークンベースの認証を使用してください
• トークンは定期的にローテーションしてください（90 日ごとを推奨）
• 最小権限の原則に従い、必要な権限のみを付与してください
• Wrangler CLI でシークレットを保存してください：wrangler secret put SECRET_NAME

パフォーマンス：

• レイテンシーを最小限に抑えるため、ワーカーをデプロイしてください（Cloudflare のエッジで実行されます）
• 頻繁に読み取るデータには KV ストレージを使用してください（頻繁に書き込むデータには使用しないでください）
• 大きなファイルには R2 を使用してください（KV のキーあたりの上限は 25MB です）
• 適切な TTL を設定してキャッシュを有効にしてください
• コールドスタートを高速化するため、ワーカースクリプトは 1MB 未満にしてください

開発ワークフロー：

• まずローカルでテストしてください：ローカルテストには wrangler dev を使用します
• 本番環境の前にステージング環境を使用してください
• トークンの更新後に認証情報を検証してください：bun scripts/validate-api-key.ts
• ワーカーのログを監視してください：wrangler tail worker-name
• ワーカーにバージョンを付けてください：api-v1、api-v2 などの名前を使用します

命名規則：

• ワーカー：説明的な名前を使用してください（例：worker1 ではなく user-auth-worker）
• KV 名前空間：用途を名前に含めてください（例：app-sessions、api-cache）
• R2 バケット：小文字とハイフンを使用してください（例：media-assets-prod）
• インフラストラクチャ全体で一貫性を保ってください

リソース管理：

• 使用していないワーカー、名前空間、バケットを削除してください
• Cloudflare ダッシュボードで使用状況を監視してください
• 無料枠の上限：Workers は 1 日あたり 100,000 リクエストです
• 予期しない請求を避けるため、請求アラートを設定してください

高度な使い方

以下を含む高度なシナリオについては：

• 複雑なルーティング設定
• マルチリージョンデプロイ
• カスタムドメインの設定
• ワーカー間通信
• Durable Objects との統合
• 一括操作と移行

包括的な例とパターンについては、examples.md を参照してください。

スクリプトリファレンス

すべてのスクリプトは ~/.claude/skills/cloudflare-manager/scripts/ にあります：

• validate-api-key.ts：API 認証情報を検証し、権限を表示します
• workers.ts：Workers のデプロイ、更新、管理を行います
• kv-storage.ts：KV 名前空間とキーと値のペアを作成、管理します
• r2-storage.ts：R2 バケットとオブジェクトを作成、管理します
• pages.ts：Cloudflare Pages プロジェクトをデプロイ、設定します
• dns-routes.ts：DNS レコードとワーカールートを設定します
• utils.ts：API 呼び出しとエラー処理のための共通ユーティリティです

テンプレート

スターターテンプレートは ~/.claude/skills/cloudflare-manager/templates/ にあります：

• worker-template.js：fetch ハンドラーを備えた基本的なワーカーテンプレート
• wrangler.toml.template：Wrangler 設定テンプレート

トラブルシューティング

クイックリンク：優先度の高い問題

本番環境で発生する最も重大な問題については、上記の よくある落とし穴 を参照してください：

• API トークンのスコープ設定の問題 → API トークンのスコープ設定
• Wrangler OAuth の失敗 → Wrangler OAuth のポート競合
• デプロイのタイムアウト → デプロイのタイムアウト

診断コマンド

問題が発生した場合の最初の手順：

# 1. Validate API credentials and permissions
bun scripts/validate-api-key.ts

# 2. List existing resources to check state
bun scripts/workers.ts list
bun scripts/kv-storage.ts list-namespaces
bun scripts/r2-storage.ts list-buckets
bun scripts/pages.ts list-projects

# 3. Check specific resource details
bun scripts/workers.ts get worker-name
bun scripts/pages.ts list-deployments project-name

各手順を使用するタイミング：

• 手順 1（検証）：どのコマンドでも失敗した場合は、必ず最初に実行してください
• 手順 2（一覧表示）：実際に存在するリソースを確認します
• 手順 3（詳細の取得）：特定のリソースの状態を調査します

よくある問題と解決策

問題: 「Worker のデプロイに失敗しました（原因不明のエラー）」

症状: デプロイコマンドがエラーコード 1 で終了し、具体的なエラーメッセージが表示されない

解決策:

1. スクリプトの構文を確認します：node --check ./worker.js
2. ファイルが存在することを確認します：ls -lh ./worker.js
3. API キーを再検証します：bun scripts/validate-api-key.ts --no-cache
4. Worker 名が有効であることを確認します（英数字、ハイフン、アンダースコアのみ）

---

問題: 「KV 名前空間が見つかりません」

症状: 名前空間の読み書きを試みるとエラーが発生する

解決策:

1. すべての名前空間を一覧表示します：bun scripts/kv-storage.ts list-namespaces
2. コマンドでは名前ではなく名前空間 ID を使用していることを確認します
3. 名前空間が削除されていないことを確認します
4. API トークンに KV Storage の権限があることを確認します

---

問題: 「R2 バケットはすでに存在します」または「バケット名は使用されています」

症状: 選択した名前でバケットを作成できない

解決策:

1. バケット名は、すべての Cloudflare アカウント間で一意である必要があります
2. より具体的な名前を試します：media ではなく my-app-media-2024
3. 既存のバケットを使用します：bun scripts/r2-storage.ts list-buckets
4. 名前は 3～63 文字で、小文字の英字、数字、ハイフンのみ使用できます

---

問題: 「Pages のデプロイがタイムアウトしました」または「デプロイが保留中です」

症状: デプロイが完了せず、保留中の状態のままになる

解決策:

1. デプロイのステータスを確認します：bun scripts/pages.ts list-deployments project-name
2. ダッシュボードで確認します：https://dash.cloudflare.com/pages
3. 大規模なデプロイ（>1000 ファイル）には 5～10 分かかることがあります
4. 停滞している場合はキャンセルして再試行します：プロジェクトを削除して再作成します

---

問題: 「DNS レコードの作成に失敗しました」

症状: DNS レコードまたはルートを作成できない

解決策:

1. ゾーンが存在することを確認します：bun scripts/dns-routes.ts list-zones
2. ドメインが Cloudflare に追加され、アクティブであることを確認します
3. ネームサーバーが Cloudflare を指していることを確認します：dig NS yourdomain.com
4. API トークンに Zone > DNS > Edit の権限があることを確認します

---

問題: 「API レート制限を超えました（429）」

症状: コマンドが「リクエストが多すぎます」というメッセージで失敗する

解決策:

1. スクリプトは指数バックオフを使って自動的に再試行します
2. 手動で再試行する前に 1～2 分待ちます
3. 同時に実行する操作を減らします
4. レート制限：5 分あたり 1200 リクエスト

---

問題: 「環境変数に CLOUDFLARE_API_KEY が見つかりません」

症状: 環境エラーによりコマンドがすぐに失敗する

解決策:

1. プロジェクトのルート（スキルディレクトリではありません）に .env ファイルを作成します
2. ファイルの内容を確認します：cat .env | grep CLOUDFLARE_API_KEY
3. 余分なスペースがないことを確認します：CLOUDFLARE_API_KEY=token（= の前後にスペースは入れません）
4. .env が存在するプロジェクトのルートからコマンドを実行します

すぐに解決する方法:

cd /path/to/your/project
echo "CLOUDFLARE_API_KEY=your_token_here" > .env
bun scripts/validate-api-key.ts

セキュリティに関する注意事項

• API キーがログに記録されたり、出力に表示されたりすることはありません
• すべての API リクエストで HTTPS を使用します
• API を呼び出す前にユーザー入力を検証します
• 破壊的な操作（削除）には確認が必要です
• トークンの露出を最小限に抑えるため、権限は 24 時間キャッシュされます

追加リソース

• Cloudflare API ドキュメント：https://developers.cloudflare.com/api/
• Workers ドキュメント：https://developers.cloudflare.com/workers/
• KV Storage ガイド：https://developers.cloudflare.com/kv/
• R2 Storage ガイド：https://developers.cloudflare.com/r2/
• Pages ドキュメント：https://developers.cloudflare.com/pages/