企业官网建设流程全解析

• 网络
• 通信
• 后端
• CLI

Cloudflare Tunnel client（即cloudflared）是 Cloudflare Tunnel 的命令行客户端，一个常驻进程（daemon），负责在 Cloudflare 网络与你的源站（origin，例如本地 Web 服务器）之间建立出站连接并代理流量。本文围绕仓库根目录的 README.md 展开，结合 cmd/cloudflared/main.go、cmd/cloudflared/tunnel、cmd/cloudflared/access、Makefile、Dockerfile 等源码，系统讲解安装、Tunnel 创建与流量路由、TryCloudflare 快速隧道、版本兼容策略，以及从源码构建与开发测试的完整流程。读完本文，你将能独立完成 cloudflared 的部署、命名隧道的创建与运行、DNS/负载均衡/私有网络路由的配置，以及使用cloudflared access在 Layer 4（SSH、RDP 等）场景下访问受保护源站。

1. cloudflared 是什么：一个不出站的隧道代理

cloudflared是一个隧道守护进程，它代理从 Cloudflare 网络到源站的流量。该 daemon 位于 Cloudflare 网络和你的源站（如 Web 服务器）之间：Cloudflare 吸引客户端请求，并通过这个 daemon 将请求发送给你，无需在防火墙（firewall）上开放任何入站端口——你的源站可以保持尽可能封闭的状态。这正是 Cloudflare Tunnel 的核心价值：即使没有公网 IP、没有端口转发，只要源站能发起出站连接，就能对外提供服务。

从 cmd/cloudflared/main.go 的main()可以看出，CLI 程序本身基于urfave/cli/v2构建，app.Usage定义为 "Cloudflare's command-line tool and agent"，并注册了update、version、tunnel、access、tail、management等命令族。所有与"代理到源站"相关的用法都通过cloudflared tunnel help暴露。

除了 HTTP/WebSocket 反向代理，cloudflared还可以用于访问由cloudflared tunnel保护的源站上的 TCP 流量（Layer 4，即非 HTTP/WebSocket），典型场景包括 SSH、RDP 等。这类用法集中在cloudflared access help下。此外，你还可以使用 WARP 客户端（Cloudflare WARP client）在客户端一侧访问 Tunnel 背后的私有源站 Layer 4 流量，而无需在客户端运行cloudflared access命令。

2. 开始之前：Cloudflare 账户的准备工作

在使用 Cloudflare Tunnel 之前，需要在 Cloudflare 控制台完成几个前置步骤——为你的 Cloudflare 账户添加一个网站（website）。README 特别说明：如今即使没有网站也可以使用 Tunnel（例如用于私有路由），但由于历史原因，该前置要求仍然存在：

1. 向 Cloudflare 添加网站（Add a website to Cloudflare）；
2. 将域名 nameserver 改为 Cloudflare 托管（Change your domain nameservers to Cloudflare）。

这两步是 DNS 记录由 Cloudflare 权威托管的前提，后续cloudflared tunnel route dns创建 CNAME 记录时依赖该托管关系。完成后再进入安装与认证环节。

3. 安装 cloudflared：二进制、Docker、系统包与源码构建

README 列出的安装渠道包括：独立二进制（standalone binaries）、Docker 镜像、Debian / RPM 包、Homebrew 包。发布版本可在 cloudflared 的 GitHub Releases 页面获取。具体渠道：

3.1 Docker 镜像的默认行为

仓库内的 Dockerfile 展示了镜像的构建与运行方式：多阶段构建（builder 阶段用golang:1.26.8，运行阶段使用 distroless base，以非 root 用户65532:65532运行），ENTRYPOINT ["cloudflared", "--no-autoupdate"]，CMD ["version"]。这意味着容器内默认关闭自动更新（因为容器镜像的更新由镜像自身管理），并以version命令作为默认启动命令。构建时还设置了CONTAINER_BUILD=1环境变量，用于让 metrics 服务按虚拟化环境方式绑定地址（见 Makefile 中-X ...metrics.Runtime=virtual的注入逻辑）。

3.2 从源码构建

源码构建非常简单，在满足依赖后直接运行：

make cloudflared

Makefile 中cloudflared目标的核心命令是：

GOOS=$(TARGET_OS) GOARCH=$(TARGET_ARCH) $(ARM_COMMAND) go build -mod=readonly $(GO_BUILD_TAGS) $(LDFLAGS) $(IMPORT_PATH)/cmd/cloudflared

