havline-native/app-src/docs/cloudflared-current-features.md

# Cloudflare 隧道当前功能说明

> 日期：2026-10-01
> 状态：v1.9.0 实测功能基线。本文描述**当前代码实际实现的能力**，不是早期规划稿。
> 相关文档：
> - `cloudflared-integration-plan.md`：早期融合方案
> - `cloudflared-feature-plan.md`：官方与参考项目功能全集，用于查漏
> - `cloudflared-havline-fit-plan.md`：Havline 适配版阶段计划

---

## 一、模块定位

Cloudflare 隧道在 Havline 中不是独立的 cloudflared 管理面板，而是公网访问的第二条出口：

- 本机 Nginx：适合有公网 IP 或已有端口映射的场景。
- FRP：适合需要 TCP/UDP、自控 VPS 或大流量的场景。
- Cloudflare 隧道：适合没有公网 IP、主要发布 HTTP/HTTPS Web 服务的场景。

当前模块已经融入 Havline 的规则、监控、通知、状态页、日志、备份、诊断和升级体系。

---

## 二、已实现的入口与页面

### 2.1 Cloudflare 隧道列表页

页面：`web/src/views/CloudflareView.vue`

已实现：

- 隧道列表显示：
  - 隧道名称
  - 状态
  - 副本 / cloudflared HA 连接数
  - cloudflared 版本
  - 路由数量
  - 指标端口
- 全局托管开关：
  - 关闭：停止全部隧道。
  - 开启：立即启动全部隧道。
  - 应用重启：全局托管开启时自动恢复全部隧道。
- 新建隧道弹窗：
  - 自动托管模式。
  - 手工隧道模式。
- 手工隧道暴露规则：
  - 子域名输入。
  - 域从 Cloudflare Zone 列表选择。
  - HTTP / HTTPS / TCP / SSH 服务类型。
  - `://` 与 URL 分离显示。
  - 实时显示完整主机名。
- 隧道操作：
  - 详情。
  - 配置页。
  - 启动 / 停止 / 重启。
  - 删除。
- 应用配置：
  - Account ID。
  - API Token。
  - Token 验证。
  - cloudflared 下载镜像。
  - 默认网络参数。

### 2.2 隧道配置页

页面：`web/src/views/CloudflareTunnelConfigView.vue`

已实现：

- 独立路由页面，不再使用编辑弹窗：
  - `/cloudflare/:id/config`
- 指标卡：
  - 活动副本
  - 路由数
  - 状态
  - 运行时间
- 基础配置：
  - 页面只显示“编辑基础配置”按钮。
  - 点击后弹窗编辑名称、子域名、Zone、服务类型、URL、自动启动。
- 路由列表：
  - 顺序。
  - 目标域名。
  - 路径。
  - 服务。
  - 来源。
  - 操作。
- 拓扑图：
  - 域名节点。
  - Cloudflare 出口节点。
  - 隧道节点。
  - 服务节点。
  - 点阵画布和曲线连接。
- 路由操作：
  - 添加路由。
  - 编辑路由。
  - 删除路由。
  - 上移 / 下移。
  - 复制路由。
  - 测试源服务 TCP 连通性。
- 路由弹窗：
  - 子域名 + Zone 下拉。
  - HTTP / HTTPS / TCP / SSH + URL。
  - 完整主机名实时预览。
- 全部捕获规则：
  - 默认显示 `http_status:404`。
- 运行控制：
  - 启动、停止、重启。

自动托管隧道的路由只读，来源显示为“反向代理规则”，并提示到“反向代理”页维护。

---

## 三、Cloudflare 账号与二进制

### 3.1 账号配置

实现文件：

- `internal/cloudflared/cloudflare_api.go`
- `internal/cloudflared/service.go`

已实现：

- 保存 Account ID + API Token。
- API Token 加密存储。
- Token 掩码回显。
- 调用账号级 `tokens/verify` 验证 Token。
- 查询当前 Token 可访问的 Zone。
- 根据域名向上查找所属 Zone。
- 创建、读取、删除 Cloudflare 隧道。
- 获取隧道 Token。
- 读取和覆盖远端 ingress。
- 创建、更新、删除 DNS CNAME。
- 只读检测 Cloudflare Access。

### 3.2 cloudflared 二进制

实现文件：

- `internal/cloudflared/binary.go`

已实现：

