docs: 基于官方文档与参考项目输出 Cloudflare 隧道全功能规划

docs/cloudflared-feature-plan.md

@@ -0,0 +1,442 @@
+# Cloudflare 隧道模块全功能规划
+
+> 调研日期：2026-09-30
+> 调研对象：Cloudflare 官方文档（developers.cloudflare.com，2026-08/09 更新）+ `F:\WWW\cf\Tunnel-Cloudflared-linux`（Tunnel-Cloudflared-Manager 1.0.1）+ Fonu 1.8.0 现有实现
+> 目标：把 Fonu 的「Cloudflare 隧道」从「可用的创建与托管」推进到「覆盖官方主要能力、可长期运维」的完整模块。
+
+---
+
+## 一、官方文档调研结论
+
+Cloudflare 把 Tunnel 分成两条产品线，Fonu 目前主要落在第一条，规划时需要同时兼顾两条：
+
+| 产品线 | 文档入口 | 典型用途 |
+| --- | --- | --- |
+| Zero Trust / 私有网络 | [cloudflare-one Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) | 私有网络、SSH/RDP、VPN 替代、Access 保护 |
+| 公开发布应用 | [tunnel](https://developers.cloudflare.com/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-file`
+- `ingress` 必须末条 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`；Fonu 已显式下发 `4`，与国内链路建议一致。
+- 官方把「公开发布应用」与「Zero Trust 私有网络」拆成两条文档线，Fonu 需要明确自己的默认定位是公开发布应用。
+
+---
+
+## 二、参考项目功能清单（Tunnel-Cloudflared-Manager 1.0.1）
+
+参考项目是一个独立面板，功能面比 Fonu 当前实现更宽，但缺少与 Fonu 的规则、健康、通知、状态页体系融合。
+
+### 2.1 隧道管理
+
+- 命名隧道：token 启动、config-file 启动
+- 快速隧道：`--url` 启动、从日志解析 `*.trycloudflare.com` URL
+- 启动 / 停止 / 停止全部 / 运行列表 / 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-connections`
+- `originRequest`：`caPool`、`noTLSVerify`、`httpHostHeader`
+- 网络诊断接口
+- Windows 子进程隐藏控制台
+
+### 2.7 运维
+
+- 版本检查与应用自更新
+- JWT + bcrypt 登录、失败锁定
+- 多语言、主题
+- Docker 与 Linux 安装脚本
+
+---
+
+## 三、Fonu 当前实现（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 | ❌ 未实现 |
+| 接入 Fonu monitor / 通知 / 状态页 | ❌ 未实现 |
+| cloudflared 自动更新 | ❌ 未实现 |
+| 自定义镜像管理、下载进度 | ❌ 未实现 |
+| Origin 高级参数 UI | ❌ 未实现 |
+| 令牌轮换、权限审计 | ❌ 未实现 |
+| 私有网络 / WARP routing / Access / 负载均衡 | ❌ 未实现 |
+| 边缘 IP 优选、post-quantum、region/tag | ❌ 未实现 |
+
+---
+
+## 四、差距与机会
+
+### 4.1 必须补齐（否则模块不完整）
+
+1. **云端隧道列表与导入**：目前 Fonu 只能管理自己创建的隧道，已有隧道无法纳管。
+2. **端点级 CRUD**：现在是整体覆盖 ingress，无法单独增删改一条 hostname/path。
+3. **云端配置拉取与漂移检测**：云端被手动修改后，Fonu 无法发现。
+4. **健康接入 Fonu 体系**：隧道状态没有进入 monitor、通知、状态页、可用率。
+5. **实时日志**：轮询文件在故障排查时体验差。
+6. **诊断能力**：缺 `tunnel info`、`tunnel diag`、网络预检、端口要求检查。
+
+### 4.2 高价值增强
+
+1. 快速隧道（临时演示、开发调试）
+2. 多副本与零停机更新
+3. cloudflared 自动更新与版本策略
+4. 令牌轮换
+5. Origin 高级参数（HTTPS 回源、自签证书、Host 头）
+6. 自定义镜像与下载进度
+7. 审计日志（谁在何时修改了隧道、端点、DNS）
+
+### 4.3 远期能力
+
+1. 账号模式（cert.pem）与多账号管理
+2. 私有网络 / WARP routing / virtual network
+3. Cloudflare Access / Service Auth 集成
+4. 负载均衡集成
+5. 边缘 IP 优选
+6. Workers VPC / Hyperdrive / Spectrum 等生态集成
+
+---
+
+## 五、全量功能规划
+
+### P0：模块完整性（先补齐）
+
+**P0-1 云端隧道同步与导入**
+
+- 目标：列出 Cloudflare 账号下的全部隧道，把未纳管的隧道导入 Fonu。
+- 实现：`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 云端配置拉取与漂移检测**
+
+- 目标：云端被手动修改后，Fonu 能发现差异并选择拉取或覆盖。
+- 实现：`GET /accounts/{id}/cfd_tunnel/{tunnel}/configurations`；与本地 config 做 diff；提供「拉取到本地」「推送到云端」。
+- 验收：diff 可见；两个方向都能执行并留痕。
+
+**P0-4 健康接入 Fonu 体系**
+
+- 目标：隧道断连、恢复进入现有 monitor、通知、状态页与可用率。
+- 实现：新增 cloudflared 的 `monitor.Source`；`/ready` + `ha_connections` 判活；断连/恢复事件复用 notify；状态页增加隧道条目。
+- 验收：停掉隧道后产生告警；恢复后产生恢复通知；状态页可见。
+
+**P0-5 实时日志（SSE）**
+
+- 目标：日志页实时滚动，替代轮询。
+- 实现：Fonu 现有日志 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、进程随 Fonu 生命周期、默认关闭。
+- 边界：明确标注不保证 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、令牌与全局开关。
+- 实现：复用 Fonu 日志/审计基础设施；操作前记录旧值、操作后记录新值。
+- 验收：关键变更可查询、可导出。
+
+### 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`：端点 CRUD
+- `POST /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/防火墙。
+- **运行边界**：Fonu 只托管自己启动的 cloudflared 进程；不接管外部 systemd 服务。
+- **数据边界**：凭据加密存储；预览脱敏；审计日志不记录明文 token。
+
+---
+
+## 十、结论
+
+Fonu 的 Cloudflare 隧道模块已经具备「创建、运行、托管、DNS」的闭环。下一阶段的目标是把它从「能用」推进到「可长期运维」：
+
+1. 先补齐云端同步、端点 CRUD、漂移检测、健康接入、实时日志、诊断（阶段 1）。
+2. 再补快速隧道、多副本、自动更新、令牌轮换、Origin 高级参数、审计（阶段 2）。
+3. 最后做镜像、图表、版本回滚、日志治理、系统检查与网络调优扩展（阶段 3）。
+4. 私有网络、Access、负载均衡、边缘优选等平台化能力按需推进（阶段 4）。
+
+这样 Fonu 才能在官方能力、参考项目功能与自身产品体系之间取得平衡，而不是停留在「进程开关 + 配置预览」。