From 36d8b1e464d82f273fec3e441d10671a29986567 Mon Sep 17 00:00:00 2001
From: mrlee <470349233@qq.com>
Date: Wed, 30 Sep 2026 13:16:35 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8C=89=20Fonu=20=E5=AE=9A=E4=BD=8D?=
 =?UTF-8?q?=E8=BE=93=E5=87=BA=20Cloudflare=20=E9=9A=A7=E9=81=93=E9=80=82?=
 =?UTF-8?q?=E9=85=8D=E7=89=88=E5=8A=9F=E8=83=BD=E8=AE=A1=E5=88=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/README.md                    |   5 +-
 docs/cloudflared-fonu-fit-plan.md | 370 ++++++++++++++++++++++++++++++
 2 files changed, 373 insertions(+), 2 deletions(-)
 create mode 100644 docs/cloudflared-fonu-fit-plan.md

diff --git a/docs/README.md b/docs/README.md
index a9b275e..4ff18e5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -11,8 +11,9 @@
 | `improvement-roadmap-2026-09-27.md` | P0-P3 改进路线实施方案：逐项改法、测试、验收、依赖、发布与回滚 | P0-1、P0-3、P0-4 已完成，其余待实施 |
 | `system-upgrade.md` | Docker Compose 一键升级：sidecar 架构、首次部署、安全边界、回滚、故障排查与验证页 | 已实施（v1.3.8） |
 | `agent-listen-strategy-plan.md` | Agent 默认监听策略：回环监听、SSH 隧道优先、HTTPS pin 可选与自动迁移方案 | 阶段 1-4 已实施（v1.4.0）；2.0.0 兼容清理待后续 |
-| `cloudflared-integration-plan.md` | Cloudflare Tunnel（cloudflared）与 Fonu 的融合方案：托管模型、复用面、分阶段落地与 v2 优化 | 阶段 1-2 已实施（v1.6.0）；后续按 `cloudflared-feature-plan.md` 推进 |
-| `cloudflared-feature-plan.md` | Cloudflare 隧道全功能规划：官方最新文档、参考项目功能、Fonu 现状差距与 P0-P3 路线 | 待实施（阶段 1 优先） |
+| `cloudflared-integration-plan.md` | Cloudflare Tunnel（cloudflared）与 Fonu 的融合方案：托管模型、复用面、分阶段落地与 v2 优化 | 阶段 1-2 已实施（v1.6.0）；后续按 `cloudflared-fonu-fit-plan.md` 推进 |
+| `cloudflared-feature-plan.md` | Cloudflare 隧道功能全集：官方最新文档、参考项目功能、Fonu 现状差距与 P0-P3 路线 | 查漏用；实施以 `cloudflared-fonu-fit-plan.md` 为准 |
+| `cloudflared-fonu-fit-plan.md` | Cloudflare 隧道 Fonu 适配版计划：出口抽象、规则同源、体系整合、明确不做项与阶段实施 | 待实施（阶段 1 优先） |
 | `project-audit-2026-09-24.md` | 全项目审查：P0/P1/P2 分级，含精确行号与逐条修法 | **进行中**——P0 已随 v1.2.7 完成，P1 实施中 |
 | `frp-server-list-merge-plan.md` | FRP 服务端列表并入「公网服务端」页（方案 A，四步） | 步 1/2 已完成（v1.2.6）；步 3 文案收尾、步 4 死样式清理未做 |
 | `agent-capability-plan.md` | fonu-agent 能力扩展（P0/P1/P2/P3） | 已实施（agent 0.11.0）；P3 三项不做 |