- 内置多种下载镜像。
- 下载并原子替换本机 cloudflared。
- 校验文件大小和可执行性。
- 显示当前版本。
- 查询 GitHub 最新版本。
- 下载指定版本。
- 保留上一版并支持回滚。

版本显示统一为语义版本，例如：

```text
2026.9.3
```

---

## 四、隧道生命周期

实现文件：

- `internal/cloudflared/service.go`
- `internal/cloudflared/manager.go`
- `internal/cloudflared/store.go`

已实现：

- 通过 Cloudflare API 创建命名隧道。
- 生成本地凭据：
  - `creds.json`
  - `config.yml`
  - `cloudflared.log`
- 支持隧道模式模型：
  - `account-local`
  - `token-local`
  - `token-remote`
- 进程托管：
  - 启动。
  - 停止。
  - 重启。
  - 崩溃后读取日志尾部便于诊断。
- 开机启动：
  - 全局托管开启时，应用启动会恢复全部隧道。
  - “随 Havline 自动启动”开关保留为隧道级选项。
- 全局总开关：
  - 开启时启动全部隧道。
  - 关闭时停止全部隧道。
- 凭据刷新：
  - 重新获取隧道 Token。
  - 更新本地 `creds.json`。
  - 运行中时自动重启。

---

## 五、出口抽象与反向代理规则

实现文件：

- `internal/proxy/proxy.go`
- `internal/service/proxy.go`
- `internal/cloudflared/service.go`

迁移：

- `migrations/035_proxy_exits.sql`

已实现：

- 反向代理规则增加出口字段：
  - `local`
  - `cloudflare`
- 支持同时选择：
  - 本机 Nginx + Cloudflare。
- Cloudflare 出口增加目标隧道：
  - `cf_tunnel_id`
- 规则变化自动同步：
  - 新增规则。
  - 修改规则。
  - 删除规则。
  - 启停规则。
- 托管隧道 ingress 从规则派生：
  - 每条域名使用自己的回源地址。
  - 仅同步启用的 Cloudflare 出口规则。
- 仅 Cloudflare 出口的规则不生成无用的本机 Nginx server。
- 规则保存成功但 Cloudflare 同步失败时：
  - 本地规则仍保存。
  - 返回 `sync_warning`。
  - 前端显示警告而不是把整次保存判为失败。

---

## 六、路由与 ingress

实现文件：

- `internal/cloudflared/routes.go`
- `internal/cloudflared/config.go`

已实现：

- 手工隧道路由来自本地 `config.yml`。
- 托管隧道路由来自反向代理规则。
- 路由列表支持：
  - 添加。
  - 编辑。
  - 删除。
  - 上移 / 下移。
  - 复制。
  - 源服务连通性测试。
- 保存路由时：
  - 重新生成本地 `config.yml`。
  - 覆盖 Cloudflare 云端 ingress。
  - 同步 DNS。
  - 运行中时重启 cloudflared。
- 末条 catch-all 固定为：
  ```text
  http_status:404
  ```
- 通配路径处理：
  - UI 显示 `*`。
  - 发送到 Cloudflare 时省略 `path`。
  - 避免 `*` 被当作非法正则。
- 支持正则 path 的后端字段，但当前页面主要使用通配路径。

### P0：接入与调和

- Cloudflare 页面新增“接入向导”。
- 接入预检检查：
  - cloudflared 二进制。
  - Account ID。
  - API Token。
  - Zone 权限。
- 隧道列表新增“调和”列：
  - 已同步。
  - 有漂移。
  - 手工隧道。
- 有漂移时可一键修复：
  - 以本地规则覆盖 Cloudflare 云端配置。

---

## 七、DNS 管理

实现文件：

- `internal/cloudflared/cloudflare_api.go`
- `internal/cloudflared/service.go`
- `internal/cloudflared/store.go`

迁移：

- `migrations/035_proxy_exits.sql`

已实现：

- 自动创建 CNAME：
  ```text
  <hostname> -> <tunnel-id>.cfargotunnel.com
  ```
- 开启 Cloudflare 代理（橙云）。
- 记录 Havline 创建或接管的 DNS 记录：
  - `cf_dns_records`
- 删除域名或移除出口时：
  - 只删除 Havline 自己接管的记录。
- 不覆盖指向其他目标的用户 DNS 记录。
- 域名从一条隧道迁移到另一条隧道时支持接管迁移。

