cloudflare-tunnel-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare Tunnel Setup Skill

Cloudflare Tunnel 搭建技能

Interactive guide for setting up a new Cloudflare Tunnel from scratch.

交互式引导，从头搭建全新的Cloudflare Tunnel。

Quick Start

快速开始

Run this skill when you need to:

Create a new Cloudflare Tunnel
Replace an expired or invalid tunnel token
Set up remote access for a fresh installation

Minimum requirements: Cloudflare account, domain on Cloudflare, Docker installed.

在以下场景使用本技能：

创建新的Cloudflare Tunnel
替换过期或无效的隧道令牌
为全新安装配置远程访问

最低要求： Cloudflare账户、托管在Cloudflare的域名、已安装Docker。

When to Use This Skill
What This Skill Does
Instructions
- 3.1 Check Prerequisites
- 3.2 Create Tunnel in Dashboard
- 3.3 Configure Token in .env
- 3.4 Restart Cloudflared Container
- 3.5 Configure Public Hostnames
- 3.6 Verify Connectivity
Supporting Files
Expected Outcomes
Requirements
Red Flags to Avoid

何时使用本技能
本技能能做什么
操作步骤
- 3.1 检查前置条件
- 3.2 在控制台创建隧道
- 3.3 在.env中配置令牌
- 3.4 重启Cloudflared容器
- 3.5 配置公共主机名
- 3.6 验证连通性
支持文件
预期结果
要求
需要避免的风险

When to Use This Skill

何时使用本技能

Explicit Triggers:

"Setup cloudflare tunnel"
"Create a new tunnel"
"Configure remote access"
"Replace tunnel token"
"Tunnel from scratch"

Implicit Triggers:

Fresh installation of network infrastructure
Tunnel token expired or invalid
CLOUDFLARE_TUNNEL_TOKEN missing from .env
Moving infrastructure to new hardware

Debugging Triggers:

"Tunnel token not found"
"cloudflared container won't start"
"No CLOUDFLARE_TUNNEL_TOKEN in .env"

明确触发场景：

"Setup cloudflare tunnel"
"Create a new tunnel"
"Configure remote access"
"Replace tunnel token"
"Tunnel from scratch"

隐含触发场景：

网络基础设施全新安装
隧道令牌过期或无效
.env文件中缺少CLOUDFLARE_TUNNEL_TOKEN
将基础设施迁移到新硬件

调试触发场景：

"Tunnel token not found"
"cloudflared container won't start"
"No CLOUDFLARE_TUNNEL_TOKEN in .env"

What This Skill Does

本技能能做什么

Checks Prerequisites - Verifies .env exists and cloudflared is in docker-compose
Guides Tunnel Creation - Step-by-step instructions for Cloudflare dashboard
Configures Token - Adds tunnel token to .env file
Restarts Container - Restarts cloudflared to apply new token
Guides Hostname Setup - Instructions for configuring public hostnames
Verifies Connectivity - Confirms tunnel is connected and working

检查前置条件 - 验证.env文件是否存在，以及docker-compose中是否包含cloudflared服务
引导隧道创建 - 提供Cloudflare控制台的分步操作指南
配置令牌 - 将隧道令牌添加到.env文件
重启容器 - 重启cloudflared以应用新令牌
引导主机名配置 - 提供配置公共主机名的操作说明
验证连通性 - 确认隧道已连接并正常工作

Instructions

操作步骤

3.1 Check Prerequisites

3.1 检查前置条件

Step 1: Verify .env file exists

bash

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

If missing, create from example:

bash

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

Step 2: Check if CLOUDFLARE_TUNNEL_TOKEN exists

bash

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

Possible outcomes:

Line exists with value: Token already configured (check if valid)
Line exists but empty/placeholder: Needs real token
Line not found: Token needs to be added

Step 3: Verify docker-compose has cloudflared service

bash

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

If cloudflared service is missing, it needs to be added. See

references/reference.md

for service definition.

步骤1：验证.env文件是否存在

bash

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

如果文件缺失，从示例文件创建：

bash

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

步骤2：检查CLOUDFLARE_TUNNEL_TOKEN是否存在

bash

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

可能的结果：

存在带值的行：令牌已配置（需检查是否有效）
存在行但为空/占位符：需要替换为真实令牌
未找到该行：需要添加令牌

步骤3：验证docker-compose是否包含cloudflared服务

bash

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

如果缺少cloudflared服务，需要添加。请查看

references/reference.md

获取服务定义。

3.2 Create Tunnel in Dashboard

3.2 在控制台创建隧道

Provide these instructions to the user:

Go to: https://one.dash.cloudflare.com -> Access -> Tunnels
Click "Create a tunnel" -> Select "Cloudflared" connector
Name tunnel (e.g., "pi-home") -> Choose "Docker" as connector type
Copy the tunnel token (long base64 string after
```
--token
```
)
Save token securely

