[优化] Phase2

2026-10-03 23:06:36 +08:00 · 2026-06-01 08:26:45 +08:00
parent 78047d1b38
commit 4196343ad3
26 changed files with 1814 additions and 350 deletions
@@ -2,7 +2,9 @@

 你会学到：OpenFlare 的整体架构、Server、Agent、OpenResty 与管理端前端的职责边界，以及一次配置发布从管理端到节点生效的请求流。

-OpenFlare 由 Server、Agent、节点本地 OpenResty 和管理端前端组成。Server 是控制面，Agent 是节点侧唯一受控落地入口，OpenResty 是实际数据面。
+OpenFlare 由 Server、Agent、节点本地 OpenResty 和管理端前端组成。Server 是控制面，Agent 是节点侧唯一受控落地入口，OpenResty 是实际数据面。内网穿透场景中，Relay（frps 管理器）和 OpenFlared（frpc 管理器）扩展了数据面流量路径。
+
+### 标准反代流量路径

 ```text
 Browser
@@ -24,14 +26,38 @@ OpenResty binary
 Origin
 ```

+### 内网穿透流量路径
+
+```text
+Browser
+  |
+  | HTTPS request
+  v
+OpenResty (Agent, TLS/WAF)         <-- TunnelRelay 节点
+  |
+  | proxy_pass http://localhost:vhost_port (Host header preserved)
+  v
+OpenFlareRelay (frps)              <-- TunnelRelay 节点，与 Agent 同机部署
+  |
+  | frp tunnel protocol (HTTP Vhost routing by Host header)
+  v
+OpenFlared (frpc)                  <-- 内网服务器
+  |
+  | HTTP/HTTPS forward
+  v
+Internal Service (192.168.x.x)
+```
+
 ## 组件职责

-| 组件      | 职责                                                                   |
-| --------- | ---------------------------------------------------------------------- |
-| Server    | 管理端 UI、管理 API、Agent API、配置渲染、版本发布、数据存储与聚合查询 |
-| Agent     | 注册、心跳、同步、写入文件、校验、reload、失败回滚、自更新与轻量采集   |
-| OpenResty | 接收真实流量，按 OpenFlare 渲染的配置执行 WAF、PoW、认证与反向代理     |
-| Frontend  | 管理网站配置、WAF、源站、证书、节点、版本、用户、设置与观测页面        |
+| 组件            | 职责                                                                   |
+| --------------- | ---------------------------------------------------------------------- |
+| Server          | 管理端 UI、管理 API、Agent/Relay/Client API、配置渲染、版本发布、数据存储与聚合查询 |
+| Agent           | 注册、心跳、同步、写入文件、校验、reload、失败回滚、自更新与轻量采集   |
+| OpenResty       | 接收真实流量，按 OpenFlare 渲染的配置执行 WAF、PoW、认证与反向代理     |
+| OpenFlareRelay  | 管理 frps 进程生命周期，提供隧道中继服务，通过心跳接收 frps 配置       |
+| OpenFlared      | 管理 frpc 进程（可多个），连接 Relay 中继，将流量转发到内网服务        |
+| Frontend        | 管理网站配置、WAF、源站、证书、节点、Tunnel、版本、用户、设置与观测页面 |

 ## Server

