版数: 1.1  |  更新日: 2026-06-09  |  対象: Phase 1-4（Named Tunnel + DNS 移管）

Phase 1-4 ナレッジ

関連資料 基本・詳細設計書（Phase 1-4）  |  DNS 移管手順書  |  システム通信経路一覧と図解  |  開発ログ

Phase 1-4（Named Tunnel + DNS 移管）を進める過程で発生した疑問・エラー・判断を、後から読んでも再現できるよう丁寧に残した資料です。

開発ログは「いつ・何を実行したか」の時系列。本ページは「なぜそうなったか」「どう調べて・何を直して解消したか」を中心に記述します。

この資料の読み方

見出し意味
きっかけ質問が生まれた背景、またはエラーに気づいた状況
経緯試したこと・判明したこと・次に何をしたか（解決までの流れ）
結論最終的な理解・正しい操作・再発防止
Tips現場のインフラ担当が伝えそうな助言（第3者視点）

目次

ID テーマ 種別
K-01 Named Tunnel と Quick Tunnel の違い 設計理解
K-02 --token と --url の競合によるタイムアウト エラー解消
K-03 ドメイン管理の5層モデル（所有権 vs DNS 管理） 設計理解
K-04 「ドメイン移管」と「DNS 管理移行」の違い 設計理解
K-05 DNS 移行前のリスク評価（Google Workspace への影響） 運用
K-06 Public Hostname 設定が必要な理由 設計理解
K-07 修正後のデータ転送フロー全体像 まとめ

K-01   Named Tunnel と Quick Tunnel の違い

きっかけ

Phase 1-2 では Quick Tunnel（--url）で外部公開できた。Phase 1-4 で Named Tunnel（--token）に切り替えた理由が分からなかった。

経緯

Quick Tunnel はコンテナ再起動のたびに URL が変わる仕様（例: occur-thompson-theorem-bracket.trycloudflare.com）。継続的なテストや本番運用には URL が固定されている Named Tunnel が必要と判明。Named Tunnel は Cloudflare ダッシュボードで事前に作成し、トークンで認証する方式。

結論

Quick Tunnel: URL が毎回変わる。PoC 初期の「繋がるか確認する」用途に最適。設定不要で即使える。
Named Tunnel: URL 固定。本番用ドメインへの紐付け・継続テストに必須。事前にダッシュボードでトンネル作成が必要。

Tips

「Quick Tunnel は開発者の動作確認ツール。本番に使うものではない。Named Tunnel を使うなら、ダッシュボードでの設定が必ず必要になる。この2つを混同すると後でハマる。」

K-02   --token と --url の競合によるタイムアウト

きっかけ

https://api.your-domain.com/ping にアクセスすると ERR_CONNECTION_TIMED_OUT が発生。DNS 解決（CNAME）は正常で、Tunnel 接続も確立されているのにリクエストが届かない。

原因

docker-compose.yml の cloudflared 起動コマンドに --token（Named Tunnel 用）と --url（Quick Tunnel 用）を同時に指定していた。Named Tunnel では転送先は Cloudflare ダッシュボードの「Public Hostname」設定で決まるため、--url は無視される。結果として転送先が未定義のままタイムアウトとなった。

# 誤った設定例
command: tunnel --no-autoupdate run --token <TOKEN> --url http://api:8000
結論

--url を削除し、転送先は Cloudflare ダッシュボードの Public Hostname 設定で行う。

# 正しい設定例
command: tunnel --no-autoupdate run --token <TOKEN>
Tips

「Named Tunnel の --token を使う場合、ingress（転送先）の設定はダッシュボード側で完結している。--url を追加しても効かないどころか、混乱の元になる。コマンドはシンプルに保つのが鉄則。」

K-03   ドメイン管理の5層モデル（所有権 vs DNS 管理）

きっかけ

Cloudflare ダッシュボードで Public Hostname を設定しようとしたが、ドメイン（your-domain.com）が選択肢に出てこなかった。Cloudflare アカウントは持っているのに、なぜ使えないのか分からなかった。

経緯

調査の結果、Named Tunnel の Public Hostname 機能は「対象ドメインが Cloudflare の DNS ゾーンで管理されている」場合のみ利用可能と判明。当時はドメインの所有権も DNS 管理も Squarespace（実体は Google Cloud DNS）にあったため、Cloudflare からは「管理外のドメイン」として扱われていた。

結論

ドメインには「所有権（レジストラ）」と「DNS 管理（ネームサーバー）」の2つの概念がある。Cloudflare の機能を使うには DNS 管理を Cloudflare に移す必要がある。

Layer 5: アプリケーション層  ← ブラウザが URL を入力する
Layer 4: DNS 解決層         ← 名前を IP アドレスに変換する
Layer 3: DNS 管理層         ← DNSレコードを誰が管理するか（ネームサーバー）★今回の問題
Layer 2: ドメイン登録層     ← ドメイン名の所有権を誰が持つか（レジストラ）
Layer 1: ルート DNS 層      ← .com / .jp 等を管理するインターネットの根幹
Tips