---

## 八、状态、指标与日志

实现文件：

- `internal/cloudflared/manager.go`
- `internal/cloudflared/health.go`

已实现：

- 从 cloudflared metrics 端口读取：
  - HA 连接数。
  - 延迟。
  - 上下行速率。
  - 传输协议。
- 隧道列表实时状态。
- 配置页指标卡。
- 日志中心新增“Cloudflare 隧道”页签：
  - 选择隧道。
  - 查看 200 / 500 / 2000 行日志。
  - 关键词筛选。

---

## 九、健康巡检、通知与状态页

迁移：

- `migrations/036_cf_health.sql`

实现文件：

- `internal/cloudflared/health.go`
- `internal/monitor/monitor.go`
- `internal/app/monitor_source.go`

已实现：

- 记录 Cloudflare 域名健康状态变化：
  - `up`
  - `down`
  - `unknown`
- 24 小时可用率。
- 不可用区间。
- 巡检复用现有：
  - 路由健康开关。
  - 隧道断开通知开关。
  - 连续失败阈值。
- 连续不通和恢复复用通知事件 `tunnel_down`。
- 公开状态页合并：
  - FRP 路由。
  - Cloudflare 路由。
- 状态页展示每条路由的不可用区间：
  - 开始时间。
  - 持续分钟数。
  - 原因。
- 状态页只显示域名、来源、状态和可用率，不泄露隧道 ID 与内网地址。

---

## 十、仪表盘

实现文件：

- `internal/api/status_handler.go`
- `web/src/views/DashboardView.vue`

已实现：

- `/api/status` 增加：
  - Cloudflare 隧道总数。
  - 在线数。
  - 状态。
  - 摘要消息。
- 仪表盘健康列表增加“Cloudflare 隧道”条目。

---

## 十一、备份与恢复

实现文件：

- `internal/backup/service.go`

已实现：

- 备份内容包含：
  - `havline.db`
  - `certs`
  - `nginx`
  - `cloudflared/tunnels`
- `cloudflared/tunnels` 包含：
  - `config.yml`
  - `creds.json`
- 数据库中的 `cf_tunnels`、`cf_settings`、`cf_dns_records` 随 `havline.db` 恢复。
- 恢复后仍建议重启 Havline，由启动流程恢复全部隧道。

---

## 十二、漂移检测与诊断

实现文件：

- `internal/cloudflared/operations.go`

已实现：

### 12.1 漂移检测

- 比较本地规则派生 ingress 与 Cloudflare 云端 ingress。
- 检出：
  - 本地有、云端缺失。
  - 云端有、本地已移除。
  - 回源地址不一致。
- 支持“以本地覆盖”：
  ```text
  POST /api/cloudflare/tunnels/{id}/sync
  ```
- 当前未实现“以云端为准拉取”。

### 12.2 一键诊断

检查项：

- cloudflared 二进制。
- 本地 `config.yml`。
- 隧道进程状态。
- Cloudflare API 与云端配置可访问性。
- Havline 接管的 DNS 记录。
- Cloudflare edge region1。
- Cloudflare edge region2。

---

## 十三、NAS 场景能力

实现文件：

- `internal/discovery/service.go`
- `web/src/views/ProxyView.vue`

已实现：

- 服务发现目录包含：
  - 飞牛 fnOS
  - AList
  - Jellyfin
  - PhotoPrism
  - qBittorrent
  - Portainer
  - Home Assistant
  - Immich
  - AdGuard Home
  - Synology DSM
- 反向代理页“扫描服务”打开发现列表。
- 点击“发布”会：
  - 预填服务名称。
  - 预填内网 upstream。
  - 若已有托管隧道，自动选择 Cloudflare 出口。
  - 打开规则编辑表单等待填写域名。

当前不是完全一键创建，仍需要用户填写域名并确认保存。

---

## 十四、安全与保护提示

已实现：

- Cloudflare Tunnel 条款提示：
  - 不适合持续大文件/视频分发。
- 仅 Cloudflare 出口时：
  - 提示无需申请本机 HTTPS 证书。
- Access 只读检测：
  - 检测域名是否已有 Access 应用。
  - 不代配 Access 策略。
- API Token 权限提示：
  - `Account: Cloudflare Tunnel: Edit`
  - `Zone: Zone: Read`
  - `Zone: DNS: Edit`
  - Zone Resources 必须包含待发布根域名。