其中TARGET_OS/TARGET_ARCH会自动从本机go env GOOS与uname -m推导（支持 linux/darwin/windows/freebsd/openbsd，以及 amd64/arm64/arm/s390x 等架构，见 Makefile）；LDFLAGS注入Version、BuildTime等构建信息。另外，make cloudflared-deb、cloudflared-rpm、cloudflared-msi可分别构建 Debian、RPM 与 Windows MSI 安装包。

4. 创建 Tunnel 并路由流量：登录、创建、路由、运行

安装完成后，你需要先认证cloudflared到 Cloudflare 账户，然后开始创建 Tunnel 来向源站提供流量。核心流程如下（与 cmd.go 中命令文档一致）：

$ cloudflared tunnel login # 获取证书 cert.pem $ cloudflared tunnel create my-first-tunnel # 创建命名隧道 $ cloudflared tunnel route dns my-first-tunnel my-first-tunnel.mydomain.com # 路由 DNS $ cloudflared tunnel run my-first-tunnel # 运行隧道

4.1 登录认证（login）

cloudflared tunnel login会引导完成浏览器 OAuth 流程，并将生成的cert.pem保存到本地（默认路径由credentials.FindDefaultOriginCertPath()解析，默认目录为~/.cloudflared/，参见 config/configuration.go 中defaultUserConfigDirs的定义）。这个证书用于管理（创建/路由/删除）属于你账户的隧道。

4.2 创建命名隧道（create）

cloudflared tunnel create my-tunnel

create子命令的实现在 subcommands.go：它要求恰好一个参数（隧道名），并支持--credentials-file（凭据文件路径）、--secret（Base64 编码的隧道密钥，解码后至少 32 字节，不指定则自动生成随机 32 字节密钥，见 generateTunnelSecret）与--output（json/yaml 输出）选项。创建成功后，隧道凭据（Tunnel credentials JSON，含AccountTag、TunnelSecret、TunnelID）会写入本地文件，文件名形如<TunnelID>.json，权限为0400（见 writeTunnelCredentials）。该文件是后续run必需的凭据。

4.3 路由流量到 Tunnel

路由是定义"Cloudflare 边缘如何把请求代理到这个隧道"，README 给出三种方式：

• 公有 DNS 记录（DNS records in Cloudflare）：通过cloudflared tunnel route dns <TUNNEL> <HOSTNAME>创建指向该隧道的 CNAME 记录；
• 公有主机名 + Cloudflare Load Balancer：通过cloudflared tunnel route lb <TUNNEL> <HOSTNAME> <LB-POOL>将隧道作为负载均衡器源站，必要时自动创建 pool 与 load balancer；
• WARP 客户端私有流量（private traffic）：通过cloudflared tunnel route ip <NETWORK CIDR> <TUNNEL>将隧道作为私有网络源站，供同账户内已加入 Zero Trust WARP 的客户端访问（即 README 所述的 Layer 4 私有路由场景）。

这三个子命令在 buildRouteCommand 中定义。route dns支持--overwrite-dns（别名-f）覆盖同主机名已存在的 DNS 记录；route ip的详细用法见cloudflared tunnel route ip --help。

4.4 运行隧道（run）

cloudflared tunnel run [TUNNEL]

run子命令（buildRunCommand）通过隧道名/UUID 或配置文件中的tunnel: TUNNEL字段识别隧道，在本地与 Cloudflare 边缘之间建立高可用连接。其关键行为包括：

• 需要cloudflared tunnel create生成的凭据文件；但如果用 UUID 识别隧道，则不需要cloudflared login的 cert.pem；
• 也支持直接以 Tunnel Token 运行：--token <token>或--token-file <path>（token 是 Base64 编码的 JSON，解析逻辑见 ParseToken，优先级高于凭据文件）；
• 若连接出现历史残留问题，cloudflared tunnel cleanup可清除旧连接记录；
• run同时支持--protocol（QUIC/HTTP2/auto，见 selectProtocolFlag）、--post-quantum（实验性后量子安全隧道）、--features（试用开发中功能）等选项。

运行入口 StartServer 展示了隧道进程的完整组件编排：注册信号处理与 systemd 通知、启动自动更新器、创建 metrics/readiness/diagnostic 服务、初始化 orchestrator 与 management 服务、运行连接性 prechecks（可用--no-prechecks跳过）、最终由 supervisor 启动隧道 daemon，并在收到 SIGINT/SIGTERM 时按--grace-period（默认 30 秒）优雅停机。

4.5 其他管理子命令

cloudflared tunnel help下还包含（Commands()）：