「ドメインを『買った』だけでは Cloudflare の機能は使えない。DNS を Cloudflare に向ける（NS レコードを変更する）ことが必須。この区別を知らないと、設定画面でドメインが出てこない理由が永遠に分からない。」

K-04   「ドメイン移管」と「DNS 管理移行」の違い

きっかけ

「DNS を Cloudflare に移す」と調べると「ドメイン移管」という言葉が出てきた。移管は複雑でリスクがあると聞き、本当にやる必要があるのか不安になった。

経緯

調査の結果、今回必要なのは「ドメイン移管（Transfer）」ではなく「DNS 管理移行（Connect a domain）」と判明。前者はレジストラ（所有権）ごと変更する大がかりな手続きだが、後者はネームサーバー（NS）レコードを変更するだけで完了する。

結論

ドメイン移管（Transfer）: 所有権ごと別レジストラへ。手続きが複雑・リスクあり。今回は不要。
DNS 管理移行（Connect a domain）: 所有権はそのまま、DNS 管理のみ Cloudflare へ委譲。NS レコードを変更するだけ。今回はこちらを採用。

Tips

「ドメイン移管と DNS 移行は全く別物。混同している人は多い。NS レコードを変えるだけなら30分以内に終わる作業。ただし既存の DNS レコード（MX・TXT 等）を事前に書き写しておかないと、メールが止まる事故になる。」

K-05   DNS 移行前のリスク評価（Google Workspace への影響）

きっかけ

DNS 管理を Cloudflare に移行する際、既存のメール設定（Google Workspace）に影響が出ないか心配だった。

経緯

移行前に PowerShell で現在の DNS レコードを確認した。

# MX レコード（メール受信）
Resolve-DnsName -Name "your-domain.com" -Type MX

# TXT レコード（SPF/DKIM 等）
Resolve-DnsName -Name "your-domain.com" -Type TXT

# A レコード（ウェブサイト）
Resolve-DnsName -Name "your-domain.com" -Type A

確認の結果、MX レコードが存在せず、SPF レコードも -all（全拒否）だったため、メールシステムへの影響はないと判断。

結論

DNS 移行前に必ず MX・TXT（SPF/DKIM/DMARC）・A レコードを確認する。今回は影響なしと判断し安全に移行を実施。Cloudflare 側でも既存レコードを手動で再登録することで継続性を担保する。

Tips

「DNS 移行で一番怖いのはメールが止まること。MX レコードと SPF/DKIM を移行先に正しく設定できているか、移行後 24〜48 時間は監視するのが基本。今回はそもそもメール設定がなかったので問題なかったが、本番環境では必ずチェックリストを作って臨むこと。」

K-06   Public Hostname 設定が必要な理由

きっかけ

Named Tunnel を作成してトークンを取得したのに、api.your-domain.com にアクセスしてもタイムアウトになった。Tunnel は動いているのに、なぜリクエストが届かないのか分からなかった。

経緯

Cloudflare ダッシュボードの Tunnel 設定を確認すると、「Public Hostname」タブに何も設定されていなかった。Named Tunnel は「どのホスト名のリクエストをどのローカルサービスに転送するか」をダッシュボードで明示的に設定する必要がある。

結論

Named Tunnel を使う場合、以下の2つがセットで必要：

  1. Cloudflare ダッシュボード → Zero Trust → Networks → Tunnels → 対象 Tunnel → Public Hostname タブ → ホスト名（api.your-domain.com）と転送先（http://api:8000）を設定
  2. docker-compose.yml の cloudflared コマンドから --url を削除し --token のみにする
Tips

「Named Tunnel は『トンネルを掘る』部分と『どこに繋ぐか』の設定が分離している。トークンはトンネルを確立するだけ。どのドメインのリクエストをどのサービスに流すかは、ダッシュボードの Public Hostname で設定する。この2段階を理解しないと永遠にハマる。」

K-07   修正後のデータ転送フロー全体像

きっかけ

全ての設定が完了した後、リクエストがどのように流れているのか全体像を整理したかった。

結論（修正後の正しいフロー） 
【ユーザー（ブラウザ / curl）】
    │  https://api.your-domain.com/ping にアクセス
    ▼
【Cloudflare DNS（Layer 3）】
    │  api.your-domain.com → Cloudflare エッジ IP に解決
    ▼
【Cloudflare エッジサーバー】
    │  Public Hostname 設定に基づき your-tunnel-name にルーティング
    ▼
【cloudflared コンテナ（Raspberry Pi 上）】
    │  トンネル経由でリクエストを受信
    │  http://api:8000 へ転送（Docker 内部ネットワーク）
    ▼
【FastAPI コンテナ（api:8000）】
    │  {"message":"pong"} を生成して返却
    ▼
【ユーザー】  ← レスポンス受信
Tips

「このフローを頭に入れておくと、どこで詰まっているかを素早く特定できる。DNS 解決の問題か、Tunnel 接続の問題か、Public Hostname 設定の問題か、FastAPI コンテナの問題か——それぞれ確認ポイントが違う。フローを書き出すことが障害対応の第一歩。」