cloudflare-troubleshooting

Cloudflare のトラブルシューティング

方法論の基盤： 一般的な、証拠に基づくネットワーク診断の手法（反証、レイヤーごとの切り分け、相互レビュー）は debugging-network-issues スキルで扱います。このスキルは、その上に重ねる Cloudflare のドメイン固有のレイヤーです。

基本原則

思い込みではなく、証拠に基づいて調査します。 問題を診断する前に、必ず Cloudflare API を照会して実際の設定を確認してください。このスキルの価値は、あらかじめ決められた解決策ではなく、体系的な調査方法にあります。

調査方法

1. 認証情報を取得する

ユーザーまたはプロジェクトの設定からすでに提供されているドメインと、認証済みの Cloudflare 接続を再利用します。不足している接続情報（ドメイン、アカウントのメールアドレスと Global API Key、または API Token）だけを尋ねます。現在使用中の認証方法を維持してください。トラブルシューティングのために置き換える必要はありません。

Global API Key の場所：Cloudflare Dashboard → My Profile → API Tokens → View Global API Key

2. ゾーン情報を取得する

ゾーン単位のトラブルシューティングでは、ゾーン ID を取得します。

curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=<domain>" \
  -H "X-Auth-Email: <email>" \
  -H "X-Auth-Key: <api_key>" | jq '.'

id を抽出する前に、完全に一致するゾーンとアカウントを選択してください。アカウントやドメインの識別情報が曖昧な場合、最初の結果を無条件に選択してはいけません。アカウント単位の呼び出しには、そのゾーンの account.id を使用します。

一度も割り当てられたことのない Pages ホスト名では、完全一致するゾーンが空でも、それは調査結果であり、アカウント ID でもサイトが存在しない証拠でもありません。認証済みの設定から既存のアカウント／プロジェクトを特定し、Pages のカスタムドメインと DNSSEC の移行に従ってください。この検索を成功させるためだけにゾーンを作成してはいけません。

3. 体系的に調査する

問題ごとに、結論を出す前に証拠を集めます。Cloudflare API を使用して、次の項目を確認します。

• 現在の設定状態
• 最近の変更（監査ログを利用できる場合）
• 関連する可能性のある設定

よくある調査パターン

リダイレクトループ（ERR_TOO_MANY_REDIRECTS）

証拠収集の手順：

1. SSL/TLS モードを確認します：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/ssl" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

   確認する項目：result.value - 現在の SSL モードを示します

2. Always Use HTTPS の設定を確認します：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/always_use_https" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

3. リダイレクトを行う Page Rules を確認します：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/pagerules" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

   確認する項目：forwarding_url または always_use_https のアクション

4. 可能であれば、オリジンサーバーに直接接続してテストします：

   curl -I -H "Host: <domain>" https://<origin_ip>
   

診断の考え方：

• SSL モードが「flexible」で、オリジンが HTTPS を強制している場合は、リダイレクトループが発生します
• 複数のリダイレクトルールが競合することがあります
• ブラウザーと curl の挙動の違いを確認します

修正：

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/ssl" \
  -H "X-Auth-Email: email" \
  -H "X-Auth-Key: key" \
  -H "Content-Type: application/json" \
  --data '{"value":"full"}'

修正後も古い HTTP リダイレクトが残っている場合は、該当する HTTP キャッシュをパージします。

curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache" \
  -H "X-Auth-Email: email" \
  -H "X-Auth-Key: key" \
  -d '{"purge_everything":true}'

メールルーティングと転送

エイリアスへの配信、宛先の検証、キャッチオールの動作、または転送用 MX の問題については、メールルーティングに従ってください。アカウント／ゾーンの API 読み取り手順を示し、保存済みの設定と実際の受信トレイへの到着を区別します。

DNS の問題

pages.dev サイトは動作しているのにカスタムホスト名に到達できない場合、Pages のバインドがない場合、またはネームサーバー／DNSSEC を移行する場合は、DNS を変更する前にPages のカスタムドメインと DNSSEC の移行を読み込んでください。レジストラーの識別情報、親ゾーンでの公開、再帰キャッシュ、通常のホスト名の受け入れを区別します。

証拠収集：

1. DNS レコードを一覧表示します：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

2. 外部からの DNS 解決を確認します：

   dig <domain>
   dig @8.8.8.8 <domain>
   

3. DNSSEC の状態を確認します：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dnssec" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

確認する項目：

• A／AAAA／CNAME レコードの欠落
• プロキシの状態が正しくない（プロキシ経由か DNS のみか）
• TTL 値
• 競合するレコード

SSL 証明書エラー

証拠の収集：

1. SSL 証明書の状態を確認します：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/ssl/certificate_packs" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

2. オリジン証明書を確認します（Full Strict を使用している場合）：

   openssl s_client -connect <origin_ip>:443 -servername <domain>
   

3. SSL 設定を確認します：

   • 最小 TLS バージョン
   • TLS 1.3 の状態
   • Opportunistic Encryption

よくある問題：

• Error 526：SSL モードが「strict」に設定されていますが、オリジン証明書が無効です
• Error 525：オリジンで SSL ハンドシェイクに失敗しました
• プロビジョニングの遅延：選択した製品の証明書／ドメイン検証の状態を調べ、残っている前提条件または保留中の状態を報告します

オリジンサーバーのエラー（502/503/504）

証拠の収集：

1. オリジンに到達できるか確認します：

   curl -I -H "Host: <domain>" https://<origin_ip>
   

2. DNS レコードが正しいオリジンを指しているか確認します：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

3. 該当する場合は、ロードバランサーの設定を確認します：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/load_balancers" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