@@ -97,6 +123,27 @@ Agent 执行 OpenResty 校验与 reload
 Agent 上报应用结果
 ```

+### Relay 同步流
+
+```text
+Relay HTTP heartbeat -> Server 返回 frps 配置
+Relay 生成 frps.toml 并启动/重启 frps
+Relay 定期上报 frps 状态
+```
+
+Relay 使用与 Agent 相同的 `agent_token` 认证（同一节点），通过 `/api/relay/*` 端点通信。frps 配置相对静态（端口、认证 Token），通过心跳下发，不纳入版本化发布流。
+
+### OpenFlared 同步流
+
+```text
+Client HTTP heartbeat -> Server 返回 tunnel 配置版本摘要
+Client 发现新版本 -> 拉取 tunnel 路由配置（relay 列表 + proxy 定义）
+Client 为每个 Relay 生成 frpc.toml 并启动/重载 frpc 进程
+Client 上报应用结果
+```
+
+OpenFlared 使用独立的 `tunnel_token` 认证，通过 `/api/flared/*` 端点通信。Tunnel 路由配置随发布流程版本化同步，配置变更时优先使用 `frpc reload` 热重载。
+
 **WebSocket 升级流程**（可选，通过 `AgentWebsocketUpgradeEnabled` 选项控制）：

 当启用 WebSocket 升级时：
@@ -126,6 +173,7 @@ WAF 在 OpenResty `access_by_lua_file` 阶段执行。规则来自当前激活
 * `origins`
 * `config_versions`
 * `nodes`
+* `tunnels`
 * `auth_sources`
 * `external_accounts`
 * `node_system_profiles`
@@ -152,6 +200,9 @@ WAF 在 OpenResty `access_by_lua_file` 阶段执行。规则来自当前激活
 | 全局单激活版本                 | 降低 MVP 复杂度，保证所有节点默认一致；支持版本预览、历史查询与一键回滚     |
 | 网站配置聚合多域名             | 支持一个业务站点共享站点级策略，同时允许按域名绑定证书                      |
 | 观测数据服务端聚合             | 避免前端临时统计造成口径不一致                                              |
+| 内网穿透基于 frp 整合          | 复用成熟隧道协议，避免自研隧道的稳定性风险；frps HTTP Vhost 路由天然适配    |
+| Relay/Client 独立二进制         | 职责分离，Relay 管理 frps，Client 管理 frpc，各自独立升级和部署             |
+| Tunnel 与 Node 体系分离         | Tunnel 客户端在内网运行，与公网节点概念不同，使用独立的注册和认证体系       |

 ## 贡献者阅读建议

@@ -31,12 +31,15 @@ OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingre
 | 节点管理 | 节点状态、令牌体系、部署与更新链路 |
 | 管理端前端 | 基于 Next.js 的正式管理端 |
 | 认证源登录 | 支持以认证源形式配置 GitHub 与标准 OIDC 登录入口，并允许第三方账号绑定已有本地用户 |
+| 内网穿透 | 通过 TunnelRelay 节点与 OpenFlared 客户端，将内网 HTTP 服务安全暴露到公网，复用 Agent 的 HTTPS/WAF 能力 |

 默认工作方式：

 * 所有节点消费同一份全局激活版本。
 * Server 保存配置与状态，不直接 SSH 管理节点。
 * Agent 是节点侧唯一受控落地入口。
+* TunnelRelay 节点同时运行 Agent（OpenResty）和 Relay（frps），提供内网穿透中继。
+* OpenFlared 客户端在内网运行，管理 frpc 进程连接 Relay，将流量转发到内网服务。

 ## 典型使用场景

@@ -48,6 +51,7 @@ OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingre
 | 快速回滚 | 重新激活旧版本，让 Agent 拉取并应用 |
 | 证书托管 | 为不同域名绑定 TLS 证书 |
 | 基础观测 | 查看节点状态、请求聚合、访问分析和健康事件 |
+| 内网穿透 | 通过 Tunnel 将无法直接公网访问的内网 HTTP 服务暴露到互联网，享有 HTTPS、WAF 等全部防护能力 |


 ## 网站配置约束
@@ -71,13 +75,45 @@ OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingre

 上游约束：

-* `proxy_routes` 至少包含一个上游地址。
+* `proxy_routes` 至少包含一个上游地址（直连类型），或关联一个 Tunnel（内网穿透类型）。
+* `proxy_routes.upstream_type` 区分上游类型：`direct`（默认，直连）或 `tunnel`（内网穿透）。
 * 为兼容历史数据保留 `origin_url` 主上游字段，也允许在同一规则内补充多个上游做负载均衡。
 * 上游统一渲染为带 keepalive 的 named `upstream`。
 * 单上游可附带 base path 或 query 并在 `proxy_pass` 中追加。
 * 多上游限定为纯 `scheme://host[:port]`。
 * `proxy_routes.origin_host` 为可选字段，用于回源时覆盖 `Host` 请求头。
-* 所有上游地址都必须为合法 `http://` 或 `https://`。
+* 所有直连类型上游地址都必须为合法 `http://` 或 `https://`。
+* 内网穿透类型上游必须关联 `tunnel_id`，并指定内网目标地址与协议。
+
+## 内网穿透约束
+
+OpenFlare 通过 TunnelRelay 节点与 OpenFlared 客户端实现内网穿透，底层基于 frp 构建。
+
+节点类型：
+
+* `nodes.node_type` 区分节点类型：`edge_node`（边缘节点，默认）和 `tunnel_relay`（隧道中继）。
+* TunnelRelay 节点同时运行 Agent（管理 OpenResty）和 Relay（管理 frps），共享同一个 `agent_token`。
+* Agent 负责 HTTPS 终结、WAF 防护等，Relay 负责隧道流量中继。
+
+Tunnel 实体：
+
+* `tunnels` 表存储内网穿透客户端注册信息，与 `nodes` 体系独立。
+* 每个 Tunnel 拥有唯一的 `tunnel_id`（格式 `tun-<32hex>`）和 `tunnel_token`。
+* OpenFlared 客户端使用 `tunnel_token` 认证，通过 `/api/flared/*` 端点通信。
+
+流量路径：
+
+* 数据面：浏览器 → Agent（OpenResty，TLS/WAF）→ Relay（frps，HTTP Vhost 路由）→ 隧道 → Client（frpc）→ 内网服务。
+* frps 使用 HTTP Vhost 单端口复用，通过 Host 头将请求路由到对应 frpc，无需为每个隧道分配端口。
+* Relay 配置（frps 端口、认证 Token）通过心跳下发，相对静态。
+* Tunnel 路由配置（frpc 代理定义）随发布流程版本化同步。
+
+当前阶段约束：
+
+* 仅支持 HTTP 协议隧道流量，保留未来 TCP 隧道扩展性。
+* Tunnel 类型上游的域名 DNS 应仅解析到 TunnelRelay 节点，EdgeNode 上对应请求会因 frps 不可达返回 502。
+* 一个 OpenFlared 客户端可连接多个 Relay（每个 Relay 对应一个 frpc 进程）。
+

 ## HTTPS 约束