⚙️ Cloudflare R2 / Hyperdrive / Queues セットアップ手順

Parky API 統合用の Cloudflare リソース作成・設定ガイド

🪣R2 バケット作成（オブジェクトストレージ）

1
Cloudflare ダッシュボード にログイン
https://dash.cloudflare.com/

アカウントを選択して進みます。

2
R2 セクションに移動
左メニュー > Workers & Pages > R2

R2 のホーム画面が表示されます。

3
バケットを作成
[Create bucket] ボタンをクリック

モーダルが開きます。以下を入力：

項目 入力値
Bucket name
Region

→ リージョンは東京（asia-tokyo）を含む APJC を選択

4
バケット作成確認

[Create bucket] で確定。

✅ バケット作成完了
画面に parky が表示され、「Settings」タブが見える状態になります。
5
R2 API トークン生成
バケット詳細 > Settings > R2 API token

[Create API token] をクリック

📝 Token 設定：

項目 値
Token name
Permissions
TTL
💡 注意： 権限は「Object Read & Write」を選択（パケットの作成・削除は不要）
6
認証情報をコピー

Token 作成後、以下の 3 つの値が画面に表示されます。すべて安全に保管してください：

📌 必要な値：

環境変数 コピー元 説明
R2_ACCESS_KEY_ID Token 画面の「Access Key ID」 API 認証用 ID（秘密）
R2_SECRET_ACCESS_KEY Token 画面の「Secret Access Key」 API 認証用シークレット（秘密）
R2_ENDPOINT Token 画面の「S3 API Endpoint」 例：https://[account-id].r2.cloudflarestorage.com
# これらを .env ファイルにコピー R2_ACCESS_KEY_ID=your_access_key_here R2_SECRET_ACCESS_KEY=your_secret_key_here R2_ENDPOINT=https://[account-id].r2.cloudflarestorage.com R2_REGION=auto R2_BUCKET=parky
⚠️ セキュリティ：
これらの値を GitHub に push しないでください。.env ファイルは .gitignore に含めてください。
7
wrangler.toml を更新

プロジェクトの api/wrangler.toml の以下の行をコメント解除：

[[env.dev.r2_buckets]] binding = "R2" bucket_name = "parky"

（行頭の # を削除）

✅ 検証チェック
  • Cloudflare dash に parky バケットが表示されている
  • .env に 4 つの R2 環境変数が設定されている
  • wrangler.toml の R2 バインディングがコメント解除されている

🚀Hyperdrive セットアップ（接続プール）

1
Cloudflare Hyperdrive に移動
Cloudflare Dashboard > Workers & Pages > Hyperdrive

[Create Hyperdrive] ボタンをクリック

2
基本情報を入力
項目 入力値
Name
Database Type
3
Supabase 接続情報を取得

別タブで Supabase Dashboard を開きます：

Supabase Dashboard > Project Settings > Database > Connection pooler

📋 以下を確認・コピー：

項目 Supabase での位置 例
Mode Connection pooler > Mode ドロップダウン Transaction
Port 自動表示 6543
Host pooler ホスト（コピーボタン有） db.xxxxx.supabase.co
User User フィールド postgres.[project-ref]
Password Database password（Project Settings > Database） あなたの DB パスワード
Database 固定値 postgres
⚠️ Mode の確認：
Connection pooler の「Mode」を必ず Transaction に設定してください。 この設定がないと Hyperdrive と一貫性の問題が生じる可能性があります。
4
Hyperdrive に接続情報を入力

Cloudflare の Hyperdrive 作成画面に以下を入力：

Hyperdrive フィールド 入力値（Supabase から）
Hostname
Port
Database
User
Password
💡 キー設定：
左下の「Test connection」をクリックすると接続確認できます（オプション）。
5
Hyperdrive ID を取得

[Create Hyperdrive] で確定後、ダッシュボードに戻ります。

作成された Hyperdrive をクリックし、詳細ページの右上または URL から ID を確認：

例） URL: https://dash.cloudflare.com/...?id=a1b2c3d4e5f6... ID = a1b2c3d4e5f6...