• cloudflared tunnel list：列出隧道，支持--show-deleted/-d、--name、--name-prefix、--id、--when（RFC3339 时间点）、--sort-by（name/id/createdAt/deletedAt/numConnections）、--invert-sort、--output json|yaml等过滤与排序（见 buildListCommand）；
• cloudflared tunnel info [TUNNEL]：展示隧道的活跃连接器（connector）详情，包括连接器 ID、创建时间、架构、版本、源站 IP、边缘节点分布（见 buildInfoCommand）；
• cloudflared tunnel delete [TUNNEL]：按 UUID 或名称删除隧道；存在活跃连接时需-f强制删除（见 buildDeleteCommand）；
• cloudflared tunnel cleanup [TUNNEL]：删除隧道的连接记录，可用--connector-id限定单台连接器（见 buildCleanupCommand）；
• cloudflared tunnel token [TUNNEL]：获取既有隧道的凭据 token（要求隧道创建于 cloudflared 2022.3.0 之后），支持--cred-file输出到 JSON 文件（见 buildTokenCommand）；
• cloudflared tunnel ready：调用 metrics 服务上的/ready端点并根据结果返回退出码，用于容器/编排环境就绪探针（见 buildReadyCommand，需要先指定--metrics）；
• cloudflared tunnel diag：收集本机 cloudflared 实例的故障排查信息（2024.12.2 引入，见 CHANGES.md）。

5. 快捷试用：TryCloudflare 快速隧道（Quick Tunnel）

如果还没有向 Cloudflare 添加网站，可以先通过TryCloudflare快速体验 Cloudflare Tunnel。README 明确指出其文档入口，而本仓库的 quick_tunnel.go 提供了该能力的实现细节：

cloudflared tunnel --url localhost:8080

RunQuickTunnel（quick_tunnel.go）会向https://api.trycloudflare.com（--quick-service可覆盖，默认值见 cmd.go）发起 provisioning 请求，拿到随机的<random>.trycloudflare.com主机名与临时凭据，然后启动隧道并打印访问地址。README 也给出重要提示：这类无账户隧道没有可用性保证（no uptime guarantee），受 Cloudflare Online Services Terms of Use 约束，Cloudflare 保留调查隧道使用行为的权利——因此它只适合测试，不适合生产环境。源码注释同样强调："Quick tunnels shouldn't be used for production usage"，并因此强制把连接数覆写为 1（quick_tunnel.go）。

Quick Tunnel 还支持受保护模式：通过--allowed-mail指定允许访问的邮箱或通配域名后，隧道会用 Cloudflare Access 做 One-Time PIN 认证（auth_mode: otp），并展示允许的收件人数量与本地源站信息（见 buildQuickTunnelRequestBody 与 quickTunnelStartupLines）。注意：--allowed-mail仅对 Quick Tunnel 有效，命名隧道会直接报错（见 rejectAllowedMailForNamedTunnel）。

另外，cloudflared tunnel --name <NAME> --url <URL>提供"一条命令创建 + 路由（可选）+ 运行"的 ad-hoc 模式（TunnelCommand），但官方建议生产环境仍应分步执行各子命令。

6. cloudflared access：从客户端访问 Layer 4 流量

cloudflared不仅能发布服务，还能访问由cloudflared tunnel保护的 TCP 服务（Layer 4），典型如 SSH、RDP、SMB。所有相关命令位于cloudflared access help下（实现见 access/cmd.go）：

• cloudflared access login <url>：对 Access 应用发起认证流程，启动浏览器完成身份提供商（IdP）认证；无头系统会提供 URL。认证成功后生成一个 JWT（作用域绑定你的身份、目标应用与会话时长），cloudflared将其保存在本地存储。--quiet/-q不打印 JWT，--app指定应用 URL，--no-verbose仅输出 JWT 到 stdout（见 login）；
• cloudflared access curl <url> [curl args...]：包装curl并自动把 JWT 注入cf-access-token请求头，--allow-request/-ar允许在无 JWT 时继续请求（见 curl）；
• cloudflared access token <url>：直接产出可用于请求认证的 JWT；
• cloudflared access tcp（别名ssh/rdp/smb）：通过代理把数据发送到 Cloudflare 边缘，用于 SSH/RDP/SMB 等 Layer 4 协议。关键选项（access/cmd.go）：
  • --hostname/--tunnel-host/-T：应用的主机名（环境变量TUNNEL_SERVICE_HOSTNAME）；
  • --destination：SSH 服务器目标地址（环境变量TUNNEL_SERVICE_DESTINATION）；
  • --url/--listener/-L：转发到边缘的本地host:port（环境变量TUNNEL_SERVICE_URL）；
  • --header/-H：额外请求头；
  • --service-token-id/--service-token-secret：使用 Access 服务令牌（service token）认证（环境变量TUNNEL_SERVICE_TOKEN_ID/TUNNEL_SERVICE_TOKEN_SECRET）；
  • --loglevel：日志级别 {debug, info, warn, error, fatal}；
