cloudflare-tunnel-setup

Cloudflare Tunnel のセットアップスキル

Cloudflare Tunnel を一から新規作成するための対話型ガイドです。

クイックスタート

次のことが必要な場合に、このスキルを実行します。

1. 新しい Cloudflare Tunnel を作成する
2. 期限切れまたは無効なトークンを置き換える
3. 新規インストールでリモートアクセスをセットアップする

最小要件： Cloudflare アカウント、Cloudflare に登録されたドメイン、Docker がインストールされていること。

目次

1. このスキルを使用する場面
2. このスキルの機能
3. 手順
   • 3.1 前提条件を確認する
   • 3.2 ダッシュボードでトンネルを作成する
   • 3.3 .env でトークンを設定する
   • 3.4 Cloudflared コンテナを再起動する
   • 3.5 パブリックホスト名を設定する
   • 3.6 接続を確認する
4. 関連ファイル
5. 期待される結果
6. 要件
7. 避けるべき危険な兆候

このスキルを使用する場面

明示的なトリガー：

• 「cloudflare tunnel をセットアップ」
• 「新しいトンネルを作成」
• 「リモートアクセスを設定」
• 「トンネルトークンを置き換え」
• 「トンネルを一から作成」

暗黙的なトリガー：

• ネットワークインフラストラクチャの新規インストール
• トンネルトークンの期限切れまたは無効化
• .env に CLOUDFLARE_TUNNEL_TOKEN がない
• インフラストラクチャを新しいハードウェアに移行

デバッグのトリガー：

• 「トンネルトークンが見つからない」
• 「cloudflared コンテナが起動しない」
• 「.env に CLOUDFLARE_TUNNEL_TOKEN がない」

このスキルの機能

1. 前提条件の確認 - .env が存在し、docker-compose に cloudflared があることを確認します
2. トンネル作成の案内 - Cloudflare ダッシュボードでの手順を順を追って説明します
3. トークンの設定 - トンネルトークンを .env ファイルに追加します
4. コンテナの再起動 - 新しいトークンを適用するため、cloudflared を再起動します
5. ホスト名設定の案内 - パブリックホスト名の設定手順を説明します
6. 接続の確認 - トンネルが接続され、機能していることを確認します

手順

3.1 前提条件を確認する

手順 1：.env ファイルが存在することを確認する

ls -la /home/dawiddutoit/projects/network/.env

存在しない場合は、サンプルから作成します。

cp /home/dawiddutoit/projects/network/.env.example /home/dawiddutoit/projects/network/.env

手順 2：CLOUDFLARE_TUNNEL_TOKEN が存在するか確認する

grep -E "^CLOUDFLARE_TUNNEL_TOKEN" /home/dawiddutoit/projects/network/.env

考えられる結果：

• 値を含む行が存在する：トークンは設定済みです（有効か確認してください）
• 行は存在するが空またはプレースホルダー：実際のトークンが必要です
• 行が見つからない：トークンを追加する必要があります

手順 3：docker-compose に cloudflared サービスがあることを確認する

grep -A 10 "cloudflared:" /home/dawiddutoit/projects/network/docker-compose.yml

cloudflared サービスがない場合は、追加する必要があります。サービス定義については references/reference.md を参照してください。

3.2 ダッシュボードでトンネルを作成する

以下の手順をユーザーに案内します。

1. https://one.dash.cloudflare.com -> Access -> Tunnels に移動します
2. 「Create a tunnel」をクリックし、「Cloudflared」コネクターを選択します
3. トンネルに名前を付け（例：「pi-home」）、「Docker」をコネクターの種類として選択します
4. トンネルトークンをコピーします（--token の後にある長い base64 文字列）
5. トークンを安全に保存します

トークンの形式： アカウント ID、トンネル ID、シークレットを含む Base64 エンコード済み JSON です。

3.3 .env でトークンを設定する

手順 1：現在のトークンの状態を確認する

grep "CLOUDFLARE_TUNNEL_TOKEN" /home/dawiddutoit/projects/network/.env

手順 2：トークンを追加または更新する

行が存在する場合は更新します。存在しない場合は追加します。

# If line exists, use sed to replace
# If not, append to file

# The token should look like:
# CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiYWJjZDEyMzQ...

Edit ツールを使用して .env を更新します。

• 既存の CLOUDFLARE_TUNNEL_TOKEN= 行を探します
• 新しいトークン値に置き換えます
• または、存在しない場合は新しい行を追加します

トークンの形式を検証する：

# Token should be base64 decodable
TUNNEL_TOKEN=$(grep "CLOUDFLARE_TUNNEL_TOKEN=" /home/dawiddutoit/projects/network/.env | cut -d'=' -f2)
echo "$TUNNEL_TOKEN" | base64 -d 2>/dev/null | python3 -c "import sys, json; d=json.load(sys.stdin); print('Valid token for account:', d.get('a', 'unknown'))"

3.4 Cloudflared コンテナを再起動する

手順 1：コンテナを再起動する

cd /home/dawiddutoit/projects/network && docker compose restart cloudflared

または、コンテナがまだ存在しない場合：

cd /home/dawiddutoit/projects/network && docker compose up -d cloudflared