この ID を以下に記録してください：

HYPERDRIVE_ID =
6
wrangler.toml を更新

プロジェクトの api/wrangler.toml で以下を有効化：

[[env.dev.hyperdrive]] binding = "HYPERDRIVE" id = "a1b2c3d4e5f6..." # ← 上で取得した ID を入力

（行頭の # を削除し、ID を記入）

✅ 検証チェック
  • Cloudflare Hyperdrive ダッシュボードに parky-db が表示されている
  • Hyperdrive 詳細で Status が「Connected」と表示されている
  • wrangler.toml の Hyperdrive バインディングがコメント解除され、ID が入力されている

📤Queues セットアップ（非同期キュー）

1
Cloudflare Queues に移動
Cloudflare Dashboard > Workers & Pages > Queues

[Create Queue] ボタンをクリック

2
メイン キュー作成

キュー 1：ストア同期ジョブ用

項目 値
Queue name

→ [Create Queue] でキュー作成

3
Dead Letter Queue（DLQ）作成【オプション】

失敗メッセージを保存するキューを作成（オプションですが推奨）：

[Create Queue] > Queue name: parky-store-sync-dlq
💡 Dead Letter Queue：
リトライ失敗メッセージが自動的にここに移動。問題デバッグに便利です。
4
wrangler.toml を更新

プロジェクトの api/wrangler.toml で以下を有効化：

[[env.dev.queues.producers]] binding = "STORE_SYNC_QUEUE" queue = "parky-store-sync" [[env.dev.queues.consumers]] queue = "parky-store-sync" max_batch_size = 10 max_batch_timeout = 30 max_retries = 3 dead_letter_queue = "parky-store-sync-dlq"

（行頭の # を削除）

各設定の説明：

設定項目 値 説明
max_batch_size 10 一度に処理するメッセージ数（最大）
max_batch_timeout 30 メッセージ蓄積待機時間（秒）。これを超えたら処理開始
max_retries 3 失敗時のリトライ回数（3 回失敗後は DLQ へ）
dead_letter_queue parky-store-sync-dlq 失敗メッセージ移動先（DLQ を作成済みの場合）
5
デプロイ & 動作確認

すべてのリソース設定が完了したら、デプロイします：

cd api wrangler deploy --env dev

✅ デプロイ後の確認：

  1. ログを確認：wrangler tail --env dev
  2. Queues ダッシュボード → Queues セクションでメッセージ状況を監視
  3. API テスト：
    curl -X POST https://dev-api.parky.co.jp/v1/admin/store-sync/trigger \ -H "Authorization: Bearer [YOUR_JWT]" \ -H "Content-Type: application/json" \ -d '{ "store": "all", "task": "all" }'
  4. レスポンス確認：202 Accepted + sync_run_id が返ってくる
  5. Queues ダッシュボード → メッセージが処理される様子を監視
✅ 検証チェック
  • Cloudflare Queues ダッシュボードに parky-store-sync が表示されている
  • parky-store-sync-dlq も表示されている（DLQ 作成時）
  • wrangler.toml の Queues セクションがコメント解除されている
  • デプロイ成功（wrangler deploy でエラーなし）
  • API リクエストで 202 が返される

🔄全リソース統合確認

1
.env ファイルの確認

以下のすべてが設定されているか確認：

# R2 設定 R2_ENDPOINT=https://[account-id].r2.cloudflarestorage.com R2_REGION=auto R2_BUCKET=parky R2_ACCESS_KEY_ID=your_access_key R2_SECRET_ACCESS_KEY=your_secret_key # Supabase 設定（既存、変更なし） SUPABASE_URL=https://[project-id].supabase.co SUPABASE_SERVICE_ROLE_KEY=... SUPABASE_ANON_KEY=...
2
wrangler.toml の確認

すべてのバインディングが有効化されているか確認：