diff --git a/docs/cloudflared-fonu-fit-plan.md b/docs/cloudflared-fonu-fit-plan.md
new file mode 100644
index 0000000..6216497
--- /dev/null
+++ b/docs/cloudflared-fonu-fit-plan.md
@@ -0,0 +1,370 @@
+# Cloudflare 隧道：Fonu 适配版功能计划
+
+> 日期：2026-09-30
+> 定位：`cloudflared-feature-plan.md` 是「官方 + 参考项目的功能全集」；本文是**按 Fonu 产品定位筛选后的适配版计划**，实施以本文为准。
+> 核心原则：Fonu 不是 cloudflared 管理面板，而是「NAS / 家庭服务器的公网访问管理面板」。Cloudflare 隧道只是它的第二条出口。
+
+---
+
+## 一、先明确 Fonu 是什么
+
+### 1.1 产品定位
+
+Fonu 面对的是家庭 NAS、小主机、家用服务器的用户，核心价值是：
+
+- 用域名访问内网服务，而不是记 IP 和端口；
+- 自动处理证书、反代、穿透、DDNS；
+- 尽量少配置、少暴露、少维护。
+
+Fonu 已经有三条主线：
+
+1. **反向代理**：域名 → 本机 Nginx → 内网服务；
+2. **FRP 穿透**：本机 frpc → VPS frps → 域名；
+3. **公网 Agent**：管理 VPS 上的 frps 与 Nginx。
+
+Cloudflare 隧道的加入，是为了解决一类现有链路解决不了的人：
+
+> 没有公网 IP、也不想长期租 VPS，但想让内网 Web 服务通过域名安全访问。
+
+### 1.2 因此有三条不可动摇的原则
+
+1. **CF 隧道是第二条出口，不是替代 FRP**：TCP/UDP、自主可控、大流量仍走 FRP。
+2. **规则同源**：用户维护的是「服务发布规则」，不是「隧道 ingress」。CF 只是一个出口选项。
+3. **融入 Fonu 体系**：监控、通知、状态页、日志、备份、升级、审计都复用现有模块，不另造一套面板。
+
+---
+
+## 二、目标用户与场景
+
+### 2.1 适合
+
+- 家宽没有公网 IPv4，或运营商封 80/443；
+- 有域名托管在 Cloudflare，或愿意把域名 NS 切到 Cloudflare；
+- 主要暴露 HTTP/HTTPS 服务：NAS 面板、PhotoPrism、Jellyfin 管理页、Home Assistant、qBittorrent WebUI、OpenWrt 面板等；
+- 希望「一次配置好，之后自动跟随反代规则」。
+
+### 2.2 不适合
+
+- 需要裸 TCP/UDP 端口（游戏服、非 HTTP 协议）；
+- 需要完全自主可控、流量不经过第三方；
+- 大文件/视频持续分发（Cloudflare 非 Enterprise 条款限制）；
+- 企业级 Zero Trust 私有网络、VPN 替代。
+
+---
+
+## 三、借鉴与不借鉴
+
+参考项目 `Tunnel-Cloudflared-Manager 1.0.1` 是一个独立的 cloudflared 面板。以下判断按「是否符合 Fonu 产品形态」给出：
+
+### 3.1 值得借鉴
+
+| 参考项目做法 | Fonu 该怎么用 |
+| --- | --- |
+| token 解码成本地凭据 | 已用 Account ID + API Token 替代；保留解码能力用于导入 |
+| metrics 端口从日志发现 | 已实现，继续沿用 |
+| ingress 三条不变式 | 已实现，继续沿用 |
+| 云端 / 本地配置互相同步 | 值得做，但要简化为「diff → 拉取或覆盖」 |
+| 端点级增删改 | 值得做，但必须挂在 Fonu 的「服务发布规则」下 |
+| 快速隧道 | 只做「临时演示」，不做正式功能 |
+| 网络诊断 | 值得做，做成 Fonu 的一键诊断 |
+| 镜像与下载进度 | 值得做，但复用 Fonu 现有镜像表，不做用户自定义镜像管理 |
+| Windows 隐藏控制台 | 已实现，继续沿用 |
+
+### 3.2 不借鉴
+
+| 参考项目做法 | 不借鉴的理由 |
+| --- | --- |
+| 自带 JWT + 账号体系 | Fonu 已有会话 + API Token，重复建设 |
+| 独立主题、多语言 | 与 Fonu 全局设置重复 |
+| 多账号 cert.pem 登录 | 与 Fonu 的 Account ID + API Token 模型冲突；远期若有需求再评估 |
+| 私有网络 / WARP routing / virtual network | 面向企业 Zero Trust，NAS 用户不需要 |
+| Kubernetes / Ansible / Terraform / 云厂商部署指南 | 不是 Fonu 的交付形态 |
+| 负载均衡 | 家用单机场景不需要 |
+| Workers VPC / Hyperdrive / Spectrum / Keyless SSL | 超出 Fonu 定位 |
+| WebSocket 实时日志 | Fonu 已有 SSE 日志模式，不为 CF 单独引入 WSS |
+| 自定义镜像管理（增删改测） | Fonu 只需内置镜像表 + 自定义 URL，不需要用户维护镜像源 |
+| 独立 systemd / Windows service 安装 | Fonu 自己托管进程，不接管外部服务 |
+| 快速隧道作为正式功能 | 官方明确不保证 SLA，只做演示入口 |
+
+---
+
+## 四、符合 Fonu 的功能全景
+
+按「用户价值」而不是「参考项目有什么」重新分组。
+
+### 4.1 出口抽象（Fonu 的核心差异化）
+
+**F-1 服务发布规则增加「出口」字段**
+
+- 一条规则描述「域名 → 内网服务」，出口可选：本机 Nginx / FRP / Cloudflare 隧道。
+- 现有反向代理规则作为基础，新增出口选择，不新建第二套规则模型。
+- 验收：同一条规则可以切换出口，切换后域名与服务保持不变。
+
+**F-2 CF 隧道 ingress 自动跟随反代规则**
+
+- 反代规则新增/修改/删除域名时，自动同步到该隧道的 ingress。
+- 只同步 HTTP/HTTPS 规则；TCP/UDP 规则在出口选择里标为「Cloudflare 不支持」。
+- 验收：改一条反代规则，CF 隧道配置与云端 ingress 自动更新，无需手工编辑。
+
+**F-3 一条规则可以同时走 FRP 与 CF**
+
+- 出口支持多选（FRP + Cloudflare），用于灰度或双保险。
+- 验收：同一域名可同时存在 FRP 与 CF 入口，互不影响。
+
+### 4.2 自动化（延续 Fonu「自动为主」）
+
+**F-4 一次配置，后续全自动**（大部分已完成）
+
+- Account ID + API Token 一次保存；
+- 自动创建隧道、写 `creds.json` / `config.yml`、推送 ingress、创建 CNAME；
+- 自动启动、自动重连、崩溃重启。
+
+**F-5 反代规则变化自动同步**
+
+- 规则增删改 → 生成新 ingress → 本地与云端同步 → 需要时重载配置。
+- 验收：用户不需要理解 ingress，也不需要手工点同步。
+
+**F-6 自动 DNS 管理**
+
+- 创建域名时自动 CNAME 到 `<tunnel-id>.cfargotunnel.com`；
+- 删除域名或隧道时，删除「指向该隧道」的 DNS 记录（只删自己创建的）。
+- 验收：域名增删与 DNS 一致，不误删用户其他记录。
+
+**F-7 自动健康与自愈**
+
+- 进程退出自动重启；
+- `/ready` 与 `ha_connections` 判活；
+- 连续失败进入 Fonu 告警；恢复后发通知。
+
+### 4.3 融入 Fonu 现有体系
+
+**F-8 监控与可用率**
+
+- 新增 cloudflared 的 `monitor.Source`；
+- 隧道健康进入 Fonu 现有可用率与历史指标。
+
+**F-9 通知**
+
+- 隧道断连、恢复、证书/DNS 失败复用 `notify`；
+- 通知文案面向 NAS 用户，而不是 cloudflared 术语。
+
+**F-10 状态页**
+
+- 公开状态页增加 CF 隧道域名与可用率；
+- 只展示域名与状态，不泄露隧道 ID、本机地址。
+
+**F-11 日志中心**
+
+- CF 隧道日志进入 Fonu 日志页；
+- 复用 SSE 增量推送，不单独做 WebSocket。
+
+**F-12 仪表盘**
+
+- 仪表盘增加「Cloudflare 隧道」卡片：隧道数、在线数、最近错误。
+
+**F-13 备份与迁移**
+
+- `cf_tunnels` 与凭据纳入 Fonu 备份/恢复流程；
+- 恢复后自动重启隧道。
+
+**F-14 一键升级与版本策略**
+
+- cloudflared 版本跟随 Fonu 升级流程；
+- 提供「检查更新 / 更新 cloudflared / 回滚」；
+- 不要求用户手工替换二进制。
+
+**F-15 审计**
+
+- 记录谁在何时修改了服务发布规则、出口、CF 凭据、全局开关；
+- 复用 Fonu 的日志/审计基础设施。
+
+### 4.4 NAS 场景体验
+
+**F-16 Docker 服务发现一键发布**
+
+- 复用现有 `discovery`，发现本机 Docker 服务；
+- 选择服务 → 填域名 → 自动创建反代规则 + CF 出口。
+
+**F-17 常用 NAS 应用预设**
+
+- NAS 面板、PhotoPrism、Jellyfin、Home Assistant、qBittorrent 等端口预设；
+- 用户只需选应用与域名。
+
+**F-18 域名与 Zone 选择器**
+
+- 通过 API Token 列出账号下的 Zone 与可用域名；
+- 用户从列表选择，而不是手输。
+
+**F-19 证书提示**
+
+- 使用 CF 出口时，CF 边缘自动提供 HTTPS；
+- 页面提示「该域名无需在 Fonu 申请证书」，避免用户重复操作。
+
+### 4.5 运维与安全
+
+**F-20 端点级编辑**
+
+- 在 Fonu 规则详情里编辑 hostname、path、service、协议；
+- 提供 `ingress validate` 与 `ingress rule <url>` 校验。
+
+**F-21 云端漂移检测**
+
+- 定期比较本地 ingress 与云端配置；
+- 发现漂移后提示「以本地为准覆盖」或「以云端为准拉取」。
+
+**F-22 一键诊断**
+
+- `tunnel info`、`tunnel diag`、网络预检（region1/region2、7844、443）、系统要求检查；
+- 结果转成 Fonu 风格的可读结论与建议。
+
+**F-23 令牌轮换**
+
+- 提供「重新签发隧道凭据」入口；
+- 轮换过程尽量不中断，失败自动回滚。
+
+**F-24 全局托管开关**（已完成）
+
+- 一键停止全部隧道，重启不自动拉起；
+- 开启时只恢复 auto_start 的隧道。
+
+**F-25 条款与用量提示**
+
+- 页面常驻说明：不适合大文件/视频分发；
+- 不采集、不上报用户流量到外部。
+
+**F-26 Access 保护状态检测（只读）**
+
+- 检测域名是否启用 Cloudflare Access；
+- 只提示，不代配策略。
+
+### 4.6 可选增强
+
+**F-27 快速隧道（临时演示）**
+
+- 临时把某个本地端口发到 `trycloudflare.com`；
+- 明确标注不保证 SLA、URL 每次变化、仅用于测试。
+
+**F-28 多副本**
+
+- 高级选项，用于「主备两台设备跑同一条隧道」；
+- 默认关闭，不打扰普通用户。
+
+**F-29 边缘 IP 优选**
+
+- 只影响「本机 → CF 边缘」一段；
+- 页面展示优选建议，不代写 hosts；
+- 面向国内链路质量差的用户。
+
+**F-30 账号模式（cert.pem）**
+
+- 仅当用户明确需要「多账号 / 团队权限」时提供；
+- 默认仍推荐 Account ID + API Token。
+
+---
+
+## 五、明确不做的功能
+
+| 功能 | 结论 | 理由 |
+| --- | --- | --- |
+| 独立登录、JWT、多用户体系 | 不做 | Fonu 已有认证与 API Token |
+| 独立主题、多语言 | 不做 | 属于 Fonu 全局设置 |
+| 私有网络 / WARP routing | 不做（远期评估） | 面向 Zero Trust 企业，NAS 用户不需要 |
+| 负载均衡 | 不做 | 家用单机场景不需要 |
+| Kubernetes / Ansible / Terraform 指南 | 不做 | 不是 Fonu 交付形态 |
+| Workers VPC / Hyperdrive / Spectrum | 不做 | 超范围 |
+| WebSocket 实时日志 | 不做 | 复用 Fonu SSE |
+| 自定义镜像管理 | 不做 | 内置镜像表 + 自定义 URL 足够 |
+| 接管外部 systemd / Windows service | 不做 | Fonu 只托管自己启动的进程 |
+| 快速隧道作为正式功能 | 不做 | 官方不保证 SLA，只做演示 |
+| 代配 Access 策略 | 不做 | 高风险，只做只读检测 |
+| 自动扩权 / 自动改系统防火墙 | 不做 | 保持 Fonu 现有安全边界 |
+
+---
+
+## 六、与现有模块的整合点
+
+| Fonu 模块 | 整合方式 |
+| --- | --- |
+| 反向代理规则 | 增加「出口」字段；CF 隧道从规则派生 |
+| FRP 多服务端 | 与 CF 出口并列，互不影响 |
+| 证书管理 | CF 出口域名提示无需本地证书 |
+| DDNS | CF 橙色云代理后本地 IP 变化不再影响访问，可提示用户 |
+| 监控 / 可用率 | 新增 cloudflared Source |
+| 通知 | 断连、恢复、DNS 失败复用 |
+| 公开状态页 | 增加 CF 隧道条目 |
+| 日志中心 | CF 日志进入现有日志页 |
+| 仪表盘 | 新增 CF 隧道卡片 |
+| Docker 服务发现 | 一键发布到 CF |
+| 备份 / 恢复 | cf_tunnels 与凭据纳入 |
+| 一键升级 | cloudflared 版本更新纳入 |
+| 审计 | 规则、出口、凭据变更记录 |
+
+---
+
+## 七、数据模型与 API 变更
+
+### 7.1 数据模型
+
+- `frp_proxies`（或服务发布规则表）增加 `exit` 字段：`local` / `frp` / `cloudflare` / 多选；
+- `cf_tunnels` 增加 `rule_id`（可选，关联服务发布规则）、`source`、`last_sync_at`；
+- 新增 `cf_endpoint_drift` 或复用现有漂移检测表；
+- `cf_settings` 增加 `auto_update`、`update_channel`。
+
+### 7.2 API
+
+- `PUT /api/proxies/{id}/exit`：切换出口；
+- `GET /api/cloudflare/tunnels/{id}/drift`：漂移检测；
+- `POST /api/cloudflare/tunnels/{id}/pull`：从云端拉取；
+- `POST /api/cloudflare/tunnels/{id}/diagnostics`：一键诊断；
+- `GET /api/cloudflare/zones`：Zone / 域名列表；
+- `POST /api/cloudflare/tunnels/{id}/token/rotate`：令牌轮换；
+- `GET /api/cloudflare/tunnels/{id}/logs/stream`：SSE 日志；
+- `GET /api/discovery/docker`：Docker 服务发现（若尚未提供）。
+
+### 7.3 前端
+
+- 反向代理规则表单增加「出口」选择器；
+- 规则详情增加「Cloudflare 隧道」状态与操作；
+- CF 页面聚焦「隧道状态 / 诊断 / 日志 / 全局开关」，弱化「手工建隧道」；
+- 仪表盘、状态页、日志中心增加 CF 条目。
+
+---
+
+## 八、阶段计划
+
+| 阶段 | 内容 | 目标 |
+| --- | --- | --- |
+| 阶段 1 | F-1 ~ F-3 出口抽象；F-5 规则同步；F-6 DNS 管理完善 | 让 CF 成为反代规则的一个出口，而不是独立模块 |
+| 阶段 2 | F-8 ~ F-15 体系整合；F-20 ~ F-22 编辑与诊断 | 让 CF 隧道进入 Fonu 监控、通知、状态页、日志、备份、审计 |
+| 阶段 3 | F-16 ~ F-19 NAS 体验；F-23 ~ F-26 运维安全 | 一键发布、域名选择、令牌轮换、条款提示、Access 检测 |
+| 阶段 4 | F-27 ~ F-30 可选增强 | 快速隧道、多副本、边缘优选、账号模式按需 |
+
+**优先级建议**：阶段 1 是产品形态的关键，先做；阶段 2 决定「能不能长期运维」；阶段 3 决定「好不好用」；阶段 4 是加分项。
+
+---
+
+## 九、验收标准
+
+- 用户只维护「域名 → 服务」的规则，出口切换不需要改域名或端口；
+- 反代规则变化后，CF 隧道与 DNS 自动跟随；
+- 隧道断连能进 Fonu 告警与状态页；
+- 一条规则可以同时走 FRP 与 CF，互不影响；
+- CF 出口域名不需要本地证书；
+- 备份恢复后隧道能自动恢复；
+- 所有 CF 凭据加密存储、预览脱敏；
+- 明确不做的功能不会出现在界面里，避免用户误解。
+
+---
+
+## 十、结论
+
+Fonu 需要的不是「另一个 cloudflared 面板」，而是：
+
+> 把 Cloudflare 隧道做成反向代理规则的一个出口选项，并让监控、通知、状态页、日志、备份、升级、审计自动覆盖它。
+
+按本文阶段 1-3 实施，Fonu 的 CF 模块会形成与参考项目不同的产品形态：参考项目面向「管理 cloudflared」，Fonu 面向「管理我的服务怎么上公网」。
+
+本文与 `cloudflared-feature-plan.md` 的关系：
+
+- `cloudflared-feature-plan.md`：官方 + 参考项目的功能全集，用于查漏；
+- 本文：按 Fonu 定位筛选后的实施计划，**实施以本文为准**。