[优化] Phase2

docs/design/architecture.md

@@ -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 客户端在内网运行，与公网节点概念不同，使用独立的注册和认证体系       |
 
 ## 贡献者阅读建议