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 を実行すると、現在の権限がこのセクションに表示されます。

クイックスタートガイド

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 秒で完了します

KV Storage を作成して使用する

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 Storage では結果整合性が使用されます。書き込みがグローバルに反映されるまで、最大 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 が必要です。

bunx 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 Storage、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 Storage で一括操作を実行するには：

# 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 設定テンプレート

トラブルシューティング

よくある問題と解決方法

問題: "Worker deployment failed with unknown error"

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

解決方法:

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

---

問題: "KV namespace not found"

症状: ネームスペースの読み取り／書き込み時にエラーが発生する

解決方法:

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

---

問題: "R2 bucket already exists" または "Bucket name taken"

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

解決方法:

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

---

問題: "Pages deployment timeout" または "Deployment pending"

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

解決方法:

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

---

問題: "DNS record creation failed"

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

解決方法:

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

---

問題: "API rate limit exceeded (429)"

症状: コマンドが "Too many requests" で失敗する

解決方法:

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

---

問題: "CLOUDFLARE_API_KEY not found in environment"

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

解決方法:

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/