mcpField
C
cloudflare-tunnel-setup

cloudflare-tunnel-setup

github.com/dawiddutoit云与 DevOps293 次安装40 周前更新
代码仓库

关于 cloudflare-tunnel-setup

用于从头配置 Cloudflare Tunnel 的交互式 Skill，面向需要为服务设置远程访问的运维人员。它涵盖前置检查、控制面板与令牌配置、容器重启、主机名设置及连通性验证。

主要功能

  1. 01检查配置前置条件
  2. 02指导在控制面板创建隧道
  3. 03在 .env 中配置令牌
  4. 04重启并检查 cloudflared
  5. 05设置公共主机名并验证访问

适用场景

  1. 01为全新安装创建隧道
  2. 02替换无效或过期的隧道令牌
  3. 03迁移基础设施后配置远程访问

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dawiddutoit/custom-claude --skill cloudflare-tunnel-setup

安装后在 Claude Code 中输入/cloudflare-tunnel-setup确认已加载。

附带文件examples/examples.mdreferences/reference.md

详细介绍

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. 安全保存令牌

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

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-holepiholepihole:80
Webhookwebhookwebhook:9000
Jaegerjaeger192.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"

预期结果： 出现 4 条 "Registered tunnel connection" 消息

步骤 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.mdDocker-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
  • 不要为内部服务后端使用 HTTPS URL
  • 不要在不同环境之间共享隧道令牌
  • 不要跳过验证步骤（3.6）
  • 隧道连接后不要忘记配置公共主机名
  • 不要在 .env 中留有占位令牌值

备注

  • 隧道令牌不会过期，但可以在控制面板中撤销
  • 每条隧道可以有多个连接器（用于冗余）
  • 隧道配置更改会自动生效（无需重启）
  • 使用 ./scripts/cf-tunnel-config.sh configure 通过 API 更新入口配置
  • 如需身份验证，请在隧道设置完成后使用 configure-google-oauth skill
  • 现有的 troubleshoot-tunnel-connectivity skill 可处理运行中隧道的问题

评论

支持 Markdown