手順 2：コンテナが実行中であることを確認する

docker ps | grep cloudflared

期待される出力：

CONTAINER ID   IMAGE                         STATUS         NAMES
abc123...      cloudflare/cloudflared:latest Up X seconds   cloudflared

手順 3：ログで接続の成功を確認する

docker logs cloudflared --tail 30

次の成功を示す情報を確認します：

INF Registered tunnel connection connIndex=0 location=...
INF Registered tunnel connection connIndex=1 location=...
INF Registered tunnel connection connIndex=2 location=...
INF Registered tunnel connection connIndex=3 location=...

登録済みの接続が 4 つあれば、トンネルは正常です（Cloudflare のエッジロケーションごとに接続が 2 つあります）。

エラーが表示された場合：

• token is invalid：トークンのコピーに誤りがあるか、期限切れです
• already registered：別のインスタンスが同じトークンを使用しています（他のインスタンスを停止してください）
• network error：インターネット接続を確認してください

3.5 パブリックホスト名を設定する

トンネルの接続後、Cloudflare ダッシュボードでサービスを設定します。

1. https://one.dash.cloudflare.com -> Access -> Tunnels に移動します
2. トンネル名をクリック -> Configure -> Public Hostname -> Add をクリックします
3. サービスごとに、サブドメイン、ドメイン（temet.ai）、タイプ（HTTP）、URL を入力します

ホスト名の例：

サービス	サブドメイン	URL
Pi-hole	pihole	pihole:80
Webhook	webhook	webhook:9000
Jaeger	jaeger	192.168.68.135:16686

URL のパターン：

• Docker コンテナ：container:port（例：pihole:80）
• ホストサービス：host-ip:port（例：192.168.68.135:16686）
• LAN デバイス：device-ip:port（例：192.168.68.105:80）

重要： バックエンドには HTTP（HTTPS ではなく）を使用してください。Linux では host.docker.internal を使用しないでください。

3.6 接続を確認する

ステップ 1：トンネルが登録されていることを確認する

docker logs cloudflared 2>&1 | grep -E "Registered tunnel|connIndex"

想定される結果： 「Registered tunnel connection」のメッセージが 4 件表示されます

ステップ 2：ダッシュボードでトンネルのステータスを確認する

Go to: https://one.dash.cloudflare.com
Navigate to: Access -> Tunnels
Status should show: "HEALTHY" with green indicator

ステップ 3：外部からのアクセスをテストする（モバイルデータ通信または外部ネットワークから）

# From a device NOT on home network:
curl -I https://pihole.temet.ai

# Expected: HTTP 302 (redirect to Cloudflare Access) or HTTP 200 (if no auth)

ステップ 4：診断スクリプトを実行する（任意）

./scripts/cf-tunnel-config.sh show

サポートファイル

ファイル	用途
references/reference.md	Docker-compose のサービス定義、トークン形式の詳細
examples/examples.md	一般的な構成の例

期待される結果

成功：

• .env に CLOUDFLARE_TUNNEL_TOKEN が設定されている
• cloudflared コンテナが実行中
• ログにトンネル接続が 4 件登録されている
• ダッシュボードでトンネルが「HEALTHY」と表示される
• 外部ネットワークから *.temet.ai 経由でサービスにアクセスできる

部分的な成功：

• トークンは設定済みだが、ホスト名が設定されていない（ユーザーへのリマインダーが表示されます）
• トンネルは接続済みだが、サービスが 502 を返す（バックエンドの設定に問題があります）

失敗の兆候：

• ログに「token is invalid」と表示される -> ダッシュボードからトークンをコピーし直します
• コンテナが再起動を繰り返す -> トークンの形式を確認します
• 登録された接続が 0 件 -> ネットワークまたはファイアウォールの問題です

要件

環境：

• ドメインを持つ Cloudflare アカウント
• Docker と Docker Compose がインストールされていること
• インターネット接続
• プロジェクトルートに .env ファイルがあること

アカウント／アクセス：

• Cloudflare ダッシュボードへのアクセス
• Zero Trust が有効であること（無料プランで利用できます）

必要なツール：

• Read、Write、Edit（.env の設定用）
• Bash（Docker コマンドと確認用）
• Grep（既存の設定の確認用）

避けるべき注意事項

• トンネルトークンを Git にコミットしないでください（.env のみに保存します）
• Linux ホストでは host.docker.internal を使用しないでください
• 内部サービスのバックエンド URL に HTTPS を使用しないでください
• 環境間でトンネルトークンを共有しないでください
• 確認手順（3.6）を省略しないでください
• トンネル接続後にパブリックホスト名を設定するのを忘れないでください
• .env にプレースホルダーのトークン値を残さないでください

注記

• トンネルトークンに有効期限はありませんが、ダッシュボードで取り消すことができます
• 各トンネルには複数のコネクターを設定できます（冗長化のため）
• トンネルの設定変更は自動的に適用されます（再起動は不要です）
• ./scripts/cf-tunnel-config.sh configure を使用すると、API 経由でイングレスを更新できます
• 認証には、トンネル設定後に configure-google-oauth スキルを使用してください
• 既存の troubleshoot-tunnel-connectivity スキルは、実行中のトンネルに関する問題に対処します