Token format: Base64-encoded JSON containing Account ID, Tunnel ID, and Secret.

向用户提供以下操作说明：

访问：https://one.dash.cloudflare.com -> Access -> Tunnels
点击“Create a tunnel” -> 选择“Cloudflared”连接器
为隧道命名（例如："pi-home"）-> 选择“Docker”作为连接器类型
复制隧道令牌（
```
--token
```
后的长base64字符串）
安全保存令牌

令牌格式： 包含账户ID、隧道ID和密钥的Base64编码JSON。

3.3 Configure Token in .env

3.3 在.env中配置令牌

Step 1: Check current token status

bash

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

Step 2: Add or update token

If line exists, update it. If not, add it.

bash

undefined

步骤1：检查当前令牌状态

bash

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

步骤2：添加或更新令牌

如果该行已存在，则更新；如果不存在，则添加。

bash

undefined

If line exists, use sed to replace

如果行已存在，使用sed替换

If not, append to file

如果不存在，追加到文件末尾

The token should look like:

令牌格式示例：

CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiYWJjZDEyMzQ...


Use the Edit tool to update `.env`:
- Look for existing `CLOUDFLARE_TUNNEL_TOKEN=` line
- Replace with new token value
- Or add new line if not present

**Validate token format:**

```bash


使用编辑工具更新`.env`：
- 查找现有的`CLOUDFLARE_TUNNEL_TOKEN=`行
- 替换为新令牌值
- 如果不存在则添加新行

**验证令牌格式：**

```bash

Token should be base64 decodable

令牌应可进行base64解码

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

undefined

undefined

3.4 Restart Cloudflared Container

3.4 重启Cloudflared容器

Step 1: Restart the container

bash

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

Or if container doesn't exist yet:

bash

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

Step 2: Check container is running

bash

docker ps | grep cloudflared

Expected output:

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

Step 3: Check logs for successful connection

bash

docker logs cloudflared --tail 30

Look for these success indicators:

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 registered connections = healthy tunnel (2 connections per Cloudflare edge location)

If errors appear:

```
token is invalid
```
: Token was copied incorrectly or expired
```
already registered
```
: Another instance using same token (stop other instances)
```
network error
```
: Check internet connectivity

步骤1：重启容器

bash

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

如果容器尚未创建：

bash

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

步骤2：检查容器是否运行

bash

docker ps | grep cloudflared

预期输出：

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

步骤3：检查日志确认连接成功

bash

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 Configure Public Hostnames

3.5 配置公共主机名

After tunnel is connected, configure services in Cloudflare dashboard:

Go to: https://one.dash.cloudflare.com -> Access -> Tunnels
Click tunnel name -> Configure -> Public Hostname -> Add
For each service, enter subdomain, domain (temet.ai), Type (HTTP), and URL

Example hostnames:

Service	Subdomain	URL
Pi-hole	pihole	pihole:80
Webhook	webhook	webhook:9000
Jaeger	jaeger	192.168.68.135:16686

URL patterns:

Docker container:
```
container:port
```
(e.g., pihole:80)
Host service:
```
host-ip:port
```
(e.g., 192.168.68.135:16686)
LAN device:
```
device-ip:port
```
(e.g., 192.168.68.105:80)

Important: Use HTTP (not HTTPS) for backends. Do NOT use

host.docker.internal

on Linux.

隧道连接成功后，在Cloudflare控制台配置服务：

访问：https://one.dash.cloudflare.com -> Access -> Tunnels
点击隧道名称 -> Configure -> Public Hostname -> Add
为每个服务输入子域名、域名（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 Verify Connectivity

3.6 验证连通性

Step 1: Verify tunnel is registered

bash

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

Expected: 4 "Registered tunnel connection" messages

Step 2: Check tunnel status in dashboard

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

Step 3: Test external access (from mobile data or external network)

bash

undefined

步骤1：验证隧道已注册

bash

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

预期结果： 4条“Registered tunnel connection”消息

步骤2：在控制台检查隧道状态

访问：https://one.dash.cloudflare.com
导航至：Access -> Tunnels
状态应显示：“HEALTHY”并带有绿色标识

步骤3：测试外部访问（使用移动数据或外部网络）

bash

undefined

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)

预期结果：HTTP 302（重定向到Cloudflare Access）或HTTP 200（无认证配置时）


**Step 4: Run diagnostic script (optional)**

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


**步骤4：运行诊断脚本（可选）**

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

Supporting Files

支持文件

File	Purpose
`references/reference.md`	Docker-compose service definition, token format details
`examples/examples.md`	Example configurations for common setups

文件	用途
`references/reference.md`	Docker-compose服务定义、令牌格式详情
`examples/examples.md`	常见配置示例

Expected Outcomes