# R2 バケット [[env.dev.r2_buckets]] binding = "R2" bucket_name = "parky" # Hyperdrive [[env.dev.hyperdrive]] binding = "HYPERDRIVE" id = "a1b2c3d4e5f6..." # Queues [[env.dev.queues.producers]] binding = "STORE_SYNC_QUEUE" queue = "parky-store-sync" [[env.dev.queues.consumers]] queue = "parky-store-sync" max_batch_size = 10 max_batch_timeout = 30 max_retries = 3 dead_letter_queue = "parky-store-sync-dlq"

※ すべて行頭の # が削除されているか確認

3
デプロイ実行
cd api wrangler deploy --env dev

✅ 完了メッセージが表示されれば成功

4
ログ確認
wrangler tail --env dev

リアルタイムログが流れます。Ctrl+C で終了。

エラーメッセージがないか確認

5
API テスト

キャッシュミドルウェア テスト：

curl -i https://dev-api.parky.co.jp/v1/parking-lots?limit=1

レスポンスヘッダーに以下が含まれているか確認：

Cache-Control: public, max-age=300

ストア同期 Trigger テスト：

curl -X POST https://dev-api.parky.co.jp/v1/admin/store-sync/trigger \ -H "Authorization: Bearer [YOUR_JWT]" \ -H "Content-Type: application/json" \ -d '{"store": "all", "task": "all"}'

レスポンス例：

{ "sync_run_id": "uuid-here", "status": "queued" }
6
ダッシュボード監視

各 Cloudflare ダッシュボードでリアルタイム監視：

リソース ダッシュボード 確認ポイント
R2 Workers > R2 > parky Object count が増えているか
Hyperdrive Workers > Hyperdrive > parky-db Status が「Connected」か、Query count が増えているか
Queues Workers > Queues > parky-store-sync Message count が増えて処理されているか
Analytics Workers > parky-api-dev > Analytics Request count、Error rate をチェック
🎉 全設定完了！
R2、Hyperdrive、Queues の統合が完了しました。 これで Cloudflare 移行の dev 環境セットアップが完成です。

🔧トラブルシューティング

❌
R2 アップロード時に「InvalidAccessKeyId」エラー

原因： API キーが無効 or 期限切れ

対処：

  1. Cloudflare > R2 > parky > Settings > R2 API token
  2. 古いトークンがあれば削除
  3. 新しいトークンを作成（TTL = Unlimited）
  4. .env を更新
  5. wrangler deploy --env dev 再実行
❌
Hyperdrive 接続失敗「ETIMEDOUT」

原因： Postgres 接続不可 or 認証エラー

対処：

  1. Supabase > Project Settings > Database > Connection pooler
  2. Mode が「Transaction」か確認（重要）
  3. Host、User、Password を再度確認
  4. Cloudflare > Hyperdrive > parky-db > [Test connection]
  5. 接続テストが成功するまで修正
❌
Queues メッセージが処理されない

原因： Consumer が起動していない or コンシューマーコードにバグ

対処：

  1. wrangler logs --env dev でエラーを確認
  2. Cloudflare > Queues > parky-store-sync > Metrics
  3. 「Pending」メッセージ数をチェック（多い = 処理遅延）
  4. 「DLQ」に移動したメッセージがないか確認
  5. api/src/queue/store-sync.ts のエラーハンドリングを確認
❌
wrangler deploy 時に「binding not found」エラー

原因： wrangler.toml のバインディングがコメント状態のまま

対処：

  1. api/wrangler.toml を開く
  2. [[env.dev.r2_buckets]], [[env.dev.hyperdrive]], [[env.dev.queues.*]] の行頭 # を削除
  3. 保存して再度 wrangler deploy --env dev
❌
API が「502 Bad Gateway」を返す

原因： Worker コードエラー or 外部依存（DB など）がダウン

対処：

  1. wrangler tail --env dev でエラーメッセージを確認
  2. Supabase Status（https://status.supabase.com）を確認
  3. Cloudflare Status（https://www.cloudflarestatus.com）を確認
  4. コードにバグがないか確認（特に新しい実装）
  5. ローカル dev サーバーで wrangler dev --env dev テスト

Generated: 2026-04-18