• cloudflared access ssh-config：打印可加入~/.ssh/config的示例配置（支持--short-lived-cert生成短时证书模式，见 sshConfigTemplate）；
• cloudflared access ssh-gen --hostname <h>：为指定主机名生成短时证书。

README 还提到替代方案：在客户端安装 WARP client，即可访问 Tunnel 背后的私有源站 Layer 4 流量，无需在客户端执行cloudflared access命令——这正是第 4.3 节route ip私有路由的配套场景。

7. Breaking Changes 与版本兼容策略

README 明确了破坏性变更的定义与节奏：

• 定义：移除 CLI flags、环境变量、配置键或命令，均属于破坏性变更（breaking change）；
• 发布前公告：此类移除必须在 Cloudflare Tunnel 的 changelog（developer documentation 中的 product/tunnel 分类）中提前公告，然后再随版本移除；
• 版本支持窗口：Cloudflare 目前支持距最新发布一年以内的 cloudflared 版本；超过一年的旧版本可能遭遇与功能可用性无关的破坏性变更。例如，截至 2023 年 1 月，支持范围是 2022.1.1 到 2023.1.1。

仓库内 CHANGES.md 记录了若干近期的破坏性变更实例，可作参考：如 2026.4.0 将--edge-ip-version默认值从4改为auto（改用系统解析器返回的第一个地址族，IPv4-only 用户需显式--edge-ip-version 4）；2026.2.0 移除了proxy-dns功能及相关命令与resolver配置段；cmd.go 中proxydns.Command()的注释也印证了这一点——该命令仅保留用于向旧脚本提示错误信息。此外db-connect命令已移除（cmd.go）。

8. 配置文件与运行模式

cloudflared还支持以守护/服务模式运行（无参数启动时进入 service mode，见 main.go）：它会通过 watcher/file.go 监视配置文件，并在文件变化时热重载。配置文件的搜索逻辑位于 config/configuration.go：

• 默认文件名：config.yml、config.yaml；
• 用户目录：~/.cloudflared、~/.cloudflare-warp、~/cloudflare-warp；非 Windows 系统追加/etc/cloudflared、/usr/local/etc/cloudflared；
• Windows 下优先使用CFDPATH环境变量或%ProgramFiles(x86)%\cloudflared。

配置模型（config/model.go）包含logDirectory、logLevel、forwarders（客户端侧监听器，含url、listener、serviceTokenID、serviceTokenSecret、destination、isFedramp，用于服务模式的转发配置）与tunnels字段。--config <path>可显式指定配置文件；cloudflared tunnel run也支持从配置文件读取tunnel:字段与 ingress 规则（详见 ingress/config.go）。

9. Development：从源码开发、测试与贡献

9.1 环境要求（Requirements）

根据 README.md 与 go.mod（go 1.26）：

• GNU Make（构建入口）；
• capnp（Cap'n Proto 编译器，用于重新生成 tunnelrpc/proto 下的协议代码）；
• go >= 1.26；
• 可选工具：capnpc-go（capnp Go 插件）、goimports（import 排序格式化）、golangci-lint（静态检查）、gomocks（go.uber.org/mock，mock 生成）。

9.2 常用命令

9.3 Git Hooks

为减少 CI 失败，可安装 pre-push hooks，使每次 push 前自动运行 lint 与测试：

make install-hooks

该命令会把 git 的core.hooksPath指向.githooks/，其中的 hook 会在每次 push 前依次执行make fmt-check lint test（见 Makefile）。

10. 附：仓库源码阅读索引

围绕本文主题，可继续深入阅读的关键文件：

• 入口与命令注册：cmd/cloudflared/main.go
• 隧道子命令（create/list/info/delete/cleanup/token/route/run）：cmd/cloudflared/tunnel/subcommands.go
• 隧道命令族与运行编排：cmd/cloudflared/tunnel/cmd.go
• Quick Tunnel 实现：cmd/cloudflared/tunnel/quick_tunnel.go
• Access 客户端命令：cmd/cloudflared/access/cmd.go
• 配置文件模型与默认路径：config/configuration.go、config/model.go
• 构建与打包：Makefile、Dockerfile
• 协议定义：tunnelrpc/proto/tunnelrpc.capnp
• 更新日志（破坏性变更参考）：CHANGES.md

提示：以上安装、登录、隧道创建与路由、运行、测试等操作均在本机命令行完成；若以只读方式浏览本仓库，所有源码阅读与验证路径均可用go build/make在本地副本上复现，仓库本身无需任何修改。

• 网络
• 通信
• 后端
• CLI