19 KiB
19 KiB
Cloudflare 隧道模块全功能规划
调研日期：2026-09-30 调研对象：Cloudflare 官方文档（developers.cloudflare.com，2026-08/09 更新）+
F:\WWW\cf\Tunnel-Cloudflared-linux（Tunnel-Cloudflared-Manager 1.0.1）+ Havline 1.8.0 现有实现 目标：把 Havline 的「Cloudflare 隧道」从「可用的创建与托管」推进到「覆盖官方主要能力、可长期运维」的完整模块。
一、官方文档调研结论
Cloudflare 把 Tunnel 分成两条产品线，Havline 目前主要落在第一条，规划时需要同时兼顾两条：
| 产品线 | 文档入口 | 典型用途 |
|---|---|---|
| Zero Trust / 私有网络 | cloudflare-one Tunnel | 私有网络、SSH/RDP、VPN 替代、Access 保护 |
| 公开发布应用 | tunnel | 把公网域名指向自建服务，替代 VPS 与端口暴露 |
1.1 核心概念（官方）
- Tunnel：一条以 UUID 标识的持久对象，是源站与 Cloudflare 之间的逻辑链路。
- Connector：一个
cloudflared进程；同一条隧道可以运行多个 connector。 - Replica：同一隧道的多个
cloudflared实例，用于高可用与零停机更新。 - Remotely-managed：隧道由 Cloudflare 面板 / API 管理，规则在云端，
cloudflared用 token 启动。 - Locally-managed：规则在本机
config.yml，用credentials-file启动。 - Quick tunnel：
trycloudflare.com临时隧道，无需账号，官方明确仅用于测试与开发。 - Virtual network：私有网络中用于隔离不同网络的路由域。
1.2 官方关键能力清单
隧道与连接器
- 创建、删除、列出、按名称或 UUID 查询隧道
- 获取隧道 token；token 轮换
- 同一隧道部署多个 replica
cloudflared tunnel info查看连接器与连接状态- 每个 connector 默认建立 4 条出站连接，分布在至少两个数据中心
- 支持 post-quantum 加密（
--post-quantum）
路由
- Published application：
hostname（可带path）→service - 支持服务协议：
http、https、ssh、rdp、smb、tcp、unix、http_status、http_host、TCP over WebSocket 等 - DNS：创建 CNAME 指向
<tunnel-id>.cfargotunnel.com，需开启代理 - 私有网络：CIDR route、WARP routing、virtual network
- Load Balancing：公开负载均衡与私有负载均衡
配置
config.yml顶层：tunnel、credentials-file、ingress、warp-routing、originRequest、protocol、edge-ip-version、ha-connections、retries、grace-period、post-quantum、region、tag、logfile、loglevel、metrics、pidfile、token、token-fileingress必须末条 catch-all（如http_status:404），按顺序匹配 hostname / path- Origin 参数：TLS（
originServerName、matchSNItoHost、caPool、noTLSVerify、tlsTimeout、http2Origin）、HTTP（httpHostHeader、disableChunkedEncoding）、连接（connectTimeout、noHappyEyeballs、proxyType、proxyAddress、proxyPort、keepAliveTimeout、keepAliveConnections、tcpKeepAlive）、Access（access） - 校验工具：
cloudflared tunnel ingress validate、cloudflared tunnel ingress rule <url>
观测
- Tunnel health：面板隧道健康、
cloudflared tunnel info - Cloudflare Notifications：隧道健康事件通知
- Logs：Cloudflare 侧日志、remote log streaming、network session logs、本机
cloudflared日志 - Metrics：
/metrics（Prometheus 格式）、/ready、/healthcheck - Diagnostic logs：
cloudflared tunnel diag生成诊断文件
运维与部署
- Linux systemd、macOS launch agent、Windows service
- Docker、Kubernetes、Ansible、Terraform、AWS/Azure/GCP 指南
- 更新 cloudflared；多实例零停机更新
- 系统要求：出站 7844（TCP/UDP）与 443；ulimit；容量计算
- 文件权限要求：
cert.pem、<UUID>.json、config.yml
权限与安全
- API Token 权限：
Account > Cloudflare Tunnel > Edit、Zone > DNS > Edit（查询 Zone 还需Zone > Zone > Read） - Access、Service Auth、mTLS、Keyless SSL、Spectrum、Workers VPC、Hyperdrive 等集成
- Tunnel ownership、account-scoped roles、撤销账号证书
1.3 官方版本要点（2026-09）
- 运行参数文档最近更新 2026-09；
post-quantum、token-file、region、tag、dns-resolver-addrs、edge-bind-address等参数已进入官方参考。 edge-ip-version官方默认值曾由4调整为auto；Havline 已显式下发4，与国内链路建议一致。- 官方把「公开发布应用」与「Zero Trust 私有网络」拆成两条文档线，Havline 需要明确自己的默认定位是公开发布应用。
二、参考项目功能清单（Tunnel-Cloudflared-Manager 1.0.1）
参考项目是一个独立面板，功能面比 Havline 当前实现更宽，但缺少与 Havline 的规则、健康、通知、状态页体系融合。
2.1 隧道管理
- 命名隧道：token 启动、config-file 启动
- 快速隧道：
--url启动、从日志解析*.trycloudflare.comURL - 启动 / 停止 / 停止全部 / 运行列表 / URL 查询
- 创建隧道（账号模式，
tunnel create） - 初始化 token 隧道：解码 token → 写
creds.json+config.yml - 删除云端隧道
2.2 路由与云端同步
- 端点列表：读取本地
config.yml的 ingress - 新增 / 更新 / 删除端点（本地）
- 新增端点时自动调用
tunnel route dns创建 DNS - 从云端拉取 ingress 到本地
- 把本地 ingress 推送到云端
- ingress 三条不变式：catch-all、
localhost归一化、插入在 catch-all 之前
2.3 账号模式
cert.pem登录与 finalize- 列出账号下的隧道
- 同步云端隧道
- 删除账号
2.4 二进制与镜像
- 检查 / 下载 / 替换 cloudflared
- 下载进度
- 镜像管理：列出、新增、更新、删除、测试
- 内置官方与多个 gh-proxy 镜像
2.5 指标与日志
- 每 2 秒抓取
/metrics - QUIC：
quic_client_receive_bytes、quic_client_sent_bytes、quic_client_smoothed_rtt - HTTP/2：RPC latency、主动 HEAD 探测；带宽用进程 socket 统计（Windows 需要管理员）
- 连接数：
cloudflared_tunnel_ha_connections - 实时日志：WebSocket 推送
- 清空日志
2.6 网络与调优
protocol（auto/http2/quic）、代理环境探测与回落edge-ip-version、ha-connectionsoriginRequest：caPool、noTLSVerify、httpHostHeader- 网络诊断接口
- Windows 子进程隐藏控制台
2.7 运维
- 版本检查与应用自更新
- JWT + bcrypt 登录、失败锁定
- 多语言、主题
- Docker 与 Linux 安装脚本
三、Havline 当前实现（v1.8.0）
| 能力 | 状态 |
|---|---|
| Account ID + API Token 凭据 | ✅ 已实现 |
API Token 验证（/accounts/{id}/tokens/verify） |
✅ 已实现 |
| 创建 / 删除云端隧道 | ✅ 已实现 |
获取隧道 token、写 creds.json / config.yml |
✅ 已实现 |
| 推送 ingress 到云端 | ✅ 已实现 |
| 自动创建 CNAME DNS | ✅ 已实现 |
| 二进制下载与版本检查 | ✅ 已实现（多镜像、大小与可执行校验） |
| 进程托管、启停、重启、日志文件 | ✅ 已实现 |
metrics 端口发现、/ready、ha_connections、QUIC 带宽/RTT |
✅ 已实现（基础） |
| 全局托管开关 | ✅ 已实现 |
| auto_start | ✅ 已实现 |
| 前端页面与弹窗 | ✅ 已实现 |
| 云端隧道列表同步 / 导入已有隧道 | ❌ 未实现 |
| 端点级 CRUD（path / 协议 / 多服务） | ❌ 未实现 |
| 从云端拉取 ingress（pull） | ❌ 未实现 |
| 多副本 / 零停机更新 | ❌ 未实现 |
| 快速隧道 | ❌ 未实现 |
| 账号模式（cert.pem） | ❌ 未实现 |
| 实时日志流（WebSocket/SSE） | ❌ 未实现 |
| 诊断日志、网络预检、隧道 info | ❌ 未实现 |
| 接入 Havline monitor / 通知 / 状态页 | ❌ 未实现 |
| cloudflared 自动更新 | ❌ 未实现 |
| 自定义镜像管理、下载进度 | ❌ 未实现 |
| Origin 高级参数 UI | ❌ 未实现 |
| 令牌轮换、权限审计 | ❌ 未实现 |
| 私有网络 / WARP routing / Access / 负载均衡 | ❌ 未实现 |
| 边缘 IP 优选、post-quantum、region/tag | ❌ 未实现 |
四、差距与机会
4.1 必须补齐（否则模块不完整）
- 云端隧道列表与导入：目前 Havline 只能管理自己创建的隧道，已有隧道无法纳管。
- 端点级 CRUD：现在是整体覆盖 ingress，无法单独增删改一条 hostname/path。
- 云端配置拉取与漂移检测：云端被手动修改后，Havline 无法发现。
- 健康接入 Havline 体系：隧道状态没有进入 monitor、通知、状态页、可用率。
- 实时日志：轮询文件在故障排查时体验差。
- 诊断能力：缺
tunnel info、tunnel diag、网络预检、端口要求检查。
4.2 高价值增强
- 快速隧道（临时演示、开发调试）
- 多副本与零停机更新
- cloudflared 自动更新与版本策略
- 令牌轮换
- Origin 高级参数（HTTPS 回源、自签证书、Host 头）
- 自定义镜像与下载进度
- 审计日志（谁在何时修改了隧道、端点、DNS）
4.3 远期能力
- 账号模式（cert.pem）与多账号管理
- 私有网络 / WARP routing / virtual network
- Cloudflare Access / Service Auth 集成
- 负载均衡集成
- 边缘 IP 优选
- Workers VPC / Hyperdrive / Spectrum 等生态集成
五、全量功能规划
P0：模块完整性（先补齐）
P0-1 云端隧道同步与导入
- 目标：列出 Cloudflare 账号下的全部隧道，把未纳管的隧道导入 Havline。
- 实现：
GET /accounts/{id}/cfd_tunnel列表；导入时读取 token、写creds.json/config.yml、落库。 - 验收：账号下已有隧道能在页面看到并导入；重复导入不产生重复记录。
P0-2 端点级 CRUD 与 ingress 校验
- 目标：不再整体覆盖 ingress，支持单条 hostname/path/service 的增删改。
- 实现：本地
config.yml解析与增量修改；云端PUT configurations同步；cloudflared tunnel ingress validate与ingress rule <url>自检。 - 验收：新增、修改、删除单个端点后本地与云端一致；非法规则被拒绝。
P0-3 云端配置拉取与漂移检测
- 目标：云端被手动修改后，Havline 能发现差异并选择拉取或覆盖。
- 实现：
GET /accounts/{id}/cfd_tunnel/{tunnel}/configurations；与本地 config 做 diff；提供「拉取到本地」「推送到云端」。 - 验收：diff 可见；两个方向都能执行并留痕。
P0-4 健康接入 Havline 体系
- 目标：隧道断连、恢复进入现有 monitor、通知、状态页与可用率。
- 实现：新增 cloudflared 的
monitor.Source；/ready+ha_connections判活；断连/恢复事件复用 notify；状态页增加隧道条目。 - 验收：停掉隧道后产生告警；恢复后产生恢复通知；状态页可见。
P0-5 实时日志（SSE）
- 目标：日志页实时滚动，替代轮询。
- 实现：Havline 现有日志 SSE 模式复用；cloudflared 日志文件 tail + 增量推送；保留轮询回退。
- 验收：页面实时看到新日志；切换页面/重连不丢关键行。
P0-6 诊断能力
- 目标：一键完成常见故障排查。
- 实现：
cloudflared tunnel info <name>、cloudflared tunnel diag、cloudflared tunnel ingress validate、网络预检（region1/region2、7844、443）、端口与系统要求检查。 - 验收：诊断页给出结构化结果与建议，不只是原始输出。
P1：运维与安全
P1-1 快速隧道
- 目标：临时把本地端口发布到
trycloudflare.com，用于演示与开发。 - 实现：
--url启动、日志解析公共 URL、进程随 Havline 生命周期、默认关闭。 - 边界：明确标注不保证 SLA、URL 每次变化。
P1-2 多副本与零停机更新
- 目标：同一隧道支持多个 connector，更新时不中断。
- 实现：replica 配置与进程管理；逐个重启；
tunnel info确认新连接注册后再停旧实例。 - 验收：更新过程中隧道可用率不下降。
P1-3 cloudflared 自动更新与版本策略
- 目标：可检查新版本、按策略升级、支持回滚。
- 实现：官方 Release 检查；保留旧版本目录；升级前校验；失败回滚。
- 验收：升级成功可回滚；版本信息可追溯。
P1-4 令牌轮换
- 目标：按官方
tunnel token支持重新签发 token。 - 实现：
GET /accounts/{id}/cfd_tunnel/{tunnel}/token；轮换后更新creds.json并重启连接器；双凭据过渡窗口。 - 验收：轮换过程不中断或只短暂闪断。
P1-5 Origin 高级参数
- 目标：支持 HTTPS 回源、自签证书、Host 头等官方 origin 参数。
- 实现：
originRequest的originServerName、matchSNItoHost、caPool、noTLSVerify、httpHostHeader、connectTimeout、keepAliveTimeout等。 - 验收：HTTPS 回源与自签证书场景可用；参数写入本地与云端配置。
P1-6 审计日志
- 目标：记录谁在何时修改了隧道、端点、DNS、令牌与全局开关。
- 实现：复用 Havline 日志/审计基础设施；操作前记录旧值、操作后记录新值。
- 验收：关键变更可查询、可导出。
P2：体验与增强
P2-1 自定义镜像与下载进度
- 目标：镜像可增删改测，下载有进度。
- 实现：镜像表（URL 模板）+ 连通性测试；SSE 推送下载进度。
P2-2 指标图表与历史
- 目标：展示隧道延迟、带宽、连接数、可用率历史。
- 实现：复用
metrics_samples；前端图表；区分 QUIC/HTTP2 可用指标。
P2-3 配置版本、diff 与回滚
- 目标：隧道
config.yml与云端 ingress 的版本化。 - 实现：复用
fsutil.BackupVersioned；变更前留版本；支持 diff 与回滚。
P2-4 日志导出与清理
- 目标：导出、清理单隧道日志；限制日志体积。
- 实现：日志文件轮转、下载、清空；保留期设置。
P2-5 系统要求与容量检查
- 目标：按官方要求检查 ulimit、出站 7844/443、系统资源。
- 实现：启动前检查与页面提示；不做自动修改系统参数。
P2-6 网络调优扩展
- 目标：暴露官方 run parameters。
- 实现：
post-quantum、region、tag、dns-resolver-addrs、edge-bind-address、retries、grace-period、loglevel、logfile、pidfile。
P3：平台化
P3-1 账号模式（cert.pem）与多账号管理
- 支持
cloudflared tunnel login、cert.pem 导入、多账号切换、账号下隧道同步。
P3-2 私有网络（WARP routing / CIDR / virtual network）
- 支持
warp-routing: enabled: true、CIDR route、virtual network、私有主机名路由。
P3-3 Access / Service Auth
- 只做诊断与提示，或在用户显式配置后生成 Access 应用；不代配高风险策略。
P3-4 负载均衡集成
- 公开/私有负载均衡池与隧道关联；只做只读展示与跳转。
P3-5 边缘 IP 优选
- 探测官方 IPv4 段的 TCP 7844 延迟，生成两个 region 的优选建议；页面展示，不代写 hosts。
P3-6 生态集成
- Workers VPC、Hyperdrive、Spectrum、Keyless SSL、Data Localization 等按需评估。
六、推荐实施顺序
| 阶段 | 内容 | 预计 | 完成标志 |
|---|---|---|---|
| 阶段 1 | P0-1 ~ P0-6 | 1-2 周 | 云端同步、端点 CRUD、漂移检测、健康接入、实时日志、诊断全部可用 |
| 阶段 2 | P1-1 ~ P1-6 | 2-3 周 | 快速隧道、多副本、自动更新、令牌轮换、Origin 高级参数、审计 |
| 阶段 3 | P2-1 ~ P2-6 | 2 周 | 镜像、图表、版本回滚、日志治理、系统检查、网络调优扩展 |
| 阶段 4 | P3-1 ~ P3-6 | 按需 | 账号模式、私有网络、Access、负载均衡、边缘优选、生态集成 |
建议先做阶段 1，因为它直接补齐「已经有隧道但无法纳管」「云端被改无法发现」「故障无法定位」这三类现实问题。
七、数据模型与 API 变更
7.1 数据模型
cf_tunnels：增加source（created/imported）、cloud_status、connector_count、last_sync_at。- 新增
cf_tunnel_endpoints：tunnel_id、hostname、path、service、protocol、origin_json。 - 新增
cf_tunnel_events：健康事件、审计事件、同步事件。 cf_settings：扩展enabled、auto_update、update_channel、mirror。
7.2 API
GET /api/cloudflare/cloud-tunnels：列出云端隧道POST /api/cloudflare/cloud-tunnels/{id}/import：导入GET/POST/PUT/DELETE /api/cloudflare/tunnels/{id}/endpoints：端点 CRUDPOST /api/cloudflare/tunnels/{id}/pull：从云端拉取GET /api/cloudflare/tunnels/{id}/drift：漂移检测GET /api/cloudflare/tunnels/{id}/logs/stream：实时日志GET /api/cloudflare/tunnels/{id}/diagnostics：诊断POST /api/cloudflare/tunnels/{id}/token/rotate：令牌轮换GET/POST /api/cloudflare/mirrors：镜像管理
7.3 前端
- 隧道详情增加端点列表、diff、诊断、实时日志、指标图表。
- 新增「云端隧道」页签或导入入口。
- 应用配置增加自动更新策略、镜像管理、系统要求检查结果。
八、测试与验收
单元测试
- ingress 增删改与三条不变式
- 云端配置 diff
- token 解码、轮换
- metrics 解析与降级
- 诊断结果解析
集成测试
- 创建 → 启动 → 健康 → 停止 → 删除全流程
- 云端修改后用 diff 发现并拉取
- 多副本零停机更新
- 自动 DNS 创建/更新
前端
- 端点编辑、diff 视图、诊断面板、实时日志
真机矩阵
- Windows、Linux、Docker 容器内、host 网络
- 代理环境、QUIC 被拦、7443/7844 被占用、无 IPv6
- Cloudflare Access 与无 Access
九、风险与边界
- 官方接口演进：Cloudflare API 与 cloudflared 参数会变；所有参数需要可配置 + 默认值 + 可恢复默认。
- 权限边界：API Token 权限不足时只提示，不自动扩权。
- 网络边界：只做本机到 CF 边缘的调优；访客侧不可控。
- 合规边界：大文件/视频分发不在推荐用法内。
- 安全边界：不代配 Access 高风险策略；不写 hosts；不改系统 ulimit/防火墙。
- 运行边界：Havline 只托管自己启动的 cloudflared 进程；不接管外部 systemd 服务。
- 数据边界：凭据加密存储；预览脱敏；审计日志不记录明文 token。
十、结论
Havline 的 Cloudflare 隧道模块已经具备「创建、运行、托管、DNS」的闭环。下一阶段的目标是把它从「能用」推进到「可长期运维」：
- 先补齐云端同步、端点 CRUD、漂移检测、健康接入、实时日志、诊断（阶段 1）。
- 再补快速隧道、多副本、自动更新、令牌轮换、Origin 高级参数、审计（阶段 2）。
- 最后做镜像、图表、版本回滚、日志治理、系统检查与网络调优扩展（阶段 3）。
- 私有网络、Access、负载均衡、边缘优选等平台化能力按需推进（阶段 4）。
这样 Havline 才能在官方能力、参考项目功能与自身产品体系之间取得平衡，而不是停留在「进程开关 + 配置预览」。