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

基本原則

仮定ではなく証拠で調査する。 問題を診断する前に、常にCloudflare APIをクエリして実際の設定を確認します。このスキルの価値は、事前に決められたソリューションではなく、体系的な調査方法論にあります。

調査方法論

1. 認証情報を収集

ユーザーに以下をリクエスト:

• ドメイン名
• Cloudflareアカウントメールアドレス
• Cloudflare Global API Key (またはAPI Token)

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

2. ゾーン情報を取得

Cloudflareのトラブルシューティングの最初のステップ - ゾーン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 '.'

後続のAPI呼び出しのため、result[0].idからzone_idを抽出します。

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. リダイレクトのページルールを確認:

   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"}'

修正後キャッシュをパージ:

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}'

DNS問題

証拠収集:

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 onlyか)
• 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

一般的な問題:

• エラー 526: SSLモードが「strict」だがオリジンサーティフィケートが無効
• エラー 525: オリジンでのSSLハンドシェイク失敗
• プロビジョニング遅延: Universal SSLの場合、15～30分待機

オリジンサーバーエラー (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を探索するためのパターン:

# ゾーンで利用可能な設定をリスト
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フィールドを確認 - レスポンスの"success": true/false
3. エラーを適切に処理 - レスポンスのerrors配列を読む
4. レート制限を尊重 - Cloudflare APIには制限あり
5. 適切なメソッドを使用:
   • GET: 情報を取得
   • PATCH: 設定を更新
   • POST: リソースを作成 / アクションをトリガー
   • DELETE: リソースを削除

変更を加える

1. 最初に証拠を集める - 現在の状態を理解
2. 根本原因を特定 - 推測しない
3. 対象を絞った修正を適用 - 必要な部分のみ変更
4. 必要に応じてキャッシュをパージ - 特にSSL/リダイレクト変更の場合
5. 修正を検証 - APIをリクエリして確認
6. 待機時間をユーザーに通知:
   • エッジサーバー伝播: 30～60秒
   • DNS伝播: 最大48時間
   • ブラウザキャッシュ: 手動クリアが必要

セキュリティ

• APIキーを出力にログしない
• ユーザーが公開コンテキストで認証情報を共有する場合は警告
• Global API Keyより、スコープ付きの権限を持つAPI Tokensを推奨
• 調査には読み取り専用操作を使用

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

1. 集める: ドメイン、メール、APIキー
2. zones APIを経由してzone_idを取得
3. 調査:
   - 証拠のため関連APIをクエリ
   - 複数の関連設定を確認
   - 外部ツール (dig、curl) で検証
4. 証拠を分析して根本原因を判定
5. 適切なAPIエンドポイント経由で修正を適用
6. 設定変更がデリバリーに影響する場合はキャッシュをパージ
7. APIクエリと外部テストで修正を検証
8. ユーザーに解決と必要なアクションを通知

例: 完全な調査

ユーザーが「サイトに ERR_TOO_MANY_REDIRECTS が表示される」と報告した場合:

# 1. ゾーンIDを取得
curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com" \
  -H "X-Auth-Email: user@example.com" \
  -H "X-Auth-Key: abc123" | jq '.result[0].id'

# 2. SSLモードを確認 (リダイレクトループの主な原因)
curl -s -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl" \
  -H "X-Auth-Email: user@example.com" \
  -H "X-Auth-Key: abc123" | jq '.result.value'

# 「flexible」が返され、オリジンがGitHub Pages/Netlify/Vercelの場合:

# 3. 「full」に変更して修正
curl -X PATCH "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl" \
  -H "X-Auth-Email: user@example.com" \
  -H "X-Auth-Key: abc123" \
  -H "Content-Type: application/json" \
  --data '{"value":"full"}'

# 4. キャッシュをパージ
curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "X-Auth-Email: user@example.com" \
  -H "X-Auth-Key: abc123" \
  -d '{"purge_everything":true}'

# 5. ユーザーに通知: 60秒待機、ブラウザキャッシュをクリア、再試行

スクリプトが有用な場合

バンドルされたスクリプト (scripts/check_cloudflare_config.py、scripts/fix_ssl_mode.py) は以下として機能:

• 調査パターンの参考実装
• Pythonが利用可能な場合の迅速な診断ツール
• プログラムによるAPI使用法の例

ただし、柔軟性と透明性のため、Bash/curl経由での直接API呼び出しを優先してください。スクリプトは機能を制限しないべき - 便利な場合は使用しますが、以下が必要な場合は生APIコールを使用:

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

調査方法論とAPI知識がコアスキルであり、スクリプトではありません。