diff --git a/AGENTS.md b/AGENTS.md index ba069493..c3a54880 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,65 +2,38 @@ 本文件是 OpenFlare 的 AI 接手入口，不承载详细设计、规范和计划。接手项目时，请根据以下分层文档指引进行阅读与开发： +### 1. 开发指导规范 (AI & Developer Guidelines) -### 面向 AI 的开发指导规范 (AI Guidelines) 必须阅读 +* **必须阅读**： + * **[docs/guideline/development-constraints.md](./docs/guideline/development-constraints.md)**：掌握核心后端/Agent/前端分层约束、数据模型规范、数据库迁移升级协议、API 与鉴权设计准则及变更准入与验收标准。 + * **[docs/guideline/Role.md](./docs/guideline/Role.md)**：通用的 Go 后端开发与高质量编码准则，包括架构、并发、错误处理、安全及工作流程。 +* **正在进行的开发计划与接手 (Handover & Plans)**： + * **[docs/plan/index.md](./docs/plan/index.md)**：查看正在进行的开发实现计划（Implementation Plan）与 AI 代理交接文档（Handover），接手项目时优先检查。 -为了理解 OpenFlare 的设计理念、产品边界、核心机制以及代码编写的工程约束，**AI 在接手项目时必须首先且完整阅读以下文档**： +### 2. 系统设计与架构 (Design Docs) -* **[docs/guildline/development-constraints.md](./docs/guildline/development-constraints.md)** - *作用：掌握核心后端/Agent/前端分层约束、数据模型规范、数据库迁移升级协议、API 与鉴权设计准则。* -* **[docs/guildline/Guidelines.md](docs/guildline/Role.md)** - *作用：通用的 Go 后端开发与高质量编码准则，包括架构、并发、错误处理、安全及工作流程。* +* **[docs/design/index.md](./docs/design/index.md)**：理解产品范围、系统边界、核心对象及长期约束，以及[仓库结构](./docs/design/index.md#仓库结构)。 +* **[docs/design/architecture.md](./docs/design/architecture.md)**：理解 Server、Agent、OpenResty 与前端的职责边界与网络拓扑。 +* **[docs/design/agent-design.md](./docs/design/agent-design.md)**：理解 Agent 设计原则、与 Server 交互时序、OpenResty 管控与配置发布回滚模型。 -### 系统参阅文档 按需查阅 -* **[docs/reference/configuration.md](./docs/reference/configuration.md)** - *作用：系统启动时支持的所有环境变量、命令行参数、运行时 Option 选项和 Agent 配置文件字段。* -* **[docs/reference/cli.md](./docs/reference/cli.md)** - *作用：Server 与 Agent 可用的命令行参数、安装/卸载脚本参数等参考。* +### 3. 部署与参考手册 (Deployment & References) -### 面向开发者的文档 按需查阅 -* **[docs/design/index.md](./docs/design/index.md)** - *作用：理解当前 MVP 的产品范围、系统边界、核心对象和长期约束。* -* **[docs/design/architecture.md](./docs/design/architecture.md)** - *作用：理解 Server、Agent、OpenResty 与前端的职责边界与网络拓扑。* -* **[docs/design/agent-design.md](./docs/design/agent-design.md)** - *作用：理解 Agent 设计原则、与 Server 交互时序、OpenResty 管控、配置版本发布与三阶段异常回滚模型。* -* **[docs/design/development.md](./docs/design/development.md)** - *作用：了解如何搭建本地开发环境，运行后端 Server、Agent 和前端开发服务器，以及运行测试与构建的命令。* -* **[docs/design/repository.md](./docs/design/repository.md)** - *作用：熟悉仓库的整体物理结构和各子目录的职责。* - -### 部署与升级指南 -* **[docs/deployment/deployment.md](./docs/deployment/deployment.md)** - *作用：理解 Server 和 Agent 的单机、Docker 部署配置，以及 Agent 接入、升级、卸载和联调步骤。* -* **[docs/deployment/server.md](./docs/deployment/server.md)** - *作用：如何配置系统配置、服务环境变量并正确启动 Server 服务。* -* **[docs/deployment/agent.md](./docs/deployment/agent.md)** - *作用：理解 Agent 接入的 discovery/agent 令牌鉴权机制、本地配置文件及 Docker 部署参数。* -* **[docs/deployment/upgrade.md](./docs/deployment/upgrade.md)** - *作用：Server 及各代理节点 Agent 的升级步骤与维护策略。* +* **[docs/deployment/deployment.md](./docs/deployment/deployment.md)** / **[server.md](./docs/deployment/server.md)** / **[agent.md](./docs/deployment/agent.md)** / **[upgrade.md](./docs/deployment/upgrade.md)**：Server 和 Agent 的单机、Docker 部署配置，接入、升级与维护策略。 +* **[docs/reference/configuration.md](./docs/reference/configuration.md)** / **[cli.md](./docs/reference/cli.md)**：支持的环境变量、参数、命令行与配置文件参考。 --- -## 执行要求 +## 开发与执行要求 -* 如果实现内容超出 [产品边界](./docs/design/index.md)，先修改设计文档，再继续编码。 -* 如果实现方式违反 [开发约束](./docs/guildline/development-constraints.md)，应优先调整方案，而不是绕过规范。 -* 如果实现方式涉及后端代码逻辑，必须严格遵循 [docs/guildline/](./docs/guildline/) 下的所有开发准则。 -* 如果需求与当前阶段原则冲突，优先遵守 [开发约束](./docs/guildline/development-constraints.md) 中的变更准入与验收标准。 -* 如果任务涉及前端改造或管理端 UI，必须同时遵守 [开发约束](./docs/guildline/development-constraints.md) 中的前端规范。 - -## 文档维护要求 - -当以下内容发生变化时，应同步更新对应中文文档，不要同步英文文档： - -* 产品范围或系统边界变化：更新 `docs/design/index.md` -* 系统结构、模块职责变化：更新 `docs/design/architecture.md` -* 发布、同步、回滚与 Agent 模型变化：更新 `docs/design/agent-design.md` -* 业务分层、数据模型边界、接口约定、阶段原则、测试基线变化：更新 `docs/guildline/development-constraints.md` -* 后端开发规范、代码质量要求、重构模式、去重逻辑与避坑指南变化：更新 `docs/guildline/` 下的对应开发准则文件 -* 产品启动、部署、升级、联调方式变化：更新 `docs/guide/quick-start.md`、`docs/deployment/deployment.md` 和 `README.md` -* 用户操作路径、常见场景变化：更新 `docs/guide/usage.md` -* 本地开发、测试、构建方式变化：更新 `docs/design/development.md` -* 环境变量、命令行参数、运行时配置、Agent 配置变化：更新 `docs/reference/configuration.md` -* **任何代码、配置或文档变更完成后：必须在 [`docs/changelog/index.md`](./docs/changelog/index.md) 的 `[Unreleased]` 区块补充对应条目（新增 / 变更 / 修复），格式遵循文件内已有模板。** +1. **设计先行**： + * 开发新功能或重要特性时，必须在 `docs/design/` 下创建/更新对应的设计文档，理清架构与核心决策。 + * 新增的设计文档应同步更新至 `docs/design/architecture.md` 及在 `docs/config.ts` 中注册侧边栏路由。 + * 若实现内容超出产品边界，必须先修改设计文档，再编码实现。 +2. **遵守约束**： + * 必须严格遵循 `docs/guideline/` 下的所有开发准则与开发约束规范，不得绕过任何规范。 + * 涉及前端改造或管理端 UI 时，必须遵守 `docs/guideline/development-constraints.md` 中的前端规范。 +3. **开发计划与交接**： + * 正在进行的开发计划或 AI 接手交接发生变化时，在 `docs/plan/` 下创建或更新对应的开发计划或接手文档，并使用相应模板初始化。 +4. **文档与变更日志**： + * 当相关内容发生变化时，同步更新对应的**中文文档**（不要同步英文文档）。 + * 任何代码、配置或文档变更完成后，必须在 [`docs/changelog/index.md`](./docs/changelog/index.md) 的 `[Unreleased]` 区块补充对应变更条目。 diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index eebb34eb..1299dec1 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -12,7 +12,9 @@ export default defineConfig({ srcExclude: [ 'zh/**', 'components/**', - 'snippets/**' + 'snippets/**', + 'plan/**', + 'guideline/**' ], markdown: { diff --git a/docs/changelog/index.md b/docs/changelog/index.md index f198c011..1a12a237 100644 --- a/docs/changelog/index.md +++ b/docs/changelog/index.md @@ -20,11 +20,21 @@ sidebar: false ### 新增 +- 新增 Pages 静态托管使用指南（`pages-usage.md`），讲解 ZIP 上传、SPA Fallback 与 API 代理配置 +- 新增 Uptime Kuma 监控同步集成指南（`uptime-kuma.md`），说明同步参数与专属标签隔离机制 +- 完善 WAF IP 组订阅模式使用指南（`waf-usage.md`），补充 JSON 路径提取映射规则与同步参数说明 + ### 变更 +- 将 `usage.md` 改名为 `proxy-config.md`（新建反代配置），重新梳理大纲结构，专注于如何从导入/申请证书开始，一步步新增并发布代理路由规则，并同步更新全部导航与文档引用链接 - WAF 白名单调整为准入名单语义：存在白名单规则时，未命中白名单的请求会被拦截 - 更新仓库结构设计文档，使 `openflare_agent` 和 `openflare_server` 的目录结构描述与实际物理结构保持一致 - 新增 `pages-design.md` 设计文档，详细说明 Pages 静态托管功能在 Server 与 Agent 侧的架构设计和渲染逻辑 +- 新增 `kuma-design.md` 设计文档，详细说明 Uptime Kuma 自动监控同步机制、Socket.IO 控制流、防污染标签模型与差分状态机算法 +- 更新 `architecture.md` 系统架构文档，完善 Pages 静态托管与 Uptime Kuma 监控同步在组件职责及贡献建议中的关联 +- 移除 design 分区下冗余的 `development.md` 本地开发文档，并同步清理 `guide/index.md` 和 `AGENTS.md` 中的导航与指引引用 +- 重构并简化 `architecture.md` 系统架构文档，移除非宏观功能设计细节，采用“总分”结构引流至各个专项设计文档 +- 精简 `index.md` 产品边界文档，将 `repository.md` 仓库结构完整合并至其中，物理删除冗余的 `repository.md` 文件并重定向其所有超链接引用 --- diff --git a/docs/config.ts b/docs/config.ts index c816f168..64393b67 100644 --- a/docs/config.ts +++ b/docs/config.ts @@ -70,10 +70,12 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { items: [ { text: '概览', link: '' }, { text: '快速开始', link: 'quick-start' }, - { text: '基础使用', link: 'usage' }, + { text: '新建反代配置', link: 'proxy-config' }, + { text: 'Pages 静态托管使用', link: 'pages-usage' }, { text: '内网穿透与隧道使用', link: 'tunnel-usage' }, { text: 'WAF 安全防护使用', link: 'waf-usage' }, { text: 'WAF 自动 IP 组语法', link: 'waf-ip-group-expr' }, + { text: 'Uptime Kuma 监控同步', link: 'uptime-kuma' }, { text: 'SSO 登录配置', link: 'sso' }, { text: '发布第一份配置', link: 'first-site' }, { text: '故障排查', link: 'troubleshooting' }, @@ -115,8 +117,9 @@ function sidebarDesign(): DefaultTheme.SidebarItem[] { { text: '内网穿透隧道设计', link: 'tunnel-design' }, { text: 'WAF 设计', link: 'waf-design' }, { text: 'Pages 静态托管设计', link: 'pages-design' }, - { text: '仓库结构', link: 'repository' } + { text: 'Uptime Kuma 监控同步设计', link: 'kuma-design' } ] } ] } + diff --git a/docs/design/architecture.md b/docs/design/architecture.md index bfe1ed3a..1fe7a1a3 100644 --- a/docs/design/architecture.md +++ b/docs/design/architecture.md @@ -1,244 +1,174 @@ # 系统架构 -你会学到：OpenFlare 的整体架构、Server、Agent、OpenResty 与管理端前端的职责边界，以及一次配置发布从管理端到节点生效的请求流。 +你会学到：OpenFlare 的整体架构、各核心组件（Server, Agent, OpenResty, Relay, Client）的职责分工，以及主要数据与请求流的宏观流向。 -OpenFlare 由 Server、Agent、节点本地 OpenResty 和管理端前端组成。Server 是控制面，Agent 是节点侧唯一受控落地入口，OpenResty 是实际数据面。内网穿透场景中，Relay（frps 管理器）和 OpenFlared（frpc 管理器）扩展了数据面流量路径。 +OpenFlare 是一套自托管的 OpenResty 控制面。它在物理上由 Server（控制面）、Agent（配置落地端）、节点本地 OpenResty（数据面）、内网穿透组件（Relay 与 OpenFlared，数据面扩展）以及管理端前端组成。 -### 标准反代流量路径 +--- +## 流量路径概览 + +根据不同的网站上游类型，OpenFlare 支持三种不同的数据面流量路径： + +### 1. 标准反代流量路径 ```text Browser | - | Management UI / API + | HTTPS/HTTP request v -OpenFlare Server (Gin + GORM + SQLite/PostgreSQL) +OpenResty (WAF, TLS, Rate Limit) | - | Agent API / heartbeat / config pull + | reverse proxy (proxy_pass) v -OpenFlare Agent - | - | write config / openresty -t / reload / rollback - v -OpenResty binary - | - | reverse proxy - v -Origin +Origin Server (直连公网/局域网上游) ``` -### 内网穿透流量路径 - +### 2. 内网穿透流量路径 +适用于内网受限服务器上的源站服务接入： ```text Browser | - | HTTPS request + | HTTPS/HTTP request v -OpenResty (Agent, TLS/WAF) <-- TunnelRelay 节点 +OpenResty (Agent 宿主机, TLS/WAF) | | proxy_pass http://localhost:vhost_port (Host header preserved) v -OpenFlareRelay (frps) <-- TunnelRelay 节点，与 Agent 同机部署 +OpenFlareRelay (frps) <-- 与 Agent 同机部署，提供中继 | - | frp tunnel protocol (HTTP Vhost routing by Host header) + | frp tunnel protocol (Host header routing) v -OpenFlared (frpc) <-- 内网服务器 +OpenFlared (frpc) <-- 内网受限服务器 | | HTTP/HTTPS forward v Internal Service (192.168.x.x) ``` -### Pages 静态托管流量路径 - +### 3. Pages 静态托管流量路径 +适用于预构建的单页应用（SPA）或静态网站托管： ```text Browser | - | HTTPS request + | HTTPS/HTTP request v OpenResty (Agent, TLS/WAF) | - | root/try_files - v -Agent 本地 Pages 部署目录 + +---> [静态服务] root/try_files ---> Agent 本地 Pages 部署目录 + | + +---> [API 反代] proxy_pass ---> 后端 API 服务 (如果启用了 API 代理) ``` +--- + ## 组件职责 -| 组件 | 职责 | -| --------------- | ---------------------------------------------------------------------- | -| Server | 管理端 UI、管理 API、Agent/Relay/Client API、配置渲染、版本发布、Pages 部署包存储、数据存储与聚合查询 | -| Agent | 注册、心跳、同步、写入文件、Pages 部署包拉取与解压、校验、reload、失败回滚、自更新与轻量采集 | -| OpenResty | 接收真实流量，按 OpenFlare 渲染的配置执行 WAF、PoW、认证、反向代理与 Pages 静态文件服务 | -| OpenFlareRelay | 管理 frps 进程生命周期，提供隧道中继服务，通过心跳接收 frps 配置 | -| OpenFlared | 管理 frpc 进程（可多个），连接 Relay 中继，将流量转发到内网服务 | -| Frontend | 管理网站配置、WAF、源站、证书、节点、Tunnel、版本、用户、设置与观测页面 | +| 组件 | 职责 | 详细设计参考 | +| --------------- | ---------------------------------------------------------------------- | ------------ | +| **Server** | 管理端 UI/API、控制面状态持久化、配置编译渲染、发布版本控制、Pages 部署包存储与 Uptime Kuma 监控同步 | [Agent 与发布模型](./agent-design.md) / [Uptime Kuma 监控同步设计](./kuma-design.md) | +| **Agent** | 周期心跳与 WS 同步、静态资源包拉取与解压、OpenResty 配置写入/校验/重载与自愈 | [Agent 与发布模型](./agent-design.md) | +| **OpenResty** | 接收真实流量，执行 WAF 过滤、PoW 防护、Basic Auth 认证与静态/反代服务 | [WAF 设计](./waf-design.md) / [Pages 设计](./pages-design.md) | +| **Relay** | 部署于边缘节点，管理 `frps` 守护进程生命周期，接受心跳派发的穿透中继配置 | [内网穿透设计](./tunnel-design.md) | +| **OpenFlared** | 部署于内网，管理 `frpc` 进程组，向多个 Relay 建立反向隧道，上报连接状态 | [内网穿透设计](./tunnel-design.md) | +| **Frontend** | Next.js 管理界面，提供路由、WAF、证书、节点、穿透隧道和 Pages 项目的可视化管理 | [开发约束](../guideline/development-constraints.md) | -## Server +--- -`openflare_server` 是单体控制面： +## 组件架构与分工 -* Gin 提供 HTTP 服务。 -* GORM 访问 SQLite 或 PostgreSQL。 -* 现有登录体系签发管理端用户 Token，管理端 API 通过 `OPENFLARE_TOKEN` 请求头鉴权。 -* 认证源与外部账号绑定支持 GitHub OAuth 和标准 OIDC。 -* Go Server 托管 `openflare_server/web` 静态构建产物。 +### 1. Server (控制面) +`openflare_server` 是 Go 编写的单体控制面： +* 提供管理端 REST API，通过 `OPENFLARE_TOKEN` 请求头鉴权。 +* 包含配置编译器（Compiler），将数据库中的规则、证书与全局参数统一编译为不可变的配置快照及 OpenResty 物理配置文件文本。 +* 存储 Pages 部署 ZIP 包于本地 Artifacts 目录，并向 Agent 提供受控的下载接口。 +* 后台集成 Uptime Kuma 监控同步服务，自动为可用站点维护 HTTP 探测任务。 +* *详细设计请参阅：[Agent 与发布模型设计](./agent-design.md) 以及 [Uptime Kuma 监控同步设计](./kuma-design.md)* -Server 不直接 SSH 到节点，也不在线修改节点文件。它只保存控制面状态、生成完整配置版本，并通过 Agent API 让节点主动拉取。 +### 2. Agent (配置落地端) +`openflare_agent` 是运行在节点本地的守护进程： +* 启动后维持与控制面的周期性心跳，并通过可选的 WebSocket 接收实时的配置发布广播。 +* 负责拉取最新激活版本的配置文件及证书，写入本地目录，并通过 `openresty -t` 执行安全校验后平滑重载 (`reload`)。 +* 在本地处理 Pages 部署包的下载、SHA-256 校验与解压缩切换。 +* *详细设计请参阅：[Agent 与发布模型设计](./agent-design.md)* -Pages 静态托管场景中，Server 保存 Pages 项目、SPA fallback 回退路径、不可变部署元数据、文件清单和 zip 部署包；发布版本只记录部署引用、checksum 与静态渲染策略，不把大体积静态资源写入 `config_versions`。 +### 3. OpenResty (数据面) +接收访客流量并执行最终的业务落地： +* 流量入口，支持 HTTP/2、HTTP/3（QUIC）和 TLS 证书动态绑定。 +* 嵌入 Lua 逻辑，在 `access_by_lua` 阶段高效过滤 WAF 规则、验证工作量证明 (PoW) 挑战，并在此之后执行连接数/速率限制及基础缓存。 +* *详细设计请参阅：[WAF 设计文档](./waf-design.md) 与 [Pages 静态托管设计文档](./pages-design.md)* -## Agent +### 4. Relay 与 OpenFlared (穿透组件) +扩展数据面反穿透能力： +* `openflare_relay` 守护本地 `frps`，接受 Server 的配置派发，自动更新中继端口。 +* `openflared` 在内网守护一组 `frpc` 客户端进程，实现多中继就近建连与高可用容灾。 +* *详细设计请参阅：[内网穿透隧道设计文档](./tunnel-design.md)* -`openflare_agent` 是 Go 单体程序： +--- -* 单二进制运行在节点侧。 -* 启动后读取或生成本地节点信息。 -* 周期性 heartbeat，上报状态并获取激活版本摘要。 -* 发现新版本后拉取配置、备份旧文件、写入新文件、校验并 reload。 -* 当激活配置引用 Pages 部署时，先按部署 ID 下载 zip 包，校验 checksum，解压到本地 `pages_dir` 并切换当前部署目录。 -* 应用失败时尝试恢复运行并回滚。 -* 维护 WAF GeoIP mmdb，启动时写入内置初始库，并按配置定期更新。 - -Agent 通过 `openresty_path` 指向的 OpenResty 二进制统一执行校验、reload、启动与重启；未配置时默认调用 `openresty`。Docker 部署时，Agent 镜像内置 OpenResty 二进制，仍走同一套二进制控制逻辑。 - -节点 IP 默认由 Agent 注册和心跳上报维护；如果管理端锁定节点 IP，Server 只更新运行状态、版本、观测等运行态字段，不再接受 Agent 上报覆盖该 IP。 - -## Frontend - -`openflare_server/web` 是正式管理端前端： - -* Next.js 15 App Router。 -* React 19。 -* TypeScript。 -* Tailwind CSS。 -* TanStack Query 管理服务端状态。 - -前端采用静态导出模式（`output: 'export'`），导出后由 Go Server 通过 `embed.FS` 托管。所有 API 请求应统一经过 `lib/api/`，并处理 `success/message/data` 响应结构。 - -Server 集成以下安全特性： -* CORS 中间件：跨域请求保护。 -* 速率限制：全局与关键接口限流。 -* 会话管理：基于 Cookie/Redis 的会话存储。 - -## 数据与请求流 - -### 管理端请求流 +## 数据与请求流概览 +### 1. 配置发布与同步流 ```text -Browser -> Frontend -> /api/* -> controller -> service -> model -> database +管理端修改配置 -> 发布新版本 -> 生成全局唯一 Checksum 激活版本 + | + +------------------+------------------+ + | (WebSocket 广播或周期 Heartbeat) | + v v + [边缘节点 Agent] [内网 OpenFlared] + 拉取最新 OpenResty 配置/证书 拉取最新 Tunnel 映射配置 + 增量拉取/解压 Pages 静态部署包 生成/重写 frpc.toml + Nginx 校验配置并平滑重载 (reload) 平滑重载或拉起 frpc 进程 + 上报应用状态 (Success / Error) 上报隧道连接状态与活跃指标 ``` +* *同步与自愈的精细时序及回滚模型详见：[Agent 与发布模型设计](./agent-design.md)* -管理端变更类接口使用 `POST`，只读接口使用 `GET`。成功与失败都返回清晰的 `message`。 +### 2. 静态托管与 API 代理流 +* 静态资源解压落地于 Agent 节点的 `deployments/{id}/current` 下，OpenResty 通过 `root`/`index`/`try_files` 指令在边缘直接向访客提供极低延迟的静态资源服务。 +* 当启用 API 代理时，OpenResty 自动根据站点配置的 `api_proxy_path`（如 `/api`）将 API 请求重写并转发（`proxy_pass`）给后端动态接口。 +* *部署包校验、解压逃逸防御及 Nginx 规则渲染详见：[Pages 静态托管设计文档](./pages-design.md)* -### Agent 同步流 +### 3. WAF 安全过滤流 +* WAF 引擎嵌入在 OpenResty 请求生命周期中。 +* 过滤规则直接从 Agent 落地在节点本地的 `waf_config.json` 及 `waf_ip_groups.json` 读取，判决逻辑白名单优先、黑名单层层过滤，完全在本地内存中完成，不产生数据库或网络 I/O 损耗。 +* *IP组增量同步、自动 IP 组计算与拦截响应机制详见：[WAF 设计文档](./waf-design.md)* -```text -Agent HTTP heartbeat -> Server 返回激活版本摘要 -Agent 发现新版本 -> 拉取配置详情 -Agent 确保 Pages 部署包已下载、校验并解压 (如配置引用 Pages) -Agent 写入主配置 / 路由配置 / 证书 / Lua 资源 / WAF 运行时配置 -Agent 执行 OpenResty 校验与 reload -Agent 上报应用结果 -``` - -### Relay 同步流 - -Relay（OpenFlareRelay 进程）运行在 TunnelRelay 节点上，与 Agent 共享同一 `agent_token`： - -```text -Relay HTTP heartbeat -> Server 返回 frps 基础配置 (bindPort, vhostHTTPPort, auth_token) -Relay 生成 frps.toml 并启动或更新 frps 进程 -Relay 定期上报 frps 健康状态与连接统计 -Relay 尝试升级 WebSocket 连接以支持实时配置推送 -``` - -frps 配置相对静态（端口、认证 Token），通过心跳下发，**不纳入版本化发布流**。Relay 需要监听 frps 进程异常并自动恢复。认证方式：`X-Agent-Token` + API 路径前缀 `/api/relay/*`，Server 通过 `node_type = tunnel_relay` 区分。 - -### OpenFlared 同步流 - -OpenFlared（客户端）运行在内网服务器，使用独立的 `tunnel_token` 认证： - -```text -Client HTTP heartbeat -> Server 返回 tunnel 配置版本摘要 (version, checksum) -Client 发现新版本 -> 拉取完整 tunnel 路由配置 (relay 列表 + frpc proxy 定义) -Client 为每个 Relay 生成独立的 frpc.toml 配置文件 -Client 为新 Relay 启动 frpc 进程，或为已有 Relay 执行热重载 (frpc reload) -Client 上报应用结果 (成功/失败原因) -``` - -OpenFlared 通过 `/api/flared/*` 端点与 Server 通信，认证使用 `X-Tunnel-Token`。Tunnel 路由配置随发布流程版本化同步，所有配置变更通过单一版本号关联并一致性发布到 Agent 和 Client。 - -**WebSocket 升级流程**（可选，通过 `AgentWebsocketUpgradeEnabled` 选项控制）： - -当启用 WebSocket 升级时： -1. Agent 通过 HTTP heartbeat 获取运行配置与设置。 -2. Agent 尝试升级连接到 `GET /api/agent/ws`（WebSocket）。 -3. WS 连接成功后，周期性状态上报和实时消息由 WebSocket 承载，降低延迟。 -4. Server 发布或激活版本后，可向已连接 Agent 立即广播激活版本摘要，使 Agent 立即进入同步流程。 -5. 若 WebSocket 断开或建立失败，Agent 自动降级回 HTTP heartbeat，保证可用性。 - -通过 `OpenRestyWebsocketEnabled` 选项，可在 OpenResty 层面启用或禁用 WebSocket 反向代理支持。 - -### 反向代理流 - -```text -Client -> OpenResty server block -> WAF Lua -> named upstream -> Origin -``` - -网站配置是反向代理聚合边界。一条网站配置可绑定多个域名，并共享站点级流量限制、反向代理和缓存配置。 - -WAF 在 OpenResty `access_by_lua_file` 阶段执行。规则来自当前激活版本携带的 `waf_config.json`，全局规则组默认生效，网站可叠加自定义规则组。`waf_config.json` 只保存规则组直接 IP 和 IP 组引用 ID；IP 组成员由 Agent 独立同步到本地 `waf_ip_groups.json`，OpenResty Lua 按引用 ID 合并判断。 - -WAF IP 组由 Server 管理。手动 IP 组直接保存 IP/IP 段列表；自动 IP 组由 Server 定时任务读取请求日志、按单个 IP 聚合指标并执行 Expr 规则；订阅 IP 组由 Server 定时任务同步远程文本或 JSON 源。Agent 心跳会上报本地 IP 组 checksum，Server 只返回不一致的 IP 组；Server 侧 IP 组更新时会通过 Agent WebSocket 广播变更组。OpenResty Lua 只读取 Agent 落地的运行时 JSON，不直接访问 Server 数据库、请求日志或远程订阅源。 +--- ## 核心对象 -当前有效实体包括： +当前系统核心实体包括： -* `proxy_routes` -* `origins` -* `config_versions` -* `pages_projects` -* `pages_deployments` -* `pages_deployment_files` -* `nodes` -* `tunnels` -* `auth_sources` -* `external_accounts` -* `node_system_profiles` -* `apply_logs` -* `tls_certificates` -* `managed_domains` -* `node_request_reports` -* `node_access_logs` -* `node_metric_snapshots` -* `traffic_analytics_rollups` -* `node_health_events` -* `waf_rule_groups` -* `waf_ip_groups` -* `waf_rule_group_bindings` -* `acme_accounts` -* `dns_accounts` -* `geoip_update_configs` +* **反代与配置**：`proxy_routes` (网站配置), `origins` (源站), `config_versions` (配置版本), `tls_certificates` (证书), `managed_domains` (托管域名). +* **Pages 静态托管**：`pages_projects` (Pages项目), `pages_deployments` (不可变部署), `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 双协议 | -| 全局单激活版本 | 降低 MVP 复杂度，保证所有节点默认一致；支持版本预览、历史查询与一键回滚 | -| 网站配置聚合多域名 | 支持一个业务站点共享站点级策略，同时允许按域名绑定证书 | -| 观测数据服务端聚合 | 避免前端临时统计造成口径不一致 | -| 内网穿透基于 frp 整合 | 复用成熟隧道协议，避免自研隧道的稳定性风险；frps HTTP Vhost 路由天然适配 | -| Relay/Client 独立二进制 | 职责分离，Relay 管理 frps，Client 管理 frpc，各自独立升级和部署 | -| Tunnel 与 Node 体系分离 | Tunnel 客户端在内网运行，与公网节点概念不同，使用独立的注册和认证体系 | +| 完整配置版本，而不是在线 patch | 让预览、激活、历史和回滚有稳定边界，保证节点状态一致 | +| Agent 主动拉取 | Server 不需要 SSH 权限，降低安全风险；支持 HTTP 与 WebSocket 双协议灵活切换 | +| 全局单激活版本 | 降低控制面复杂度，保证所有节点默认一致；提供一键秒级回滚的稳定机制 | +| 网站配置聚合多域名 | 支持单个业务站点共享站点级策略，同时支持按域名灵活绑定不同的 TLS 证书 | +| 内网穿透基于 frp 整合 | 复用成熟隧道协议，避免自研隧道引起稳定性风险；其 Vhost 机制天然适配反代路由 | +| 运行时配置与控制库解耦 | 如 WAF 运行时只读取本地 JSON 规则包，配置变更通过差分广播或快速重载热生效 | + +--- ## 贡献者阅读建议 -如果要修改架构相关代码，先阅读： +修改系统架构或开发新功能前，请按以下顺序阅读： -1. [产品边界](./index.md) -2. [Agent 与发布模型](./agent-design.md) -3. [开发约束](../guildline/development-constraints.md) -4. [仓库结构](./repository.md) +1. **[产品边界](./index.md)**：了解 OpenFlare 核心定位与不允许逾越的设计边界。 +2. **[开发约束](../guideline/development-constraints.md)**：掌握数据模型、API 约定、数据库迁移（Goose）与前端规范。 +3. **[Agent 与发布模型](./agent-design.md)**：理解版本快照同步及失败回滚的安全兜底逻辑。 +4. **细分领域设计**： + * 穿透相关开发：阅读 [内网穿透隧道设计](./tunnel-design.md)。 + * WAF 相关开发：阅读 [WAF 设计](./waf-design.md)。 + * Pages 托管开发：阅读 [Pages 静态托管设计](./pages-design.md)。 + * 监控同步开发：阅读 [Uptime Kuma 监控同步设计](./kuma-design.md)。 +5. **[仓库结构](./index.md#仓库结构)**：明确各个物理目录分层职责，避免堆砌和重复开发。 diff --git a/docs/design/development.md b/docs/design/development.md deleted file mode 100644 index 8aa980c1..00000000 --- a/docs/design/development.md +++ /dev/null @@ -1,182 +0,0 @@ -# 本地开发 - -你会学到：如何搭建 OpenFlare 的本地开发环境、启动 Server、Agent 和管理端前端，运行测试与构建命令，并理解贡献代码前需要遵守的边界。 - -本页面向贡献者。产品边界、数据模型约束、API 约定和前端分层规范以 [开发约束](../guildline/development-constraints.md) 为准；本页只提供可执行的本地开发流程。 - -## 仓库结构 - -项目的核心物理目录及各模块（Server、Agent、Frontend 等）的职责分层，详见 [仓库结构](./repository.md)。 - -## 环境要求 - -| 项目 | 要求 | -| --- | --- | -| Go | `1.25+` | -| Node.js | `18+` | -| pnpm | 推荐通过 `corepack enable` 使用项目声明版本 | -| Docker | Server 容器、本地联调和 Agent Docker 镜像需要 | -| OpenResty | 本地运行 Agent 时需要可执行 `openresty` | -| PostgreSQL | 可选；未配置时 Server 使用 SQLite | - -## 初始化前端依赖 - -```bash -cd openflare_server/web -corepack enable -pnpm install -``` - -构建供 Go Server 托管的静态产物： - -```bash -pnpm build -``` - -## 启动 Server - -SQLite 模式： - -```bash -cd openflare_server -export JWT_SECRET='dev-jwt-secret' -export SQLITE_PATH='./openflare-dev.db' -export LOG_LEVEL='debug' -go run . -``` - -PostgreSQL 模式： - -```bash -cd openflare_server -export JWT_SECRET='dev-jwt-secret' -export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable' -export LOG_LEVEL='debug' -go run . -``` - -默认访问地址： - -```text -http://localhost:3000 -``` - -默认账号是 `root` / `123456`。 - -## 启动前端开发服务器 - -前端开发服务器默认监听 `3001`，并通过 `NEXT_DEV_BACKEND_URL` 代理到后端： - -```bash -cd openflare_server/web -export NEXT_DEV_BACKEND_URL='http://127.0.0.1:3000' -pnpm dev -``` - -访问： - -```text -http://localhost:3001 -``` - -## 启动 Agent - -创建本地 `agent.json`： - -```json -{ - "server_url": "http://127.0.0.1:3000", - "agent_token": "replace-with-node-auth-token", - "data_dir": "./data", - "heartbeat_interval": 10000, - "request_timeout": 10000 -} -``` - -运行： - -```bash -cd openflare_agent -export LOG_LEVEL='debug' -go run ./cmd/agent -config ./agent.json -``` - -未配置 `openresty_path` 时，Agent 默认调用 `openresty`。调试时可显式配置 `openresty_path`、`main_config_path`、`route_config_path` , `access_log_path`、`cert_dir`、`lua_dir` 和 `runtime_config_dir`。 - -## 测试 - -Server： - -```bash -cd openflare_server -GOCACHE=/tmp/openflare-go-cache go test ./... -``` - -Agent： - -```bash -cd openflare_agent -GOCACHE=/tmp/openflare-go-cache go test ./... -``` - -Frontend： - -```bash -cd openflare_server/web -pnpm lint -pnpm typecheck -pnpm test -pnpm test:e2e -``` - -Docs： - -```bash -cd docs -pnpm build -``` - -## 构建 - -管理端静态产物： - -```bash -cd openflare_server/web -pnpm build -``` - -Server 二进制： - -```bash -cd openflare_server -go build -o openflare-server . -``` - -Agent 二进制： - -```bash -cd openflare_agent -go build -o openflare-agent ./cmd/agent -``` - -## 调试入口 - -| 场景 | 命令或位置 | -| --- | --- | -| Server 日志 | `LOG_LEVEL=debug go run .` | -| Agent 日志 | `LOG_LEVEL=debug go run ./cmd/agent -config ./agent.json` | -| Swagger | `http://localhost:3000/swagger/index.html` | -| 前端 API 代理 | `NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev` | -| OpenResty 配置校验 | `openresty -t -c ./data/etc/nginx/nginx.conf` | - -## 代码风格与变更准入 - -贡献前先确认： - -1. 需求符合 [产品边界](./index.md)。 -2. 实现符合 [开发约束](../guildline/development-constraints.md)。 -3. 不破坏发布、同步、回滚或升级主链路。 -4. 涉及配置、部署、API 或产品边界时同步更新文档。 -5. 风险较高的修改补充测试或等效联调验证。 - -数据库结构变更必须提升数据库版本号，并补充显式迁移方法和校验逻辑。v8-v17 保留为旧升级框架兼容链；v17 之后统一使用 goose，新的 goose 框架代码必须集中在 `openflare_server/model/goose` 包下；每次数据库升级都要在该包下新增独立的 `goose__.go` 文件，不得把具体迁移逻辑集中堆在 goose 注册入口中，也不得把新 goose 框架代码放回 `openflare_server/model` 根包。 diff --git a/docs/design/index.md b/docs/design/index.md index bd92b0d8..42dd1a1d 100644 --- a/docs/design/index.md +++ b/docs/design/index.md @@ -1,222 +1,169 @@ # 产品边界 -你会学到：OpenFlare 是什么、解决什么问题、目标用户是谁、当前稳定能力有哪些，以及哪些设计边界在实现时不能被绕过。 +你会学到：OpenFlare 是什么、当前稳定能力，以及开发时应遵守的核心产品边界与仓库结构目录分工。 -OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景。它解决反向代理配置、节点同步、证书托管、配置发布回滚与基础观测分散管理的问题。 +OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景。 + +--- ## 项目定位 -OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队： +OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具备以下定位： +* **控制与落地分离**：Server 控制面不直接 SSH 到代理节点，而是通过 Agent 主动拉取版本并应用。 +* **不可变配置发布**：采用完整的配置版本进行预览、发布、激活和一键回滚。 +* **一体化网关托管**：在同一个控制面内集成网站反代、TLS 证书自动续期申请、WAF 防护拦截、内网穿透（Tunnel）以及 Pages 静态网站托管。 -* 希望用管理端维护反向代理网站配置。 -* 希望每次配置变更都有完整版本、预览、激活与回滚。 -* 希望节点主动同步配置，而不是由控制面 SSH 到节点执行命令。 -* 希望在同一系统中管理 TLS 证书、域名资产、节点状态和基础访问分析。 +**非本产品定位**：多租户云平台、Kubernetes Ingress Controller、服务网格或通用日志平台。 -OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingress Controller 或多租户云平台。 +--- ## 当前能力 -| 能力 | 说明 | -| --- | --- | -| 反代规则管理 | 以网站配置为聚合边界，支持多域名与源站配置 | -| 网站级配置 | 一条规则对应一个网站，可绑定一个或多个域名，并共享站点级配置 | -| 源站管理 | 维护轻量源站目录，并允许网站保存可渲染的源站快照 | -| 配置版本 | 支持预览、发布、激活、不可变历史与回滚 | -| Agent 同步 | 支持注册、心跳、同步、应用结果上报与自更新 | -| OpenResty 托管 | 管理主配置模板、性能参数、缓存参数与 Lua 资源 | -| HTTPS/TLS | 托管证书与域名资产，并按域名绑定证书 | -| WAF | 以全局规则组与网站自定义规则组维护 IP/IP 段、IP 组、国家级地域黑白名单 | -| 基础观测 | 聚合节点请求、资源快照、健康事件和访问分析 | -| 节点管理 | 节点状态、令牌体系、部署与更新链路 | -| 管理端前端 | 基于 Next.js 的正式管理端 | -| 认证源登录 | 支持以认证源形式配置 GitHub 与标准 OIDC 登录入口，并允许第三方账号绑定已有本地用户 | -| 内网穿透 | 通过 TunnelRelay 节点与 OpenFlared 客户端，将内网 HTTP 服务安全暴露到公网，复用 Agent 的 HTTPS/WAF 能力 | -| Pages 静态托管 | 以 Pages 项目管理静态站点部署包，发布后由边缘 Agent 拉取并在本地 OpenResty 静态服务 | +| 能力 | 说明 | 详细设计/使用指南 | +| --- | --- | --- | +| **反代配置管理** | 以网站规则（Proxy Route）为聚合边界，支持多域名与多上游负载均衡 | [新建反代配置](../guide/proxy-config.md) | +| **配置版本控制** | 支持全局单一激活版本的预览、发布、不可变快照历史与秒级一键回滚 | [Agent 与发布模型](./agent-design.md) | +| **WAF 安全防护** | 全局与自定义规则组，支持手动/自动/订阅型 IP 组，GeoIP 准入与 PoW CC 防护 | [WAF 设计](./waf-design.md) / [WAF 使用指南](../guide/waf-usage.md) | +| **内网穿透** | 通过中继节点（Relay）与内网客户端（OpenFlared），反向穿透暴露内网 Web 服务 | [内网穿透设计](./tunnel-design.md) / [穿透使用指南](../guide/tunnel-usage.md) | +| **Pages 静态托管** | 直接上传前端 zip 包，由边缘节点拉取并由 OpenResty 本地服务，支持 API 反代与 SPA Fallback | [Pages 静态托管设计](./pages-design.md) | +| **TLS 证书自动续期** | 绑定 managed_domains 并通过 ACME 协议向 Let's Encrypt 申请/续期证书 | [新建反代配置](../guide/proxy-config.md) | +| **多节点监控与观测** | 收集节点资源快照、健康事件，聚合请求指标与访问日志明细 | [系统架构](./architecture.md) | -默认工作方式： +--- -* 所有节点消费同一份全局激活版本。 -* Server 保存配置与状态，不直接 SSH 管理节点。 -* Agent 是节点侧唯一受控落地入口。 -* TunnelRelay 节点同时运行 Agent（OpenResty）和 Relay（frps），提供内网穿透中继。 -* OpenFlared 客户端在内网运行，管理 frpc 进程连接 Relay，将流量转发到内网服务。 +## 核心产品边界与约束 -## 典型使用场景 +在开发与贡献代码时，**必须严格遵守**以下业务边界与技术约束，禁止为了临时需求而绕过限制： -| 场景 | 说明 | -| --- | --- | -| 内部服务统一入口 | 把多个内部 HTTP 服务通过统一域名和证书暴露 | -| 多节点反代配置同步 | 多台 OpenResty 节点消费同一份激活配置 | -| 配置变更审查 | 发布前查看预览或 diff，发布后保留不可变历史 | -| 快速回滚 | 重新激活旧版本，让 Agent 拉取并应用 | -| 证书托管 | 为不同域名绑定 TLS 证书 | -| 基础观测 | 查看节点状态、请求聚合、访问分析和健康事件 | -| 内网穿透 | 通过 Tunnel 将无法直接公网访问的内网 HTTP 服务暴露到互联网，享有 HTTPS、WAF 等全部防护能力 | -| 静态站点托管 | 上传已构建的静态资源包，将网站规则上游绑定到 Pages 项目，在边缘节点本地服务静态文件 | +### 1. 网站配置与上游约束 +* **单站点域名共享策略**：一条路由规则对应一个网站，该站点下的多域名共享限流、缓存与反代上游等配置，不支持在同一规则内为不同域名做差异化服务配置。 +* **上游类型互斥**：上游必须是直连地址（`direct`）、内网穿透（`tunnel`）或 Pages 静态托管（`pages`）三者之一，不允许在同一规则中混用。 +* **直连类型限制**：直连上游可以是纯 `http://` 或 `https://` 的单个或多个地址（多地址仅支持纯 `scheme://host[:port]`），不支持非 HTTP 协议（如 TCP/UDP）上游。 +### 2. WAF 安全边界 +* **白名单优先原则**：白名单拥有绝对匹配权。若未命中白名单规则，才依次触发全局和自定义黑名单过滤。 +* **GeoIP 弱依赖性**：地域准入解析完全依赖节点本地 MaxMind 库。当 GeoIP 异常或解析失败时，系统必须自动忽略地域规则，**绝对不能**破坏 IP 组过滤和反代主链路的可用性。 +* **运行时数据解耦**：OpenResty 拦截时仅读取 Agent 同步至本地的 JSON，不与 Server 数据库通信。IP 组成员同步与版本发布解耦，通过 Chestsum 差分拉取以实现零重载平滑生效。 -## 网站配置约束 +### 3. 内网穿透边界 +* **仅限 HTTP 流量**：穿透组件仅支持 HTTP/HTTPS 协议（底层依靠 frp 虚拟主机 Vhost 机制实现单端口域名路由复用），暂不支持单独的 TCP/UDP 端口分配。 +* **中继配置静态化**：中继节点（Relay）配置相对静态，通过心跳被动获取，不纳入控制面的配置版本化管理体系。 +* **Tunnel 与 Node 体系隔离**：Tunnel 客户端在内网发起出向建连，与控制面托管的边缘 Node（公网节点）是独立的实体，使用专属的 `tunnel_token` 进行鉴权。 -`proxy_routes` 是“网站配置”的聚合对象。一条记录对应一个网站，可绑定一个或多个域名，并共享一组站点级配置。 +### 4. Pages 静态托管边界 +* **Direct Upload 托管模式**：仅支持直接上传预构建的 ZIP 静态资源包。不支持外部 Git 仓库自动构建、边缘 Serverless 函数、动态 SSR 服务或生成的二级预览域名。 +* **包体硬上限限制**：为了保障边缘节点安全，ZIP 压缩包体最大 25 MiB，解压文件树不超过 1,000 个且总体积不超过 100 MiB。禁止上传含有任何软链接或目录跨越（Zip-Slip）的安全高危压缩包。 -约束： +### 5. 系统与版本边界 +* **全局单一激活版本**：所有节点拉取并消费同一份全局激活配置。不进行按节点分组的差异化配置发布。 +* **单租户架构**：OpenFlare 仅供单团队在受信任的内部网络部署使用。采用单租户设计，不支持细粒度的多用户角色或多租户资源隔离。 -* `proxy_routes.site_name` 是网站的业务唯一标识。 -* `proxy_routes.domains` 至少包含一个域名，且 `domains[0]` 作为主域名。 -* 任一域名全局只能属于一个 `proxy_routes`。 -* 网站级流量限制、反向代理与缓存配置均按站点共享，不在同一网站内做域名级差异化配置。 -* HTTPS 允许在同一站点内按域名绑定证书。 +--- -## 源站与上游约束 +## 仓库结构 -`origins` 服务于源站目录复用，仅保存源站地址、展示名与备注，不承载协议、端口、路径、权重或健康检查策略。`proxy_routes` 可选关联一个 `origins`，但规则内部仍保存完整上游快照以参与渲染。 +在贡献代码时，请严格遵守以下物理分层与目录分工，保持代码结构清晰： -上游约束： +| 路径 | 职责 | +| ---------------------- | ---------------------------------------------------- | +| `openflare_server` | Gin + GORM + SQLite/PostgreSQL 单体控制面 | +| `openflare_server/web` | Next.js 15 App Router 管理端前端，由 Go Server 托管 | +| `openflare_agent` | Go 单体 Agent，运行在节点侧 | +| `openflare_relay` | Tunnel 中继代理，运行在公网边缘管理 frps 进程 | +| `openflared` | Tunnel 客户端，运行在内网服务器侧管理 frpc 进程 | +| `scripts` | 安装、自更新等系统辅助脚本 | +| `docs` | VitePress 文档站、设计基线、开发规范、部署与配置文档 | +| `docs/en` | 英文版文档 | -* `proxy_routes` 至少包含一个上游地址（直连类型 `direct`），或关联一个 Tunnel（内网穿透类型 `tunnel`），或关联一个 Pages 项目（静态托管类型 `pages`）。 -* 多上游负载均衡统一渲染为带 keepalive 的 named `upstream`。 -* 单上游允许附带 base path 或 query，并在 `proxy_pass` 中追加。多上游限定为纯 `scheme://host[:port]` 结构，且同一规则内的协议必须一致。 -* `proxy_routes.origin_host` 为可选字段，用于回源时覆盖 `Host` 请求头。 -* 所有直连类型上游地址都必须为合法的 `http://` 或 `https://`。 -* 内网穿透类型上游必须关联有效 `tunnel_id`，并指定内网目标地址与协议。 -* Pages 类型上游必须关联有效 Pages 项目，且项目必须存在已激活部署。Pages 站点不执行服务端构建、边缘函数或动态运行时代码，仅托管预构建静态资源。 +### 1. Server 分层 (`openflare_server/`) -## Pages 静态托管约束 +| 目录 | 职责 | +| ------------- | ------------------------------------------------ | +| `controller/` | 参数解析、调用 service、返回响应 | +| `service/` | 业务逻辑、校验、事务编排、配置渲染 | +| `model/` | 纯净实体模型类定义、旧迁移框架兼容与上下文注入 | +| `model/goose/` | goose 迁移提供者、桥接逻辑、注册入口与具体迁移文件 | +| `router/` | 路由注册 | +| `middleware/` | 认证、鉴权、限流、CORS、Turnstile 验证等横切逻辑 | +| `common/` | 配置、全局状态与初始化入口 | +| `utils/` | 纯工具函数与通用 helper | +| `job/` | 定时任务（各业务定时逻辑在独立文件中定义，cron.go 仅用于初始化调度） | +| `upload/` | 运行时本地临时文件上传目录（在 .gitignore 中忽略） | +| `logs/` | 运行时本地日志输出目录（在 .gitignore 中忽略） | +| `docs/` | API 文档（Swagger） | +| `data/` | 静态数据（如 GeoIP 数据库） | -OpenFlare Pages 面向边缘节点静态站点托管，采用“项目 + 不可变部署 + 网站规则绑定”的模型。 +### 2. Agent 模块 (`openflare_agent/`) -约束： +| 目录/模块 | 职责 | +| ----------------------------- | -------------------------------------------- | +| `cmd/agent/` | Agent 命令行启动入口及主函数 | +| `internal/config/` | 配置读取与默认值 | +| `internal/heartbeat/` | 心跳与版本摘要判断 | +| `internal/sync/` | 配置拉取与应用编排 | +| `internal/nginx/` | OpenResty 文件写入、校验、reload、启动与回滚 | +| `internal/state/` | 本地状态与观测补报缓冲 | +| `internal/httpclient/` | Server 通信 | +| `internal/wsclient/` | WebSocket 客户端通信 | +| `internal/protocol/` | Agent API 协议类型 | +| `internal/updater/` | Agent 自更新逻辑 | +| `internal/logging/` | 日志处理 | +| `internal/observability/` | 可观测性（指标、链路等） | +| `internal/geoipdata/` | GeoIP 数据处理 | +| `internal/geoipupdate/` | GeoIP 数据更新 | +| `internal/agent/` | 核心 Agent 逻辑与生命周期 | -* Pages 项目保存名称、标识、启用状态、SPA fallback 启用状态、自定义回退路径和当前激活部署。 -* Pages 部署由管理端上传预构建 zip 包生成；部署包保存在 Server 本地 Pages 存储目录，数据库只保存部署元数据和文件清单，不保存大体积文件内容。 -* 只有项目存在激活部署后，`proxy_routes.upstream_type = 'pages'` 的网站规则才能绑定该项目。 -* Pages 网站继续复用网站规则的域名、HTTPS、WAF、PoW、Basic Auth、限流、缓存配置和配置版本发布机制。 -* 发布快照保存 Pages 项目、部署 ID、部署 checksum、入口文件、SPA fallback 启用状态和回退路径。Agent 拉取激活配置时按部署 checksum 下载并校验部署包，解压到本地 `pages_dir` 后再应用 OpenResty 配置。 -* V1 不支持 Git 自动构建、预览域名、边缘函数、动态 SSR、外部对象存储或多租户隔离。 +### 3. Frontend 分层 (`openflare_server/web/`) -## 内网穿透约束 +| 目录 | 职责 | +| ------------- | -------------------------------------------- | +| `app/` | Next.js App Router 路由、布局、页面组装 | +| `features/` | 按业务域组织的功能模块 | +| `components/` | 跨 feature 复用的 UI 组件 | +| `lib/` | 请求客户端、环境变量、工具函数、常量 | +| `store/` | 少量跨页面 UI 状态管理 | +| `types/` | 共享类型定义 | +| `styles/` | 全局样式 | +| `tests/` | 前端单元测试与集成测试（Vitest、Playwright） | +| `scripts/` | 构建和部署相关脚本 | +| `public/` | 静态资源 | -OpenFlare 通过 TunnelRelay 节点与 OpenFlared 客户端实现内网穿透，底层基于 frp（快速反向代理）构建。 +### 4. Relay 模块 (`openflare_relay/`) -### 节点与组件模型 +| 模块 | 职责 | +| ---------------- | ------------------------------------------------ | +| `cmd/` | Relay 命令行启动入口及初始化主函数 | +| `internal/config/`| 本地配置文件解析与默认参数初始化 | +| `internal/frps/` | 管理 frps 进程生命周期、端口与 Token 并监控运行 | +| `internal/heartbeat/`| 周期性 HTTP 心跳通信、上报状态并获取更新请求 | +| `internal/httpclient/`| Server 的通用 API 客户端调用工具类 | +| `internal/observability/`| 采集本地宿主机、frps 的基础运行指标并进行预聚合 | +| `internal/relay/` | 协调中继的核心生命周期、初始化与清理 | +| `internal/state/` | 本地运行时状态、错误记录与持久化缓存 | +| `internal/updater/`| Relay 升级检查、下载安装与重启机制 | +| `internal/wsclient/`| 与 Server 保持的长连接 WebSocket 双向通信管道 | -**节点类型**： +### 5. OpenFlared (Client) 模块 (`openflared/`) -* `nodes.node_type` 区分节点类型：`edge_node`（边缘节点，默认）和 `tunnel_relay`（隧道中继）。 -* TunnelRelay 节点同时运行 Agent（OpenResty）和 Relay（frps 管理器），共享同一个 `agent_token`。 - - Agent 负责 HTTPS 终结、WAF 防护、缓存与流量限制等。 - - Relay 管理 frps 进程，为内网客户端提供隧道中继服务。 -* TunnelRelay 节点新增字段：`node_type`、`relay_bind_port`（frpc 连接端口，默认 7000）、`relay_vhost_http_port`（HTTP Vhost 端口，默认 8080）、`relay_auth_token`（自动生成）、`relay_status` 等。 +| 模块 | 职责 | +| ---------------- | ------------------------------------------------ | +| `cmd/` | Client 命令行启动入口及初始化主函数 | +| `internal/config/`| 本地客户端配置加载与解析 | +| `internal/flared/`| 内网穿透客户端的核心调度与状态管理机制 | +| `internal/frpc/` | 热重载/动态生成多 Relay 的 `frpc.toml` 并监控 frpc | +| `internal/heartbeat/`| 与控制面进行的心跳通信，包含 Token 校验机制 | +| `internal/httpclient/`| 客户端通用 API 通信客户端 | +| `internal/sync/` | 增量拉取最新 Tunnel 路由绑定关系、生成快照并应用 | +| `internal/updater/`| 客户端自更新、新版检查与更新落地逻辑 | +| `internal/wsclient/`| 用于实时监听 Server 端隧道配置变更推送的 WS 信道 | -**Tunnel 客户端**： - -* `tunnels` 表独立存储内网穿透客户端注册信息，与 `nodes` 体系无关。 -* 每个 Tunnel 拥有唯一的 `tunnel_id`（格式 `tun-<32hex>`）和 `tunnel_token`（客户端认证凭据）。 -* OpenFlared 客户端运行在内网，不对外暴露，使用 `tunnel_token` 认证，通过 `/api/flared/*` 端点与 Server 通信。 -* 一个 OpenFlared 客户端可同时连接多个 Relay（为高可用）。 - -### 上游类型扩展 - -`proxy_routes` 的上游配置分为两种类型，通过 `upstream_type` 字段区分： - -* **直连上游（`direct`，默认）**：直接将流量转发到源站地址，行为与现有完全一致。 -* **内网穿透上游（`tunnel`）**：通过 TunnelRelay 节点将流量转发到内网服务。 - - 必须指定 `tunnel_id`（关联 `tunnels` 表）。 - - 必须指定 `tunnel_target_addr`（内网目标地址，如 `192.168.1.100:8080`）和 `tunnel_target_protocol`（`http` 或 `https`）。 - - 发布时，Server 自动将上游地址替换为 `http://127.0.0.1:{relay_vhost_http_port}`。 - -### 流量路径与协议 - -**完整数据面流量路径**： - -``` -浏览器 → OpenResty (Agent, TLS/WAF) [TunnelRelay 节点] - ↓ - frps (Relay, HTTP Vhost 路由) [TunnelRelay 节点, 127.0.0.1:{vhost_port}] - ↓ - frp 隧道协议 (Host 头路由) - ↓ - frpc (Client, 多进程) [内网服务器] - ↓ - 内网服务 (192.168.x.x:port) -``` - -**关键特性**： - -* frps 使用 HTTP Vhost 单端口复用机制，所有 HTTP 隧道共享一个 `vhost_port`，通过 Host 头自动路由到对应 frpc。 -* Agent 保留原始 `Host` 请求头，frps 依据此头进行虚拟主机匹配。 -* 每个隧道对应一条 `proxy_routes`，可绑定多个域名。 -* OpenFlared 客户端为每个连接的 Relay 管理一个独立的 frpc 进程，通过单一 frp 隧道传输多个 HTTP 代理定义。 - -### 配置同步模型 - -发布流程同时生成两类配置版本数据，统一使用 `config_version` 版本号关联： - -* **Agent 侧配置**：OpenResty 主配置 + 路由配置 + WAF 规则。包含 tunnel 上游时，自动渲染为 `http://127.0.0.1:{vhost_port}` 上游。 -* **Tunnel 侧配置**：Relay 列表 + frpc 代理定义。随发布流程版本化，变更时优先使用 `frpc reload` 热重载。 -* **Relay 配置**：通过心跳响应下发，相对静态，不纳入版本化流程。 - -### 隧道设计约束 - -* 仅支持 HTTP 协议隧道流量（保留 TCP/UDP 隧道的可扩展性），暂不支持单独的 TCP/UDP 端口分配。 -* Tunnel 类型上游的域名 DNS 应当解析到指定的 TunnelRelay 中继节点。 -* frp 二进制（v0.61+）由系统部署脚本或容器镜像统一打包提供。 - - -## HTTPS 约束 - -`proxy_routes.domain_cert_ids` 用于记录与 `domains` 平行的域名证书绑定；值为 `0` 表示该域名不启用 HTTPS，仅保留 HTTP。 - -发布渲染时： - -* 带证书的域名按证书分组输出独立 `443 ssl` `server` 块。 -* 未绑定证书的域名不得被自动带入 HTTPS。 -* 必须将 `proxy_routes.domains` 中的全部域名一并纳入同一站点配置，避免同站点在版本快照中被拆散。 - -## WAF 约束 - -WAF 以规则组为核心配置边界。系统提供唯一的全局规则组（默认应用至所有站点），网站可在此基础上叠加多个自定义规则组。 - -核心能力： - -* 支持单个 IP / CIDR 网段黑白名单。 -* 支持 IP 组引用（包括手动、自动Expr计算、URL订阅三类 IP 组）。 -* 支持基于 GeoIP 的国家/地区级地域准入过滤。 -* 支持规则组自定义拦截响应（支持自定义状态码与拦截 HTML 页面，默认返回 `418`）。 - -IP 组与判定约束： - -* **运行时解耦**：WAF 运行时只读取本地 JSON，不访问 Server 数据库；配置版本仅保存引用的 IP 组 ID。IP 组成员通过哈希 Checksum 差分心跳及 WebSocket 异步推送，实现无需平滑重载 Nginx 的热生效。 -* **内置预设 Expr 规则**： - * 高频 404 扫描封禁：`request_count > 100 && status_404_ratio >= 0.8` - * 恶意 IP 直连探测：`ip_host_count > 50 && ip_host_ratio > 0.5` -* **判决优先级**：白名单拥有绝对优先权。若未命中白名单，则触发黑名单漏斗匹配（全局规则组优先，自定义组按 ID 升序匹配）。 -* 地域解析依赖节点本地 MaxMind 库；当 GeoIP 异常时自动忽略地域规则，不得破坏 IP 规则与反代主链路的可用性。 - -## 认证源约束 - -`auth_sources` 统一支持 `github` 与 `oidc` 登录配置入口。`external_accounts` 存储第三方与本地用户的绑定关系。第三方账号首次接入逻辑： - -* 已绑定时直接授权登录；若已有本地会话则自动建立绑定。 -* 未绑定且允许注册时自动创建本地账号；若关闭注册，则要求用户提供已有本地账号密码以建立关联。 - -## 版本与观测约束 - -* `config_versions` 必须保存完整快照、渲染结果与 `checksum`。 -* 全局同时只能有一个激活版本。 -* 回滚通过重新激活旧版本实现。 -* `nodes` 只承载控制面状态与低频摘要，不承载高频观测事实。 -* 指标、趋势和访问分析优先使用服务端聚合结果，而不是前端临时统计。 -* 访问明细只保留受控时间窗口，不演变成通用日志平台。 +--- ## 文档维护原则 -* 产品范围或系统边界变化时更新本文档。 -* 系统结构或模块职责变化时更新 [系统架构](./architecture.md)。 -* 发布、同步、回滚与 Agent 模型变化时更新 [Agent 与发布模型](./agent-design.md)。 -* 开发约束、代码规范、接口约定变化时更新 [开发约束](../guildline/development-constraints.md)。 -* 部署方式变化时更新 [部署说明](../deployment/deployment.md) 与 README. -* 配置项变化时更新 [配置项参考](../reference/configuration.md)。 -* 已完成阶段不再以“版本计划”形式回填。 -* 新阶段开始前，先补设计，再进入实现。 +* 产品范围或系统边界变化：更新本文档（[产品边界](./index.md)）。 +* 系统结构、组件分工变化：更新 [系统架构](./architecture.md)。 +* 发布、同步、回滚与 Agent 模型变化：更新 [Agent 与发布模型](./agent-design.md)。 +* 开发约束、代码规范、接口约定变化：更新 [开发约束](../guideline/development-constraints.md)。 +* 部署方式变化：更新 [部署说明](../deployment/deployment.md) 与 README。 +* 配置项变化：更新 [配置项参考](../reference/configuration.md)。 diff --git a/docs/design/kuma-design.md b/docs/design/kuma-design.md new file mode 100644 index 00000000..0f18a90c --- /dev/null +++ b/docs/design/kuma-design.md @@ -0,0 +1,109 @@ +# Uptime Kuma 监控同步设计 + +你会学到：OpenFlare 与 Uptime Kuma 监控服务集成的设计背景、基于 Socket.IO 协议的控制流设计、以标签隔离为核心的防污染模型，以及差分增量同步的状态机比对逻辑。 + +--- + +## 需求分析 + +在多节点的网关架构中，监控系统的状态与反向代理路由的状态通常是相互脱节的： +1. **录入开销大**：每当网关控制面新增或下线一个站点，管理员都必须在监控系统（如 Uptime Kuma）中重复配置对应的探测地址与告警策略。 +2. **数据不一致**：当代理路由域名发生变更或切换 HTTPS 时，容易遗漏修改监控参数，导致监控系统误报或漏报。 +3. **环境污染隐患**：如果简单的在监控中执行全量“删除-重建”同步，不仅会清空监控系统中的历史统计指标和 SLA 曲线，还会影响到用户在此监控实例上自行配置的、与网关无关的其他监控任务。 + +为了解决这些痛点，OpenFlare 引入了基于客户端/服务器模式的 **Uptime Kuma 自动监控同步机制**，实现网关站点路由定义与可用性监测系统的强一致、低开销以及零污染同步。 + +--- + +## 核心架构设计 + +Uptime Kuma 同步子系统完全运行在 **Server 控制面** 的后台调度器中。 + +```text + [ OpenFlare 控制面 / 数据库 ] [ Uptime Kuma 实例 ] + │ │ + 1. 定时 Cron 触发 (Job) │ + │ │ + 2. 读取代理路由与选项配置 │ + │ │ + 3. 连接 Socket.IO 接口 <──── 4. Socket.IO 握手 & 登录 ───┤ + │ │ + ├────── 5. 校验 / 创建 "OpenFlare" 标签 ────────►│ + ├────── 6. 比对监测站点属性与 Kuma 监控清单 ──────►│ + │ │ + └────── 7. 执行差分指令 (add / edit / delete) ─►│ +``` + +同步子系统不经过数据面的 Agent 节点，而是由 Server 通过 Uptime Kuma 暴露的 Socket.IO 端点直接交互。这种设计可以降低边缘节点的网络开销，并将鉴权凭证（Kuma 用户名与密码）安全收拢在控制面中。 + +--- + +## 标签隔离与防污染设计 + +为了在一个共享的 Uptime Kuma 实例中安全运行，而不干扰用户手动创建的其他监控项，设计上采用了 **专属标签隔离机制**： + +1. **`OpenFlare` 专属标签**： + * 同步程序首次连接时，会调用 `getTags` 接口拉取实例中的所有标签。 + * 检查是否存在名为 `OpenFlare` 的标签（默认颜色为靛蓝色 `#4f46e5`）。如果不存在，则通过 `addTag` 接口在 Kuma 中自动创建它。 +2. **过滤范围收拢**： + * 同步任务在拉取 Uptime Kuma 的监控列表（`monitorList`）后，仅会保留**打有 `OpenFlare` 标签**的监控项。 + * 所有的修改比对（`editMonitor`）和下线清理（`deleteMonitor`）**仅在此过滤子集内进行**。任何未绑定 `OpenFlare` 标签的监控项对同步程序均是“隐形”的，实现了完美的防污染隔离。 + +--- + +## 差分同步状态机逻辑 + +同步程序每次执行时，会对 OpenFlare 本地配置与 Uptime Kuma 数据进行差分计算，根据比对结果执行不同的 Socket.IO 事件： + +```mermaid +stateDiagram-v2 + [*] --> 检查站点状态与监控范围 + + state "检查监控范围" as Scope { + [*] --> 校验站点是否启用并且在 Scope 内 + 校验站点是否启用并且在 Scope 内 --> 在Scope内 : 是 + 校验站点是否启用并且在 Scope 内 --> 不在Scope内 : 否 + } + + 不在Scope内 --> 检查Kuma中是否存在同名且带标签的监控 + 检查Kuma中是否存在同名且带标签的监控 --> 执行清理 : 存在 + 检查Kuma中是否存在同名且带标签的监控 --> 忽略 : 不存在 + + 在Scope内 --> 检查Kuma中是否存在同名监控 + + state "比对属性" as Compare { + [*] --> 检查是否存在 + 检查是否存在 --> 新建监控项 : 否 + 检查是否存在 --> 比对元数据 : 是 + 比对元数据 --> 属性一致 : 匹配 + 比对元数据 --> 属性不一致 : 不匹配 + } + + 新建监控项 --> 发送add指令并绑定Tag + 属性不一致 --> 发送editMonitor指令 + 属性一致 --> 忽略 + + 执行清理 --> 发送deleteMonitor指令 + 忽略 --> [*] +``` + +### 1. 监测 URL 规范化 +站点路由在 OpenFlare 中可配置多个域名，同步程序自动提取其主域名（Primary Domain）并根据是否启用 HTTPS 组装为标准的 `http://` 或 `https://` 前缀。 + +### 2. 比对属性清单 +如果同名且带标签的监控已存在，同步程序会细致比对以下 5 个关键字段是否与当前网关全局 Option 一致。只要有一个字段不匹配，便会触发更新： +* **URL 地址**：`Url` +* **探测频率**：`Interval`（默认 60s） +* **重试次数**：`MaxRetries` +* **重试间隔**：`RetryInterval`（默认 60s） +* **请求超时**：`Timeout`（默认 48s） + +--- + +## 调度器与高并发保护 + +1. **基于 Cron 的单线程执行**： + * Server 周期性（每 1 分钟）通过后台的 Cron Job 探测是否达到配置的同步间隔（`UptimeKumaSyncInterval`）。 + * 任务内部设计了互斥锁（Mutex Locking）。如果前一次同步请求因为网络延迟等原因尚未结束，下一次调度将自动跳过，防止并发多个 Socket.IO 连接对 Uptime Kuma 实例造成 DDOS 冲击。 +2. **WebSocket 状态监听**： + * 同步程序利用 Socket.IO 的事件监听机制，在连接建立后，必须等到监听到 `monitorList` 事件的完整列表推送后，才允许向下执行差分算法，以规避因为数据加载不完整导致误删监控项的边界情况。 diff --git a/docs/design/repository.md b/docs/design/repository.md deleted file mode 100644 index 2f121de4..00000000 --- a/docs/design/repository.md +++ /dev/null @@ -1,95 +0,0 @@ -# 仓库结构 - -你会学到：OpenFlare 仓库中 Server、Agent、前端、脚本和文档目录分别负责什么，以及贡献代码时应把逻辑放到哪一层。 - -| 路径 | 职责 | -| ---------------------- | ---------------------------------------------------- | -| `openflare_server` | Gin + GORM + SQLite/PostgreSQL 单体控制面 | -| `openflare_server/web` | Next.js 15 App Router 管理端前端，由 Go Server 托管 | -| `openflare_agent` | Go 单体 Agent，运行在节点侧 | -| `openflare_relay` | Tunnel 中继代理，运行在公网边缘管理 frps 进程 | -| `openflared` | Tunnel 客户端，运行在内网服务器侧管理 frpc 进程 | -| `scripts` | 安装、自更新等系统辅助脚本 | -| `docs` | VitePress 文档站、设计基线、开发规范、部署与配置文档 | -| `docs/en` | 英文版文档 | - -## Server 分层 - -| `controller/` | 参数解析、调用 service、返回响应 | -| `service/` | 业务逻辑、校验、事务编排、配置渲染 | -| `model/` | 纯净实体模型类定义、旧迁移框架兼容与上下文注入 | -| `model/goose/` | goose 迁移提供者、桥接逻辑、注册入口与具体迁移文件 | -| `router/` | 路由注册 | -| `middleware/` | 认证、鉴权、限流、CORS、Turnstile 验证等横切逻辑 | -| `common/` | 配置、全局状态与初始化入口 | -| `utils/` | 纯工具函数与通用 helper | -| `job/` | 定时任务（如 SSL 证书续期） | -| `upload/` | 运行时本地临时文件上传目录（在 .gitignore 中忽略） | -| `logs/` | 运行时本地日志输出目录（在 .gitignore 中忽略） | -| `docs/` | API 文档（Swagger） | -| `data/` | 静态数据（如 GeoIP 数据库） | - -## Agent 模块 - -| 目录/模块 | 职责 | -| ----------------------------- | -------------------------------------------- | -| `cmd/agent/` | Agent 命令行启动入口及主函数 | -| `internal/config/` | 配置读取与默认值 | -| `internal/heartbeat/` | 心跳与版本摘要判断 | -| `internal/sync/` | 配置拉取与应用编排 | -| `internal/nginx/` | OpenResty 文件写入、校验、reload、启动与回滚 | -| `internal/state/` | 本地状态与观测补报缓冲 | -| `internal/httpclient/` | Server 通信 | -| `internal/wsclient/` | WebSocket 客户端通信 | -| `internal/protocol/` | Agent API 协议类型 | -| `internal/updater/` | Agent 自更新逻辑 | -| `internal/logging/` | 日志处理 | -| `internal/observability/` | 可观测性（指标、链路等） | -| `internal/geoipdata/` | GeoIP 数据处理 | -| `internal/geoipupdate/` | GeoIP 数据更新 | -| `internal/agent/` | 核心 Agent 逻辑与生命周期 | - -## Frontend 分层 - -| 目录 | 职责 | -| ------------- | -------------------------------------------- | -| `app/` | Next.js App Router 路由、布局、页面组装 | -| `features/` | 按业务域组织的功能模块 | -| `components/` | 跨 feature 复用的 UI 组件 | -| `lib/` | 请求客户端、环境变量、工具函数、常量 | -| `store/` | 少量跨页面 UI 状态管理 | -| `types/` | 共享类型定义 | -| `styles/` | 全局样式 | -| `tests/` | 前端单元测试与集成测试（Vitest、Playwright） | -| `scripts/` | 构建和部署相关脚本 | -| `public/` | 静态资源 | - -## Relay 模块 - -| 模块 | 职责 | -| ---------------- | ------------------------------------------------ | -| `cmd/` | Relay 命令行启动入口及初始化主函数 | -| `internal/config/`| 本地配置文件解析与默认参数初始化 | -| `internal/frps/` | 管理 frps 进程生命周期、端口与 Token 并监控运行 | -| `internal/heartbeat/`| 周期性 HTTP 心跳通信、上报状态并获取更新请求 | -| `internal/httpclient/`| Server 的通用 API 客户端调用工具类 | -| `internal/observability/`| 采集本地宿主机、frps 的基础运行指标并进行预聚合 | -| `internal/relay/` | 协调中继的核心生命周期、初始化与清理 | -| `internal/state/` | 本地运行时状态、错误记录与持久化缓存 | -| `internal/updater/`| Relay 升级检查、下载安装与重启机制 | -| `internal/wsclient/`| 与 Server 保持的长连接 WebSocket 双向通信管道 | - -## OpenFlared (Client) 模块 - -| 模块 | 职责 | -| ---------------- | ------------------------------------------------ | -| `cmd/` | Client 命令行启动入口及初始化主函数 | -| `internal/config/`| 本地客户端配置加载与解析 | -| `internal/flared/`| 内网穿透客户端的核心调度与状态管理机制 | -| `internal/frpc/` | 热重载/动态生成多 Relay 的 `frpc.toml` 并监控 frpc | -| `internal/heartbeat/`| 与控制面进行的心跳通信，包含 Token 校验机制 | -| `internal/httpclient/`| 客户端通用 API 通信客户端 | -| `internal/sync/` | 增量拉取最新 Tunnel 路由绑定关系、生成快照并应用 | -| `internal/updater/`| 客户端自更新、新版检查与更新落地逻辑 | -| `internal/wsclient/`| 用于实时监听 Server 端隧道配置变更推送的 WS 信道 | - diff --git a/docs/en/design/architecture.md b/docs/en/design/architecture.md index 0a9f8f6e..97a26235 100644 --- a/docs/en/design/architecture.md +++ b/docs/en/design/architecture.md @@ -219,5 +219,5 @@ Before modifying architectural code, please read: 1. [Product Boundaries](./index.md) 2. [Agent & Publish Model](./agent-design.md) -3. [Development Constraints](../../guildline/development-constraints.md) +3. [Development Constraints](../../guideline/development-constraints.md) 4. [Repository Structure](./repository.md) diff --git a/docs/en/design/development.md b/docs/en/design/development.md index 80f2d052..df44130e 100644 --- a/docs/en/design/development.md +++ b/docs/en/design/development.md @@ -2,7 +2,7 @@ You will learn: How to build OpenFlare's local development environment, start the Server, the Agent, and the Admin Frontend, run test and build commands, and understand the boundaries to respect before contributing code. -This page is aimed at contributors. Product boundaries, data model constraints, API conventions, and frontend layering specifications are governed by [Development Constraints](../../guildline/development-constraints.md); this page only provides actionable workflows for local development. +This page is aimed at contributors. Product boundaries, data model constraints, API conventions, and frontend layering specifications are governed by [Development Constraints](../../guideline/development-constraints.md); this page only provides actionable workflows for local development. ## Repository Structure @@ -174,7 +174,7 @@ go build -o openflare-agent ./cmd/agent Before contributing, verify: 1. The requirement matches [Product Boundaries](./index.md). -2. The implementation conforms to [Development Constraints](../guildline/development-constraints.md). +2. The implementation conforms to [Development Constraints](../guideline/development-constraints.md). 3. The change does not disrupt publishing, sync, rollback, or upgrading lifecycles. 4. Update corresponding documentation if configurations, deployments, APIs, or boundaries change. 5. High-risk edits must be accompanied by unit tests or equivalent integration testing. diff --git a/docs/en/design/index.md b/docs/en/design/index.md index 33f4ef2f..888c3fde 100644 --- a/docs/en/design/index.md +++ b/docs/en/design/index.md @@ -197,7 +197,7 @@ IP Group & Judgment Constraints: * Update this document when the product range or system boundaries change. * Update [System Architecture](./architecture.md) when the system structure or module responsibilities change. * Update [Agent & Publish Model](./agent-design.md) when the publishing, synchronization, rollback, or Agent model changes. -* Update [Development Constraints](../../guildline/development-constraints.md) when developer constraints, code specifications, or API conventions change. +* Update [Development Constraints](../../guideline/development-constraints.md) when developer constraints, code specifications, or API conventions change. * Update README and [Deployment Instructions](../../deployment/deployment.md) when deployment methods change. * Update [Configurations Reference](../reference/configuration.md) when configuration items change. * Completed phases should no longer be backfilled as "version plans". diff --git a/docs/en/guide/index.md b/docs/en/guide/index.md index c557cccc..72d70ccd 100644 --- a/docs/en/guide/index.md +++ b/docs/en/guide/index.md @@ -30,7 +30,7 @@ If you are new to OpenFlare, read the documents in the following order: | Start Server from source code | [Launch Server](../deployment/server.md) | | Configure GitHub or OIDC SSO | [SSO Login Configuration](./sso.md) | | Upgrade Server or Agent | [Upgrade & Maintenance](../deployment/upgrade.md) | -| Participate in development or bug fixing | [Local Development](../design/development.md) and [Development Constraints](../../guildline/development-constraints.md) | +| Participate in development or bug fixing | [Local Development](../design/development.md) and [Development Constraints](../../guideline/development-constraints.md) | | Understand architecture and publishing | [System Architecture](../design/architecture.md) and [Agent & Publish Model](../design/agent-design.md) | | View open-source references and credits | [Credits](./credits.md) | diff --git a/docs/guide/first-site.md b/docs/guide/first-site.md index 9f05ee30..a3a4203a 100644 --- a/docs/guide/first-site.md +++ b/docs/guide/first-site.md @@ -1,100 +1,69 @@ # 发布第一份配置 -你会学到：如何创建第一条网站配置、绑定源站与证书、发布配置版本，并确认 Agent 已经应用。 +你会学到：如何以最简单的方式创建第一条反向代理规则、发布配置版本，并确认 Agent 已经拉取并应用配置。 -OpenFlare 的发布链路以完整配置版本为中心。你在管理端修改网站配置后，需要发布并激活新版本，Agent 才会在后续 heartbeat 中拉取并应用。 +OpenFlare 的发布链路以“不可变配置版本”为核心。你在管理端修改规则后，需要发布并激活新版本，在线的 Agent 才会自动同步并应用。 + +--- ## 发布前检查 -确认以下条件已经满足： +在开始发布前，请确保以下条件已满足： -| 项目 | 期望 | +| 检查项 | 状态要求 | | --- | --- | -| Server | 可以登录管理端 | -| Agent | 至少一个节点在线 | -| 源站 | Agent 节点可以访问源站地址 | -| 域名 | 域名已经解析到 OpenResty 节点，或准备通过本地 hosts / curl Host 头验证 | -| HTTPS | 如需 HTTPS，证书已上传或托管 | +| **Server** | 控制面板已正常启动，且能顺利登录管理端 | +| **Agent** | 至少有一个 Agent 节点处于在线状态（可在「节点管理」中确认） | +| **源站** | 确认你的后端源站服务可从 Agent 宿主机正常访问 | +| **域名/测试** | 域名已完成 DNS 解析，或者准备好在客户端使用本地 hosts / curl 命令行 Host 头进行测试 | -## 创建网站配置 +--- -在管理端新增网站配置时至少需要： +## 步骤一：创建首个网站配置 -| 字段 | 说明 | -| --- | --- | -| 网站名称 | 业务唯一标识；未显式填写时可使用主域名 | -| 域名 | 至少一个域名，第一项视为主域名 | -| 源站地址 | 合法的 `http://` 或 `https://` 上游地址 | -| 启用状态 | 只有启用的网站配置会参与发布渲染 | +为了快速验证，我们首先部署一个最基础的 HTTP 反代站点： -示例： +1. 登录控制面板，进入 **「网站配置」**，点击 **「创建网站」**。 +2. 填写最基础的站点配置： + * **网站名称**：输入简易标识（如 `first-app`）。 + * **域名 (Domains)**：输入用于测试的域名（如 `first.example.com`）。**第一项默认作为主域名**。 +3. 配置上游源站（Upstream）： + * **源站类型**：选择「标准反代」。 + * **源站地址**：勾选手动输入并填入后端服务地址（如 `http://10.0.0.10:8080` 或测试专用的 `http://httpbin.org`）。 +4. 点击保存，完成网站创建。 -| 字段 | 示例 | -| --- | --- | -| 网站名称 | `app` | -| 域名 | `app.example.com` | -| 源站地址 | `http://10.0.0.20:8080` | +> [!TIP] +> **关于 HTTPS 与证书准备** +> 本节仅引导快速部署基础 HTTP 规则。若你需要导入已有的 SSL 证书或通过 ACME 协议向 Let's Encrypt 自动申请证书并开启 443 端口 HTTPS 代理，请前往 [新建反代配置](./proxy-config.md) 查阅详细步骤。 -同一个域名只能属于一个网站配置。同一网站内的流量限制、反向代理和缓存配置按站点共享。 +--- -## 绑定证书 +## 步骤二：预览并发布配置版本 -HTTPS 证书按域名绑定。没有绑定证书的域名不会被自动放入 `443 ssl` server 块。 +新增的网站配置仍保存在 Server 的数据库中，处于草稿状态，需要通过发布版本分发到数据面： -如果一个网站包含多个域名，发布渲染会按证书分组生成 HTTPS 配置，并确保所有域名仍属于同一站点快照。 +1. 点击控制面板右上角的 **「配置预览」** 按钮，系统会展示本次新增路由的物理配置文件 Diff 差异。 +2. 确认渲染出的配置内容正确无误后，点击 **「发布并激活」**。 +3. 控制面将生成一个唯一的配置版本号（格式为 `YYYYMMDD-NNN`）。 -## 发布与激活 +--- -标准链路： +## 步骤三：验证 Agent 生效状态 -```text -修改规则 -> 预览 / 查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果 -``` +发布成功后，控制面会立即通过 WebSocket 通知在线 Agent（若 WebSocket 离线，则会在 Agent 的心跳中作为差分感知）： -发布时 Server 会读取全部启用的网站配置、OpenResty 主配置模板、性能参数与缓存参数，渲染完整 OpenResty 配置，计算 `checksum`，写入 `config_versions`，再切换激活版本。 - -## 验证结果 - -发布后在管理端确认： - -| 位置 | 期望结果 | -| --- | --- | -| 节点列表 | 节点在线 | -| 节点详情 | 当前版本与激活版本一致 | -| 应用记录 | 最近一次应用成功 | -| 版本页面 | 新版本处于激活状态 | - -在节点上确认 Agent 日志： - -```bash -journalctl -u openflare-agent -n 100 --no-pager -``` - -用域名访问： - -```bash -curl -I http://app.example.com -``` - -如果域名还没有正式解析，可以临时指定 Host 头访问节点 IP： - -```bash -curl -I -H 'Host: app.example.com' http://NODE_IP -``` - -HTTPS 验证： - -```bash -curl -I https://app.example.com -``` - -## 回滚 - -如果目标版本应用失败并回滚，Agent 会在本地阻断同一 `version + checksum` 的重复应用，直到控制面激活版本或 checksum 发生变化。 - -回滚到旧版本： - -1. 打开配置版本页面。 -2. 找到上一个确认可用的历史版本。 -3. 重新激活该版本。 -4. 查看节点应用记录，确认 Agent 应用成功。 +1. **管理端验证**：进入「节点管理」-> 点击节点进入详情，检查**当前版本号**是否已成功变为刚刚发布的最新激活版本，且「应用记录」显示为成功。 +2. **边缘节点验证**：你可以在 Agent 节点宿主机上通过日志检查应用情况： + ```bash + # 如果是 Docker 部署的 Agent + docker logs openflare-agent + + # 如果是本地 systemd 部署的 Agent + journalctl -u openflare-agent -n 50 --no-pager + ``` +3. **连通性测试**： + 在客户端电脑上，使用 `curl` 携带测试 Host 请求 Agent 节点的 IP 地址进行最终验证： + ```bash + curl -I -H "Host: first.example.com" http://AGENT_NODE_IP + ``` + 若返回的状态码与后端源站响应一致，即代表你的第一条反代规则已成功在边缘节点落地生效！ diff --git a/docs/guide/index.md b/docs/guide/index.md index 2dc3e787..2871cbfd 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -9,13 +9,16 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站 如果你第一次接触 OpenFlare，按下面顺序阅读： 1. [快速开始](./quick-start.md)：用 Docker Compose 启动 Server，登录管理端，并接入第一个 Agent。 -2. [基础使用](./usage.md)：了解网站配置、源站、证书、发布、回滚和观测的常见操作。 -3. [内网穿透与隧道使用](./tunnel-usage.md)：学习部署 Relay 与 Client，实现安全、无公网 IP 反向穿透。 -4. [WAF 安全防护使用](./waf-usage.md)：掌握 IP 黑白名单、自动 IP 组 Expr 自动聚合、地域限制与 PoW CC 防护。 -5. [WAF 自动 IP 组语法](./waf-ip-group-expr.md)：编写自动 IP 组 Expr 规则，了解关键字含义和预设规则。 -6. [部署说明](../deployment/deployment.md)：把 Server 和 Agent 放到更接近生产的环境中运行。 -7. [配置项参考](../reference/configuration.md)：查 Server 环境变量、运行时 Option 和 Agent 配置字段。 -8. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty 应用和前端构建问题。 +2. [发布第一份配置](./first-site.md)：快速新建一条最基础的 HTTP 反代站点规则，并验证节点生效状态。 +3. [新建反代配置](./proxy-config.md)：一步一步了解如何从证书导入与申请开始，配置 HTTPS 加密与上游源站管理。 +4. [Pages 静态托管使用](./pages-usage.md)：了解静态项目 ZIP 上传限制、SPA Fallback、以及内置 API 反向代理配置。 +5. [内网穿透与隧道使用](./tunnel-usage.md)：部署 Relay 与 Client，实现安全、无公网 IP 反向穿透。 +6. [WAF 安全防护使用](./waf-usage.md)：配置 WAF 规则组，掌握 IP 黑白名单、自动/订阅 IP 组、地域限制与 PoW CC 防护。 +7. [WAF 自动 IP 组语法](./waf-ip-group-expr.md)：编写自动 IP 组 Expr 规则，了解关键字含义和预设规则。 +8. [Uptime Kuma 监控同步](./uptime-kuma.md)：配置并使用 Uptime Kuma 自动差分同步和监控范围控制。 +9. [SSO 登录配置](./sso.md)：配置 GitHub 或 OIDC 实现第三方单点登录 (SSO) 接入。 +10. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty 应用和前端构建问题。 +11. [引用与致谢](./credits.md)：查看系统依赖的优秀开源项目与社区致谢清单。 ## 按角色查找 @@ -23,14 +26,17 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站 | --- | --- | | 5 分钟内跑起管理端 | [快速开始](./quick-start.md) | | 发布第一条反向代理配置 | [发布第一份配置](./first-site.md) | +| 配置域名证书与高级反代 | [新建反代配置](./proxy-config.md) | +| 托管单页应用或静态网站 | [Pages 静态托管使用](./pages-usage.md) | | 配置内网穿透映射 | [内网穿透与隧道使用](./tunnel-usage.md) | | 配置防 CC 与 IP 组拦截 | [WAF 安全防护使用](./waf-usage.md) | | 编写自动 IP 组规则 | [WAF 自动 IP 组语法](./waf-ip-group-expr.md) | +| 自动同步监测站点状态 | [Uptime Kuma 监控同步](./uptime-kuma.md) | | 接入或重装节点 Agent | [接入 Agent](../deployment/agent.md) | | 从源码启动 Server | [启动 Server](../deployment/server.md) | | 配置 GitHub 或 OIDC 登录 | [SSO 登录配置](./sso.md) | | 升级 Server 或 Agent | [升级与维护](../deployment/upgrade.md) | -| 参与开发或修复问题 | [本地开发](../design/development.md) 与 [开发约束](../guildline/development-constraints.md) | +| 参与开发或修复问题 | [启动 Server](../deployment/server.md) 与 [开发约束](../guideline/development-constraints.md) | | 理解架构和发布模型 | [系统架构](../design/architecture.md) 与 [Agent 与发布模型](../design/agent-design.md) | | 查看开源引用与致谢 | [引用与致谢](./credits.md) | diff --git a/docs/guide/pages-usage.md b/docs/guide/pages-usage.md new file mode 100644 index 00000000..c49c6d55 --- /dev/null +++ b/docs/guide/pages-usage.md @@ -0,0 +1,86 @@ +# Pages 静态托管使用 + +你会学到：如何在 OpenFlare 中使用 Pages 静态托管功能部署前端项目（如 React、Vue 等 SPA 或 VitePress、Hugo 等静态站点），配置单页应用 (SPA) Fallback 路由以及接口反向代理 (API Proxy)，并理解不可变部署与 Agent 侧原子切换的底层逻辑。 + +--- + +## 核心机制与工作流 + +OpenFlare Pages 提供受 Cloudflare Pages 启发的 **Direct Upload (直接上传)** 静态网站托管服务。它与常规代理站点的不同之处在于，数据面的边缘节点 (Agent) 会将静态文件拉取并解压到节点本地，直接通过本地的 OpenResty 提供高性能的静态文件服务，无需维护额外的 Nginx 宿主机静态目录同步。 + +```text + [ 管理员 / CI ] ────── 1. 上传 ZIP 压缩包 ──────► [ OpenFlare Server ] + │ + [ 访客浏览器 ] ◄────── 4. 访问页面 / 静态资源 ────────── [ Agent 节点 / OpenResty ] + ▲ + │ + 2. 检查 Checksum 并拉取 ZIP + 3. 解压并原子切换 current 链接 +``` + +1. **直接上传部署包**：在控制面上传预构建好的网站 `.zip` 压缩包，Server 会生成一条带有唯一 SHA-256 校验和 (Checksum) 的不可变部署记录。 +2. **发布与推送**：在路由配置中将源站类型 (Upstream Type) 设为 `Pages 静态托管` 并绑定项目。发布配置版本后，Server 会广播给所有 Agent 节点。 +3. **安全拉取与部署**：Agent 节点识别到新配置引用了新的 Pages 部署，增量下载 ZIP 包，校验 Checksum 保证一致性，并在本地解压、完成原子目录切换，重载 OpenResty 使服务生效。 + +--- + +## 第一步：上传部署包与创建 Pages 项目 + +1. 登录管理端控制面板，进入左侧导航 **「静态托管 (Pages)」**，点击 **「创建项目」**。 +2. 填写项目基本信息： + * **项目名称**：业务名称（如 `我的前端应用`）。 + * **项目标识 (Slug)**：URL 友好的唯一英文标识（如 `my-react-app`），将作为存储目录的文件夹名。 +3. 设定站点目录结构与入口： + * **入口文件名**：默认为 `index.html`。 + * **静态资源根路径 (RootDir)**：如果你的打包产物在压缩包的子目录下（例如打包出来的 zip 里包含一个 `dist/` 目录），则需要在这里填入子路径（如 `dist`）。若打包产物直接在 zip 根目录，留空即可。 +4. **上传 ZIP 压缩包**： + * 上传你的项目静态资源打包生成的 `.zip` 文件。 + +> [!IMPORTANT] +> **部署包安全限制规范** +> 为了保障控制面和边缘节点的系统安全与性能，上传的部署包必须满足以下硬性指标，否则会被系统拒绝： +> * **大小限制**：ZIP 压缩包体积不得超过 **25 MiB**，解压后的总文件大小不得超过 **100 MiB**。 +> * **数量限制**：解压后的文件总数不得超过 **1,000 个**。 +> * **软链接拦截**：ZIP 包内禁止包含任何软链接 (Symbolic Link)，防御软链接劫持攻击。 +> * **Zip-Slip 防御**：压缩包中所有文件路径会被强制规范化，禁止使用 `..` 或以 `/` 开头，防止解压路径穿越攻击。 +> * **入口文件检查**：你指定的入口文件（在静态资源根路径下，如 `dist/index.html`）**必须在压缩包中存在**。 + +--- + +## 第二步：配置高级路由规则 + +在项目详情的配置页面中，你可以根据前端项目类型开启以下高级特性： + +### 1. 单页应用 (SPA) Fallback 路由 +对于使用 React Router、Vue Router 等进行前端路由的单页应用 (SPA)，当用户直接刷新类似 `/profile/settings` 的子路径时，边缘节点本地并不存在该物理文件，会导致 404 错误。 +* **配置方式**：在项目设置中开启 **「SPA Fallback」**，并将路径设为入口文件（如 `/index.html`）。 +* **生效逻辑**：开启后，如果访客请求的静态资源在物理上不存在，OpenResty 会自动降级重定向渲染入口文件，将路由交由前端 JavaScript 接管，避免 404 报错。 + +### 2. 内置 API 反向代理 +为了避免前端请求后端 API 时遭遇跨域 (CORS) 限制，Pages 托管支持在同一个域名下直通后端 API。 +* **配置方式**： + * **API 代理路径 (APIProxyPath)**：匹配的 URL 前缀（如 `/api`）。 + * **后端服务地址 (APIProxyPass)**：后端 API 的源站地址（如 `http://10.0.0.5:8080`）。 + * **重写规则 (APIProxyRewrite)**：可选。如果需要剥离前缀或重写路径，可使用正则匹配。例如： + * 剥离前缀：将请求 `/api/users` 重写为 `/users` 发送给后端，配置为 `^/api/(.*)$ /$1`。 +* **生效逻辑**：所有以 `/api` 开头的请求会被直接转发至后端服务，而其他请求则继续由静态托管服务处理。 + +--- + +## 第三步：绑定代理路由并发布 + +Pages 项目配置并上传好部署包后，需要绑定到对外公开的域名上才能被访客访问。 + +1. 导航至左侧菜单 **「网站配置」**，创建或编辑一个代理站点。 +2. 在「路由规则」中修改或添加一条路由： + * **源站类型 (Upstream Type)**：选择 **「Pages 静态托管」**。 + * **绑定 Pages 项目**：选择你刚才创建的项目，并指定要激活的部署版本（默认会自动关联最新上传成功的部署）。 +3. 点击右上角 **「配置预览」** -> 确认无误后点击 **「发布并激活」**。 + +## 运维与回滚 + +* **不可变部署与回滚**：每次在 Pages 项目下上传 `.zip` 文件，系统都会产生一个全新且唯一的部署版本。如果在历史部署列表中将上一版本设为激活并重新发布，可实现边缘节点的秒级回滚。 +* **原子切换与自愈**：边缘节点（Agent）在拉取静态资源包时，会执行校验与流式解压，并通过原子切换物理目录来保障服务的无缝过渡。同时，Agent 会定时清理不再引用的历史部署包。 + +> [!TIP] +> 关于不可变部署、目录结构设计、增量拉取和安全防逃逸校验等底层架构与自愈细节，请参阅 [Pages 静态托管设计](../design/pages-design.md)。 diff --git a/docs/guide/proxy-config.md b/docs/guide/proxy-config.md new file mode 100644 index 00000000..f67d273b --- /dev/null +++ b/docs/guide/proxy-config.md @@ -0,0 +1,102 @@ +# 新建反代配置 + +你会学到：如何一步一步在 OpenFlare 中从零新建并发布一个反向代理网站配置。本指南将指导你如何完成证书导入与申请、源站定义、路由规则配置、版本发布以及连通性验证。 + +--- + +## 推荐操作流程 + +在网关控制面中，建议遵循以下步骤新增反代规则： + +```text + [ 步骤 1. 证书管理 ] ──► [ 步骤 2. 源站定义 (可选) ] ──► [ 步骤 3. 新增网站配置 ] + │ + [ 步骤 5. 验证访问 ] ◄── [ 步骤 4. 发布与激活版本 ] ◄───────────────┘ +``` + +--- + +## 第一步：证书准备（导入与申请） + +在使用 HTTPS 安全加密流量前，你需要先配置对应的 TLS 证书。OpenFlare 支持以下两种证书获取方式： + +### 1. 手动导入已有证书 +如果你已经有第三方的证书（如腾讯云、阿里云申请的免费/收费证书，或者自签证书）： +1. 导航至左侧菜单 **「证书管理」**，点击 **「导入证书」**。 +2. 填入证书名称（如 `my-domain-cert`）。 +3. 复制并粘贴你的 **证书内容 (PEM 格式公钥)** 以及 **证书私钥 (KEY 格式)**，点击保存。 + +### 2. 通过 ACME 协议自动申请 +OpenFlare 集成了 ACME 客户端，支持自动向 Let's Encrypt 申请并到期续签证书： +1. **添加 ACME 账户**：进入「证书管理」->「ACME 账户」->「创建账户」，填入你的联系邮箱。 +2. **添加 DNS 账户 (用于 DNS-01 验证)**：进入「证书管理」->「DNS 账户」->「创建账户」，选择你的 DNS 托管商（当前仅 Cloudflare）并填入 API Token 凭证。 +3. **申请证书**：在「证书管理」中点击「申请证书」： + * 选择配置好的 ACME 账户和 DNS 账户。 + * 输入需要托管证书的域名（支持通配符，如 `*.example.com`）。 + * 点击申请，系统将自动配置 DNS 挑战码并向 CA 申请证书，且会在到期前 30 天自动触发续期。 + +--- + +## 第二步：准备上游源站（可选） + +源站（Origin）代表被代理的后端真实服务地址。虽然在新建网站时可以直接填写 IP，但推荐先在源站库中进行注册，以便后续复用与维护： + +1. 进入左侧导航 **「源站管理」**，点击 **「创建源站」**。 +2. 填写源站名称（如 `production-api`）。 +3. 填入合法的上游地址（如 `http://10.0.0.10:8080`），点击保存。 + +--- + +## 第三步：新建网站配置 + +证书和源站就绪后，即可创建核心网站代理路由： + +1. 进入左侧导航 **「网站配置」**，点击 **「创建网站」**。 +2. 填写网站基本配置： + * **网站名称**：业务唯一标识（如 `app-portal`）。 + * **域名 (Domains)**：输入该站点绑定的域名列表。**第一项将自动视为主域名**。 +3. 配置上游源站（Upstream）： + * **源站类型**：选择「标准反代」。 + * **源站地址**：从下拉框中选择第二步创建的源站；或者勾选手动输入并填入 `http://10.0.0.20:9000`。 +4. **绑定证书启用 HTTPS**： + * 在域名列表中，点击域名旁边的配置按钮或 HTTPS 切换开关。 + * 勾选「启用 HTTPS」，并从证书下拉列表中选择第一步准备好的证书。 + * *注意：未绑定证书的域名只会保留 80 端口 HTTP 服务，不会被写入 443 端口代理中。* +5. 点击保存创建配置。 + +--- + +## 第四步：发布并生效配置 + +你在管理端新增的网站配置仅保存在 Server 数据库中，**不会立即生效**。必须生成配置版本快照并分发到 Agent 边缘节点： + +1. 点击控制面板右上角的 **「配置预览」** 按钮。 +2. 检查配置文件的 Diff 差异，确认你刚刚新增的 `server` 块以及证书绑定规则无误。 +3. 点击 **「发布并激活」** 按钮。 +4. **Agent 落地机制**： + * 数据面的 Agent 节点在心跳中发现激活的版本 Checksum 变更，会自动拉取完整的 OpenResty 配置文件和证书包到本地。 + * 自动在本地执行配置校验（类似于 `openresty -t`），确认无语法错误后，执行平滑重载（`reload`）。 + * *如果重载或校验失败，Agent 会安全阻断并回滚至上一稳定版本，保证节点高可用。* + +--- + +## 第五步：连通性与回滚验证 + +### 1. 验证访问 +你可以通过以下方式验证新配置是否生效： +* **浏览器访问**：直接在浏览器输入 `https://your-domain.com` 查看是否成功代理后端。 +* **命令行验证**（推荐）：使用 `curl` 探测： + ```bash + curl -I https://your-domain.com + ``` +* **绕过 DNS 校验**：若你的域名尚未正式解析，可以临时指定 `Host` 请求头请求 Agent 节点物理 IP： + ```bash + curl -I -H "Host: your-domain.com" https://AGENT_NODE_IP --insecure + ``` + +### 2. 一键秒级回滚 +如果发布的新配置导致了线上业务异常： +1. 导航至左侧 **「配置版本」** 菜单。 +2. 在历史列表中找到发布前的上一个稳定版本。 +3. 点击 **「激活此版本」**。 +4. 所有在线 Agent 节点将在秒级自动重载回历史配置，实现秒级避险。 diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md index 01ad4d1b..a67bd983 100644 --- a/docs/guide/quick-start.md +++ b/docs/guide/quick-start.md @@ -164,34 +164,15 @@ journalctl -u openflare-agent -f 如果没有 systemd，脚本会输出手动启动命令。 -## 4. 发布第一份配置 +## 4. 后续步骤 -在管理端完成以下操作： +完成控制面板启动和 Agent 节点接入后，你已经成功搭建好了 OpenFlare 网关的基础运行环境。接下来你可以按顺序继续阅读以下两份指南，开始部署你的第一个反代站点： -1. 新增网站配置，填写网站名称、域名和源站地址。 -2. 确认网站配置处于启用状态。 -3. 发布前查看预览或变更摘要。 -4. 发布并激活新版本。 -5. 等待 Agent 在后续 heartbeat 中发现版本并应用。 +1. **发布第一个网站**： + * 请参阅 [发布第一份配置](./first-site.md)。它将引导你以最简单的方式（使用纯 HTTP）发布你的第一条代理规则，并验证节点落地状态。 +2. **完整配置反向代理（HTTPS 与源站管理）**： + * 请参阅 [新建反代配置](./proxy-config.md)。它将指导你从证书导入与申请开始，配置域名 HTTPS 证书绑定、源站管理并预览发布。 -版本号格式为 `YYYYMMDD-NNN`。历史版本不可变，回滚通过重新激活旧版本完成。 - -## 5. 验证是否成功 - -在管理端确认： - -| 位置 | 期望结果 | -| --- | --- | -| 节点列表 | Agent 节点在线 | -| 节点详情 | 当前版本与激活版本一致 | -| 应用记录 | 最近一次应用成功 | -| 版本页面 | 新版本处于激活状态 | - -在 Agent 节点确认： - -```bash -journalctl -u openflare-agent -n 100 --no-pager -``` ## 常见失败原因 diff --git a/docs/guide/uptime-kuma.md b/docs/guide/uptime-kuma.md new file mode 100644 index 00000000..037414e7 --- /dev/null +++ b/docs/guide/uptime-kuma.md @@ -0,0 +1,49 @@ +# Uptime Kuma 监控同步 + +你会学到：如何启用并配置 Uptime Kuma 自动同步集成，控制监测站点的同步范围与心跳探测参数，以及 OpenFlare 与 Uptime Kuma 差分同步的底层原理。 + +--- + +## 功能概述 + +在边缘多节点运维中，及时了解各个代理站点的可用性至关重要。为了避免手动在监控系统中重复录入站点信息，OpenFlare 提供了与开源监控服务 **Uptime Kuma** 的深度集成。 + +启用集成后，OpenFlare 会启动一个后台同步调度器，自动将管理端配置的代理站点同步为 Uptime Kuma 中的 HTTP 监控任务。支持检测范围过滤、差分属性更新以及对下线站点的自动清理。 + +--- + +## 第一步：在系统设置中配置集成 + +1. 登录管理端控制面板，进入左侧导航 **「系统设置」** -> **「Uptime Kuma 集成」**（或通过控制台中的集成配置入口）。 +2. 配置以下核心连接参数： + * **启用状态 (Enabled)**：开启集成开关。 + * **实例地址 (Instance URL)**：你的 Uptime Kuma 服务地址。例如 `http://192.168.1.100:3001` 或 `https://kuma.example.com`（必须包含协议前缀 `http://` 或 `https://`）。 + * **用户名 (Username)** 与 **密码 (Password)**：具有管理权限的 Uptime Kuma 账户凭证，用于 API 鉴权。 + +--- + +## 第二步：控制监控范围与心跳参数 + +在集成面板中，你可以对监控范围和具体探测行为进行细粒度控制： + +### 1. 监控范围 (Monitor Scope) +* **全部站点 (All)**：默认选项。OpenFlare 将自动同步所有**已启用**的代理路由站点。当新站点被创建且启用，或者旧站点被停用时，监控列表将自动增删。 +* **选择站点 (Selected)**：仅监控指定站点。选择此模式后，可以点击 **「选择监控站点」** 弹出框。在弹出框内可以通过搜索过滤站点并进行勾选。被取消勾选或未勾选的站点将不会被同步（若已存在则会被自动清理）。 + +### 2. 监测频率与心跳设置 +你可以为自动生成的监控项指定统一的探测参数： +* **同步间隔 (Sync Interval)**：自动差分同步的频率（分钟），默认为 `5` 分钟。即控制面每 5 分钟与 Uptime Kuma 进行一次状态比对。 +* **心跳检测频率 (Interval)**：Uptime Kuma 探测站点的频率（秒），默认为 `60` 秒。 +* **最大重试次数 (Retry)**：探测失败后，判定为 Down 之前的最大重试次数，默认为 `0`。 +* **重试间隔时间 (Retry Interval)**：重试之间的等待秒数，默认为 `60` 秒。 +* **请求超时时间 (Timeout)**：探测请求判定为超时的秒数，默认为 `48` 秒。 + +--- + +## 同步与清理机制 + +* **专属标签隔离**：所有自动创建的监控项均会绑定 `OpenFlare` 专属标签（紫蓝色）。同步和清理程序仅操作带有该标签的监控任务，**绝不干扰或破坏你在 Uptime Kuma 中手动创建的其他监控项**。 +* **差分增量同步**：同步程序会周期性对比监控元数据。当检测到域名或心跳配置变更时，仅执行差分更新，避免中断历史统计数据；当站点停用或移出范围时，会自动执行监控下线清理。 + +> [!TIP] +> 关于 Uptime Kuma 监控同步的 Socket.IO 控制流、防污染标签模型及差分比对算法细节，请参阅 [Uptime Kuma 监控同步设计](../design/kuma-design.md)。 diff --git a/docs/guide/usage.md b/docs/guide/usage.md deleted file mode 100644 index 229bb7a0..00000000 --- a/docs/guide/usage.md +++ /dev/null @@ -1,171 +0,0 @@ -# 基础使用 - -你会学到：OpenFlare 中网站配置、源站、证书、版本、节点和观测分别是什么，以及日常使用时应按什么顺序操作。 - -OpenFlare 不直接在线修改节点上的 Nginx/OpenResty 配置。你在管理端修改的是控制面数据；只有发布并激活新版本后，Agent 才会拉取完整配置并应用到节点。 - -## 核心概念 - -| 概念 | 说明 | -| --- | --- | -| 网站配置 | 反向代理配置的聚合对象，一条网站配置可以绑定一个或多个域名 | -| 主域名 | `domains` 列表中的第一个域名，用作该网站的主要展示域名 | -| 源站 | 被反向代理访问的上游地址，例如 `http://10.0.0.10:8080` | -| 配置版本 | 一次发布生成的完整 OpenResty 配置快照，历史版本不可变 | -| 激活版本 | 当前全局生效的配置版本，所有节点默认消费同一份激活版本 | -| Agent | 节点侧进程，负责注册、心跳、同步、校验、reload 和失败回滚 | - -## 推荐操作顺序 - -日常发布一条反向代理配置时，推荐按这个顺序： - -1. 确认至少有一个 Agent 节点在线。 -2. 新增或选择源站地址。 -3. 新增网站配置，填写域名、源站和站点级配置。 -4. 如需 HTTPS，上传或选择证书，并按域名绑定。 -5. 预览配置或查看变更摘要。 -6. 发布并激活新版本。 -7. 在节点详情和应用记录中确认应用结果。 - -## 创建网站配置 - -网站配置至少需要： - -| 字段 | 要求 | -| --- | --- | -| 网站名称 | 业务唯一标识；未显式填写时通常可使用主域名 | -| 域名 | 至少一个域名，第一项为主域名；任一域名全局只能属于一个网站 | -| 源站地址 | 合法的 `http://` 或 `https://` 地址 | -| 启用状态 | 只有启用的网站配置会参与发布渲染 | - -示例： - -| 字段 | 示例 | -| --- | --- | -| 网站名称 | `docs` | -| 域名 | `docs.example.com` | -| 源站地址 | `http://10.0.0.10:8080` | -| 回源 Host | `docs.internal.example.com` | - -上游地址规则： - -* 单上游可以携带 base path 或 query，例如 `https://app.example.com/base?from=openflare`。 -* 多上游用于负载均衡时，每个上游必须是纯 `scheme://host[:port]`。 -* 多上游在同一规则内应使用一致协议。 - -## 管理源站 - -源站是轻量目录，用来复用常见上游地址。网站配置关联源站后，仍会保存可渲染的 `origin_url` 快照，确保历史配置版本可以独立回放。 - -推荐做法： - -* 把经常复用的内部服务地址维护为源站。 -* 修改源站目录后，检查已发布的网站配置是否需要同步更新源站快照。 -* 发布前使用预览或 diff 确认渲染结果。 - -## 托管 Pages 静态站点 - -Pages 用于托管已经构建完成的静态资源包。当前阶段只支持 Direct Upload，不执行 Git 构建、边缘函数或 SSR。 - -操作顺序： - -1. 进入 **Pages** 页面，点击 **新建 Pages 项目**。 -2. 填写项目名称、标识、描述；如为前端 history 路由应用，启用 **SPA fallback** 并填写回退路径，默认是 `/index.html`，也可以设置为 `/app.html` 等站点内绝对路径。 -3. 创建后回到 Pages 项目列表，点击项目进入详情。 -4. 在项目详情中上传 zip 静态资源包，并激活某个部署。 -5. 新建或编辑网站规则，将回源方式切换为 **Pages 静态站点**，选择该 Pages 项目。 -6. 发布并激活配置版本，Agent 会下载部署包、校验 checksum、解压到本地 Pages 目录，再由 OpenResty 本地服务静态文件。 - -Pages 项目只有在启用且存在激活部署后，才会出现在网站规则的 Pages 项目选择列表中。 - -## 启用 HTTPS - -HTTPS 按域名绑定证书，而不是按整个网站统一强制启用。 - -操作顺序： - -1. 在证书管理中上传或托管证书。 -2. 进入网站配置，为需要 HTTPS 的域名选择证书。 -3. 未绑定证书的域名会保留 HTTP，不会被自动放入 `443 ssl` server 块。 -4. 发布并激活新版本。 - -如果一个网站包含多个域名，Server 发布时会按证书分组渲染 HTTPS 配置，同时保持这些域名属于同一份网站快照。 - -## 配置 WAF 与 PoW - -安全防护统一从管理端侧边栏的 **WAF** 入口进入： - -* WAF 页面维护全局规则组和自定义规则组。全局规则组始终应用到全部网站；自定义规则组可以在规则组内一键选择网站，也可以在网站详情的 `WAF` 分区绑定。 -* 点击 WAF 页面中的 **管理 IP 组** 可以进入独立 IP 组页面。手动 IP 组直接维护 IP/IP 段；自动 IP 组使用 Expr 规则按单个 IP 聚合请求日志并定时更新名单；订阅 IP 组可从远程文本或 JSON 源定时同步。 -* 自动 IP 组页面提供两个预设：单个 IP 请求数大于 100 且 404 占比不低于 80%；单个 IP 通过 IP 地址访问次数大于 50 且该访问占比大于 50%。保存前可点击 **测试规则** 查看当前日志窗口命中的 IP，保存后可点击 **立即执行** 更新组内名单，语法见 [WAF 自动 IP 组规则语法](./waf-ip-group-expr.md)。 -* 在 WAF 规则组的黑白名单中，IP 维度既可以直接添加 IP/IP 段，也可以引用已有 IP 组。发布时版本只携带 IP 组引用 ID；Agent 会按 checksum 差异同步 IP 组成员，并在 Server 通过 WebSocket 广播 IP 组更新时实时落地到节点。 -* `PoW` 是规则组内的一个配置 Tab，位于 `黑白名单` 与 `拦截返回` 之间，复用站点已有 PoW 执行逻辑，可将当前 PoW 配置应用到全部网站或当前规则组绑定的网站。 -* 网站详情页不再单独编辑 PoW 规则，只展示全局 WAF 规则组并绑定自定义 WAF 规则组。PoW 的启用范围和规则内容应回到 WAF 页面统一维护。 - -WAF 规则组、网站绑定或 PoW 配置修改后，需要重新发布并激活配置版本，Agent 才会拉取并应用到 OpenResty。IP 组成员变化不需要重新发布版本；在线 Agent 会通过 WebSocket 增量更新，离线或未升级 WS 的 Agent 会在下一次心跳中按 checksum 差异补齐。 - -详细的 WAF 安全配置与拦截判决原理请查阅 [WAF 安全防护使用](./waf-usage.md)。 - -## 发布、激活与回滚 - -标准链路： - -```text -修改配置 -> 预览 / diff -> 发布 -> 生成完整版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果 -``` - -发布时 Server 会读取全部启用的网站配置、OpenResty 主配置模板、性能参数、缓存参数和证书资源，生成完整配置并计算 `checksum`。 - -回滚不是修改历史版本，而是重新激活旧版本。Agent 发现激活版本变化后，会按普通同步流程拉取并应用。 - -## 查看节点与观测 - -节点页面适合回答三个问题： - -| 问题 | 查看位置 | -| --- | --- | -| 节点是否在线 | 节点列表或节点详情 | -| 当前运行哪个版本 | 节点详情中的当前版本 | -| 最近一次应用是否成功 | 应用记录 | - -节点 IP 默认由 Agent 注册和后续心跳自动回填。若在管理端填写或修改 IP，节点编辑会默认开启“锁定节点 IP”；开启后 Agent 上报不会覆盖该 IP。关闭锁定后，下一次 Agent 心跳或 WebSocket 状态上报会重新按自动逻辑更新。 - -访问分析和资源快照用于基础观测。OpenFlare 只保留受控时间窗口内的访问明细，不定位为通用日志平台。如果需要长期日志检索，应接入独立日志系统。 - -## 常见场景 - -### 新增一个内部服务反代 - -1. 确认源站服务可从 Agent 节点访问。 -2. 在管理端新增网站配置。 -3. 填写域名，例如 `app.example.com`。 -4. 填写源站，例如 `http://10.0.0.20:8080`。 -5. 发布并激活版本。 -6. 在 Agent 节点或浏览器访问域名验证。 - -> [!TIP] -> 如果你的源站部署在内网、没有公网 IP 且 Agent 无法直接访问，请使用内网穿透隧道功能将服务映射至公网。详细操作步骤请查阅 [内网穿透与隧道使用](./tunnel-usage.md)。 - -### 给已有域名启用 HTTPS - -1. 准备覆盖该域名的证书。 -2. 在证书管理中上传或创建证书记录。 -3. 回到网站配置，为对应域名选择证书。 -4. 发布并激活版本。 -5. 用浏览器或 `curl -I https://your-domain` 验证证书链和状态码。 - -### 回滚一次失败发布 - -1. 打开配置版本页面。 -2. 找到上一个已知可用版本。 -3. 重新激活该版本。 -4. 查看节点应用记录，确认 Agent 已应用旧版本。 -5. 修正配置后再发布新版本。 - -## 推荐实践 - -* 生产环境必须显式配置 `JWT_SECRET`，并优先使用 PostgreSQL。 -* 修改网站配置后先看预览或 diff，再发布。 -* 每次发布后检查节点详情与应用记录。 -* 多节点部署时保持 Agent 到 Server 的网络路径稳定。 -* 不在节点上手动修改 OpenFlare 托管的 OpenResty 配置文件；下次发布会覆盖这些文件。 diff --git a/docs/guide/waf-usage.md b/docs/guide/waf-usage.md index 85badba2..c7dc6e81 100644 --- a/docs/guide/waf-usage.md +++ b/docs/guide/waf-usage.md @@ -42,8 +42,22 @@ IP 组是进行大批量 IP 过滤的基石。OpenFlare 提供了极富弹性的 * **配置**：点击「创建 IP 组」-> 类型选择「手动」-> 按行直接填入 IP 或 CIDR 格式（例如 `192.168.1.100` 或 `10.0.0.0/24`）。 #### 2. 订阅 IP 组 (Subscription) -* **用途**：接入第三方威胁情报库或云厂商公布的 IP 范围。 -* **配置**：类型选择「订阅」-> 输入抓取 URL（支持按行分隔的文本文件或标准的 JSON 格式）。控制面板的定时任务会周期性拉取订阅源并自动同步至该组名单中。 +* **用途**：接入第三方开源威胁情报库、云厂商公布的官方网段（如 Cloudflare, GitHub Action IP 列表），或团队内部统一维护的动态 IP 源。 +* **配置参数**： + * **订阅 URL**：必须是合法的 `http` 或 `https` 链接。 + * **订阅格式**：支持 `Text` 与 `JSON` 两种数据格式： + * **Text 格式**：纯文本格式。按行分隔读取 IP/CIDR，会自动过滤掉以 `#` 开头的注释行和空白行。 + * **JSON 格式**：当订阅源是一个结构化的 JSON 响应时，需要编写 **映射规则 (Mapping Rule)** 从 JSON 数据中提取 IP 列表。 + * **映射规则**：使用类似 JSONPath 的轻量点语法定位 IP 数组，支持以 `[]` 展开数组。例如： + * 若 JSON 结构为 `{"data": {"ips": ["1.1.1.1", "2.2.2.2"]}}`，则映射规则填写 `$.data.ips[]`（或 `data.ips[]`）。 + * 若 JSON 根节点本身即为字符串数组（如 `["1.1.1.1", "2.2.2.2"]`），映射规则留空或填写 `$` 即可。 + * **同步间隔 (分钟)**：该订阅组自动同步的周期，默认为 `1440` 分钟（24小时），允许范围为 `5` 至 `43200` 分钟。 +* **安全限额与同步频率**： + * 为防止恶意或超大订阅源造成系统负担，单次抓取上限限制为 **2 MiB**，网络拉取超时为 15 秒。 + * Server 默认每 5 分钟在后台扫描一次到期的订阅 IP 组并拉取同步。 + +> [!TIP] +> 关于 WAF 的动态 IP 组异步差分同步模型（WebSocket 实时热同步、不触发 Nginx Reload 机制）以及高性能 Lua 缓存方案等底层设计细节，请参阅 [WAF 设计](../design/waf-design.md)。 #### 3. 自动 IP 组 (Automatic) * **用途**：**最具杀伤力的防扫描、防爆破自动通道**。 diff --git a/docs/guildline/Role.md b/docs/guideline/Role.md similarity index 100% rename from docs/guildline/Role.md rename to docs/guideline/Role.md diff --git a/docs/guildline/development-constraints.md b/docs/guideline/development-constraints.md similarity index 98% rename from docs/guildline/development-constraints.md rename to docs/guideline/development-constraints.md index ec901ea4..8c00912c 100644 --- a/docs/guildline/development-constraints.md +++ b/docs/guideline/development-constraints.md @@ -45,7 +45,7 @@ Frontend： ## 工程分层约束 -各组件和模块（Server、Agent、Frontend）的物理目录分层职责详见 [仓库结构](../design/repository.md)。在此结构下，开发必须遵守以下核心分层规则： +各组件和模块（Server、Agent、Frontend）的物理目录分层职责详见 [仓库结构](../design/index.md#仓库结构)。在此结构下，开发必须遵守以下核心分层规则： * **Server 开发规则**： * 禁止在 `controller/` 堆积业务逻辑，禁止在 `middleware/` 实现业务流程，禁止为简单需求新增平台层抽象。 diff --git a/docs/index.md b/docs/index.md index 9b1a925f..74ac3e2e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ layout: home hero: name: OpenFlare text: 开源 CDN 编排与边缘安全平台 - tagline: 支持反向代理、集中式配置同步、内网穿透（Tunnels）、动态 WAF 防护与人机防 CC 挑战。 + tagline: 支持反向代理、集中式配置同步、Pages 静态托管、内网穿透（Tunnels）、动态 WAF 防护与人机防 CC 挑战。 actions: - theme: brand text: 快速开始 @@ -23,6 +23,9 @@ features: - icon: 🌐 title: 分布式 CDN 编排 details: 将独立的 OpenResty 编排为高度协同的分布式 CDN 舰队，支持源站多负载均衡。 + - icon: 📄 + title: Pages 静态托管 + details: 直接上传前端打包 zip 资产，由边缘节点拉取解压并提供高性能本地服务与 API 代理。 - icon: 🚇 title: 安全内网穿透 (Tunnels) details: 对标 Cloudflare Tunnels，无须公网 IP 或暴露入向端口，安全穿透本地服务至公网。 diff --git a/docs/plan/handover-plan-template.md b/docs/plan/handover-plan-template.md new file mode 100644 index 00000000..06f6b22d --- /dev/null +++ b/docs/plan/handover-plan-template.md @@ -0,0 +1,32 @@ +# AI 接手计划模板 + +说明：本模板用于在 AI 代理上下文发生截断、压缩（Compaction）或将任务转移给另一个 AI 代理时使用，帮助新接手的 AI 快速恢复 100% 的工作状态。 + +--- + +## 1. 当前任务状态 (Current Status) +* **主线任务描述**：用一句话说清楚当前正在解决的核心问题。 +* **开发分支/提交**：记录当前的工作目录、修改的未暂存文件、或 Git 临时分支名。 +* **已完成内容 (Completed)**： + - [x] 功能 A 后端接口及单测 + - [x] 前端面板表单组件 +- **进行中内容 (In Progress)**： + - [/] 配置文件渲染与重写模块 +- **待处理内容 (To Do)**： + - [ ] 边缘节点同步下载与校验落地 + - [ ] 发布功能整体连通性验证 + +## 2. 核心文件与上下文 (Key Files & Context) +列出与当前开发高度相关的核心文件以及需要注意的特殊背景： +* `file:///path/to/core_file.go#L100-L150`：此处负责...，修改时需要注意... +* `file:///path/to/frontend_component.tsx`：用于展现... + +## 3. 待决策与遗留问题 (Outstanding Decisions & Issues) +* [ ] **疑问/阻塞点**：是否需要支持某某场景？目前是如何兜底处理的？ +* [ ] **异常与缺陷**：单测 `./controller/...` 运行时目前有 1 个 Fail，失败原因为... + +## 4. 下一步行动指南 (Next Steps) +新接手 AI 进来后应当立即执行的前 3 步命令或编辑操作： +1. **第一步**：执行 `go test ./controller/...` 确认环境并复现 Fail 异常。 +2. **第二步**：修改 `openflare_server/controller/xxx.go` 中的逻辑以修复该 Fail。 +3. **第三步**：在管理端前端页面调试 xxx 表单的提交是否正常。 diff --git a/docs/plan/implementation-plan-template.md b/docs/plan/implementation-plan-template.md new file mode 100644 index 00000000..68670637 --- /dev/null +++ b/docs/plan/implementation-plan-template.md @@ -0,0 +1,47 @@ +# 功能开发实现计划模板 + +说明：本模板用于指导新特性或重大模块开发前的技术规划，明确需求、范围与设计决策。 + +--- + +## 1. 目标与背景 (Goal & Context) +* **需求背景**：说明为什么要开发这个特性，解决什么业务痛点或安全隐患。 +* **开发范围 (Scope)**：明确 V1 阶段的核心交付指标。哪些是本次必做的，哪些是留到后续迭代的（Out of Scope）。 + +## 2. 设计与决策决策 (Design & Decisions) +* **核心对象/数据模型**： + * 说明是否需要修改或新增数据库表（Gorm 结构体、Migration SQL，包括新增字段与关联）。 +* **API 与鉴权设计**： + * 详细定义新增的 REST API 路由、请求载荷（Payload JSON）与响应格式。 +* **数据流与架构图**： + * 使用 Mermaid 绘制数据或控制流的流向。 +* **设计决策权衡**： + * 记录为何选用方案 A 而非方案 B。 + +## 3. 具体修改文件清单 (Proposed Changes) +按模块或组件列出需要修改的物理文件路径及修改点： + +### 后端 Server +* #### [NEW] `openflare_server/model/entity.go` + * 职责：... +* #### [MODIFY] `openflare_server/service/feature.go` + * 职责：... + +### 边缘 Agent 与 OpenResty +* #### [MODIFY] `openflare_agent/sync/sync.go` + * 职责：... + +### 前端 Web +* #### [NEW] `openflare_server/web/features/feature-view.tsx` + * 职责：... + +--- + +## 4. 验证计划 (Verification Plan) + +### 自动化单元测试 +* 运行的单测命令，如：`go test -v ./service/...` + +### 数据面重载与生效验证 +* 说明如何验证新配置在数据面落地。 +* 提供验证测试的 `curl` 指令或手动操作路径。 diff --git a/docs/plan/index.md b/docs/plan/index.md new file mode 100644 index 00000000..0da35a68 --- /dev/null +++ b/docs/plan/index.md @@ -0,0 +1,16 @@ +# 开发计划与 AI 接手 + +本分区用于存放正在进行的开发计划（Plan）以及 AI 代理之间的工作接手计划（Handover）。这能帮助不同的 AI 代理快速掌握当前项目状态、历史上下文与后续开发步骤。 + +## 计划模板 + +在创建具体的开发计划或接手文档时，请使用以下标准模板进行初始化： + +1. **[实现计划模板](./implementation-plan-template.md)**：用于新功能开发或重大重构前的技术方案规划。 +2. **[AI 接手计划模板](./handover-plan-template.md)**：用于在上下文截断、压缩或更换 AI 代理时，记录当前任务状态、已完成内容与下一步执行计划。 + +## 使用建议 + +* **命名规范**：正在进行的开发计划建议命名为 `docs/plan/YYYYMMDD-[feature-name].md`，接手计划建议命名为 `docs/plan/handover-[task-name].md`。 +* **物理隔离**：本目录下的计划文件只在开发周期内进行更新。当对应功能开发完毕并上线后，相应的计划文档应予以保留或归档，以供日后维护与新 AI 追溯历史决策。 +* **禁止空文件**：请确保新创建的计划文档均基于对应的模板进行初始化填充。 diff --git a/docs/reference/index.md b/docs/reference/index.md index 98c3c4ca..2cc02a6e 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -8,5 +8,5 @@ | --- | --- | | [配置项](./configuration.md) | Server 环境变量、命令行参数、运行时 Option 与 Agent 配置字段 | | [命令与脚本](./cli.md) | 常用启动、构建、测试、安装和卸载命令 | -| [仓库结构](../design/repository.md) | `openflare_server`、`openflare_agent`、`openflare_relay`、`openflared` 模块的职责与分层目录说明 | +| [仓库结构](../design/index.md#仓库结构) | `openflare_server`、`openflare_agent`、`openflare_relay`、`openflared` 模块的职责与分层目录说明 | | [部署与升级](../deployment/) | Server 与 Agent 的部署、配置与升级指南（见专属分区） |