预期结果

Success:

CLOUDFLARE_TUNNEL_TOKEN in .env
cloudflared container running
4 tunnel connections registered in logs
Tunnel shows "HEALTHY" in dashboard
Services accessible via *.temet.ai from external network

Partial Success:

Token configured but hostnames not set up (user reminder provided)
Tunnel connected but services return 502 (backend configuration issue)

Failure Indicators:

"token is invalid" in logs -> Re-copy token from dashboard
Container restart loop -> Check token format
0 registered connections -> Network/firewall issue

成功：

.env文件中存在CLOUDFLARE_TUNNEL_TOKEN
cloudflared容器正在运行
日志中显示4条隧道连接已注册
控制台中隧道状态显示“HEALTHY”
外部网络可通过*.temet.ai访问服务

部分成功：

令牌已配置但未设置主机名（会向用户发送提醒）
隧道已连接但服务返回502（后端配置问题）

失败标识：

日志中出现"token is invalid" -> 重新从控制台复制令牌
容器循环重启 -> 检查令牌格式
0条已注册连接 -> 网络/防火墙问题

Requirements

要求

Environment:

Cloudflare account with domain
Docker and Docker Compose installed
Internet connectivity
```
.env
```
file in project root

Accounts/Access:

Cloudflare dashboard access
Zero Trust enabled (free tier works)

Tools needed:

Read, Write, Edit (for .env configuration)
Bash (for docker commands and verification)
Grep (for checking existing configuration)

环境：

带有域名的Cloudflare账户
已安装Docker和Docker Compose
网络连通性
项目根目录下存在.env文件

账户/权限：

Cloudflare控制台访问权限
已启用Zero Trust（免费套餐可用）

所需工具：

读写编辑权限（用于.env配置）
Bash（用于docker命令和验证）
Grep（用于检查现有配置）

Red Flags to Avoid

需要避免的风险

Do not commit tunnel token to git (keep in .env only)
Do not use
```
host.docker.internal
```
on Linux hosts
Do not use HTTPS URLs for internal service backends
Do not share tunnel tokens between environments
Do not skip the verification step (3.6)
Do not forget to configure public hostnames after tunnel connects
Do not leave placeholder token values in .env

请勿将隧道令牌提交到git（仅保留在.env中）
Linux主机上请勿使用
```
host.docker.internal
```
内部服务后端请勿使用HTTPS URL
请勿在不同环境之间共享隧道令牌
请勿跳过验证步骤（3.6）
隧道连接后请勿忘记配置公共主机名
请勿在.env中保留占位符令牌值

Notes

注意事项

Tunnel tokens do not expire but can be revoked in dashboard
Each tunnel can have multiple connectors (for redundancy)
Tunnel configuration changes apply automatically (no restart needed)
Use
```
./scripts/cf-tunnel-config.sh configure
```
to update ingress via API
For authentication, use the
```
configure-google-oauth
```
skill after tunnel setup
The existing
```
troubleshoot-tunnel-connectivity
```
skill handles issues with running tunnels

隧道令牌不会过期，但可在控制台中撤销
每个隧道可配置多个连接器（实现冗余）
隧道配置变更会自动应用（无需重启）
使用
```
./scripts/cf-tunnel-config.sh configure
```
通过API更新入口规则
如需认证，在隧道搭建完成后使用
```
configure-google-oauth
```
技能
现有
```
troubleshoot-tunnel-connectivity
```
技能用于处理运行中隧道的问题

cloudflare-tunnel-setup

Original

Translation

Cloudflare Tunnel Setup Skill

Cloudflare Tunnel 搭建技能

Quick Start

快速开始

Table of Contents

目录

When to Use This Skill

何时使用本技能

What This Skill Does

本技能能做什么

Instructions

操作步骤

3.1 Check Prerequisites

3.1 检查前置条件

3.2 Create Tunnel in Dashboard

3.2 在控制台创建隧道

3.3 Configure Token in .env

3.3 在.env中配置令牌

If line exists, use sed to replace

如果行已存在，使用sed替换

If not, append to file

如果不存在，追加到文件末尾

The token should look like:

令牌格式示例：

CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiYWJjZDEyMzQ...

CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiYWJjZDEyMzQ...

Token should be base64 decodable

令牌应可进行base64解码

3.4 Restart Cloudflared Container

3.4 重启Cloudflared容器

3.5 Configure Public Hostnames

3.5 配置公共主机名

3.6 Verify Connectivity

3.6 验证连通性

From a device NOT on home network:

在非家庭网络的设备上执行：

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

预期结果：HTTP 302（重定向到Cloudflare Access）或HTTP 200（无认证配置时）

Supporting Files

支持文件

Expected Outcomes

预期结果

Requirements

要求

Red Flags to Avoid

需要避免的风险

Notes

注意事项