# 系统架构 你会学到：OpenFlare 的整体架构、各核心组件（Server, Agent, OpenResty, Relay, Client）的职责分工，以及主要数据与请求流的宏观流向。 OpenFlare 是一套自托管的 OpenResty 控制面。它在物理上由 Server（控制面）、Agent（配置落地端）、节点本地 OpenResty（数据面）、内网穿透组件（Relay 与 OpenFlared，数据面扩展）以及管理端前端组成。 --- ## 流量路径概览 根据不同的网站上游类型，OpenFlare 支持三种不同的数据面流量路径： ### 1. 标准反代流量路径 ```text Browser | | HTTPS/HTTP request v OpenResty (WAF, TLS, Rate Limit, 可选源站错误页) | | reverse proxy (proxy_pass) v Origin Server (直连公网/局域网上游) ``` 源站或网关返回配置列表内错误状态码时，可返回全局自定义/默认 HTML，且保持真实 HTTP 状态码；详见 [源站错误页设计](./origin-error-page.md)。 ### 2. 内网穿透流量路径 适用于内网受限服务器上的源站服务接入： ```text Browser | | HTTPS/HTTP request v OpenResty (Agent 宿主机, TLS/WAF) | | proxy_pass http://localhost:vhost_port (Host header preserved) v OpenFlareRelay (frps) <-- 与 Agent 同机部署，提供中继 | | frp tunnel protocol (Host header routing) v OpenFlared (frpc) <-- 内网受限服务器 | | HTTP/HTTPS forward v Internal Service (192.168.x.x) ``` ### 3. Pages 静态托管流量路径 适用于预构建的单页应用（SPA）或静态网站托管： ```text Browser | | HTTPS/HTTP request v OpenResty (Agent, TLS/WAF) | +---> [静态服务] root/try_files ---> Agent 本地 Pages 部署目录 | +---> [API 反代] proxy_pass ---> 后端 API 服务 (如果启用了 API 代理) ``` --- ## 组件职责 | 组件 | 职责 | 详细设计参考 | | --------------- | ---------------------------------------------------------------------- | ------------ | | **Server** | 管理端 UI/API、控制面状态持久化、配置编译渲染、发布版本控制、Pages 部署包存储、Cloudflare A 记录指向、访问日志入库与业务流量聚合、Uptime Kuma 监控同步与登录验证码防护 | [Agent 与发布模型](./agent-design.md) / [Cloudflare DNS 指向设计](./cloudflare-pointing.md) / [边缘可观测与业务流量统计](./observability-design.md) / [Uptime Kuma 监控同步设计](./kuma-design.md) / [登录验证码设计](./login-captcha.md) | | **Agent** | 周期心跳与 WS 同步、静态资源包拉取与解压、OpenResty 配置写入/校验/重载与自愈；观测仅上报访问明细与主机/健康读数，不做业务预聚合 | [Agent 与发布模型](./agent-design.md) / [边缘可观测与业务流量统计](./observability-design.md) | | **OpenResty** | 接收真实流量，执行 WAF 过滤、PoW 防护、Basic Auth 认证、静态/反代服务与可选源站错误页 | [WAF 设计](./waf-design.md) / [Pages 设计](./pages-design.md) / [源站错误页设计](./origin-error-page.md) | | **Relay** | 部署于边缘节点，管理 `frps` 守护进程生命周期，接受心跳派发的穿透中继配置 | [内网穿透设计](./tunnel-design.md) | | **OpenFlared** | 部署于内网，管理 `frpc` 进程组，向多个 Relay 建立反向隧道，上报连接状态 | [内网穿透设计](./tunnel-design.md) | --- ## 组件架构与分工 ### 1. Server (控制面) 仓库根目录的 Go 后端（模块 `github.com/Rain-kl/Wavelet`）是 OpenFlare 控制面，基于 Wavelet 全栈脚手架构建： * 提供管理端 REST API（`/api/v1/d/*`），通过 **Session Cookie** 鉴权，可选 `X-Access-Token` 访问令牌。 * 边缘节点协议走 `/api/v1/agent|relay|tunnel/*`，分别使用 `X-Agent-Token` / `X-Tunnel-Token` 鉴权。 * 包含配置编译器（Compiler），将数据库中的规则、证书与全局参数统一编译为不可变的配置快照及 OpenResty 物理配置文件文本。 * 统一接收 Pages 本地上传、Remote URL 与公开 GitHub Release 预构建产物，完成来源检查、受限下载、归档校验和不可变 deployment；manual 上传生成待显式激活的 candidate，持久来源 sync 才 create-or-load 并原子激活。Server 向 Agent 提供受控的 latest 下载接口；内部 scanner 负责 GitHub latest 的限量检查、租约恢复、可选自动发布与孤儿上传记录补偿，通用任务管理入口不能修改该排程。未来仓库源码构建由独立 Server build executor 扩展，Agent 不执行第三方拉取或构建命令。 * 提供可选的 Cloudflare DNS 指向控制面：以 ZoneDomain 为成员维护分组期望状态，通过 Asynq 将单条 A 记录幂等同步到当前生效节点 IPv4；节点 IP 变化只做 best-effort 入队，一期不执行自动故障切换。 * 后台集成 Uptime Kuma 监控同步服务，自动为可用站点维护 HTTP 探测任务。 * 启动入口为根目录 `main.go` + `internal/cmd/`（`api` / `worker` / `scheduler` / `all`）；OpenFlare 业务在 `internal/apps/openflare/`，边缘协议处理在 `internal/apps/openflare/{agent,relay,flared}/`。 * *详细设计请参阅：[Agent 与发布模型设计](./agent-design.md) 以及 [Uptime Kuma 监控同步设计](./kuma-design.md)* ### 2. Agent (配置落地端) `openflare-agent` 是运行在节点本地的守护进程： * 启动后维持与控制面的周期性心跳，并通过可选的 WebSocket 接收实时的配置发布广播。 * 负责拉取最新激活版本的配置文件及证书，写入本地目录，并通过 `openresty -t` 执行安全校验后平滑重载 (`reload`)。 * 在本地处理 Pages 部署包的下载、SHA-256 校验与解压缩切换。 * *详细设计请参阅：[Agent 与发布模型设计](./agent-design.md)* ### 3. OpenResty (数据面) 接收访客流量并执行最终的业务落地： * 流量入口，支持 HTTP/2、HTTP/3（QUIC）和 TLS 证书动态绑定。 * 嵌入 Lua 逻辑，在 `access_by_lua` 阶段高效过滤 WAF 规则、验证工作量证明 (PoW) 挑战，并在此之后执行连接数/速率限制及基础缓存（策略见 [边缘缓存策略设计](./edge-cache-design.md)）。 * *详细设计请参阅：[WAF 设计文档](./waf-design.md) 与 [Pages 静态托管设计文档](./pages-design.md)* ### 4. Relay 与 OpenFlared (穿透组件) 扩展数据面反穿透能力： * `openflare-relay` 守护本地 `frps`，接受 Server 的配置派发，自动更新中继端口。 * `openflared` 在内网守护一组 `frpc` 客户端进程，实现多中继就近建连与高可用容灾。 * *详细设计请参阅：[内网穿透隧道设计文档](./tunnel-design.md)* --- ## 数据与请求流概览 ### 1. 配置发布与同步流 ```text 管理端修改配置 -> 发布新版本 -> 生成全局唯一 Checksum 激活版本 | +------------------+------------------+ | (WebSocket 广播或周期 Heartbeat) | v v [边缘节点 Agent] [内网 OpenFlared] 拉取最新 OpenResty 配置/证书 拉取最新 Tunnel 映射配置 增量拉取/解压 Pages 静态部署包 生成/重写 frpc.toml Nginx 校验配置并平滑重载 (reload) 平滑重载或拉起 frpc 进程 上报应用状态 (Success / Error) 上报隧道连接状态与活跃指标 ``` * *同步与自愈的精细时序及回滚模型详见：[Agent 与发布模型设计](./agent-design.md)* ### 2. 静态托管与 API 代理流 * 静态资源解压落地于 Agent 节点的 `projects/{project_id}/current` 下（按项目 latest 拉取，仅保留最新包），OpenResty 通过 `root`/`index`/`try_files` 在边缘直接提供静态资源服务。 * 当启用 API 代理时，OpenResty 自动根据站点配置的 `api_proxy_path`（如 `/api`）将 API 请求重写并转发（`proxy_pass`）给后端动态接口。 * 管理员操作和内部 scanner 都只生成受约束的 artifact candidate，并复用统一 inspect、`upload.Ingest` 与 deployment pipeline。manual 上传创建新的未激活 candidate；持久来源 sync/scanner 才 create-or-load 并原子激活。未来 repository build executor 也只能向同一 artifact pipeline 输出产物；Agent 始终只是 active deployment 消费者。 * *部署包校验、解压逃逸防御及 Nginx 规则渲染详见：[Pages 静态托管设计文档](./pages-design.md)* ### 3. WAF 安全过滤流 * WAF 引擎嵌入在 OpenResty 请求生命周期中。 * WAF 规则由控制面以可视化 DAG 编排，发布时编译为运行态图；OpenResty reload 后由每个 Worker 加载一次，后续请求只遍历内存对象。 * 全局规则固定前置，路由绑定规则按显式顺序执行；当前规则抵达“通过”后继续下一条，抵达“阻止”则立即返回该节点配置的拦截响应。 * IP 组成员独立热更新：协调 Worker 每 5 秒检查一次 checksum，仅在变化时加载完整快照，各 Worker 的请求路径始终读取本地内存对象。 * *IP 组来源与同步机制详见：[WAF 设计文档](./waf-design.md)；图模型、执行语义与发布约束详见：[WAF 可编排规则设计](./waf-orchestration-design.md)。* ### 4. 边缘可观测与业务流量统计流 ```text OpenResty access.log（业务事实） | | Agent tail 增量明细（不 sum/count/uniq） v Server 经 logstore 入库（当前日志主库：PostgreSQL / SQLite / ClickHouse） | +---> 全局聚合 --> 看板「已提供数据 / 请求 / UV」 +---> host∈Zone --> Zone「已提供数据」等（同一套语义） +---> node_id 过滤 --> 节点业务量 主机 /proc 网卡与 CPU 等 --> Agent 读数快照 --> 宿主机资源趋势（与业务交付分开展示） OpenResty 健康与连接数 --> 边缘健康（瞬时，不作 24h 业务总量） ``` * **原则**：Agent 只上报事实，Server 解释事实；业务流量唯一真相为访问日志。`openresty_tx` 与「已提供数据」不得双轨并存。 * *传输模型、示例与采集频率详见：[观测数据传输模型](./observability-transport-model.md)；字段收敛与迁移详见：[边缘可观测与业务流量统计](./observability-design.md)* ### 5. Cloudflare DNS 指向流 ```text 管理员配置连接/分组/成员 -> Server 持久化期望状态 -> Asynq 同步任务 | v Cloudflare Zone / DNS API | v 单条 A 记录 -> active_node IPv4 节点 IP 手动更新或 Agent 心跳变化 --------------------> 按节点 best-effort 入队 ``` * Cloudflare 模块只管理其缓存或接管的唯一同名 A 记录，不把 Zone 核心扩展为权威 DNS 控制面；同名多 A 时停止同步并要求管理员先在 Cloudflare 清理。 * 分组备用节点与生效节点为后续故障切换预留，一期固定使用主节点，不根据心跳离线状态自动切换。 * *连接、模型、幂等同步与分期边界详见：[Cloudflare DNS 指向设计](./cloudflare-pointing.md)。* --- ## 核心对象 当前系统核心实体包括： * **反代与配置**：`zones` (根域管理边界), `zone_domains` (明确域名与证书/路由关联), `proxy_routes` (路由策略), `origins` (源站), `config_versions` (配置版本), `tls_certificates` (证书). 详见 [Zone 与域名资源设计](./zone-design.md)。 * **Cloudflare DNS 指向**：`of_cf_connections` (全局连接), `of_cf_pointing_groups` (主/备/生效节点与默认橙云), `of_cf_pointing_members` (ZoneDomain 成员、记录缓存与同步状态). 详见 [Cloudflare DNS 指向设计](./cloudflare-pointing.md)。 * **Pages 静态托管**：`of_pages_projects` (Pages项目), `of_pages_project_sources` / `of_pages_project_source_runtime` (可变来源配置与运行态), `of_pages_deployments` (不可变部署), `of_pages_deployment_files` (部署文件清单). * **节点与穿透**：`nodes` (节点), `tunnels` (隧道客户端), `node_system_profiles` (系统概况), `apply_logs` (应用日志). * **WAF 与安全**：`waf_rule_groups` (WAF规则组), `waf_ip_groups` (WAF IP组), `waf_rule_group_bindings` (网站WAF绑定). * **系统与账号**：`acme_accounts` (ACME账户), `dns_accounts` (DNS账户), `geoip_update_configs` (GeoIP更新配置). --- ## 关键设计决策 | 决策 | 原因 | | ------------------------------ | --------------------------------------------------------------------------- | | 完整配置版本，而不是在线 patch | 让预览、激活、历史和回滚有稳定边界，保证节点状态一致 | | Agent 主动拉取 | Server 不需要 SSH 权限，降低安全风险；支持 HTTP 与 WebSocket 双协议灵活切换 | | 全局单激活版本 | 降低控制面复杂度，保证所有节点默认一致；提供一键秒级回滚的稳定机制 | | Zone 域名与路由策略分离 | Zone 提供根域入口与域名边界；路由仍可复用同一套站点级策略并按域名绑定证书 | | Cloudflare 指向独立于 Zone 核心 | ZoneDomain 只提供明确 FQDN；Cloudflare 模块以库表期望状态驱动单 A 记录，不扩大 Zone 为通用 DNS 控制面 | | 内网穿透基于 frp 整合 | 复用成熟隧道协议，避免自研隧道引起稳定性风险；其 Vhost 机制天然适配反代路由 | | 运行时配置与控制库解耦 | WAF 规则发布时编译并随 OpenResty reload 加载；动态 IP 组通过 checksum 驱动的内存快照独立刷新 | | 业务流量以访问日志为唯一真相 | Agent 禁止业务预聚合；看板与 Zone 共用 Server 侧聚合，避免 openresty_tx 与 bytes_sent 双轨 | | 业务交付 / 边缘健康 / 主机资源分层 | 已提供数据≠宿主机网卡出站≠OpenResty 连接数，UI 与 API 分名分区 | | Pages artifact 与仓库构建分离 | 现有来源只导入预构建产物；未来 checkout/build 由 Server 隔离 executor 完成并复用 artifact pipeline，Agent 不执行第三方构建 | ---