产品边界
你会学到：OpenFlare 是什么、当前稳定能力，以及开发时应遵守的核心产品边界与仓库结构目录分工。
OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景。
项目定位
OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具备以下定位：
- 控制与落地分离：Server 控制面不直接 SSH 到代理节点，而是通过 Agent 主动拉取版本并应用。
- 不可变配置发布：采用完整的配置版本进行预览、发布、激活和一键回滚。
- 一体化网关托管：在同一个控制面内集成网站反代、TLS 证书自动续期申请、WAF 防护拦截、内网穿透（Tunnel）以及 Pages 静态网站托管。
非本产品定位：多租户云平台、Kubernetes Ingress Controller、服务网格或通用日志平台。
当前能力
| 能力 | 说明 | 详细设计/使用指南 |
|---|---|---|
| 反代配置管理 | 以网站规则（Proxy Route）为聚合边界，支持多域名与多上游负载均衡 | 新建反代配置 |
| 配置版本控制 | 支持全局单一激活版本的预览、发布、不可变快照历史与秒级一键回滚 | Agent 与发布模型 |
| WAF 安全防护 | 全局与自定义规则组，支持手动/自动/订阅型 IP 组，GeoIP 准入与 PoW CC 防护 | WAF 设计 / WAF 使用指南 |
| 内网穿透 | 通过中继节点（Relay）与内网客户端（OpenFlared），反向穿透暴露内网 Web 服务 | 内网穿透设计 / 穿透使用指南 |
| Pages 静态托管 | 直接上传前端 zip 包，由边缘节点拉取并由 OpenResty 本地服务，支持 API 反代与 SPA Fallback | Pages 静态托管设计 |
| TLS 证书自动续期 | 绑定 managed_domains 并通过 ACME 协议向 Let's Encrypt 申请/续期证书 | 新建反代配置 |
| 多节点监控与观测 | 收集节点资源快照、健康事件，聚合请求指标与访问日志明细 | 系统架构 |
核心产品边界与约束
在开发与贡献代码时，必须严格遵守以下业务边界与技术约束，禁止为了临时需求而绕过限制：
1. 网站配置与上游约束
- 单站点域名共享策略：一条路由规则对应一个网站，该站点下的多域名共享限流、缓存与反代上游等配置，不支持在同一规则内为不同域名做差异化服务配置。
- 上游类型互斥：上游必须是直连地址（
direct）、内网穿透（tunnel）或 Pages 静态托管（pages）三者之一，不允许在同一规则中混用。 - 直连类型限制：直连上游可以是纯
http://或https://的单个或多个地址（多地址仅支持纯scheme://host[:port]），不支持非 HTTP 协议（如 TCP/UDP）上游。
2. WAF 安全边界
- 白名单优先原则：白名单拥有绝对匹配权。若未命中白名单规则，才依次触发全局和自定义黑名单过滤。
- GeoIP 弱依赖性：地域准入解析完全依赖节点本地 MaxMind 库。当 GeoIP 异常或解析失败时，系统必须自动忽略地域规则，绝对不能破坏 IP 组过滤和反代主链路的可用性。
- 运行时数据解耦：OpenResty 拦截时仅读取 Agent 同步至本地的 JSON，不与 Server 数据库通信。IP 组成员同步与版本发布解耦，通过 Checksum 差分拉取以实现零重载平滑生效。
3. 内网穿透边界
- 仅限 HTTP 流量：穿透组件仅支持 HTTP/HTTPS 协议（底层依靠 frp 虚拟主机 Vhost 机制实现单端口域名路由复用），暂不支持单独的 TCP/UDP 端口分配。
- 中继配置动态化控制：中继节点（Relay）在连接至 Server 后，可通过心跳周期性动态拉取并同步全局系统配置（例如是否开启内嵌 FRPS Web UI 及其监听端口），但不直接纳入控制面的不可变配置版本发布体系。
- Tunnel 与 Node 体系隔离：Tunnel 客户端在内网发起出向建连，与控制面托管的边缘 Node（公网节点）是独立的实体，使用专属的
tunnel_token进行鉴权。
4. Pages 静态托管边界
- Direct Upload 托管模式：仅支持直接上传预构建的 ZIP 静态资源包。不支持外部 Git 仓库自动构建、边缘 Serverless 函数、动态 SSR 服务或生成的二级预览域名。
- 包体硬上限限制：为了保障边缘节点安全，ZIP 压缩包体最大 25 MiB，解压文件树不超过 1,000 个且总体积不超过 100 MiB。禁止上传含有任何软链接或目录跨越（Zip-Slip）的安全高危压缩包。
5. 系统与版本边界
- 全局单一激活版本：所有节点拉取并消费同一份全局激活配置。不进行按节点分组的差异化配置发布。
- 单租户架构：OpenFlare 仅供单团队在受信任的内部网络部署使用。采用单租户设计，不支持细粒度的多用户角色或多租户资源隔离。
- 外部基础设施依赖性：Server 虽支持 SQLite 作为本地轻量关系数据库，但系统必须强制依赖外部 Redis（或 Valkey）及 ClickHouse 实例。Redis 用于处理分布式协调、后台异步队列（Asynq 框架）及系统级全局缓存；ClickHouse 用于接收海量节点访问日志与基础观测的异步 Flush。系统不支持完全脱离这两个组件运行。
仓库结构
OpenFlare 已收敛为单 monorepo（Go 模块 github.com/Rain-kl/Wavelet）。控制面 Server 与边缘组件（Agent、Relay、OpenFlared）共享同一仓库，业务代码按 Wavelet internal/apps/ 领域模块组织。
在贡献代码时，请严格遵守以下物理分层与目录分工：
| 路径 | 职责 |
|---|---|
main.go | Server 唯一入口，委派给 internal/cmd/ |
cmd/agent、cmd/relay、cmd/flared | 边缘组件 CLI 入口（不含 Server） |
internal/ | 控制面与边缘运行时实现 |
frontend/ | Next.js 管理端，构建产物嵌入 Go Server |
pkg/ | 跨组件共享库（协议、渲染、GeoIP 等） |
scripts/ | Swagger 生成、安装脚本等 |
docs/ | VitePress 文档站与设计基线 |
docker/ | 各组件 Dockerfile |
uploads/、data/ | 运行时上传目录与静态数据（.gitignore 忽略） |
1. Server 分层（main.go + internal/）
| 目录 | 职责 |
|---|---|
main.go | Server 启动入口 |
internal/cmd/ | Cobra 子命令：api、worker、scheduler、all（默认融合模式） |
internal/bootstrap/ | 跨模块装配：任务 Handler、推送域事件、进程级初始化 |
internal/router/ | HTTP 路由注册与全局中间件 |
internal/router/v1/openflare/ | OpenFlare 路由注册器（register_*.go） |
internal/apps/openflare/ | OpenFlare 控制面业务域（routers.go + logics.go） |
internal/apps/{admin,user,oauth,upload,cap,...}/ | Wavelet 平台能力（用户、认证、任务、推送等） |
internal/apps/openflare/{agent,relay,flared}/ | Server 侧边缘协议处理器（鉴权、心跳、WS） |
internal/model/ | GORM 实体（openflare_*.go + 平台模型） |
internal/db/migrator/goose/ | goose SQL 迁移（PostgreSQL / SQLite / ClickHouse） |
internal/repository/ | 平台域数据访问层 |
internal/task/ | Asynq 异步任务（Worker + Scheduler） |
internal/config/ | Viper 配置加载 |
internal/common/ | 统一 API 响应封装（response/） |
pkg/protocol/ | Relay / Tunnel 共享 HTTP/WS 协议结构 |
pkg/render/、pkg/geoip/、pkg/wsclient/ | OpenResty 配置渲染、GeoIP、WebSocket 客户端 |
API 路由前缀：
| 前缀 | 用途 | 鉴权 |
|---|---|---|
/api/v1/d/* | OpenFlare 管理控制台 API | Session Cookie + 可选 X-Access-Token |
/api/v1/agent/* | Agent 节点协议 | X-Agent-Token |
/api/v1/relay/* | Relay 中继协议 | X-Agent-Token |
/api/v1/tunnel/* | Tunnel 客户端协议 | X-Tunnel-Token |
/api/v1/admin/* | Wavelet 平台管理 API | 管理员 Session |
2. Agent 模块 (internal/apps/agent/ / cmd/agent/)
| 目录/模块 | 职责 |
|---|---|
cmd/agent/ | Agent 命令行启动入口及主函数 |
internal/apps/agent/config/ | 配置读取与默认值 |
internal/apps/agent/heartbeat/ | 心跳与版本摘要判断 |
internal/apps/agent/sync/ | 配置拉取与应用编排 |
internal/apps/agent/nginx/ | OpenResty 文件写入、校验、reload、启动与回滚 |
internal/apps/agent/state/ | 本地状态与观测补报缓冲 |
internal/apps/agent/httpclient/ | Server 通信 |
internal/apps/agent/wsclient/ | WebSocket 客户端通信 |
internal/apps/agent/protocol/ | Agent API 协议类型 |
internal/apps/agent/updater/ | Agent 自更新逻辑 |
internal/apps/agent/logging/ | 日志处理 |
internal/apps/agent/observability/ | 可观测性（指标、链路等） |
internal/apps/agent/geoipdata/ | GeoIP 数据处理 |
internal/apps/agent/geoipupdate/ | GeoIP 数据更新 |
internal/apps/agent/agent/ | 核心 Agent 逻辑与生命周期 |
3. Frontend 分层 (frontend/)
基于 Wavelet Next.js 脚手架，OpenFlare 业务 UI 以路由共置方式组织在 app/(main)/ 下。
| 目录 | 职责 |
|---|---|
app/ | Next.js App Router；(main) 控制台、(auth) 认证、(docs) 文档页 |
app/(main)/<domain>/ | 业务页面与域内组件（路由共置） |
components/ | 跨域复用 UI（ui/、layout/、common/ 等） |
lib/services/ | API 服务层：core/ 基类 + openflare/ 业务 API |
lib/navigation/ | OpenFlare 侧栏导航配置（openflare-nav.ts） |
lib/theme/ | 主题解析与切换 |
contexts/ | 跨页面 UI 状态（用户、通知等） |
hooks/、lib/hooks/ | 可复用 React Hooks |
public/ | 静态资源与主题 CSS |
scripts/ | 构建辅助脚本 |
proxy.ts | 开发/生产代理：API 限流与页面鉴权 |
API 约定：OpenFlare 业务接口统一前缀 /api/v1/d/*，通过 OpenFlareBaseService 封装；页面数据获取使用 @tanstack/react-query。
4. Relay 模块 (internal/apps/relay/ / cmd/relay/)
| 模块 | 职责 |
|---|---|
cmd/relay/ | Relay 命令行启动入口及初始化主函数 |
internal/apps/relay/config/ | 本地配置文件解析与默认参数初始化 |
internal/apps/relay/frps/ | 管理 frps 进程生命周期、端口与 Token 并监控运行 |
internal/apps/relay/heartbeat/ | 周期性 HTTP 心跳通信、上报状态并获取更新请求 |
internal/apps/relay/httpclient/ | Server 的通用 API 客户端调用工具类 |
internal/apps/relay/observability/ | 采集本地宿主机、frps 的基础运行指标并进行预聚合 |
internal/apps/relay/relay/ | 协调中继的核心生命周期、初始化与清理 |
internal/apps/relay/state/ | 本地运行时状态、错误记录与持久化缓存 |
internal/apps/relay/updater/ | Relay 升级检查、下载安装与重启机制 |
internal/apps/relay/wsclient/ | 与 Server 保持的长连接 WebSocket 双向通信管道 |
5. OpenFlared (Client) 模块 (internal/apps/flared/ / cmd/flared/)
| 模块 | 职责 |
|---|---|
cmd/flared/ | Client 命令行启动入口及初始化主函数 |
internal/apps/flared/config/ | 本地客户端配置加载与解析 |
internal/apps/flared/flared/ | 内网穿透客户端的核心调度与状态管理机制 |
internal/apps/flared/frpc/ | 热重载/动态生成多 Relay 的 frpc_{relayNodeID}.toml 并监控 frpc |
internal/apps/flared/heartbeat/ | 与控制面进行的心跳通信，包含 Token 校验机制 |
internal/apps/flared/httpclient/ | 客户端通用 API 通信（/api/v1/tunnel/*） |
internal/apps/flared/sync/ | 增量拉取最新 Tunnel 路由绑定关系、生成快照并应用 |
internal/apps/flared/updater/ | 客户端自更新、新版检查与更新落地逻辑 |
internal/apps/flared/wsclient/ | 用于实时监听 Server 端隧道配置变更推送的 WS 信道 |
说明：OpenFlared 无独立
state/包；版本与 checksum 由frpc/manager.go持久化到flared-state.json。
文档维护原则
- 产品范围或系统边界变化：更新本文档（产品边界）。
- 系统结构、组件分工变化：更新 系统架构。
- 发布、同步、回滚与 Agent 模型变化：更新 Agent 与发布模型。
- 部署方式变化：更新 部署说明 与 README。
- 配置项变化：更新 配置项参考。