4. ファイアウォールルールを確認します：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/firewall/rules" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

新しい API の学習

上記で扱っていない問題が発生した場合は、Cloudflare API のドキュメントを参照してください：

1. API リファレンスを参照します： https://developers.cloudflare.com/api/
2. 問題のキーワードを使って関連するエンドポイントを検索します
3. 利用可能な操作を理解するために、API スキーマを確認します
4. データ構造を把握するため、まずGET リクエストでテストします
5. アプローチを確認してから、PATCH/POST で変更を加えます

新しい API を調べる際のパターン：

# List available settings for a zone
curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings" \
  -H "X-Auth-Email: email" \
  -H "X-Auth-Key: key"

API リファレンスの概要

references/api_overview.md を参照してください：

• カテゴリ別に整理された一般的なエンドポイント
• リクエスト／レスポンスのスキーマ
• 認証のパターン
• レート制限とエラー処理

references/ssl_modes.md を参照してください：

• SSL/TLS モードの詳細な説明
• プラットフォームとの互換性
• セキュリティへの影響

references/common_issues.md を参照してください：

• 問題のパターンと症状
• 調査チェックリスト
• プラットフォーム固有の注意事項

ベストプラクティス

証拠に基づく調査

1. 推測する前に照会します — API を使って実際の状態を確認します
2. 複数のデータポイントを収集します — 設定を相互に照合します
3. 関連する設定を確認します — 設定同士が影響し合うことはよくあります
4. 外部から検証します — dig/curl を使って確認します
5. 段階的にテストします — 一度に変更するのは 1 つだけです

API の使用

1. JSON レスポンスを解析します — 読みやすくするために jq または python を使います
2. 成功フィールドを確認します — レスポンス内の "success": true/false を確認します
3. エラーを適切に処理します — レスポンス内の errors 配列を読みます
4. レート制限を守ります — Cloudflare API には制限があります
5. 適切なメソッドを使います：
   • GET：情報を取得します
   • PATCH：設定を更新します
   • POST：リソースを作成する／アクションを実行します
   • DELETE：リソースを削除します

変更の適用

1. まず証拠を収集します — 現在の状態を把握します
2. 根本原因を特定します — 推測しないでください
3. 対象を絞って修正します — 必要な箇所だけ変更します
4. 関連がある場合に限り、HTTP キャッシュをパージします — CDN のパージでは、レジストラの変更は公開されず、再帰 DNS キャッシュもクリアされません
5. 修正を検証します — API を再照会して確認します
6. 待機中の段階と次に確認する内容を報告します： 現在の有効化状態、レジストリの公開ポリシー、観測された TTL を使います。レジストラでの保存、親ゾーンへの公開、クライアント側での復旧は、異なるタイミングで発生することがあります。証拠なしに固定の待機時間やブラウザーキャッシュのクリアを指示しないでください。

セキュリティ

• 出力に API キーを記録しないでください
• ユーザーが公開の場で認証情報を共有した場合は警告してください
• Global API Key よりも、権限を限定した API Token を推奨してください
• 調査には読み取り専用の操作を使用してください

ワークフローテンプレート

1. Reuse the configured domain and authorized API connection; obtain only missing values
2. Get zone_id via zones API
3. Investigate:
   - Query relevant APIs for evidence
   - Check multiple related settings
   - Verify with external tools (dig, curl)
4. Analyze evidence to determine root cause
5. Apply fix via appropriate API endpoint
6. Purge HTTP cache only if stale HTTP content is implicated
7. Verify fix via API query and normal-hostname external testing; provider or forced-IP success alone is partial
8. Inform user of resolution and any required actions

例：一連の調査

ユーザーから「サイトで ERR_TOO_MANY_REDIRECTS が表示される」と報告された場合：

# 1. Get zone ID
curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com" \
  -H "X-Auth-Email: [email protected]" \
  -H "X-Auth-Key: abc123" | jq '.result[] | select(.name == "example.com") | {id, account}'

# Select the intended account from the exact-domain result before using its id.
# 2. Check SSL mode (primary suspect for redirect loops)
curl -s -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl" \
  -H "X-Auth-Email: [email protected]" \
  -H "X-Auth-Key: abc123" | jq '.result.value'

# If returns "flexible" and origin is GitHub Pages/Netlify/Vercel:

# 3. Fix by changing to "full"
curl -X PATCH "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl" \
  -H "X-Auth-Email: [email protected]" \
  -H "X-Auth-Key: abc123" \
  -H "Content-Type: application/json" \
  --data '{"value":"full"}'

# 4. Only if stale HTTP redirects remain, purge HTTP cache
curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "X-Auth-Email: [email protected]" \
  -H "X-Auth-Key: abc123" \
  -d '{"purge_everything":true}'

# 5. Recheck the ordinary hostname and browser; report observed recovery or the unresolved layer

スクリプトが役立つ場面

同梱のスクリプト（scripts/check_cloudflare_config.py、scripts/fix_ssl_mode.py）は、次の用途に使用できます。

• 調査パターンのリファレンス実装
• Python を利用できる場合の簡易診断ツール
• プログラムから API を使用する例

ただし、柔軟性と透明性を確保するため、Bash/curl による API の直接呼び出しを優先してください。スクリプトによって機能が制限されることがあってはなりません。便利な場合はスクリプトを使用しつつ、次のような場合には生の API 呼び出しを使用してください。

• 不慣れなシナリオ
• エッジケース
• 学習やデバッグ
• スクリプトで対応していない操作

重要なのは調査手法と API に関する知識であり、スクリプトではありません。