[优化] 文档更新

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#仓库结构)**：明确各个物理目录分层职责，避免堆砌和重复开发。

docs/design/development.md

@@ -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_<timestamp>_<description>.go` 文件，不得把具体迁移逻辑集中堆在 goose 注册入口中，也不得把新 goose 框架代码放回 `openflare_server/model` 根包。

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)。

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` 事件的完整列表推送后，才允许向下执行差分算法，以规避因为数据加载不完整导致误删监控项的边界情况。

docs/design/repository.md

@@ -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 信道  |
-