---

## 十五、当前 API

### 隧道

```text
GET    /api/cloudflare/tunnels
POST   /api/cloudflare/tunnels
GET    /api/cloudflare/tunnels/{id}
PUT    /api/cloudflare/tunnels/{id}
DELETE /api/cloudflare/tunnels/{id}
POST   /api/cloudflare/tunnels/{id}/start
POST   /api/cloudflare/tunnels/{id}/stop
POST   /api/cloudflare/tunnels/{id}/restart
POST   /api/cloudflare/tunnels/{id}/credentials/refresh
GET    /api/cloudflare/tunnels/{id}/status
GET    /api/cloudflare/tunnels/{id}/logs
GET    /api/cloudflare/tunnels/{id}/config
GET    /api/cloudflare/tunnels/{id}/routes
PUT    /api/cloudflare/tunnels/{id}/routes
POST   /api/cloudflare/routes/test
GET    /api/cloudflare/tunnels/{id}/drift
POST   /api/cloudflare/tunnels/{id}/sync
GET    /api/cloudflare/tunnels/{id}/diagnostics
```

### 二进制与配置

```text
GET    /api/cloudflare/binary
POST   /api/cloudflare/binary/download
GET    /api/cloudflare/binary/latest
POST   /api/cloudflare/binary/rollback
GET    /api/cloudflare/settings
PUT    /api/cloudflare/settings
POST   /api/cloudflare/settings/test
POST   /api/cloudflare/enabled
GET    /api/cloudflare/preflight
```

### Zone、候选与 Access

```text
GET    /api/cloudflare/ingress-candidates
GET    /api/cloudflare/zones
GET    /api/cloudflare/access-status
```

---

## 十六、数据表

### `cf_tunnels`

保存隧道基础信息：

- 名称。
- 模式。
- Tunnel ID。
- Account Tag。
- 加密后的凭据。
- 配置、凭据、日志路径。
- 网络设置。
- 运行状态。
- metrics 端口。
- 自动启动选项。
- 是否自动托管。

### `cf_settings`

保存应用级配置：

- Account ID。
- 加密后的默认 Token。
- 加密后的 API Token。
- 下载镜像。
- 默认网络设置。
- 全局托管开关。

### `cf_dns_records`

保存 Havline 接管的 DNS 记录：

- 本地隧道 ID。
- Zone ID。
- DNS Record ID。
- Hostname。

### `cf_health_events`

保存 Cloudflare 域名健康状态变化：

- 隧道 ID。
- 域名。
- 状态。
- 原因。
- 详情。
- 时间。

### `proxy_rules` 扩展

- `exits_json`
- `cf_tunnel_id`

---

## 十七、当前未完成或仅部分实现

以下能力尚未完成，不能按“已实现”宣传：

1. 完整审计日志
   - 尚未记录“谁在何时修改了规则、出口、凭据和设置”。

2. 云端配置拉取
   - 漂移检测支持“本地覆盖云端”。
   - 尚不支持“云端覆盖本地”。

3. 完整无感令牌轮换
   - 当前是“刷新/重新获取隧道凭据”。
   - 尚未实现创建新隧道后无缝迁移全部规则。

4. Access 策略管理
   - 只做只读检测。
   - 不创建、不修改 Access 应用。

5. 完全一键服务发布
   - 当前是扫描、预填、打开表单。
   - 仍需要用户填写域名并确认保存。

6. 正则路径 UI
   - 后端路由模型支持 `path`。
   - 当前页面主要使用通配路径，尚未提供独立的 path 高级编辑控件。

7. 多 Cloudflare 账号
   - 当前应用配置只支持一个 Account ID + API Token。
   - `cert.pem` / 多账号模式尚未实现。

---

## 十八、验证基线

当前实现覆盖以下验证：

```text
go test ./... -count=1
go vet ./...
cd web && npm run typecheck
cd web && npm test -- --run
cd web && npm run build
```

新增或重点测试：

- 出口默认值、持久化与过滤。
- Cloudflare 按规则生成 ingress。
- Cloudflare 健康状态与可用率计算。
- 手工 config 路由解析。
- 通配 path 不发送非法正则。
- DNS 记录归属。
- 备份包含 cloudflared 隧道配置。
- 漂移比较。