tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-29 05:56:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(design): update product boundaries and configuration references

Browse Source 
- Update docs/design/index.md to document system constraints, including mandatory Redis/ClickHouse dependencies and dynamic Relay Web UI settings.
- Update docs/reference/configuration.md to reflect w_system_configs table keys, option groups, and new environment variable mappings.
- Clean up old plan files.
This commit is contained in:
ryan
2026-06-27 16:03:16 +08:00
parent 196bdabc80
commit 3038304382
16 changed files with 250 additions and 3041 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/index.md
+3 -2
View File
@@ -43,11 +43,11 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具
### 2. WAF 安全边界
* **白名单优先原则**：白名单拥有绝对匹配权。若未命中白名单规则，才依次触发全局和自定义黑名单过滤。
* **GeoIP 弱依赖性**：地域准入解析完全依赖节点本地 MaxMind 库。当 GeoIP 异常或解析失败时，系统必须自动忽略地域规则，**绝对不能**破坏 IP 组过滤和反代主链路的可用性。
* **运行时数据解耦**：OpenResty 拦截时仅读取 Agent 同步至本地的 JSON，不与 Server 数据库通信。IP 组成员同步与版本发布解耦，通过 Chestsum 差分拉取以实现零重载平滑生效。
* **运行时数据解耦**：OpenResty 拦截时仅读取 Agent 同步至本地的 JSON，不与 Server 数据库通信。IP 组成员同步与版本发布解耦，通过 Checksum 差分拉取以实现零重载平滑生效。
### 3. 内网穿透边界
* **仅限 HTTP 流量**：穿透组件仅支持 HTTP/HTTPS 协议（底层依靠 frp 虚拟主机 Vhost 机制实现单端口域名路由复用），暂不支持单独的 TCP/UDP 端口分配。
* **中继配置静态化**：中继节点（Relay）配置相对静态，通过心跳被动获取，不纳入控制面的配置版本化管理体系。
* **中继配置动态化控制**：中继节点（Relay）在连接至 Server 后，可通过心跳周期性动态拉取并同步全局系统配置（例如是否开启内嵌 FRPS Web UI 及其监听端口），但不直接纳入控制面的不可变配置版本发布体系。
* **Tunnel 与 Node 体系隔离**：Tunnel 客户端在内网发起出向建连，与控制面托管的边缘 Node（公网节点）是独立的实体，使用专属的 `tunnel_token` 进行鉴权。
### 4. Pages 静态托管边界
@@ -57,6 +57,7 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具
### 5. 系统与版本边界
* **全局单一激活版本**：所有节点拉取并消费同一份全局激活配置。不进行按节点分组的差异化配置发布。
* **单租户架构**：OpenFlare 仅供单团队在受信任的内部网络部署使用。采用单租户设计，不支持细粒度的多用户角色或多租户资源隔离。
* **外部基础设施依赖性**：Server 虽支持 SQLite 作为本地轻量关系数据库，但**系统必须强制依赖外部 Redis（或 Valkey）及 ClickHouse 实例**。Redis 用于处理分布式协调、后台异步队列（Asynq 框架）及系统级全局缓存；ClickHouse 用于接收海量节点访问日志与基础观测的异步 Flush。系统不支持完全脱离这两个组件运行。
---
docs/plan/20260606-interactive-installer.md
-85
View File
@@ -1,85 +0,0 @@
# 交互式智能安装脚本实现计划
本计划旨在拓展 OpenFlare Agent 安装脚本的功能，支持交互式选择本地安装或 Docker 容器安装，并提供智能检测/在线安装 Docker 环境的机制，同时保留通过命令行传参进行自动化安装的既有能力。
---
## 1. 目标与背景 (Goal & Context)
* **需求背景**：当前安装脚本 `install-agent.sh` 仅支持在宿主机直接下载二进制并配置为本地 systemd 服务运行。随着 Docker 部署方式的普及，需要让用户在一键安装时能根据需要交互式选择 Docker 或本地部署，从而提升部署体验。
* **开发范围 (Scope)**：
* 支持交互式运行（未传参时）：提示用户选择 Local 方式或 Docker 方式。
* 当选择 Docker 方式时，检测本地是否存在 `docker` 命令。若不存在，提示并在线安装 Docker（支持国内镜像源及自动测速选择最低延迟源）。
* 交互引导用户配置 `server_url` 和 `agent-token` 或 `discovery-token`。
* 如果选择 Docker，则最终拉取 Agent 镜像并运行容器；如果选择 Local，则继续原有的本地二进制下载及配置发布逻辑。
* 兼容非交互式模式：如果执行脚本时传递了任意参数，则跳过任何交互式提示，直接进行自动化安装（支持新参数 `--docker` / `--method docker` 来自动选用 Docker 部署）。
---
## 2. 设计与决策 (Design & Decisions)
### 交互工作流
1. 检查 `$#`（参数数量）。若 `$# -eq 0`，激活 `INTERACTIVE=true`。
2. 在交互模式下：
* 引导用户选择安装方法（1: Local, 2: Docker）。
* 若选择 Docker，调用 `Install_Docker` 检测并安装环境。
* 引导用户输入 `SERVER_URL` 并进行非空校验。
* 引导用户选择 Token 类型（1: Discovery Token, 2: Agent Token），并输入对应的 Token 值。
* 若选择 Local 且未传 `--openresty-path`，如果 `openresty` 二进制未能在 $PATH 中找到，交互提示用户手动输入 OpenResty 路径。
3. 非交互模式下：
* 解析命令行参数。
* 支持通过 `--docker` 或 `--method docker` 指定 Docker 容器安装。
* 依然根据传入的 `--server-url` 和 Token 自动执行安装，绝不进行任何交互。
### 数据流与架构图
```mermaid
graph TD
Start[执行 install-agent.sh] --> CheckArgs{是否有命令行参数?}
CheckArgs -- 是 (非交互模式) --> ParseArgs[解析参数]
ParseArgs --> IsDockerParam{是否指定 Docker?}
IsDockerParam -- 是 --> RunDocker[Docker 容器拉取与启动]
IsDockerParam -- 否 --> RunLocal[本地二进制下载与 systemd 服务创建]
CheckArgs -- 否 (交互模式) --> PromptMethod[提示选择 Local 或 Docker]
PromptMethod --> MethodChosen{选择结果}
MethodChosen -- Docker --> CheckDocker{本地有 Docker 吗?}
CheckDocker -- 否 --> PromptDockerInstall[询问是否安装 Docker?]
PromptDockerInstall -- 是 --> InstallDocker[在线安装 Docker + 配置国内镜像加速]
PromptDockerInstall -- 否 --> ExitScript[取消安装并退出]
CheckDocker -- 是 --> PromptServerUrl[提示输入 Server URL & Token]
InstallDocker --> PromptServerUrl
MethodChosen -- Local --> PromptLocalConfig[检测 OpenResty 并提示输入 Server URL & Token]
PromptServerUrl --> RunDocker
PromptLocalConfig --> RunLocal
```
---
## 3. 具体修改文件清单 (Proposed Changes)
### 边缘 Agent 与部署脚本
* #### [MODIFY] [install-agent.sh](file:///Users/ryan/DEV/Go/OpenFlare/scripts/install-agent.sh)
* 职责：
1. 引入交互式选择逻辑和 `Install_Docker` / `configure_accelerator` 函数。
2. 新增 `--docker` 和 `--method` 命令行参数支持。
3. 支持用户交互输入配置项。
4. 增加 Docker 镜像拉取、停止旧容器并启动新容器的安装路径。
* #### [MODIFY] [agent.md](file:///Users/ryan/DEV/Go/OpenFlare/docs/deployment/agent.md)
* 职责：更新一键安装说明文档，增加交互式模式的说明以及 `--docker` 参数的自动化 Docker 安装说明。
---
## 4. 验证计划 (Verification Plan)
### 自动化与脚本测试
* 在干净的测试环境运行脚本：
* `bash scripts/install-agent.sh` （测试交互模式 -> 选用 Local）
* `bash scripts/install-agent.sh` （测试交互模式 -> 选用 Docker）
* `bash scripts/install-agent.sh --server-url http://127.0.0.1:3000 --discovery-token mytoken` （测试自动 Local 安装）
* `bash scripts/install-agent.sh --server-url http://127.0.0.1:3000 --discovery-token mytoken --docker` （测试自动 Docker 安装）
### 数据面生效验证
* 通过 `docker ps` 和 `docker logs openflare-agent` 确认容器成功拉取并启动，环境参数注入正确。
docs/plan/20260606-login-cap-integration.md
-92
View File
@@ -1,92 +0,0 @@
# 登录集成 Cap 验证码实现计划
本计划规定了在 OpenFlare 系统的登录流程中集成 Cap（基于 Proof-of-Work 和无感浏览器检测的验证码）的具体开发步骤。
---
## 1. 目标与背景 (Goal & Context)
### 需求背景
为解决安全分析中识别到的“登录接口缺少防暴力破解/撞库逻辑”这一安全风险，我们需要在登录接口中集成 Cap 验证码服务。通过让客户端（爬虫/浏览器）在登录前必须求解一个 PoW 工作量难题并核销，显著提高恶意爬虫爆破的计算成本，从根本上防止针对登录接口的恶意爆破。
### 开发范围
1. **后端验证服务**：在 Server 端移植 `capjs-core` 的 PoW 校验算法（包括 FNV-1a、自定义 PRNG、SHA-256 检验、JWT 难题派发与核销缓存组件）。
2. **公开路由映射**：
* `POST /api/cap/challenge` (分发难题)
* `POST /api/cap/redeem` (核销难题并核发 `cap-token`)
3. **控制开关**：增加全局选项 `CapLoginEnabled`，管理员可动态启停。
4. **前端交互接入**：在登录页面引入 `cap-widget` 自定义组件，并在提交登录请求时附带 `cap_token`。
---
## 2. 设计与决策 (Design & Decisions)
### 核心对象与数据模型
本方案不涉及复杂数据库结构重构，但需要：
1. 在 `options` 表中保存 `CapLoginEnabled` (true/false) 选项, 默认为 True, 设置路径在 设置->系统设置->登录与注册开关。
2. 建立一个全局的、线程安全的内存验证码核销存储/核销缓存，具备过期清理功能，用于存放核销的 `cap-token` 以及消费过的 JWT 难题 Nonce（Signature），支持 Redis 与本地内存模式。
### API 与鉴权设计
1. **`POST /api/cap/challenge`**：公开接口。
2. **`POST /api/cap/redeem`**：公开接口。
3. **`POST /api/user/login`**：接受可选/必选的 `cap_token` 参数。
### 算法移植 (Proof-of-Work Go 实现)
* FNV-1a 状态机复现。
* 伪随机数生成器 (PRNG) 与 `strings.HasPrefix(sha256Hex, target)` 校验。
---
## 3. 具体修改文件清单 (Proposed Changes)
### 后端 Server
* #### [MODIFY] [constants.go](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/common/constants.go)
* 增加 `CapLoginEnabled` 全局常量/变量，默认 `true`。
* #### [MODIFY] [option.go](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/model/option.go)
* 在 `InitOptionMap` 和 `updateOptionMap` 中添加 `CapLoginEnabled` 的支持。
* #### [NEW] [prng.go (utils/cap)](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/utils/cap/prng.go)
* 职责：实现 FNV-1a、FNV-1a resume 及 XORShift-based 自定义 PRNG 伪随机数算法。
* #### [NEW] [cap.go (utils/cap)](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/utils/cap/cap.go)
* 职责：实现无状态 PoW 难题生成、验证及 JWT 校验。
* #### [NEW] [store.go (utils/cap)](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/utils/cap/store.go)
* 职责：定义 `Store` 接口并提供默认的高性能、线程安全的内存 TTL 缓存核销存储实现。
* #### [NEW] [manager.go (utils/cap)](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/utils/cap/manager.go)
* 职责：封装验证码的核心逻辑，暴露出 `Generate`、`Redeem` 与 `VerifyToken` 高阶 API。
* #### [NEW] [middleware.go (utils/cap)](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/utils/cap/middleware.go)
* 职责：实现通用的 Gin 中间件 `VerifyMiddleware`。其不依赖任何 OpenFlare 业务代码，完全通过构造注入。
* #### [NEW] [cap.go (service)](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/service/cap.go)
* 职责：适配器服务，将 OpenFlare 的全局参数（如 `JWTSecret`、`CapLoginEnabled`、`RDB`）注入并实例化全局的 `CapManager` 实例。
* #### [NEW] [cap.go (middleware)](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/middleware/cap.go)
* 职责：极简的适配器中间件，直接调用并返回 `service.CapManager.VerifyMiddleware(scope)`。
* #### [NEW] [cap.go (controller)](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/controller/cap.go)
* 职责：实现 `GetCapChallenge` 和 `RedeemCapChallenge` 控制器。
* #### [MODIFY] [api-router.go](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/router/api-router.go)
* 职责：挂载 `/api/cap/challenge` 和 `/api/cap/redeem` 路由，并在 `/api/user/login` 上应用 `middleware.CapAuth("login")`。
* #### [MODIFY] [user.go (controller)](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/controller/user.go)
* 无需修改：登录控制器和入参结构体保持完全无侵入。
* #### [MODIFY] [misc.go](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/controller/misc.go)
* 职责：在 `GetStatus` 中返回 `cap_login_enabled` 开关状态。
### 前端 Web
* #### [MODIFY] [public-status.ts](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/web/types/public-status.ts)
* 添加 `cap_login_enabled: boolean` 字段。
* #### [MODIFY] [auth.ts](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/web/types/auth.ts)
* 在 `LoginPayload` 中添加可选的 `cap_token?: string` 属性。
* #### [MODIFY] [login-form.tsx](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/web/features/auth/components/login-form.tsx)
* 动态载入 `cap-widget`（脚本 CDN：`https://cdn.jsdelivr.net/npm/cap-widget`）。
* 若后台返回 `cap_login_enabled === true`，则渲染 `<cap-widget data-cap-api-endpoint="/api/cap/" />` 组件。
* 在表单提交时，将 `cap-token` 塞入 `loginMutation` 的 Payload 中提交。
---
## 4. 验证计划 (Verification Plan)
### 自动化单元测试
* 针对 Go 中的 PoW 核心算法，编写单测 `openflare-server/service/cap_test.go`。
* 运行单测命令：`go test -v ./openflare-server/service/...`
### 手动功能与防暴力破解验证
1. 打开控制台选项开启 `CapLoginEnabled`。
2. 访问登录页面，观察人机验证组件静默加载并完成 PoW 计算，输入正确账户成功登录。
3. 使用 `curl` 模拟恶意爬虫不携带或携带错误的 `cap_token` 对登录 API 发起 POST 请求，预期被拦截并返回“验证码错误”。
4. 使用已被核销的同一 `cap_token` 二次请求登录，验证防重放失效机制。
docs/plan/20260606-replace-import-paths-evaluation.md
-147
View File
@@ -1,147 +0,0 @@
# OpenFlare 引用替换为 GitHub 路径方案评估计划
## 1. 目标与背景 (Goal & Context)
* **需求背景**：当前 OpenFlare 内部组件（Server、Agent、Relay、Flared）之间采用本地包名引用（例如 `openflare`、`openflare-agent`），并使用 Go `replace` 相对路径指向本地目录。这导致代码无法直接以标准的 GitHub 路径（如 `github.com/rain-kl/openflare`）进行分发、远程安装或被外部引用（例如 `go install` 远程二进制会因为 replace 指令失效而报错）。
* **评估目标**：评估将本地引用替换为 `github.com/rain-kl/openflare` 格式的两种可行方案（单模块 Monorepo 方案 vs 多模块 Multi-Module 方案），分析各自的优缺点、工作量及对现有 CI/CD、Docker 镜像构建的影响，给出推荐方案。
## 2. 设计与决策 (Design & Decisions)
### 方案 A：标准 Go 多模块方案 (Multi-Module with Sub-paths)
保留当前 4 个独立的 Go 模块结构，在各自的 `go.mod` 中将模块名改写为符合 GitHub 结构的子路径：
- `openflare-server/go.mod` -> `module github.com/rain-kl/openflare/openflare-server`
- `openflare-relay/go.mod` -> `module github.com/rain-kl/openflare/openflare-relay`
- `openflare-agent/go.mod` -> `module github.com/rain-kl/openflare/openflare-agent`
- `openflared/go.mod` -> `module github.com/rain-kl/openflare/openflared`
同时，其他模块（Relay, Agent, Flared）的 `go.mod` 中的 `replace` 修改为：
`replace github.com/rain-kl/openflare/openflare-server => ../openflare-server`
#### 优缺点分析：
* **优点**：
- **模块边界清晰**：各二进制模块依赖独立。例如 `openflare-agent` 不会引入 Server 依赖的 GORM、Gin、Swagger 等库，保持各自模块的 `go.sum` 纯净。
- **改动小**：对 Dockerfile 和 GitHub Workflows 影响极小，构建上下文仍可保持原样。
* **缺点**：
- **远程安装不可用**：仍然需要在 `go.mod` 中保留 `replace` 指令。由于 Go 不允许在远程 `go install` 或 `go get` 时解析本地相对路径的 `replace` 指令，用户依然无法直接通过 `go install github.com/rain-kl/openflare/openflared/cmd/flared@latest` 安装，必须先克隆整个仓库到本地再构建。
---
### 方案 B：统一单模块方案 (Unified Single Module Monorepo - 推荐)
将整个仓库合并为一个 Go 模块。在仓库根目录下创建 `go.mod`，模块名为 `github.com/rain-kl/openflare`，并删除子目录中的所有 `go.mod` 和 `go.sum`。
所有内部包导入路径统一改写为：
- `"github.com/rain-kl/openflare/openflare-server/..."`
- `"github.com/rain-kl/openflare/openflare-relay/..."`
- `"github.com/rain-kl/openflare/openflare-agent/..."`
- `"github.com/rain-kl/openflare/openflared/..."`
#### 优缺点分析：
* **优点**：
- **彻底摆脱 replace**：完全不需要在 `go.mod` 中写 `replace` 指令，代码清爽、易于维持。
- **支持远程 Go 工具链**：用户和开发者可以直接使用 `go install github.com/rain-kl/openflare/openflared/cmd/flared@latest` 或 `go install github.com/rain-kl/openflare/openflare-agent/cmd/agent@latest` 远程下载并安装最新二进制。
- **版本依赖统一**：所有组件共享相同的依赖版本，避免了组件间因第三方库版本不一致导致潜在的运行时兼容问题。
* **缺点**：
- **依赖库大一统**：根目录的 `go.mod` 会包含 Server、Agent、Relay 等所有组件的依赖，但这只影响开发时的依赖下载，对最终编译出的二进制大小和运行效率**没有任何影响**（Go 编译器会自动进行死代码消除/树摇）。
- **构建配置变动**：Dockerfile 以及 GitHub Actions 需要修改构建上下文，从原本 COPY 子目录改为从根目录统一进行 COPY 和 `go build`。
---
## 3. 具体修改文件清单 (Proposed Changes)
如果采用**方案 B（推荐）**，需要修改的文件清单和逻辑如下：
### 根目录与配置文件
* #### [NEW] [go.mod](file:///Users/ryan/DEV/Go/OpenFlare/go.mod)
- 职责：全局单一 Go 模块定义，模块名：`github.com/rain-kl/openflare`。
* #### [DELETE] `openflare-server/go.mod` / `go.sum`
* #### [DELETE] `openflare-relay/go.mod` / `go.sum`
* #### [DELETE] `openflare-agent/go.mod` / `go.sum`
* #### [DELETE] `openflared/go.mod` / `go.sum`
### 源代码文件 (约 252 个 Go 文件)
* #### [MODIFY] `openflare-server/**/*.go`
- 职责：将 `import "openflare/..."` 替换为 `import "github.com/rain-kl/openflare/openflare-server/..."`。
* #### [MODIFY] `openflare-relay/**/*.go`
- 职责：将 `import "openflare-relay/..."` 替换为 `import "github.com/rain-kl/openflare/openflare-relay/..."`，将 `import "openflare/..."` 替换为 `import "github.com/rain-kl/openflare/openflare-server/..."`。
* #### [MODIFY] `openflare-agent/**/*.go`
- 职责：将 `import "openflare-agent/..."` 替换为 `import "github.com/rain-kl/openflare/openflare-agent/..."`，将 `import "openflare/..."` 替换为 `import "github.com/rain-kl/openflare/openflare-server/..."`。
* #### [MODIFY] `openflared/**/*.go`
- 职责：将 `import "openflare-flared/..."` 替换为 `import "github.com/rain-kl/openflare/openflared/..."`，将 `import "openflare/..."` 替换为 `import "github.com/rain-kl/openflare/openflare-server/..."`。
### Dockerfile & Workflows
如果采用**方案 B（推荐）**，我们将继续保持每个组件（Server、Agent、Relay、Flared）编译并产生自己独立的 Docker 镜像（共 4 个镜像），但其 Dockerfile 的构建上下文（Build Context）统一提升至仓库根目录。具体调整细节如下：
* #### [MODIFY] [openflare-server/Dockerfile](file:///Users/ryan/DEV/Go/OpenFlare/openflare-server/Dockerfile)
- 职责：由于 `openflare-server` 中没有独立的 `go.mod`，构建上下文必须在**仓库根目录**执行。
- 修改内容：
```dockerfile
# 更改 go-builder 阶段的 COPY 方式：
COPY go.mod go.sum ./
RUN go mod download
COPY openflare-server/ ./openflare-server/
# go build 指定编译子包：
RUN go build -trimpath -ldflags "-s -w -X 'github.com/rain-kl/openflare/openflare-server/common.Version=$VERSION'" -o openflare ./openflare-server
```
* #### [MODIFY] [openflare-relay/Dockerfile](file:///Users/ryan/DEV/Go/OpenFlare/openflare-relay/Dockerfile)
- 职责：适配单 go.mod 构建上下文。
- 修改内容：
```dockerfile
# 更改 builder 阶段的 COPY 方式：
COPY go.mod go.sum ./
RUN go mod download
COPY openflare-server/ ./openflare-server/
COPY openflare-relay/ ./openflare-relay/
# go build 指定编译子包：
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "-s -w -X 'github.com/rain-kl/openflare/openflare-relay/internal/config.Version=$VERSION'" -o openflare-relay ./openflare-relay/cmd/relay
```
* #### [MODIFY] [openflare-agent/Dockerfile](file:///Users/ryan/DEV/Go/OpenFlare/openflare-agent/Dockerfile)
- 职责：适配单 go.mod 构建上下文。
- 修改内容：
```dockerfile
# 更改 builder 阶段的 COPY 方式：
COPY go.mod go.sum ./
RUN go mod download
COPY openflare-server/ ./openflare-server/
COPY openflare-agent/ ./openflare-agent/
# go build 指定编译子包：
RUN go build -trimpath -ldflags "-s -w -X 'github.com/rain-kl/openflare/openflare-agent/internal/config.Version=$VERSION'" -o /build/openflare-agent ./openflare-agent/cmd/agent
```
* #### [MODIFY] [openflared/Dockerfile](file:///Users/ryan/DEV/Go/OpenFlare/openflared/Dockerfile)
- 职责：适配单 go.mod 构建上下文。
- 修改内容：
```dockerfile
# 更改 builder 阶段的 COPY 方式：
COPY go.mod go.sum ./
RUN go mod download
COPY openflare-server/ ./openflare-server/
COPY openflared/ ./openflared/
# go build 指定编译子包：
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "-s -w -X 'github.com/rain-kl/openflare/openflared/internal/config.Version=$VERSION'" -o flared ./openflared/cmd/flared
```
* #### [MODIFY] [.github/workflows/release.yml](file:///Users/ryan/DEV/Go/OpenFlare/.github/workflows/release.yml)
- 职责：更新 go build 构建命令及 ldflags 版本注入参数（例如将 `-ldflags "-X 'openflare/common.Version=$VERSION'"` 替换为 `-ldflags "-X 'github.com/rain-kl/openflare/openflare-server/common.Version=$VERSION'"`，同时编译命令需要指向正确的子包目录，如 `./openflare-server`）。
---
## 4. 验证计划 (Verification Plan)
### 编译与运行测试
* 运行单测以确保各包逻辑正常：
`go test ./...`（在根目录执行）
* 本地编译各个二进制：
`go build -o bin/openflare-server ./openflare-server`
`go build -o bin/openflare-agent ./openflare-agent/cmd/agent`
`go build -o bin/openflare-relay ./openflare-relay/cmd/relay`
`go build -o bin/openflared ./openflared/cmd/flared`
* 启动服务并检查版本输出：
`./bin/openflare-server --version`
### Docker 构建验证
* 验证镜像构建命令：
`docker build -t openflare-server -f openflare-server/Dockerfile .`
`docker build -t openflare-agent -f openflare-agent/Dockerfile .`
`docker build -t openflare-relay -f openflare-relay/Dockerfile .`
`docker build -t openflared -f openflared/Dockerfile .`
docs/plan/20260618-openflare-wavelet-backend-migration.md
-823
View File
@@ -1,823 +0,0 @@
# OpenFlare → Wavelet 后端迁移计划
> **文档类型**：实现计划（Implementation Plan）
> **创建日期**：2026-06-18
> **状态**：实施中（阶段 5 收尾；控制台 `/api/v1/d/*` + 新前端已落地，legacy 兼容层已撤销）
---
## 1. 目标与背景
### 1.1 需求背景
OpenFlare 当前控制面基于 `openflare-server`（Gin + GORM 单体），与 Wavelet 全栈脚手架在认证、任务、配置、可观测性等基础设施上存在大量重叠。为降低长期维护成本、复用 Wavelet 平台能力，需将 **OpenFlare 业务域**迁移至 Wavelet 框架，同时：
1. **阶段一（本计划核心）**：保留旧前端（`openflare-server/web`）可联调的 **原始 API 路径**（`/api/*`），完成「旧前端 + 新后端」验证。
2. **重叠职能遵循新框架**：用户系统、登录、OAuth、验证码、系统配置、文件上传、推送、任务调度等 **一律复用 Wavelet 内置实现**，禁止在 OpenFlare 业务包中重写。
3. **Agent / Relay / Flared 协议不变**：节点侧二进制与通信协议保持兼容，仅 Server 实现迁移。
### 1.2 开发范围（Scope）
| 范围内（In Scope） | 范围外（Out of Scope） |
|---|---|
| `openflare-server` 全部 HTTP API 迁移至 `Wavelet/` | `openflare-agent`、`openflare-relay`、`openflared` 代码迁移 |
| 重叠模块复用 Wavelet 内置能力 + 兼容适配层 | 多租户、细粒度 RBAC（超出 OpenFlare 单租户边界） |
| 数据模型与 goose SQL 迁移（PG + SQLite 双份） | 英文文档同步 |
| 旧路径 `/api/*` 兼容注册 | 阶段二新前端路径改造（见前端迁移计划） |
| OpenFlare 定时任务（**过渡**：API 主进程内 cron；**目标**：后续迁入统一任务框架） | Wavelet 框架核心文件修改（`v1/user.go` 等禁止改动） |
| `pkg/geoip`、`pkg/render/openresty`、`pkg/protocol` 复用 | 微信登录长期维护（评估后降级或适配） |
### 1.3 迁移总原则
```mermaid
flowchart TB
subgraph Phase1["阶段一：旧前端联调"]
OldWeb["openflare-server/web"]
CompatAPI["/api/* 兼容路由层"]
WaveletCore["Wavelet 内置模块\nuser/oauth/cap/admin"]
OFBiz["OpenFlare 业务模块\nproxy/waf/node/..."]
OldWeb --> CompatAPI
CompatAPI --> WaveletCore
CompatAPI --> OFBiz
end
subgraph Phase2["阶段二：新前端（见前端计划）"]
NewWeb["Wavelet/frontend"]
NewWeb --> V1API["/api/v1/*"]
V1API --> WaveletCore
V1API --> OFBiz
end
```
| 原则 | 说明 |
|---|---|
| **框架优先** | 严格遵守 `Wavelet/AGENTS.md` Guardrails；Skills 以 `/Users/ryan/DEV/Go/Wavelet/.claude/skills/` 为准 |
| **路径兼容** | 阶段一所有旧前端调用的 `/api/*` 路径保持不变 |
| **实现复用** | 重叠功能调用 Wavelet `internal/apps/*` Logic，不复制代码 |
| **路由隔离** | 业务路由仅注册于 `v1/custom.go`、`root/custom.go`；兼容层单独 `legacy` 包 |
| **数据独立** | OpenFlare 表使用 `of_` 前缀或保持原表名；**禁止修改** `w_users` 等框架表 |
| **响应信封** | 新实现统一 `{ error_msg, data }`；兼容层对旧前端做字段/结构适配 |
---
## 2. 架构设计与关键决策
### 2.1 目标目录结构（迁移后）
```
Wavelet/
├── internal/
│ ├── apps/
│ │ ├── user/ # ✅ 复用（禁止重写）
│ │ ├── oauth/ # ✅ 复用
│ │ ├── cap/ # ✅ 复用
│ │ ├── admin/ # ✅ 复用
│ │ ├── upload/ # ✅ 复用（Pages 部署包摄取）
│ │ └── openflare/ # 🆕 OpenFlare 业务域根包
│ │ ├── legacy/ # 🆕 /api/* 兼容 Handler（阶段一）
│ │ ├── compat/ # 🆕 响应/鉴权/角色适配
│ │ ├── proxy_route/ # 代理规则
│ │ ├── origin/ # 源站
│ │ ├── config_version/# 配置版本 + 渲染
│ │ ├── node/ # 节点管理
│ │ ├── agent/ # Agent API
│ │ ├── relay/ # Relay API
│ │ ├── flared/ # Tunnel Client API
│ │ ├── waf/ # WAF
│ │ ├── tls/ # TLS/ACME/DNS
│ │ ├── managed_domain/
│ │ ├── pages/ # Pages 静态托管
│ │ ├── dashboard/ # 仪表盘聚合
│ │ ├── observability/ # 可观测性查询（v1 单表）
│ │ ├── tasks/ # 🆕 定时/后台任务集中目录（主进程 cron）
│ │ ├── apply_log/
│ │ ├── option/ # OpenFlare 专有 Option（非框架 SystemConfig）
│ │ ├── update/ # 服务自更新
│ │ ├── uptimekuma/ # Uptime Kuma 集成
│ │ ├── geoip/ # GeoIP 查询服务
│ │ └── websocket/ # Agent/Relay/Flared/升级 WS Hub
│ ├── model/
│ │ ├── users.go # ✅ 框架表（不修改）
│ │ └── openflare_*.go # 🆕 OpenFlare 实体
│ ├── db/migrator/goose/
│ │ ├── postgres/ # 🆕 of_* 表 SQL
│ │ └── sqlite/
│ └── router/
│ ├── v1/custom.go # 🆕 注册 /api/v1/custom/openflare/*
│ └── root/custom.go # 🆕 Webhook/WS 等根路径
├── pkg/ # 从仓库根迁入或 go.mod replace
│ ├── geoip/ # 复用 OpenFlare pkg/geoip
│ ├── render/openresty/ # 复用配置渲染引擎
│ └── protocol/ # 复用节点协议
└── internal/bootstrap/ # API 启动时注册并运行 openflare/tasks
```
### 2.2 关键架构决策
| 决策点 | 选定方案 | 理由 |
|---|---|---|
| API 路径（阶段一） | 在 `apiGroup` 下新增 `/api` 直连组（非 `/v1`），注册全部旧路径 | 旧前端零改动联调 |
| API 路径（阶段二） | 新前端逐步切至 `/api/v1/custom/openflare/*` 或规范化 REST | 符合 Wavelet 规范 |
| 用户/登录 | **复用** `internal/apps/user` + `oauth`；`legacy` 层做路径与 Token 桥接 | 避免双套用户体系 |
| 认证 Token 桥接 | 阶段一同时支持 `OpenFlare-Token`（JWT）与 Wavelet Session/AccessToken；登录后 legacy 层签发兼容 JWT 或映射到 AccessToken | 旧前端依赖 Header Token |
| 角色模型 | OpenFlare `role(1/10/100)` 映射为 Wavelet `is_admin` + 扩展字段 `of_role`（SystemConfig 或用户扩展表） | Wavelet 仅 bool admin；Root 权限需扩展 |
| 系统配置 | OpenFlare `options` 表保留（70+ 热加载项）；框架 `system_configs` 仅放 Wavelet 平台项 | 业务配置语义不同，避免强行合并 |
| 定时任务（OpenFlare） | **当前**：`openflare/tasks` + `robfig/cron`，随 `wavelet api` / `wavelet all` 在 API 进程内运行；**后续**：迁入统一任务框架（文件按 job 拆分，便于替换 registry） | 阶段一优先功能完备；与 Wavelet Asynq Worker/Scheduler 解耦 |
| 数据库迁移 | Wavelet goose SQL（postgres + sqlite 双份）；默认库名 `openflare`；SQLite→PG 一次性迁移脚本待补 | 与框架迁移机制一致 |
| 可观测存储 | **v1 单表**（`of_node_*` 无 `_00`~`_09` 分片）；历史分片数据需 ETL；后续可评估 ClickHouse 或恢复分片 | 降低迁移复杂度，满足当前联调与中小规模部署 |
| 进程部署 | Wavelet 生产仍建议 `api` + `worker` + `scheduler` 三进程；**OpenFlare 业务 cron 仅需 API 进程** | 框架任务与 OpenFlare cron 职责分离 |
| 前端嵌入 | 阶段一继续托管 `openflare-server/web/build`；阶段二切换 `Wavelet/frontend` embed | 分阶段降低风险 |
### 2.3 鉴权兼容设计
```mermaid
sequenceDiagram
participant FE as 旧前端
participant LEG as legacy/auth 适配
participant USR as apps/user
participant OF as openflare/* Logic
FE->>LEG: POST /api/user/login
LEG->>USR: Login(ctx, credentials)
USR-->>LEG: Session + User
LEG-->>FE: JWT OpenFlare-Token（兼容）
FE->>LEG: GET /api/proxy-routes/ + OpenFlare-Token
LEG->>LEG: 校验 JWT / 映射 AccessToken
LEG->>OF: ListProxyRoutes(ctx, user)
OF-->>LEG: results
LEG-->>FE: 旧格式 ApiEnvelope
```
| OpenFlare 鉴权 | Wavelet 目标 | 适配位置 |
|---|---|---|
| `OpenFlare-Token` JWT | Session / AccessToken | `openflare/compat/auth.go` |
| `UserAuth` role≥1 | `oauth.LoginRequired()` | legacy 中间件 |
| `AdminAuth` role≥10 | `LoginRequired` + `of_role≥10` | legacy 中间件 |
| `RootAuth` role≥100 | `LoginAdminRequired` + `of_role≥100` | legacy 中间件 |
| `X-Agent-Token` | 保持不变 | `openflare/agent/middleware.go` |
| `X-Tunnel-Token` | 保持不变 | `openflare/flared/middleware.go` |
| Cap PoW `/api/cap/:scope/*` | `apps/cap` + scope 映射 | `openflare/legacy/cap.go` |
---
## 3. 功能模块迁移总览
### 3.1 模块分类
| 类别 | 处理方式 | 模块数 |
|---|---|---|
| **A. 直接复用 Wavelet** | 不迁移代码，仅适配路径/响应 | 12 |
| **B. 兼容适配层** | 薄 Handler 包装 Wavelet Logic | 8 |
| **C. 完整迁移 OpenFlare 业务** | 重写为 Wavelet 规范（Handler+Logic+errs） | 15 |
| **D. 基础设施迁移** | 定时任务（主进程 cron）、WS Hub、可观测单表 | 6 |
---
## 4. 模块 A：直接复用 Wavelet（禁止重写）
| # | 旧模块 | 旧 API 前缀 | Wavelet 复用位置 | 阶段一兼容路径 | 迁移动作 |
|---|---|---|---|---|---|
| A1 | 密码登录 | `POST /api/user/login` | `internal/apps/user` | 保持 | legacy Handler 委托 `user.Login` |
| A2 | 登出 | `GET /api/user/logout` | `internal/apps/user` | 保持 | legacy 委托 + 清 JWT |
| A3 | 当前用户 | `GET /api/user/self` | `internal/apps/user` | 保持 | 字段映射 `role/display_name` |
| A4 | 更新资料 | `POST /api/user/self/update` | `PUT /api/v1/user/profile` | 保持旧路径 | legacy 转发 |
| A5 | 修改密码 | — | `POST /api/v1/user/change-password` | 设置页适配 | 前端阶段二切路径 |
| A6 | 邮箱验证码 | `GET /api/verification` | `POST /api/v1/user/send-email-code` | 保持/映射 | legacy 参数适配 |
| A7 | OAuth 通用 | `/api/oauth/:source/*` | `internal/apps/oauth` | 保持 | 回调 URL 配置更新 |
| A8 | 外部账号 | `/api/oauth/external-accounts` | `oauth.ListExternalAccounts` | 保持 | 响应字段映射 |
| A9 | 用户管理 Admin | `/api/user/` CRUD | `internal/apps/admin/user` | 保持 | role 字段双向映射 |
| A10 | 认证源 CRUD | `/api/auth-sources/` | `admin/auth_source` | 保持 | legacy CRUD 包装 |
| A11 | 验证码 Cap | `/api/cap/:scope/*` | `internal/apps/cap` | 保持 | scope→scene 映射 |
| A12 | 服务自更新 | `/api/update/*` | `admin/updater` | 保持 | 升级逻辑对齐 Wavelet updater |
**目标代码位置（适配层）**：
| 文件 | 职责 |
|---|---|
| `internal/apps/openflare/legacy/auth_user.go` | 用户登录/登出/self/注册 |
| `internal/apps/openflare/legacy/auth_oauth.go` | OAuth 路径兼容 |
| `internal/apps/openflare/legacy/auth_admin.go` | 用户管理、认证源 |
| `internal/apps/openflare/legacy/cap.go` | Cap scope 兼容 |
| `internal/apps/openflare/legacy/update.go` | 升级 API 兼容 |
| `internal/apps/openflare/compat/auth.go` | JWT↔Session/Token、角色解析 |
| `internal/apps/openflare/compat/response.go` | Wavelet 信封 → 旧 ApiEnvelope |
**明确不复用/需评估**：
| 项 | 说明 |
|---|---|
| 微信登录 `GET /api/oauth/wechat` | Wavelet 无内置；阶段一保留 legacy 实现或标记废弃 |
| 注册 `POST /api/user/register` | 旧实现返回「非法请求」；对齐 Wavelet `POST /api/v1/user/register` |
| GitHub 旧回调 `GET /api/oauth/github` | 迁移到通用 OAuth 源 |
---
## 5. 模块 B：兼容适配（薄包装）
| # | 旧模块 | 旧路径 | Wavelet 对齐能力 | 目标 Logic 位置 |
|---|---|---|---|---|
| B1 | 系统状态 | `GET /api/status` | `health` + `config/public` + 自定义 | `openflare/legacy/status.go` |
| B2 | 公告 | `GET /api/notice` | Option/SystemConfig | `openflare/option/logics.go` |
| B3 | 关于 | `GET /api/about` | Option | `openflare/option/logics.go` |
| B4 | 密码重置 | `/api/reset_password`, `POST /api/user/reset` | `user` 邮件能力 | `openflare/legacy/password_reset.go` |
| B5 | 系统选项 | `GET/POST /api/option/*` | 保留 `of_options` 表 | `openflare/option/` |
| B6 | SMTP/邮件 | Option 内嵌 | `pkg/mail` + admin 配置 | 通过 `option` 读写 + `mail` 发送 |
| B7 | 限流 | 中间件 | `risk_control` + Redis | `openflare/compat/ratelimit.go` |
| B8 | Swagger | `GET /swagger/*` | 框架 Swagger | `root/custom.go` 或沿用 root |
---
## 6. 模块 C：OpenFlare 核心业务（完整迁移）
### 6.1 代理与源站
| # | 功能 | 旧路径 | 目标 Logic | 目标 Model | 目标路由注册 |
|---|---|---|---|---|---|
| C1 | 代理规则列表 | `GET /api/proxy-routes/` | `openflare/proxy_route/logics.go` | `model/openflare_proxy_route.go` | `legacy/proxy_route.go` |
| C2 | 代理规则详情 | `GET /api/proxy-routes/:id` | 同上 | 同上 | 同上 |
| C3 | 创建代理规则 | `POST /api/proxy-routes/` | 同上 | 同上 | 同上 |
| C4 | 更新代理规则 | `POST /api/proxy-routes/:id/update` | 同上 | 同上 | 同上 |
| C5 | 删除代理规则 | `POST /api/proxy-routes/:id/delete` | 同上 | 同上 | 同上 |
| C6 | 源站列表 | `GET /api/origins/` | `openflare/origin/logics.go` | `model/openflare_origin.go` | `legacy/origin.go` |
| C7 | 源站 CRUD | `GET/POST /api/origins/:id/*` | 同上 | 同上 | 同上 |
**迁移源文件对照**：
| 旧文件 | 新文件 |
|---|---|
| `openflare-server/internal/controller/proxy_route.go` | `openflare/proxy_route/routers.go` |
| `openflare-server/internal/service/proxy_route.go` | `openflare/proxy_route/logics.go` |
| `openflare-server/internal/controller/origin.go` | `openflare/origin/routers.go` |
| `openflare-server/internal/service/origin.go` | `openflare/origin/logics.go` |
### 6.2 配置版本与发布
| # | 功能 | 旧路径 | 目标 Logic | 依赖 |
|---|---|---|---|---|
| C8 | 版本列表 | `GET /api/config-versions/` | `openflare/config_version/logics.go` | `pkg/render/openresty` |
| C9 | 激活版本 | `GET /api/config-versions/active` | 同上 | |
| C10 | 预览配置 | `GET /api/config-versions/preview` | 同上 | |
| C11 | Diff | `GET /api/config-versions/diff` | 同上 | |
| C12 | 版本详情 | `GET /api/config-versions/:id` | 同上 | |
| C13 | 发布 | `POST /api/config-versions/publish` | 同上 | |
| C14 | 激活 | `POST /api/config-versions/:id/activate` | 同上 | listener 通知 Agent |
| C15 | 清理 | `POST /api/config-versions/cleanup` | 同上 | |
**目标文件**：
| 路径 | 职责 |
|---|---|
| `internal/apps/openflare/config_version/logics.go` | 快照构建、渲染、checksum |
| `internal/apps/openflare/config_version/routers.go` | HTTP Handler |
| `internal/apps/openflare/config_version/renderer.go` | 封装 `pkg/render/openresty` |
| `internal/model/openflare_config_version.go` | `of_config_versions` 表 |
### 6.3 节点管理
| # | 功能 | 旧路径 | 目标 Logic |
|---|---|---|---|
| C16 | 节点列表 | `GET /api/nodes/` | `openflare/node/logics.go` |
| C17 | 创建节点 | `POST /api/nodes/` | 同上 |
| C18 | 更新/删除 | `POST /api/nodes/:id/update|delete` | 同上 |
| C19 | Bootstrap Token | `GET/POST /api/nodes/bootstrap-token/*` | 同上 |
| C20 | Agent 升级 | `POST /api/nodes/:id/agent-update` | 同上 + `openflare/update/` |
| C21 | 强制同步 | `POST /api/nodes/:id/force-sync` | 同上 + WS 通知 |
| C22 | OpenResty 重启 | `POST /api/nodes/:id/openresty-restart` | 同上 |
| C23 | 可观测性 | `GET /api/nodes/:id/observability` | `openflare/observability/logics.go` |
| C24 | 健康事件清理 | `POST /api/nodes/:id/observability/cleanup` | 同上 |
| C25 | Agent 版本查询 | `GET /api/nodes/:id/agent-release` | `openflare/node/agent_release.go` |
**目标 Model**：`model/openflare_node.go`（表 `of_nodes`，或保留 `nodes`）
### 6.4 Agent / Relay / Flared API（节点协议）
| # | 功能 | 旧路径 | 目标 Logic | 认证中间件 |
|---|---|---|---|---|
| C26 | Agent 注册 | `POST /api/agent/nodes/register` | `openflare/agent/logics.go` | `AgentRegisterAuth` |
| C27 | Agent 心跳 | `POST /api/agent/nodes/heartbeat` | 同上 | `AgentAuth` |
| C28 | Agent WS | `GET /api/agent/ws` | `openflare/websocket/agent_hub.go` | `AgentAuth` |
| C29 | 拉取配置 | `GET /api/agent/config-versions/active` | `openflare/agent/config.go` | `AgentAuth` |
| C30 | Pages 包下载 | `GET /api/agent/pages/deployments/:id/package` | `openflare/pages/agent.go` | `AgentAuth` |
| C31 | WAF IP 同步 | `POST /api/agent/waf/ip-groups/sync` | `openflare/waf/agent_sync.go` | `AgentAuth` |
| C32 | 应用日志上报 | `POST /api/agent/apply-logs` | `openflare/apply_log/logics.go` | `AgentAuth` |
| C33 | Relay 心跳 | `POST /api/relay/heartbeat` | `openflare/relay/logics.go` | `RelayAuth` |
| C34 | Relay WS | `GET /api/relay/ws` | `openflare/websocket/relay_hub.go` | `RelayAuth` |
| C35 | Flared 心跳 | `POST /api/flared/heartbeat` | `openflare/flared/logics.go` | `TunnelAuth` |
| C36 | Flared 配置 | `GET /api/flared/config/active` | 同上 | `TunnelAuth` |
| C37 | Flared 应用日志 | `POST /api/flared/apply-log` | 同上 | `TunnelAuth` |
| C38 | Flared WS | `GET /api/flared/ws` | `openflare/websocket/flared_hub.go` | `TunnelAuth` |
**迁移源**：`openflare-server/internal/controller/agent.go`、`relay.go`、`flared.go`、`service/node*.go`
### 6.5 WAF
| # | 功能 | 旧路径 | 目标 Logic |
|---|---|---|---|
| C39 | IP 组列表 | `GET /api/waf/ip-groups` | `openflare/waf/ip_group.go` |
| C40 | IP 组 CRUD | `POST /api/waf/ip-groups/*` | 同上 |
| C41 | IP 组同步 | `POST /api/waf/ip-groups/:id/sync` | 同上 + `tasks/waf_ip_group_sync` cron |
| C42 | IP 组测试 | `POST /api/waf/ip-groups/test` | 同上 |
| C43 | 规则组列表 | `GET /api/waf/rule-groups` | `openflare/waf/rule_group.go` |
| C44 | 规则组 CRUD | `POST /api/waf/rule-groups/*` | 同上 |
| C45 | 规则组站点绑定 | `POST /api/waf/rule-groups/:id/sites` | 同上 |
| C46 | 站点规则组 | `GET/POST /api/waf/sites/:route_id/rule-groups` | `openflare/waf/site_binding.go` |
**目标 Model**：
| 模型 | 表名 |
|---|---|
| `OpenFlareWAFRuleGroup` | `of_waf_rule_groups` |
| `OpenFlareWAFIPGroup` | `of_waf_ip_groups` |
| `OpenFlareWAFRuleGroupBinding` | `of_waf_rule_group_bindings` |
### 6.6 TLS / ACME / DNS / 托管域名
| # | 功能 | 旧路径 | 目标 Logic |
|---|---|---|---|
| C47 | 托管域名 CRUD | `/api/managed-domains/*` | `openflare/managed_domain/` |
| C48 | SNI 匹配 | `GET /api/managed-domains/match` | 同上 |
| C49 | TLS 证书 CRUD | `/api/tls-certificates/*` | `openflare/tls/` |
| C50 | 证书内容 | `GET /api/tls-certificates/:id/content` | 同上 |
| C51 | ACME 申请/续期 | `POST /api/tls-certificates/apply|renew` | 同上 + `lego` |
| C52 | ACME 转换 | `POST /api/tls-certificates/:id/convert-acme` | 同上 |
| C53 | 文件导入 | `POST /api/tls-certificates/import-file` | 同上 + `upload.Ingest` |
| C54 | DNS 账号 CRUD | `/api/dns-accounts/*` | `openflare/tls/dns_account.go` |
| C55 | 默认 ACME 账号 | `GET /api/acme-accounts/default` | `openflare/tls/acme_account.go` |
**迁移源**：`openflare-server/internal/service/certificate*.go`、`acme*.go`、`dns*.go`
### 6.7 Pages 静态托管
| # | 功能 | 旧路径 | 目标 Logic | 备注 |
|---|---|---|---|---|
| C56 | 项目 CRUD | `/api/pages/*` | `openflare/pages/logics.go` | |
| C57 | 部署列表 | `GET /api/pages/:id/deployments` | 同上 | |
| C58 | 部署上传 | `POST .../deployments/upload` | 同上 | 使用 `upload.Ingest` |
| C59 | 激活部署 | `POST .../activate` | 同上 | 触发 config_version 变更 |
| C60 | 删除部署 | `POST .../delete` | 同上 | `upload.Remove` |
| C61 | 部署文件清单 | `GET /api/pages/deployments/:id/files` | 同上 | |
### 6.8 仪表盘与可观测性
| # | 功能 | 旧路径 | 目标 Logic |
|---|---|---|---|
| C62 | 仪表盘总览 | `GET /api/dashboard/overview` | `openflare/dashboard/logics.go` |
| C63 | 访问日志查询 | `GET /api/access-logs/` | `openflare/observability/access_log.go` |
| C64 | 折叠日志 | `GET /api/access-logs/folds` | 同上 |
| C65 | IP 汇总 | `GET /api/access-logs/ip-summary` | 同上 |
| C66 | IP 趋势 | `GET /api/access-logs/ip-summary/trend` | 同上 |
| C67 | 访问日志清理 | `POST /api/access-logs/cleanup` | 同上 |
| C68 | 应用日志 | `GET /api/apply-logs/` | `openflare/apply_log/logics.go` |
| C69 | 应用日志清理 | `POST /api/apply-logs/cleanup` | 同上 |
| C70 | GeoIP 查询 | `POST /api/option/geoip/lookup` | `openflare/geoip/logics.go` |
| C71 | 数据库清理 | `POST /api/option/database/cleanup` | `openflare/tasks/database_cleanup.go` |
**可观测存储（v1）**：goose 单表 `of_node_system_profiles`、`of_node_metric_snapshots`、`of_node_request_reports`、`of_node_health_events`、`of_node_obs_openresty`、`of_node_obs_frps`、`of_node_obs_frpc`、`of_node_access_logs`（迁移 `202606190010`~`012`）。访问日志查询/聚合已实装于 `model/openflare_access_log.go`。
### 6.9 运维集成与定时任务
| # | 功能 | 旧路径 / 调度 | 实现位置 | 调度（当前） |
|---|---|---|---|---|
| C72 | UptimeKuma 同步 | `POST /api/uptimekuma/sync`；Cron 每分钟检查间隔 | `openflare/uptimekuma/sync.go` | `tasks/uptimekuma_sync.go` `* * * * *` |
| C73 | SSL 自动续期 | Cron 每日 00:00 | `openflare/tls/obtain.go` + `tasks/ssl_renew.go` | `0 0 * * *` |
| C74 | WAF IP 组同步 | Cron 每 5 分钟；`POST .../ip-groups/:id/sync` | `openflare/waf/ip_group_sync.go` | `@every 5m` |
| C75 | 可观测数据自动清理 | Cron 每日 03:00（`DatabaseAutoCleanupEnabled`） | `openflare/tasks/database_cleanup.go` | `0 3 * * *` |
**任务注册**：各 job 在 `init()` 中 `registerJob`；`bootstrap.Init(API)` 调用 `tasks.Start`。WAF job 经 `waf/register_tasks.go` 注册以避免 import cycle。
---
## 7. 数据模型迁移清单
### 7.1 框架表（复用，不迁移数据结构）
| Wavelet 表 | 用途 | OpenFlare 映射 |
|---|---|---|
| `w_users` | 用户 | 替代 `users` |
| `w_access_tokens` | API Token | 替代 `users.token` 长期使用 |
| `w_auth_sources` | 认证源 | 替代 `auth_sources` |
| `w_external_accounts` | 外部账号 | 替代 `external_accounts` |
| `system_configs` | 平台配置 | 仅 Wavelet 平台项 |
### 7.2 OpenFlare 业务表（goose 新建）
| 旧表名 | 新表名建议 | 迁移优先级 | Model 文件 |
|---|---|---|---|
| `options` | `of_options` | P0 | `openflare_option.go` |
| `origins` | `of_origins` | P1 | `openflare_origin.go` |
| `proxy_routes` | `of_proxy_routes` | P1 | `openflare_proxy_route.go` |
| `config_versions` | `of_config_versions` | P1 | `openflare_config_version.go` |
| `nodes` | `of_nodes` | P1 | `openflare_node.go` |
| `managed_domains` | `of_managed_domains` | P2 | `openflare_managed_domain.go` |
| `tls_certificates` | `of_tls_certificates` | P2 | `openflare_tls_certificate.go` |
| `acme_accounts` | `of_acme_accounts` | P2 | `openflare_acme_account.go` |
| `dns_accounts` | `of_dns_accounts` | P2 | `openflare_dns_account.go` |
| `pages_projects` | `of_pages_projects` | P2 | `openflare_pages_project.go` |
| `pages_deployments` | `of_pages_deployments` | P2 | `openflare_pages_deployment.go` |
| `pages_deployment_files` | `of_pages_deployment_files` | P2 | `openflare_pages_deployment_file.go` |
| `waf_rule_groups` | `of_waf_rule_groups` | P2 | `openflare_waf_rule_group.go` |
| `waf_ip_groups` | `of_waf_ip_groups` | P2 | `openflare_waf_ip_group.go` |
| `waf_rule_group_bindings` | `of_waf_rule_group_bindings` | P2 | `openflare_waf_binding.go` |
| `apply_logs` | `of_apply_logs` | P1 | `openflare_apply_log.go` |
| `node_system_profiles` | `of_node_system_profiles` | P1 | `openflare_node_profile.go` |
| `node_health_events` | `of_node_health_events` | P2 | `openflare_health_event.go` |
| `node_metric_snapshots_XX` | `of_node_metric_snapshots`（v1 单表） | ✅ | `openflare_observability.go` |
| `node_request_reports_XX` | `of_node_request_reports`（v1 单表） | ✅ | 同上 |
| `node_access_logs_XX` | `of_node_access_logs`（v1 单表 + 复合索引） | ✅ | `openflare_access_log.go` |
| `node_observation_openresties_XX` | `of_node_obs_openresty`（v1 单表） | ✅ | `openflare_observability.go` |
| `node_observation_frps_XX` | `of_node_obs_frps`（v1 单表） | ✅ | 同上 |
| `node_observation_frpcs_XX` | `of_node_obs_frpc`（v1 单表） | ✅ | 同上 |
### 7.3 数据迁移脚本
| 脚本 | 路径 | 说明 |
|---|---|---|
| 用户迁移 | `support-files/migration/migrate_users.go` | `users` → `w_users`，角色映射 |
| 业务数据迁移 | `support-files/migration/migrate_openflare_data.go` | 全表批量迁移 |
| SQLite→PG | Wavelet 启动检测 + 一次性导入 | 参考旧 `openflare-server` 逻辑 |
---
## 8. 分阶段实施计划
### 阶段 0：基建准备（1–2 周）— ✅ 已完成
| 任务 ID | 任务 | 产出 | 验收标准 |
|---|---|---|---|
| B0-1 | 在 `Wavelet/go.mod` 添加 `pkg/geoip`、`pkg/render`、`pkg/protocol` 引用 | go.mod replace | `go build ./...` 通过 |
| B0-2 | 创建 `internal/apps/openflare/` 骨架 | 包结构 | 符合 AGENTS.md |
| B0-3 | 实现 `compat/auth.go`、`compat/response.go` | 鉴权/响应适配 | 单元测试覆盖 |
| B0-4 | 注册 legacy 路由组 | `legacy/register*.go` | `/api/status` 可访问 |
| B0-5 | bootstrap 注册 OpenFlare 后台任务 | `bootstrap.go` + `openflare/tasks` | API 启动后 cron 注册日志可见 |
| B0-6 | 同步 Wavelet Skills 到开发环境 | `.claude/skills/` | AI 开发可用 |
| B0-7 | 编写 OpenFlare 业务设计补充文档 | `docs/design/openflare-wavelet-integration.md` | 待评审（可选） |
### 阶段 1：认证与用户联调（1 周）— ✅ 已完成
| 任务 ID | 任务 | 依赖 |
|---|---|---|
| B1-1 | legacy 用户登录/登出/self | B0-3 |
| B1-2 | OAuth 路径兼容 | A7 |
| B1-3 | Cap scope 兼容 | A11 |
| B1-4 | 用户管理 Admin CRUD 兼容 | A9 |
| B1-5 | 认证源 CRUD 兼容 | A10 |
| B1-6 | 密码重置流程 | B4 |
| B1-7 | **旧前端登录联调** | B1-1~B1-6 |
**验收**：旧前端 `/login` 可登录，`OpenFlare-Token` 可访问 `/api/user/self`。
### 阶段 2：核心链路（2–3 周）— ✅ 已完成
| 任务 ID | 模块 | API 数 |
|---|---|---|
| B2-1 | Option 读写 + 热加载 | 4 |
| B2-2 | Origin CRUD | 5 |
| B2-3 | ProxyRoute CRUD | 5 |
| B2-4 | ConfigVersion 全链路 | 8 |
| B2-5 | Node 管理 | 10 |
| B2-6 | Agent API + WS | 7 |
| B2-7 | ApplyLog | 2 |
**验收**：创建节点 → 创建规则 → 发布配置 → Agent 拉取并回报 apply-log。
### 阶段 3：安全与证书（2 周）— ✅ 已完成
| 任务 ID | 模块 | 状态 |
|---|---|---|
| B3-1 | WAF 规则组 + IP 组 + 站点绑定 | ✅ |
| B3-2 | Agent WAF 同步（heartbeat + `/waf/ip-groups/sync`） | ✅ |
| B3-3 | TLS 证书 + ACME（lego DNS-01）+ DNS | ✅ |
| B3-4 | ManagedDomain | ✅ |
| B3-5 | SSL 续期定时任务 | ✅ `tasks/ssl_renew.go` |
### 阶段 4：扩展能力（2–3 周）— ✅ 已完成（v1 单表）
| 任务 ID | 模块 | 状态 |
|---|---|---|
| B4-1 | Pages 托管 + Agent 包下载 | ✅ |
| B4-2 | Relay + Flared API + WS + 观测持久化 | ✅ |
| B4-3 | Dashboard 聚合 | ✅ |
| B4-4 | 可观测性单表 + Agent heartbeat 写入 | ✅ |
| B4-5 | 访问日志查询/清理 | ✅ |
| B4-6 | UptimeKuma 集成（API + cron） | ✅ |
### 阶段 5：运维与收尾（1 周）— 进行中
| 任务 ID | 任务 | 状态 |
|---|---|---|
| B5-1 | 服务自更新兼容 | ✅ |
| B5-2 | GeoIP 查询 + Agent Geo 自动更新 | ✅ |
| B5-3 | 数据迁移脚本与文档 | ⏳ 待实现 `support-files/migration/` |
| B5-4 | `make swagger` + `make code-check` 全绿 | ⏳ |
| B5-5 | 全量 API 回归（对照旧后端 120+ 端点） | ⏳ |
| B5-6 | Handover 文档 | ✅ 见 `handover-openflare-backend-migration.md` |
---
## 9. 具体文件变更清单（汇总）
### 9.1 新建文件（核心）
```
Wavelet/internal/apps/openflare/
├── legacy/ # 阶段一 /api/* Handler（约 20 个文件）
├── compat/ # 鉴权、响应、限流适配（约 5 个文件）
├── proxy_route/ # routers.go + logics.go + errs.go
├── origin/
├── config_version/
├── node/
├── agent/
├── relay/
├── flared/
├── waf/
├── tls/
├── managed_domain/
├── pages/
├── dashboard/
├── observability/
├── apply_log/
├── option/
├── update/
├── uptimekuma/
├── geoip/
├── tasks/ # 定时/后台任务（主进程 cron，后续可迁框架）
└── websocket/
Wavelet/internal/model/openflare_*.go # 业务实体 + access_log 查询
Wavelet/internal/db/migrator/goose/ # postgres/ + sqlite/；of_* 至 202606190012
Wavelet/internal/apps/openflare/legacy/ # RegisterRoutes 委派
Wavelet/internal/bootstrap/bootstrap.go # RegisterOpenFlareBackgroundTasks + tasks.Start
Wavelet/support-files/migration/ # 数据迁移工具（待建）
```
### 9.2 修改文件（仅允许范围内）
| 文件 | 修改内容 |
|---|---|
| `internal/router/v1/custom.go` | 注册 `/api/v1/custom/openflare/*`（阶段二） |
| `internal/router/root/custom.go` | WebSocket、特殊根路径 |
| `internal/router/router.go` | 调用 `RegisterLegacyRoutes`（仅增加一行委派） |
| `internal/bootstrap/*.go` | 注册 OpenFlare 任务与监听器 |
| `go.mod` | 添加 OpenFlare pkg 依赖 |
| `config.example.yaml` | OpenFlare 相关配置项 |
### 9.3 禁止修改
```
internal/router/v1/v1.go
internal/router/v1/user.go
internal/router/v1/admin.go
internal/apps/user/*（除公开 Logic 调用）
internal/apps/oauth/*（除公开 Logic 调用）
internal/model/users.go
```
---
## 10. 验证计划
### 10.1 自动化测试
```bash
cd Wavelet
make code-check
go test ./internal/apps/openflare/... -v
go test ./internal/apps/openflare/compat/... -v
```
| 测试类型 | 覆盖 |
|---|---|
| 单元测试 | config_version 快照构建、WAF IP 解析、compat 鉴权 |
| 集成测试 | legacy 登录 → CRUD 规则 → 发布 → Agent 拉取 |
| 迁移测试 | SQLite 旧库 → Wavelet 新 schema 校验 |
| 回归测试 | 120+ API 端点对照表逐项 curl |
### 10.2 旧前端联调清单
| 场景 | 路径 | 预期 |
|---|---|---|
| 登录 | `/login` | 获取 Token，跳转首页 |
| 仪表盘 | `/` | 数据加载 |
| 节点创建 | `/node` | Bootstrap Token 显示 |
| 规则发布 | `/proxy-route` → `/config-version` | 发布成功 |
| WAF | `/waf` | 规则组 CRUD |
| 证书 | `/website/certificate` | ACME 申请 |
| 设置 | `/setting` | Option 读写 |
| 升级 | 顶栏 | WS 日志流 |
### 10.3 Agent 协议验证
```bash
# Agent 心跳
curl -X POST http://127.0.0.1:3000/api/agent/nodes/heartbeat \
-H "X-Agent-Token: <token>" -d '{...}'
# 拉取配置
curl http://127.0.0.1:3000/api/agent/config-versions/active \
-H "X-Agent-Token: <token>"
```
---
## 11. 风险与缓解
| 风险 | 影响 | 缓解措施 |
|---|---|---|
| JWT vs Session 双轨 | 旧前端鉴权失败 | compat 层统一；充分测试 |
| 角色三级 vs is_admin | Root 权限丢失 | `of_role` 扩展字段 |
| 70+ Option 热加载 | 配置行为不一致 | 保留 OptionMap 机制 |
| 旧环境 10 分片观测数据 | 无法直接挂载单表 schema | v1 采用单表；提供 ETL 脚本（待 B5-3）；新部署无影响 |
| 微信登录无 Wavelet 原生 | 部分用户无法登录 | 评估废弃或独立 legacy |
| 三进程部署运维复杂度 | 部署失败 | 提供 docker-compose 与 `wavelet all` 开发模式 |
| WebSocket Hub 迁移 | 节点掉线 | 保持 Hub 接口不变，充分压测 |
---
## 12. API 端点完整对照表（openflare-server → Wavelet 当前实现）
> **2026-06-19 更新**：阶段一 `internal/apps/openflare/legacy/` 已撤销。下表「当前路径」列反映 Wavelet 实码；路由注册见 `internal/router/v1/openflare/register_*.go`，Handler 见 `internal/apps/openflare/*/routers.go`。
### 12.1 路径前缀对照
| 类别 | 旧路径前缀（openflare-server） | 当前路径前缀（Wavelet） | 响应格式 |
|---|---|---|---|
| 管理控制台 | `/api/<resource>` | `/api/v1/d/<resource>` | `{error_msg, data}` |
| Agent 协议 | `/api/agent/*` | `/api/v1/agent/*` | `{success, message, data}` |
| Relay 协议 | `/api/relay/*` | `/api/v1/relay/*` | 同上 |
| Tunnel 协议 | `/api/flared/*` | `/api/v1/tunnel/*` | 同上（`flared` 更名为 `tunnel`） |
| 用户/OAuth/Cap | `/api/user/*`、`/api/oauth/*`、`/api/cap/*` | `/api/v1/user/*`、`/api/v1/oauth/*`、`/api/cap/*` | Wavelet 标准 |
| 认证源/用户管理 | `/api/auth-sources/*`、`/api/user/*`（Admin） | `/api/v1/admin/*` | Wavelet 标准 |
列表端点通过 `apiutil.RegisterCollection` 同时注册无尾斜杠与有尾斜杠路径。
### 12.2 平台层端点（复用 Wavelet，无旧 `/api/*` 兼容）
| 方法 | 旧路径 | 当前路径 | 实现位置 | 备注 |
|---|---|---|---|---|
| GET | `/api/verification` | `POST /api/v1/user/send-email-code` | `apps/user` | 方法变更 |
| GET | `/api/reset_password` | `—` | `apps/user` | 未映射旧路径 |
| POST | `/api/user/reset` | `—` | `apps/user` | 未映射旧路径 |
| POST | `/api/user/register` | `POST /api/v1/user/register` | `apps/user` | |
| POST | `/api/user/login` | `POST /api/v1/user/login` | `apps/user` | |
| GET | `/api/user/logout` | `POST /api/v1/user/logout` | `apps/user` | 方法变更 |
| GET | `/api/user/self` | `GET /api/v1/user/profile` | `apps/user` | 路径变更 |
| POST | `/api/user/self/update` | `PUT /api/v1/user/profile` | `apps/user` | 方法变更 |
| POST | `/api/user/self/delete` | `—` | `apps/user` | 未实现 |
| GET | `/api/user/token` | `GET /api/v1/user/access-tokens` | `apps/user` | |
| GET | `/api/user/` | `GET /api/v1/admin/users` | `apps/admin/user` | |
| GET | `/api/user/search` | `—` | `apps/admin/user` | 未实现 |
| GET | `/api/user/:id` | `GET /api/v1/admin/users/:id` | `apps/admin/user` | |
| POST | `/api/user/` | `POST /api/v1/admin/users` | `apps/admin/user` | |
| POST | `/api/user/manage` | `—` | `apps/admin/user` | 未实现 |
| POST | `/api/user/update` | `PUT /api/v1/admin/users/:id` | `apps/admin/user` | 方法变更 |
| POST | `/api/user/:id/delete` | `DELETE /api/v1/admin/users/:id` | `apps/admin/user` | 方法变更 |
| GET | `/api/oauth/:source/authorize` | `GET /api/v1/oauth/:source/authorize` | `apps/oauth` | |
| GET | `/api/oauth/:source/callback` | `GET /api/v1/oauth/:source/callback` | `apps/oauth` | |
| POST | `/api/oauth/link-existing` | `POST /api/v1/oauth/link-existing` | `apps/oauth` | |
| GET | `/api/oauth/external-accounts` | `GET /api/v1/oauth/external-accounts` | `apps/oauth` | |
| POST | `/api/oauth/external-accounts/:id/delete` | `DELETE /api/v1/oauth/external-accounts/:id` | `apps/oauth` | 方法变更 |
| POST | `/api/cap/:scope/challenge` | `POST /api/cap/challenge` | `apps/cap` | scope 改 body |
| POST | `/api/cap/:scope/redeem` | `POST /api/cap/redeem` | `apps/cap` | scope 改 body |
| GET | `/api/auth-sources/` | `GET /api/v1/admin/auth-sources` | `apps/admin/auth_source` | |
| POST | `/api/auth-sources/` | `POST /api/v1/admin/auth-sources` | `apps/admin/auth_source` | |
| POST | `/api/auth-sources/:id/update` | `PUT /api/v1/admin/auth-sources/:id` | `apps/admin/auth_source` | 方法变更 |
| POST | `/api/auth-sources/:id/delete` | `DELETE /api/v1/admin/auth-sources/:id` | `apps/admin/auth_source` | 方法变更 |
| POST | `/api/auth-sources/:id/toggle` | `POST /api/v1/admin/auth-sources/:id/toggle` | `apps/admin/auth_source` | |
### 12.3 管理控制台端点（`/api/v1/d/*`）
| 方法 | 旧路径 | 当前路径 | 实现位置 | 备注 |
|---|---|---|---|---|
| GET | `/api/status` | `/api/v1/d/status` | `openflare/option/routers.go` | |
| GET | `/api/notice` | `/api/v1/d/notice` | `openflare/option/routers.go` | |
| GET | `/api/about` | `/api/v1/d/about` | `openflare/option/routers.go` | |
| GET | `/api/option/` | `/api/v1/d/option/` | `openflare/option/routers.go` | |
| POST | `/api/option/update` | `/api/v1/d/option/update` | `openflare/option/routers.go` | |
| POST | `/api/option/update-batch` | `/api/v1/d/option/update-batch` | `openflare/option/routers.go` | |
| POST | `/api/option/geoip/lookup` | `/api/v1/d/option/geoip/lookup` | `openflare/option/routers.go` | |
| POST | `/api/option/database/cleanup` | `/api/v1/d/option/database/cleanup` | `openflare/option/routers.go` | |
| GET | `/api/proxy-routes/` | `/api/v1/d/proxy-routes/` | `openflare/proxy_route/routers.go` | |
| GET | `/api/proxy-routes/:id` | `/api/v1/d/proxy-routes/:id` | `openflare/proxy_route/routers.go` | |
| POST | `/api/proxy-routes/` | `/api/v1/d/proxy-routes/` | `openflare/proxy_route/routers.go` | |
| POST | `/api/proxy-routes/:id/update` | `/api/v1/d/proxy-routes/:id/update` | `openflare/proxy_route/routers.go` | |
| POST | `/api/proxy-routes/:id/delete` | `/api/v1/d/proxy-routes/:id/delete` | `openflare/proxy_route/routers.go` | |
| GET | `/api/origins/` | `/api/v1/d/origins/` | `openflare/origin/routers.go` | |
| GET | `/api/origins/:id` | `/api/v1/d/origins/:id` | `openflare/origin/routers.go` | |
| POST | `/api/origins/` | `/api/v1/d/origins/` | `openflare/origin/routers.go` | |
| POST | `/api/origins/:id/update` | `/api/v1/d/origins/:id/update` | `openflare/origin/routers.go` | |
| POST | `/api/origins/:id/delete` | `/api/v1/d/origins/:id/delete` | `openflare/origin/routers.go` | |
| GET | `/api/config-versions/` | `/api/v1/d/config-versions/` | `openflare/config_version/routers.go` | |
| GET | `/api/config-versions/active` | `/api/v1/d/config-versions/active` | `openflare/config_version/routers.go` | |
| GET | `/api/config-versions/preview` | `/api/v1/d/config-versions/preview` | `openflare/config_version/routers.go` | |
| GET | `/api/config-versions/diff` | `/api/v1/d/config-versions/diff` | `openflare/config_version/routers.go` | |
| GET | `/api/config-versions/:id` | `/api/v1/d/config-versions/:id` | `openflare/config_version/routers.go` | |
| POST | `/api/config-versions/publish` | `/api/v1/d/config-versions/publish` | `openflare/config_version/routers.go` | |
| POST | `/api/config-versions/:id/activate` | `/api/v1/d/config-versions/:id/activate` | `openflare/config_version/routers.go` | |
| POST | `/api/config-versions/cleanup` | `/api/v1/d/config-versions/cleanup` | `openflare/config_version/routers.go` | |
| GET | `/api/nodes/` | `/api/v1/d/nodes/` | `openflare/node/routers.go` | |
| POST | `/api/nodes/` | `/api/v1/d/nodes/` | `openflare/node/routers.go` | |
| GET | `/api/nodes/bootstrap-token` | `/api/v1/d/nodes/bootstrap-token` | `openflare/node/routers.go` | |
| POST | `/api/nodes/bootstrap-token/rotate` | `/api/v1/d/nodes/bootstrap-token/rotate` | `openflare/node/routers.go` | |
| GET | `/api/nodes/:id/agent-release` | `/api/v1/d/nodes/:id/agent-release` | `openflare/node/routers.go` | |
| POST | `/api/nodes/:id/update` | `/api/v1/d/nodes/:id/update` | `openflare/node/routers.go` | |
| POST | `/api/nodes/:id/delete` | `/api/v1/d/nodes/:id/delete` | `openflare/node/routers.go` | |
| POST | `/api/nodes/:id/agent-update` | `/api/v1/d/nodes/:id/agent-update` | `openflare/node/routers.go` | |
| POST | `/api/nodes/:id/openresty-restart` | `/api/v1/d/nodes/:id/openresty-restart` | `openflare/node/routers.go` | |
| POST | `/api/nodes/:id/force-sync` | `/api/v1/d/nodes/:id/force-sync` | `openflare/node/routers.go` | |
| GET | `/api/nodes/:id/observability` | `/api/v1/d/nodes/:id/observability` | `openflare/observability/routers.go` | |
| POST | `/api/nodes/:id/observability/cleanup` | `/api/v1/d/nodes/:id/observability/cleanup` | `openflare/observability/routers.go` | |
| GET | `/api/waf/ip-groups` | `/api/v1/d/waf/ip-groups` | `openflare/waf/routers.go` | |
| GET | `/api/waf/ip-groups/:id` | `/api/v1/d/waf/ip-groups/:id` | `openflare/waf/routers.go` | |
| POST | `/api/waf/ip-groups` | `/api/v1/d/waf/ip-groups` | `openflare/waf/routers.go` | |
| POST | `/api/waf/ip-groups/test` | `/api/v1/d/waf/ip-groups/test` | `openflare/waf/routers.go` | |
| POST | `/api/waf/ip-groups/:id/update` | `/api/v1/d/waf/ip-groups/:id/update` | `openflare/waf/routers.go` | |
| POST | `/api/waf/ip-groups/:id/delete` | `/api/v1/d/waf/ip-groups/:id/delete` | `openflare/waf/routers.go` | |
| POST | `/api/waf/ip-groups/:id/sync` | `/api/v1/d/waf/ip-groups/:id/sync` | `openflare/waf/routers.go` | |
| GET | `/api/waf/rule-groups` | `/api/v1/d/waf/rule-groups` | `openflare/waf/routers.go` | |
| GET | `/api/waf/rule-groups/:id` | `/api/v1/d/waf/rule-groups/:id` | `openflare/waf/routers.go` | |
| POST | `/api/waf/rule-groups` | `/api/v1/d/waf/rule-groups` | `openflare/waf/routers.go` | |
| POST | `/api/waf/rule-groups/:id/update` | `/api/v1/d/waf/rule-groups/:id/update` | `openflare/waf/routers.go` | |
| POST | `/api/waf/rule-groups/:id/delete` | `/api/v1/d/waf/rule-groups/:id/delete` | `openflare/waf/routers.go` | |
| POST | `/api/waf/rule-groups/:id/sites` | `/api/v1/d/waf/rule-groups/:id/sites` | `openflare/waf/routers.go` | |
| GET | `/api/waf/sites/:route_id/rule-groups` | `/api/v1/d/waf/sites/:route_id/rule-groups` | `openflare/waf/routers.go` | |
| POST | `/api/waf/sites/:route_id/rule-groups` | `/api/v1/d/waf/sites/:route_id/rule-groups` | `openflare/waf/routers.go` | |
| GET | `/api/managed-domains/` | `/api/v1/d/managed-domains/` | `openflare/tls/routers.go` | |
| GET | `/api/managed-domains/match` | `/api/v1/d/managed-domains/match` | `openflare/tls/routers.go` | |
| POST | `/api/managed-domains/` | `/api/v1/d/managed-domains/` | `openflare/tls/routers.go` | |
| POST | `/api/managed-domains/:id/update` | `/api/v1/d/managed-domains/:id/update` | `openflare/tls/routers.go` | |
| POST | `/api/managed-domains/:id/delete` | `/api/v1/d/managed-domains/:id/delete` | `openflare/tls/routers.go` | |
| GET | `/api/tls-certificates/` | `/api/v1/d/tls-certificates/` | `openflare/tls/routers.go` | |
| GET | `/api/tls-certificates/:id` | `/api/v1/d/tls-certificates/:id` | `openflare/tls/routers.go` | |
| GET | `/api/tls-certificates/:id/content` | `/api/v1/d/tls-certificates/:id/content` | `openflare/tls/routers.go` | |
| POST | `/api/tls-certificates/` | `/api/v1/d/tls-certificates/` | `openflare/tls/routers.go` | |
| POST | `/api/tls-certificates/:id/update` | `/api/v1/d/tls-certificates/:id/update` | `openflare/tls/routers.go` | |
| POST | `/api/tls-certificates/:id/update-acme` | `/api/v1/d/tls-certificates/:id/update-acme` | `openflare/tls/routers.go` | |
| POST | `/api/tls-certificates/:id/convert-acme` | `/api/v1/d/tls-certificates/:id/convert-acme` | `openflare/tls/routers.go` | |
| POST | `/api/tls-certificates/import-file` | `/api/v1/d/tls-certificates/import-file` | `openflare/tls/routers.go` | |
| POST | `/api/tls-certificates/:id/delete` | `/api/v1/d/tls-certificates/:id/delete` | `openflare/tls/routers.go` | |
| POST | `/api/tls-certificates/apply` | `/api/v1/d/tls-certificates/apply` | `openflare/tls/routers.go` | |
| POST | `/api/tls-certificates/:id/renew` | `/api/v1/d/tls-certificates/:id/renew` | `openflare/tls/routers.go` | |
| GET | `/api/acme-accounts/default` | `/api/v1/d/acme-accounts/default` | `openflare/tls/routers.go` | |
| GET | `/api/dns-accounts/` | `/api/v1/d/dns-accounts/` | `openflare/tls/routers.go` | |
| POST | `/api/dns-accounts/` | `/api/v1/d/dns-accounts/` | `openflare/tls/routers.go` | |
| POST | `/api/dns-accounts/:id/update` | `/api/v1/d/dns-accounts/:id/update` | `openflare/tls/routers.go` | |
| POST | `/api/dns-accounts/:id/delete` | `/api/v1/d/dns-accounts/:id/delete` | `openflare/tls/routers.go` | |
| GET | `/api/pages/` | `/api/v1/d/pages/` | `openflare/pages/routers.go` | |
| GET | `/api/pages/:id` | `/api/v1/d/pages/:id` | `openflare/pages/routers.go` | |
| POST | `/api/pages/` | `/api/v1/d/pages/` | `openflare/pages/routers.go` | |
| POST | `/api/pages/:id/update` | `/api/v1/d/pages/:id/update` | `openflare/pages/routers.go` | |
| POST | `/api/pages/:id/delete` | `/api/v1/d/pages/:id/delete` | `openflare/pages/routers.go` | |
| GET | `/api/pages/:id/deployments` | `/api/v1/d/pages/:id/deployments` | `openflare/pages/routers.go` | |
| POST | `/api/pages/:id/deployments/upload` | `/api/v1/d/pages/:id/deployments/upload` | `openflare/pages/routers.go` | |
| POST | `/api/pages/:id/deployments/:did/activate` | `/api/v1/d/pages/:id/deployments/:did/activate` | `openflare/pages/routers.go` | |
| POST | `/api/pages/:id/deployments/:did/delete` | `/api/v1/d/pages/:id/deployments/:did/delete` | `openflare/pages/routers.go` | |
| GET | `/api/pages/deployments/:did/files` | `/api/v1/d/pages/deployments/:did/files` | `openflare/pages/routers.go` | |
| GET | `/api/dashboard/overview` | `/api/v1/d/dashboard/overview` | `openflare/dashboard/routers.go` | |
| GET | `/api/apply-logs/` | `/api/v1/d/apply-logs/` | `openflare/apply_log/routers.go` | |
| POST | `/api/apply-logs/cleanup` | `/api/v1/d/apply-logs/cleanup` | `openflare/apply_log/routers.go` | |
| GET | `/api/access-logs/` | `/api/v1/d/access-logs/` | `openflare/observability/routers.go` | |
| GET | `/api/access-logs/folds` | `/api/v1/d/access-logs/folds` | `openflare/observability/routers.go` | |
| GET | `/api/access-logs/folds/ip-summary` | `/api/v1/d/access-logs/folds/ip-summary` | `openflare/observability/routers.go` | |
| GET | `/api/access-logs/ip-summary` | `/api/v1/d/access-logs/ip-summary` | `openflare/observability/routers.go` | |
| GET | `/api/access-logs/ip-summary/trend` | `/api/v1/d/access-logs/ip-summary/trend` | `openflare/observability/routers.go` | |
| POST | `/api/access-logs/cleanup` | `/api/v1/d/access-logs/cleanup` | `openflare/observability/routers.go` | |
| POST | `/api/uptimekuma/sync` | `/api/v1/d/uptimekuma/sync` | `openflare/option/routers.go` | |
| GET | `/api/update/latest-release` | `/api/v1/d/update/latest-release` | `openflare/update/routers.go` | |
| GET | `/api/update/logs/ws` | `/api/v1/d/update/logs/ws` | `openflare/update/routers.go` | |
| POST | `/api/update/manual-upload` | `/api/v1/d/update/manual-upload` | `openflare/update/routers.go` | |
| POST | `/api/update/manual-upgrade` | `/api/v1/d/update/manual-upgrade` | `openflare/update/routers.go` | |
| POST | `/api/update/upgrade` | `/api/v1/d/update/upgrade` | `openflare/update/routers.go` | |
### 12.4 节点协议端点（`/api/v1/agent|relay|tunnel/*`）
| 方法 | 旧路径 | 当前路径 | 实现位置 | 备注 |
|---|---|---|---|---|
| POST | `/api/agent/nodes/register` | `/api/v1/agent/nodes/register` | `openflare/agent/routers.go` | |
| GET | `/api/agent/ws` | `/api/v1/agent/ws` | `openflare/agent/routers.go` | |
| POST | `/api/agent/nodes/heartbeat` | `/api/v1/agent/nodes/heartbeat` | `openflare/agent/routers.go` | compat 信封 |
| GET | `/api/agent/config-versions/active` | `/api/v1/agent/config-versions/active` | `openflare/agent/routers.go` | |
| GET | `/api/agent/pages/deployments/:id/package` | `/api/v1/agent/pages/deployments/:deployment_id/package` | `openflare/agent/routers.go` | 参数名变更 |
| POST | `/api/agent/waf/ip-groups/sync` | `/api/v1/agent/waf/ip-groups/sync` | `openflare/agent/routers.go` | |
| POST | `/api/agent/apply-logs` | `/api/v1/agent/apply-logs` | `openflare/agent/routers.go` | |
| POST | `/api/relay/heartbeat` | `/api/v1/relay/heartbeat` | `openflare/relay/routers.go` | compat 信封 |
| GET | `/api/relay/ws` | `/api/v1/relay/ws` | `openflare/relay/routers.go` | |
| POST | `/api/flared/heartbeat` | `/api/v1/tunnel/heartbeat` | `openflare/flared/routers.go` | 路径更名 tunnel |
| GET | `/api/flared/config/active` | `/api/v1/tunnel/config/active` | `openflare/flared/routers.go` | 路径更名 tunnel |
| POST | `/api/flared/apply-log` | `/api/v1/tunnel/apply-log` | `openflare/flared/routers.go` | 路径更名 tunnel |
| GET | `/api/flared/ws` | `/api/v1/tunnel/ws` | `openflare/flared/routers.go` | 路径更名 tunnel |
---
## 13. 里程碑与交付物
| 里程碑 | 时间 | 交付物 |
|---|---|---|
| M1 基建就绪 | 第 2 周 | 骨架代码 + compat 层 + 设计文档 |
| M2 认证联调 | 第 3 周 | 旧前端可登录使用 |
| M3 核心链路 | 第 6 周 | 节点+规则+发布+Agent 闭环 |
| M4 安全证书 | 第 8 周 | WAF+TLS 全功能 |
| M5 全量功能 | 第 11 周 | 120+ API 全通过 |
| M6 生产就绪 | 第 12 周 | 迁移脚本 + 部署文档 + Handover |
---
docs/plan/20260618-openflare-wavelet-frontend-migration.md
-745
View File
@@ -1,745 +0,0 @@
# OpenFlare → Wavelet 前端迁移计划
> **文档类型**：实现计划（Implementation Plan）
> **创建日期**：2026-06-18
> **状态**：✅ 迁移完成（FC-1~20 已实装；验证见 `docs/plan/verify-frontend-*.md`）
> **前置阅读**：[`Wavelet/AGENTS.md`](../../Wavelet/AGENTS.md)、[`docs/plan/20260618-openflare-wavelet-backend-migration.md`](./20260618-openflare-wavelet-backend-migration.md)
> **依赖**：后端阶段一（旧路径 `/api/*` 兼容）完成后启动；阶段二可与后端阶段五并行
---
## 1. 目标与背景
### 1.1 需求背景
OpenFlare 管理控制台当前位于 `openflare-server/web/`（Next.js 15 + 静态导出嵌入 Go）。Wavelet 提供现代化全栈前端脚手架 `Wavelet/frontend/`（Next.js 16 + shadcn/ui + 完整 Admin 基建）。
迁移目标：
1. 将 OpenFlare **全部业务 UI** 按 Wavelet 设计风格重写，统一视觉与交互。
2. **复用 Wavelet 内置页面与组件**（布局、认证、设置、用户管理、Admin 基建），不重写平台能力。
3. 重叠职能（登录、用户、OAuth、Access Token、系统设置）**直接对接 Wavelet `/api/v1/*` API**，不再使用 `OpenFlare-Token`。
4. OpenFlare 业务 API 阶段一切至 `/api/*`（后端兼容层）；阶段二逐步规范化。
### 1.2 开发范围
| 范围内 | 范围外 |
|---|---|
| `openflare-server/web` 全部页面/功能迁移 | 文档站 `docs/` VitePress 改造 |
| Wavelet 布局/导航扩展 | Wavelet 框架核心页面逻辑修改 |
| OpenFlare 业务 Service 层新建 | 旧前端继续长期并存（迁移完成后废弃） |
| 静态导出 / embed 部署方案确认 | Agent/Relay/Flared 节点侧 UI |
| E2E 测试迁移 | 英文界面 |
### 1.3 迁移总原则
| 原则 | 说明 |
|---|---|
| **框架组件优先** | 使用 `Wavelet/frontend/components/ui/*`，禁止复制旧 `components/ui` 11 个自建组件 |
| **服务层规范** | 所有 API 调用经 `lib/services/`，继承 `BaseService` |
| **页面规范** | 遵循 AGENTS.md：`h1 text-2xl font-semibold tracking-tight`，单文件 ≤600 行 |
| **重叠不重写** | 登录/注册/用户管理/认证源/AccessToken 用 Wavelet 现成页面 |
| **业务新建** | OpenFlare 独有功能在 `app/(main)/openflare/` 新建 |
| **参考标杆** | 复杂页面参考 `/admin/database` 拆分模式、`/admin/demo` 组件用法 |
---
## 2. 现状与目标对照
### 2.1 技术栈对照
| 维度 | 旧前端 `openflare-server/web` | 目标 `Wavelet/frontend` |
|---|---|---|
| Next.js | 15 App Router | 16 App Router |
| React | 19 | 19 |
| CSS | Tailwind 4 | Tailwind 4 |
| UI 库 | 自建 11 组件 + HeroUI 混合 | shadcn/Radix 40+ |
| 图表 | ECharts | Recharts（必要时保留 ECharts） |
| 数据请求 | 原生 fetch | Axios + BaseService |
| 状态 | Context + Zustand + React Query | UserContext + React Query |
| 认证 | `OpenFlare-Token` localStorage | Session Cookie + AccessToken |
| API 路径 | `/api/*` | `/api/v1/*` + `/api/*`（业务） |
| 构建 | `output: 'export'` 嵌入 Go | `build:embed` 或 standalone |
| 路由详情 | `?id=` 查询参数 | 优先查询参数（保持静态兼容） |
### 2.2 目录结构对照
**旧前端（迁移源）**：
```
openflare-server/web/
├── app/(dashboard)/ # 18 个控制台路由
├── app/(public)/ # 7 个公开路由
├── features/ # 15 个业务模块（核心逻辑）
├── components/ # 布局 + 轻量 UI
└── lib/api/ # fetch 客户端
```
**目标前端（迁移目标）**：
```
Wavelet/frontend/
├── app/(auth)/ # ✅ 复用：login, register
├── app/(main)/
│ ├── home/ # 改造为 OpenFlare 仪表盘或重定向
│ ├── settings/ # ✅ 复用 + 扩展 OpenFlare 个人设置
│ ├── admin/ # ✅ 复用平台 Admin
│ └── openflare/ # 🆕 OpenFlare 业务路由根
│ ├── page.tsx # 仪表盘 /
│ ├── nodes/ # 节点
│ ├── proxy-routes/ # 代理规则
│ ├── pages/ # Pages 托管
│ ├── websites/ # 网站/证书
│ ├── waf/ # WAF
│ ├── origins/ # 源站
│ ├── config-versions/ # 配置发布
│ ├── access-logs/ # 访问日志
│ ├── performance/ # 性能调优
│ ├── apply-logs/ # 应用日志
│ └── components/ # 跨页面 OpenFlare 子组件
├── components/ # ✅ 复用框架组件
├── lib/services/
│ ├── index.ts # 注册 openflare 服务
│ └── openflare/ # 🆕 业务 API 服务
│ ├── types.ts
│ ├── proxy-route.service.ts
│ ├── node.service.ts
│ └── ...
└── lib/navigation/ # 🆕 侧栏导航配置
```
---
## 3. 功能板块迁移总览
### 3.1 三类处理方式
| 类别 | 数量 | 策略 |
|---|---|---|
| **F-A 直接复用 Wavelet** | 10 板块 | 不改页面，仅改导航/文案/配置 |
| **F-B 扩展 Wavelet 页面** | 5 板块 | 在现有页面增加 OpenFlare 配置块 |
| **F-C 新建 OpenFlare 页面** | 12 板块 | 按 Wavelet 风格完整重写 |
```mermaid
flowchart LR
subgraph Reuse["F-A 复用"]
Login["/login"]
Settings["/settings/*"]
AdminUsers["/admin/users"]
end
subgraph Extend["F-B 扩展"]
AdminSystem["/admin/system"]
AdminSettings["/admin/settings"]
AdminUpdater["升级能力"]
end
subgraph New["F-C 新建"]
Dashboard["/openflare"]
Nodes["/openflare/nodes"]
Routes["/openflare/proxy-routes"]
WAF["/openflare/waf"]
end
Reuse --> WaveletCore["Wavelet /api/v1"]
Extend --> MixedAPI["/api/v1 + /api"]
New --> OpenFlareAPI["/api/* 业务 API"]
```
---
## 4. F-A：直接复用 Wavelet（禁止重写）
| # | 旧路径/模块 | Wavelet 目标 | 迁移动作 | API 切换 |
|---|---|---|---|---|
| FA-1 | `/login` | `app/(auth)/login` | 删除旧登录页；导航指向 Wavelet | `/api/v1/user/login` |
| FA-2 | `/reset`, `/user/reset` | `app/(auth)/` 密码重置流 | 复用 Wavelet 重置流程 | `/api/v1/user/*` |
| FA-3 | 注册（若开放） | `app/(auth)/register` | 复用 | `/api/v1/user/register` |
| FA-4 | Cap PoW | `components/auth/cap-widget.tsx` | 直接引用 | `/api/cap/*` 或 `/api/v1/cap/*` |
| FA-5 | OAuth 回调 | `app/(auth)/` + OAuth 组件 | 回调 URL 改 Wavelet 格式 | `/api/v1/oauth/*` |
| FA-6 | `/user` 用户管理 | `app/(main)/admin/users` | **修复**：纳入侧栏导航 | `/api/v1/admin/users` |
| FA-7 | Access Token | `app/(main)/settings/access-token` | 复用 | `/api/v1/user/access-tokens` |
| FA-8 | 个人资料 | `app/(main)/settings/profile` | 复用 | `/api/v1/user/self` + `profile` |
| FA-9 | 修改密码 | `app/(main)/settings/security` | 复用 | `/api/v1/user/change-password` |
| FA-10 | 外观主题 | `app/(main)/settings/appearance` | 复用 Wavelet 40+ 主题 | 本地 |
**需删除的旧代码**：
```
openflare-server/web/features/auth/ # 整体废弃（保留类型参考）
openflare-server/web/app/(public)/login/
openflare-server/web/app/(public)/reset/
openflare-server/web/app/(dashboard)/user/ # 改用 /admin/users
openflare-server/web/lib/api/auth-token.ts # 改用 Session
```
---
## 5. F-B：扩展 Wavelet 现有页面
| # | 旧功能 | 旧位置 | Wavelet 扩展位置 | 扩展内容 |
|---|---|---|---|---|
| FB-1 | 运维设置 | `/setting` 运维 Tab | `app/(main)/admin/settings` 或 `admin/system` | Agent 心跳阈值、GeoIP Provider、OpenResty 默认参数 |
| FB-2 | 系统设置 | `/setting` 系统 Tab | `admin/system` + `new-setting` skill | 登录开关、SMTP（若未覆盖）、公告 |
| FB-3 | 认证源 CRUD | `/setting` 系统 Tab | `admin/` 已有 `auth-source` 组件 | 确认 API 对齐；移除旧 modal |
| FB-4 | 数据库清理 | `/setting` 数据库 Tab | `admin/database` 或 `admin/settings` | 观测数据保留天数、手动清理按钮 |
| FB-5 | 服务升级 | 顶栏 `version-upgrade-modal` | 复用 `admin/updater` 能力 | 增加 OpenFlare 发版渠道 stable/preview |
**实现路径**：
| 文件 | 职责 |
|---|---|
| `app/(main)/admin/settings/components/openflare-ops.tsx` | 运维参数表单 |
| `app/(main)/admin/system/` 新增 KV | OpenFlare Option 映射为 SystemConfig（可选） |
| `lib/services/openflare/option.service.ts` | 读写 `/api/option/*` |
| `components/layout/app-sidebar.tsx` | 增加 OpenFlare 设置入口 |
---
## 6. F-C：新建 OpenFlare 业务页面（完整重写）
### 6.1 页面路由映射表
| # | 旧路由 | 新路由 | 页面文件 | 优先级 | 复杂度 |
|---|---|---|---|---|---|
| FC-1 | `/` | `/openflare` 或 `/home` 改造 | `app/(main)/openflare/page.tsx` | P0 | 高 |
| FC-2 | `/node` | `/openflare/nodes` | `openflare/nodes/page.tsx` | P0 | 很高 |
| FC-3 | `/node/detail?id=` | `/openflare/nodes/detail` | `openflare/nodes/detail/page.tsx` | P0 | 很高 |
| FC-4 | `/proxy-route` | `/openflare/proxy-routes` | `openflare/proxy-routes/page.tsx` | P0 | 很高 |
| FC-5 | `/proxy-route/detail?id=&section=` | `/openflare/proxy-routes/detail` | `openflare/proxy-routes/detail/page.tsx` | P0 | 极高 |
| FC-6 | `/config-version` | `/openflare/config-versions` | `openflare/config-versions/page.tsx` | P0 | 高 |
| FC-7 | `/waf` | `/openflare/waf` | `openflare/waf/page.tsx` | P1 | 很高 |
| FC-8 | `/waf/ip-groups` | `/openflare/waf/ip-groups` | `openflare/waf/ip-groups/page.tsx` | P1 | 高 |
| FC-9 | `/website` | `/openflare/websites` | `openflare/websites/page.tsx` | P1 | 高 |
| FC-10 | `/website/detail?id=` | `/openflare/websites/detail` | `openflare/websites/detail/page.tsx` | P1 | 高 |
| FC-11 | `/website/certificate` | `/openflare/websites/certificates` | `openflare/websites/certificates/page.tsx` | P1 | 很高 |
| FC-12 | `/website/dns-account` | `/openflare/websites/dns-accounts` | `openflare/websites/dns-accounts/page.tsx` | P1 | 中 |
| FC-13 | `/pages` | `/openflare/pages` | `openflare/pages/page.tsx` | P2 | 中 |
| FC-14 | `/pages/detail?id=` | `/openflare/pages/detail` | `openflare/pages/detail/page.tsx` | P2 | 中 |
| FC-15 | `/origin` | `/openflare/origins` | `openflare/origins/page.tsx` | P2 | 低 |
| FC-16 | `/origin/detail?id=` | `/openflare/origins/detail` | `openflare/origins/detail/page.tsx` | P2 | 低 |
| FC-17 | `/access-log` | `/openflare/access-logs` | `openflare/access-logs/page.tsx` | P2 | 高 |
| FC-18 | `/apply-log?node_id=` | `/openflare/apply-logs` | `openflare/apply-logs/page.tsx` | P2 | 低 |
| FC-19 | `/performance` | `/openflare/performance` | `openflare/performance/page.tsx` | P2 | 中 |
| FC-20 | `/about` | `/docs` 或 `/openflare/about` | 复用 docs 或新建 | P3 | 低 |
### 6.2 各板块详细迁移说明
#### FC-1 总览仪表盘
| 项 | 旧实现 | 新实现 |
|---|---|---|
| 源文件 | `features/dashboard/components/dashboard-page.tsx` | `openflare/page.tsx` + `components/dashboard-overview.tsx` |
| 服务 | `features/dashboard/api.ts` | `lib/services/openflare/dashboard.service.ts` |
| API | `GET /api/dashboard/overview` | 同左（阶段一） |
| 图表 | ECharts `TrendChart`, `RankChart` | Recharts 或保留 ECharts（世界地图建议保留 ECharts/geoJSON） |
| 组件 | `world-stage` 世界地图 | `openflare/components/world-map.tsx` |
| 关键指标 | 流量/容量/节点健康/24h 趋势 | 完整保留 |
**子组件拆分**：
```
openflare/components/dashboard/
├── overview-stats.tsx # 顶部指标卡片（Stat Card 模式）
├── traffic-trend-chart.tsx # 流量趋势
├── capacity-trend-chart.tsx # 容量趋势
├── node-health-table.tsx # 节点健康列表
├── geo-distribution.tsx # 国家分布
└── world-map.tsx # 世界地图
```
#### FC-2/FC-3 节点管理
| 项 | 说明 |
|---|---|
| 源文件 | `features/nodes/components/nodes-page.tsx`（列表）、`node-detail-page.tsx`（1800+ 行）、`relay-detail-page.tsx`、`tunnel-detail-page.tsx` |
| 新结构 | 列表页 ≤400 行；详情按 `node_type` 拆三个子组件 |
| API 服务 | `node.service.ts` |
| 关键功能 | 三类型筛选、Bootstrap Token、Agent 升级、强制同步、OpenResty 重启、安装命令、5s 轮询 |
| 对话框 | 使用 `Sheet`/`Dialog` 替代旧 `app-modal` |
**详情页拆分**：
```
openflare/nodes/detail/
├── page.tsx
└── components/
├── edge-node-detail.tsx # edge_node
├── relay-node-detail.tsx # tunnel_relay
├── tunnel-node-detail.tsx # tunnel_client
├── node-observability.tsx # 可观测性 Tab
├── node-actions.tsx # 操作按钮组
└── install-command.tsx # 安装命令生成
```
**API 映射**：
| 功能 | API |
|---|---|
| 列表 | `GET /api/nodes/` |
| 创建/更新/删除 | `POST /api/nodes/` 等 |
| Bootstrap | `GET/POST /api/nodes/bootstrap-token/*` |
| Agent 升级 | `POST /api/nodes/:id/agent-update` |
| 可观测 | `GET /api/nodes/:id/observability` |
| 应用日志 | `GET /api/apply-logs/?node_id=` |
#### FC-4/FC-5 代理规则
| 项 | 说明 |
|---|---|
| 源文件 | `proxy-routes-page.tsx`、`proxy-route-config-page.tsx`（1400+ 行） |
| 新结构 | 列表 + 详情 6 Section Tab |
| Section | `domains`、`limits`、`proxy`、`cache`、`waf`、`auth` |
**详情 Tab 组件**：
```
openflare/proxy-routes/detail/components/
├── domain-section.tsx
├── limits-section.tsx
├── proxy-section.tsx
├── cache-section.tsx
├── waf-section.tsx
├── auth-section.tsx
├── publish-diff-drawer.tsx # 发布前 diff
└── route-header.tsx
```
**API 映射**：
| 功能 | API |
|---|---|
| CRUD | `/api/proxy-routes/*` |
| 关联数据 | `/api/managed-domains/`、`/api/pages/`、`/api/nodes/`、`/api/tls-certificates/` |
| WAF 绑定 | `/api/waf/sites/:routeId/rule-groups` |
| 发布 | `GET /api/config-versions/diff`、`POST /api/config-versions/publish` |
#### FC-6 配置发布
| 项 | 说明 |
|---|---|
| 源文件 | `features/config-versions/components/config-versions-page.tsx` |
| 功能 | 版本列表、快照查看、预览、diff、发布、激活、清理 |
| UI 模式 | `Table` + `Sheet` 预览 + `Dialog` 确认发布 |
#### FC-7/FC-8 WAF
| 项 | 说明 |
|---|---|
| 源文件 | `waf-page.tsx`（规则组）、`ip-groups-page.tsx` |
| 新路由 | `/openflare/waf` + `/openflare/waf/ip-groups` |
| 复杂 UI | 规则条目 Modal、PoW Tab、站点批量绑定 Drawer |
| 参考 | `/admin/demo` 的 Form/Table 模式 |
**子组件**：
```
openflare/waf/components/
├── rule-group-table.tsx
├── rule-group-form.tsx
├── rule-entry-dialog.tsx
├── rule-list-section.tsx
├── pow-config-panel.tsx
├── site-apply-sheet.tsx
├── ip-group-table.tsx
├── ip-group-form.tsx
└── ip-group-sync-button.tsx
```
#### FC-9~FC-12 网站与证书
| 页面 | 源文件 | 关键 Modal |
|---|---|---|
| 托管域名列表 | `websites-page.tsx` | 创建/编辑 Dialog |
| 域名详情 | `website-detail-page.tsx` | 证书关联、WAF 绑定 |
| 证书管理 | `certificate-page.tsx` | ACME 申请、续期、导入、转换 |
| DNS 账号 | `dns-account-page.tsx` | 多厂商表单 |
**API**：`/api/managed-domains/*`、`/api/tls-certificates/*`、`/api/dns-accounts/*`、`/api/acme-accounts/default`
#### FC-13/FC-14 Pages 静态托管
| 功能 | 说明 |
|---|---|
| 项目 CRUD | Table + Dialog |
| 部署上传 | 使用 Wavelet 上传组件 + XHR 进度 |
| 部署管理 | 版本列表、激活、删除 |
| API | `/api/pages/*` |
#### FC-15/FC-16 源站
| 功能 | 说明 |
|---|---|
| 简单 CRUD | 列表 + 详情，低复杂度 |
| API | `/api/origins/*` |
#### FC-17 访问日志
| Tab | API |
|---|---|
| 明细 | `GET /api/access-logs/` |
| 时间折叠 | `GET /api/access-logs/folds` |
| IP 汇总 | `GET /api/access-logs/ip-summary` |
| IP 趋势 | `GET /api/access-logs/ip-summary/trend` |
| 清理 | `POST /api/access-logs/cleanup` |
**UI**：`DataTable` + 筛选器 + 趋势图（Recharts）
#### FC-18 应用日志
| 功能 | 说明 |
|---|---|
| 按节点筛选 | `?node_id=` 查询参数 |
| 入口 | 节点详情页跳转 |
| API | `GET /api/apply-logs/` |
#### FC-19 性能调优
| 功能 | 说明 |
|---|---|
| 源文件 | `features/performance/` + `settings-page` 运维重叠部分 |
| 内容 | OpenResty 全局参数表单 |
| 预览 | `GET /api/config-versions/preview` |
| API | `GET/POST /api/option/*` |
---
## 7. Service 层迁移清单
### 7.1 新建服务文件
| 服务文件 | basePath | 对应旧 `features/*/api.ts` |
|---|---|---|
| `dashboard.service.ts` | `/api/dashboard` | `features/dashboard/api.ts` |
| `node.service.ts` | `/api/nodes` | `features/nodes/api.ts` |
| `proxy-route.service.ts` | `/api/proxy-routes` | `features/proxy-routes/api.ts` |
| `config-version.service.ts` | `/api/config-versions` | `features/config-versions/api.ts` |
| `waf.service.ts` | `/api/waf` | `features/waf/api.ts` |
| `website.service.ts` | `/api/managed-domains` | `features/websites/api.ts` |
| `tls-certificate.service.ts` | `/api/tls-certificates` | `features/tls-certificates/api.ts` |
| `dns-account.service.ts` | `/api/dns-accounts` | `features/dns-accounts/api.ts` |
| `acme-account.service.ts` | `/api/acme-accounts` | `features/acme-accounts/api.ts` |
| `pages.service.ts` | `/api/pages` | `features/pages/api.ts` |
| `origin.service.ts` | `/api/origins` | `features/origins/api.ts` |
| `access-log.service.ts` | `/api/access-logs` | `features/access-logs/api.ts` |
| `apply-log.service.ts` | `/api/apply-logs` | `features/apply-logs/api.ts` |
| `option.service.ts` | `/api/option` | `features/settings/api.ts` |
| `update.service.ts` | `/api/update` | `features/update/api.ts` |
| `types.ts` | — | 汇总 TypeScript 类型 |
### 7.2 服务注册
```typescript
// lib/services/index.ts 新增
import { openflareDashboardService } from './openflare/dashboard.service';
// ...
const services = {
// ... 现有 Wavelet 服务
openflareDashboard: openflareDashboardService,
openflareNode: openflareNodeService,
// ...
};
```
### 7.3 API 客户端适配
| 阶段 | 认证方式 | Base URL |
|---|---|---|
| 阶段一（过渡期） | Session Cookie（Wavelet 登录）+ 业务 API 同域 | `/api` |
| 阶段二（稳定） | Session + 可选 AccessToken | `/api` + `/api/v1` |
**注意**：移除 `OpenFlare-Token` localStorage 逻辑；统一使用 Wavelet `proxy.ts` 鉴权。
---
## 8. 组件复用与替换对照
### 8.1 旧 → Wavelet 组件映射
| 旧组件 | Wavelet 替代 |
|---|---|
| `app-card` | `Card` |
| `app-modal` | `Dialog` |
| `drawer` | `Sheet` |
| `input` | `Input` |
| `textarea` | `Textarea` |
| `switch` | `Switch` |
| `status-badge` | `Badge` |
| `theme-toggle` | 内置 ThemeProvider |
| `sonner` | `sonner`（已有） |
| `empty-state` | `components/common/empty.tsx` |
| `loading-state` | `Skeleton` + `loading.tsx` |
| `error-state` | `error.tsx` |
| `resource-primitives` | `Form` + `Field` + shadcn 表单模式 |
| `trend-chart` / `rank-chart` | Recharts 或 ECharts 封装 |
### 8.2 布局改造
| 项 | 旧实现 | 新实现 |
|---|---|---|
| 侧栏 | `dashboard-sidebar.tsx` | `components/layout/app-sidebar.tsx` 扩展 |
| 顶栏 | `dashboard-topbar.tsx` | `components/layout/header.tsx` 扩展 |
| 导航配置 | `lib/constants/navigation.ts` | `lib/navigation/openflare-nav.ts` |
| 鉴权守卫 | `DashboardAuthGuard` | Wavelet `proxy.ts` + `use-auth-redirect` |
**新侧栏导航结构**：
```
OpenFlare
├── 总览 /openflare
├── 节点 /openflare/nodes
├── 代理规则 /openflare/proxy-routes
├── 配置发布 /openflare/config-versions
├── WAF /openflare/waf
├── 网站 /openflare/websites
├── Pages /openflare/pages
├── 源站 /openflare/origins
├── 访问日志 /openflare/access-logs
├── 性能调优 /openflare/performance
---
平台（Wavelet 原生）
├── 用户管理 /admin/users
├── 系统设置 /admin/settings
├── 任务调度 /admin/tasks
├── 日志分析 /admin/logs
├── ...
```
---
## 9. 分阶段实施计划
### 阶段 0：基建（1 周）— ✅ 已完成
| 任务 ID | 任务 | 状态 |
|---|---|---|
| F0-1 | 创建 `lib/services/openflare/` 骨架 | ✅ `legacy-base.service.ts` + types |
| F0-2 | 创建 `lib/navigation/openflare-nav.ts` | ✅ |
| F0-3 | 扩展 `app-sidebar.tsx` | ✅ OpenFlare 导航组 |
| F0-4 | 确认 embed 构建方案 | ⏳ |
| F0-5 | 移除旧前端入口引用准备 | ⏳ |
### 阶段 1：认证与布局（1 周）
| 任务 ID | 任务 |
|---|---|
| F1-1 | 确认 Wavelet 登录/register 可用 |
| F1-2 | OAuth 回调路径配置 |
| F1-3 | 侧栏 + 顶栏 OpenFlare 品牌 |
| F1-4 | `/home` 重定向至 `/openflare` |
| F1-5 | 用户管理入口暴露至 `/admin/users` |
**验收**：Wavelet 登录后可看到 OpenFlare 空导航骨架。
### 阶段 2：核心链路 UI（2–3 周）— 进行中
| 任务 ID | 页面 | 状态 |
|---|---|---|
| F2-1 | 节点列表 + 详情（edge） | ✅ 列表 + Edge 详情 |
| F2-2 | 代理规则列表 + 详情 | ✅ 列表 + 6 Tab 骨架 |
| F2-3 | 配置发布 | ✅ |
| F2-4 | 应用日志 | ✅ |
| F2-5 | relay/tunnel 详情页 | ⏳ |
| F2-6 | 代理规则详情各 Section 表单实装 | ⏳ |
**验收**：UI 完成节点→规则→发布闭环操作。
### 阶段 3：安全与流量（2 周）
| 任务 ID | 页面 |
|---|---|
| F3-1 | WAF 规则组 |
| F3-2 | WAF IP 组 |
| F3-3 | 网站/域名 |
| F3-4 | TLS 证书 + ACME |
| F3-5 | DNS 账号 |
### 阶段 4：扩展（2 周）
| 任务 ID | 页面 |
|---|---|
| F4-1 | Pages 托管 |
| F4-2 | 源站 |
| F4-3 | 访问日志 |
| F4-4 | 总览仪表盘 |
| F4-5 | 性能调优 |
### 阶段 5：设置合并与收尾（1–2 周）
| 任务 ID | 任务 |
|---|---|
| F5-1 | OpenFlare 运维/系统设置并入 Admin |
| F5-2 | 服务升级 UI 对接 `admin/updater` |
| F5-3 | 废弃 `openflare-server/web` 引用 |
| F5-4 | Playwright E2E 核心路径 |
| F5-5 | 视觉走查与响应式适配 |
| F5-6 | Handover 文档 |
---
## 10. 旧前端源文件 → 新文件完整映射
| 旧文件 | 新文件 | 动作 |
|---|---|---|
| `features/dashboard/components/dashboard-page.tsx` | `openflare/page.tsx` | 重写 |
| `features/nodes/components/nodes-page.tsx` | `openflare/nodes/page.tsx` | 重写 |
| `features/nodes/components/node-detail-page.tsx` | `openflare/nodes/detail/components/edge-node-detail.tsx` | 拆分重写 |
| `features/nodes/components/relay-detail-page.tsx` | `openflare/nodes/detail/components/relay-node-detail.tsx` | 拆分重写 |
| `features/nodes/components/tunnel-detail-page.tsx` | `openflare/nodes/detail/components/tunnel-node-detail.tsx` | 拆分重写 |
| `features/nodes/components/node-editor-modal.tsx` | `openflare/nodes/components/node-form-dialog.tsx` | 重写 |
| `features/proxy-routes/components/proxy-routes-page.tsx` | `openflare/proxy-routes/page.tsx` | 重写 |
| `features/proxy-routes/components/proxy-route-config-page.tsx` | `openflare/proxy-routes/detail/page.tsx` + 6 section | 拆分重写 |
| `features/proxy-routes/components/proxy-route-create-drawer.tsx` | `openflare/proxy-routes/components/create-sheet.tsx` | 重写 |
| `features/config-versions/components/config-versions-page.tsx` | `openflare/config-versions/page.tsx` | 重写 |
| `features/waf/components/waf-page.tsx` | `openflare/waf/page.tsx` | 重写 |
| `features/waf/components/ip-groups-page.tsx` | `openflare/waf/ip-groups/page.tsx` | 重写 |
| `features/waf/components/rule-entry-modal.tsx` | `openflare/waf/components/rule-entry-dialog.tsx` | 重写 |
| `features/websites/components/websites-page.tsx` | `openflare/websites/page.tsx` | 重写 |
| `features/websites/components/website-detail-page.tsx` | `openflare/websites/detail/page.tsx` | 重写 |
| `features/tls-certificates/components/*.tsx` | `openflare/websites/certificates/components/*.tsx` | 重写 |
| `features/pages/components/pages-page.tsx` | `openflare/pages/page.tsx` | 重写 |
| `features/pages/components/pages-detail-page.tsx` | `openflare/pages/detail/page.tsx` | 重写 |
| `features/origins/components/origins-page.tsx` | `openflare/origins/page.tsx` | 重写 |
| `features/access-logs/components/access-logs-page.tsx` | `openflare/access-logs/page.tsx` | 重写 |
| `features/apply-logs/components/apply-logs-page.tsx` | `openflare/apply-logs/page.tsx` | 重写 |
| `features/performance/components/performance-page.tsx` | `openflare/performance/page.tsx` | 重写 |
| `features/settings/components/settings-page.tsx` | 拆入 `admin/settings` + `settings/*` | 拆分废弃 |
| `features/update/components/version-upgrade-modal.tsx` | 并入 `header` + `admin/updater` | 适配 |
| `features/auth/components/*.tsx` | — | **删除**，用 Wavelet |
| `features/users/components/*.tsx` | — | **删除**，用 `/admin/users` |
| `components/layout/dashboard-shell.tsx` | `components/layout/` Wavelet 布局 | 废弃 |
| `components/ui/*.tsx` | `components/ui/*.tsx` Wavelet | 废弃 |
| `lib/api/client.ts` | `lib/services/core/base.service.ts` | 废弃 |
| `store/app-shell.ts` | Wavelet 侧栏内置状态 | 废弃 |
---
## 11. 页面-API 完整依赖表（迁移后）
> 认证类 API 在阶段二切换至 `/api/v1/*`；业务 API 保持 `/api/*`。
| 新页面 | 依赖 API 端点 |
|---|---|
| `/openflare` | `GET /api/dashboard/overview` |
| `/openflare/nodes` | `GET/POST /api/nodes/`, `GET /api/nodes/bootstrap-token` |
| `/openflare/nodes/detail` | `GET/POST /api/nodes/:id/*`, `GET /api/nodes/:id/observability`, `GET /api/nodes/:id/agent-release` |
| `/openflare/proxy-routes` | `GET/POST /api/proxy-routes/*` |
| `/openflare/proxy-routes/detail` | 同上 + `GET /api/managed-domains/`, `GET /api/pages/`, `GET /api/tls-certificates/`, `GET/POST /api/waf/sites/:id/rule-groups`, `GET /api/config-versions/diff`, `POST /api/config-versions/publish` |
| `/openflare/config-versions` | `GET/POST /api/config-versions/*` |
| `/openflare/waf` | `GET/POST /api/waf/rule-groups/*`, `GET /api/proxy-routes/` |
| `/openflare/waf/ip-groups` | `GET/POST /api/waf/ip-groups/*` |
| `/openflare/websites` | `GET/POST /api/managed-domains/*` |
| `/openflare/websites/detail` | 同上 + `GET /api/proxy-routes/`, WAF 绑定 API |
| `/openflare/websites/certificates` | `GET/POST /api/tls-certificates/*`, `GET /api/acme-accounts/default` |
| `/openflare/websites/dns-accounts` | `GET/POST /api/dns-accounts/*` |
| `/openflare/pages` | `GET/POST /api/pages/*` |
| `/openflare/pages/detail` | 部署相关 `/api/pages/:id/deployments/*` |
| `/openflare/origins` | `GET/POST /api/origins/*` |
| `/openflare/access-logs` | `GET/POST /api/access-logs/*` |
| `/openflare/apply-logs` | `GET/POST /api/apply-logs/*` |
| `/openflare/performance` | `GET/POST /api/option/*`, `GET /api/config-versions/preview` |
| `/login` | `POST /api/v1/user/login`, Cap API |
| `/admin/users` | `/api/v1/admin/users/*` |
| `/settings/*` | `/api/v1/user/*` |
| `/admin/settings` | `/api/v1/admin/*` + `/api/option/*`（OpenFlare 扩展） |
| 顶栏升级 | `/api/update/*` 或 `/api/v1/admin/updater/*` |
---
## 12. 验证计划
### 12.1 开发验证
```bash
cd Wavelet/frontend
pnpm lint
pnpm build
pnpm dev # 联调 Wavelet api 进程
```
### 12.2 功能走查清单
| 场景 | 步骤 | 预期 |
|---|---|---|
| 登录 | Wavelet 登录页 | Session 建立，跳转 /openflare |
| 创建节点 | nodes → 创建 → 复制安装命令 | 节点上线 |
| 创建规则 | proxy-routes → 6 section 配置 | 保存成功 |
| 发布配置 | config-versions → diff → publish → activate | Agent 收到配置 |
| WAF 拦截 | waf → 创建规则组 → 绑定站点 | 规则生效 |
| 证书申请 | certificates → ACME | 证书签发 |
| Pages 部署 | pages → 上传 zip → 激活 | 部署成功 |
| 访问日志 | access-logs → 筛选/折叠 | 数据展示 |
| 用户管理 | admin/users | CRUD 正常 |
| 升级 | 顶栏检查更新 | WS 日志 + 升级成功 |
### 12.3 E2E 测试规划
| 测试文件 | 覆盖路径 |
|---|---|
| `e2e/openflare-auth.spec.ts` | 登录/登出 |
| `e2e/openflare-node.spec.ts` | 节点 CRUD |
| `e2e/openflare-proxy-route.spec.ts` | 规则 + 发布 |
| `e2e/openflare-waf.spec.ts` | WAF 规则组 |
---
## 13. 风险与缓解
| 风险 | 缓解 |
|---|---|
| 大文件拆分工作量大 | 按 section/tab 并行；参考 admin/database |
| ECharts → Recharts 世界地图 | 保留 ECharts 作为可选依赖 |
| 静态导出 vs SSR | 优先确认 `build:embed`；保留 `?id=` 查询参数路由 |
| 设置页 2400 行拆分遗漏 | 逐项对照 5 Tab 功能清单 |
| `/user` 无入口历史问题 | 统一纳入 `/admin/users` 侧栏 |
| 微信/OAuth 特殊流程 | 与后端 legacy 层同步验证 |
| 上传进度 | Pages 部署保留 XHR 进度；复用 Wavelet upload 基建 |
---
## 14. 里程碑
| 里程碑 | 时间 | 标志 |
|---|---|---|
| M1 布局就绪 | 第 1 周 | 导航 + 登录 + 空页面 |
| M2 核心 UI | 第 4 周 | 节点/规则/发布可用 |
| M3 安全流量 | 第 6 周 | WAF/证书/网站 |
| M4 全页面 | 第 8 周 | 全部 FC 页面完成 |
| M5 上线切换 | 第 10 周 | 废弃旧 web，embed 新前端 |
---
## 15. 与后端计划协同时间表
```mermaid
gantt
title OpenFlare 迁移协同
dateFormat YYYY-MM-DD
section 后端
基建与认证 :b0, 2026-06-18, 3w
核心链路 :b2, after b0, 3w
安全证书 :b3, after b2, 2w
扩展运维 :b4, after b3, 3w
section 前端
基建布局 :f0, 2026-07-02, 2w
核心UI :f2, after f0, 3w
安全流量UI :f3, after f2, 2w
扩展收尾 :f4, after f3, 3w
```
| 后端里程碑 | 前端可启动项 |
|---|---|
| M2 认证联调 | F1 认证与布局 |
| M3 核心链路 | F2 节点/规则/发布 |
| M4 安全证书 | F3 WAF/网站/证书 |
| M5 全量功能 | F4 仪表盘/日志/Pages |
---
## 16. 参考文档
- [`Wavelet/AGENTS.md`](../../Wavelet/AGENTS.md) — **开发前必读**
- [`docs/plan/20260618-openflare-wavelet-backend-migration.md`](./20260618-openflare-wavelet-backend-migration.md)
- Wavelet 标杆页面：`Wavelet/frontend/app/(main)/admin/database/`、`admin/demo/`
- 旧前端源码：`openflare-server/web/features/`
docs/plan/20260619-edge-phase3-tasks.md
-75
View File
@@ -1,75 +0,0 @@
# 边缘运行时 Phase 3 — 任务拆解
> **状态**：Batch 3 已完成（2026-06-19）
> **前置**：[边缘运行时重构设计](../design/edge-runtime-refactor.md) Phase 0–2 已完成
---
## 任务依赖图
```text
Batch 1（并行，互不影响）
├── T1 edge/config/duration.go
├── T2 edge/observability/linux.go
└── T3 edge/heartbeat/loop.go（仅 relay/flared）
Batch 2（串行，依赖 Batch 1 或需独立评审）
├── T4 Agent heartbeat 架构对齐（runner ↔ heartbeat service）
└── T5 agent/protocol → pkg/protocol（影响 Server 侧）
```
---
## Batch 1 — 并行任务
| ID | 任务 | 修改范围 | 风险 | 委派 |
| --- | --- | --- | --- | --- |
| **T1** | 抽取 `MillisecondDuration` | `edge/config/` + `agent/relay/flared/config` | 低 | ✅ 子代理 A |
| **T2** | 抽取 Linux 指标采集 | `edge/observability/` + `agent/relay/observability/collector.go` | 中 | ✅ 子代理 B |
| **T3** | 统一心跳 ticker 循环 | `edge/heartbeat/loop.go` + `relay/flared/heartbeat` | 低 | ✅ 子代理 C |
### 隔离规则
- **T1** 禁止修改 `heartbeat/`、`observability/`、`agent/runner.go`
- **T2** 禁止修改 `config/`、`heartbeat/`
- **T3** 禁止修改 `agent/` 任何文件（Agent 心跳留在 runner，Batch 2 处理）
---
## Batch 2 — 并行任务（已完成）
| ID | 任务 | 修改范围 | 状态 |
| --- | --- | --- | --- |
| **T4** | Agent heartbeat 架构对齐 | `heartbeat/cycle.go` + 精简 `agent/runner.go` | ✅ 子代理 D |
| **T5** | `agent/protocol` → `pkg/protocol` | `pkg/protocol/agent.go` + `protocol/alias.go` | ✅ 子代理 E |
---
## Batch 3 — 并行任务（已完成）
| ID | 任务 | 修改范围 | 状态 |
| --- | --- | --- | --- |
| **T6** | Server 侧协议统一 | `pkg/protocol/` + `internal/apps/openflare/{agent,relay,flared}/` | ✅ 子代理 F |
| **T7** | `wsclient` 收敛 | `edge/wsclient/` + 三组件 `wsclient/` 薄包装 | ✅ 子代理 G |
### T6 要点
- `openflare/agent` 的 `NodePayload`、观测类型、WAF 类型改为 `pkg/protocol` 别名
- 保留 Server 专有响应：`RegistrationResponse`（`access_token`）、`HeartbeatResponse`（含 `*model.OpenFlareNode`）
- `openflare/relay`、`openflare/flared` 心跳/配置载荷改为 `pkg/protocol` 别名
### T7 要点
- 新增 `internal/apps/edge/wsclient/`，配置表驱动（HeaderKey + WSPath）
- Agent 保留 `SendStatus` + `protocol.WebSocketConnection` 适配
- relay/flared/agent 的 `wsclient/` 仅保留 `New()` 工厂
---
## 验收标准
```bash
go build ./cmd/agent ./cmd/relay ./cmd/flared
go test ./internal/apps/edge/... ./internal/apps/agent/... ./internal/apps/relay/... ./internal/apps/flared/... ./internal/apps/openflare/... ./pkg/protocol/... -count=1
make code-check
```
docs/plan/handover-docs-restructure-update.md
-53
View File
@@ -1,53 +0,0 @@
# 文档更新 — AI 接手文档
> **状态**：已完成（2026-06-19）
> **背景**：`openflare-server/` 子目录已删除，项目收敛为 monorepo；后端迁移至 Wavelet 框架，前端迁移至 `frontend/`
> **触发**：多智能体并行分析后批量更新文档
---
## 1. 分析结论摘要
| 维度 | 主要变化 |
| --- | --- |
| 仓库形态 | 单 monorepo（`github.com/Rain-kl/Wavelet`），无 `openflare-server/` 子目录 |
| Server 入口 | `main.go` + `internal/cmd/`，非 `cmd/server/` |
| 后端分层 | `internal/apps/*/routers.go` + `logics.go`，非 `controller/service` |
| 管理 API | `/api/v1/d/*`，Session Cookie 鉴权，非 `OPENFLARE_TOKEN` |
| 边缘 API | `/api/v1/agent|relay|tunnel/*` |
| 前端 | `frontend/`，路由共置于 `app/(main)/`，非 `features/store` |
| 配置 | `config.yaml` + `APP_*`/`DB_*` 环境变量，非 `JWT_SECRET`/`DSN` |
## 2. 已更新文档（P0）
| 文件 | 更新内容 |
| --- | --- |
| `docs/design/index.md` | 重写 §仓库结构（monorepo、Wavelet 分层、API 前缀、Frontend 结构） |
| `docs/design/architecture.md` | Server 描述、鉴权方式、启动入口 |
| `docs/design/agent-design.md` | Agent API 路径 `/api/v1/agent/*` |
| `docs/reference/cli.md` | 全部命令改为仓库根目录执行 |
| `docs/reference/index.md` | 仓库结构描述 |
| `docs/deployment/deployment.md` | Compose、源码启动、配置变量 |
| `docs/deployment/server.md` | 前端构建路径、启动命令、环境变量 |
| `docs/deployment/openflared.md` | Tunnel API 路径、编译命令 |
| `docs/deployment/relay.md` | 编译命令 |
| `docs/deployment/agent.md` | 源码构建路径 |
| `docs/guideline/Constraints.md` | **新建**，消除全站断链 |
| `AGENTS.md` | 修正 skill/demo 路径 |
| `README.md` | 快速开始指向根目录 compose |
## 3. 待跟进（P1）
- [ ] `docs/reference/configuration.md` — 与 `config.example.yaml` / `.env.example` 对齐
- [ ] `docs/guide/quick-start.md`、`troubleshooting.md` — 鉴权与路径修正
- [ ] `docs/deployment/server.md` — Docker Compose 示例段落（后半部分仍有过时内容）
- [ ] `docs/DEPLOYMENT.md` — Wavelet 脚手架残留
- [ ] `docs/design/tunnel-design.md`、`pages-design.md` — API 前缀统一
- [ ] `docs/changelog/index.md` — JWT_SECRET 声明与代码对齐
- [ ] `docs/en/**` — 英文镜像同步（低优先级）
## 4. 文档维护原则
1. **单一事实来源**：配置以 `config.example.yaml` + `.env.example` 为准；目录以 `docs/design/index.md` 为准；API 以 `make swagger` 为准。
2. **禁止再引用**：`openflare-server/`、`OPENFLARE_TOKEN`、`JWT_SECRET`（除非代码重新引入）。
3. **中英文分工**：功能变更先更新中文文档；英文可标记待同步。
docs/plan/handover-openflare-backend-migration.md
-227
View File
@@ -1,227 +0,0 @@
# OpenFlare 后端迁移 — AI 接手文档
> **状态**：进行中（阶段 5 收尾）
> **主线**：`openflare-server` 业务域已迁入 `Wavelet/internal/apps/openflare/`；管理控制台走 `/api/v1/d/*` + `Wavelet/frontend`；节点协议走 `/api/v1/agent|relay|tunnel/*`
> **关联计划**：[实现计划](./20260618-openflare-wavelet-backend-migration.md)
---
## 1. 当前任务状态
### 主线任务
将 OpenFlare 控制面后端从 `openflare-server` 迁移至 Wavelet 框架，复用 Wavelet 用户/OAuth/Cap 等平台能力，并完成 Agent/Relay/Tunnel 协议兼容。
**架构现状（2026-06-19）**：原计划「阶段一 `/api/*` legacy 层 + 旧前端联调」已在 v1 路径切换时撤销。`internal/apps/openflare/legacy/`、`compat/auth.go` 已删除；`openflare-server/web` 不再能对接当前 Wavelet 后端。
### 开发分支
- 分支：`dev`
- 参考对照：旧后端 `openflare-server/`（待 ETL 验证后归档）
### 已完成（✅）
- [x] **业务模块 T-OPTION ~ T-MISC**：14 个 OpenFlare 业务包 + `internal/router/v1/openflare/register_*.go`
- [x] **goose 迁移** `202606190001` ~ `202606190014`（PostgreSQL + SQLite 双份）
- [x] **可观测性 v1 单表**：无 `_00`~`_09` 分片；heartbeat 持久化、访问日志查询、Relay/Tunnel 观测
- [x] **后台任务**：已迁入 Wavelet Asynq（`async_tasks.go` + `202606190013` 种子）
- [x] **TLS ACME** 申请/续期（lego DNS-01）
- [x] **集成测试** 4 个场景包全部通过（23 用例）
- [x] **配置默认值**：DB 名 `openflare`、监听 `:3000`、`application_name=openflare-server`、Redis 前缀 `openflare:`
- [x] **API 路径统一**：控制台 `/api/v1/d/*`；协议 `/api/v1/agent|relay|tunnel/*`；Swagger 约 99 端点
### 进行中（阶段 5）
- [/] **B5-3** 旧环境数据迁移脚本 `support-files/migration/`（用户 + 业务表 ETL，含 10 分片观测数据合并）
- [/] **B5-4** `make swagger` + `make code-check` 全绿
- [/] **B5-5** 全量 API 回归（对照实现计划 §12 端点表）
### 待处理
- [ ] 生产环境：创建并**激活** config version，消除节点列表「异常」（`openresty_status=unhealthy` + `当前没有激活版本`）
- [ ] 归档 `openflare-server/` 整包（ETL 与回归通过后）
---
## 2. 任务队列（委派状态）
| ID | 板块 | 状态 | 负责目录 |
|---|---|---|---|
| T-AUTH | 认证/用户/OAuth/Cap | ✅ | Wavelet `apps/user`、`apps/oauth`、`apps/cap`、`apps/admin`（无独立 legacy 包） |
| T-OPTION | 状态/公告/Option | ✅ | `openflare/option/`，`register_option.go` |
| T-ORIGIN | 源站 | ✅ | `openflare/origin/`，`register_origin.go` |
| T-APPLYLOG | 应用日志 | ✅ | `openflare/apply_log/`，`register_apply_log.go` |
| T-PROXY | 代理规则 | ✅ | `openflare/proxy_route/`，`register_proxy_route.go` |
| T-NODE | 节点管理 | ✅ | `openflare/node/`，`register_node.go` |
| T-WAF | WAF | ✅ | `openflare/waf/`，`register_waf.go` |
| T-TLS | TLS/证书/域名/DNS | ✅ | `openflare/tls/`，`register_tls.go` |
| T-CFGVER | 配置版本 | ✅ | `openflare/config_version/`，`register_config_version.go` |
| T-AGENT | Agent API + WS | ✅ | `openflare/agent/`，`register_agent.go` |
| T-PAGES | Pages 托管 | ✅ | `openflare/pages/`，`register_pages.go` |
| T-RELAY | Relay + Tunnel | ✅ | `openflare/relay/`、`openflare/flared/`，`register_relay_flared.go` |
| T-OBS | 仪表盘 + 可观测 | ✅ | `openflare/dashboard/`、`openflare/observability/`，`register_dashboard.go`、`register_observability.go` |
| T-MISC | 升级/GeoIP/UptimeKuma | ✅ | `openflare/update/`、`openflare/geoip/`、`openflare/uptimekuma/`，`register_update.go`、`register_option.go` |
### 任务隔离规则
| 规则 | 说明 |
|---|---|
| 文件所有权 | 每个任务 **仅修改** 自己的 `internal/apps/openflare/<module>/`、对应 `router/v1/openflare/register_<module>.go`、`internal/model/openflare_<module>.go`、goose SQL |
| 禁止修改 | `v1/user.go`、`v1/admin.go`、`model/users.go`、其他任务的 `register_*.go` |
| 控制台响应格式 | `{error_msg, data}` + `response.Abort*`（Wavelet 标准） |
| 协议响应格式 | `compat.OK/Fail`（`{success, message, data}`），供 Agent/Relay/Tunnel 二进制使用 |
| 控制台鉴权 | `apiutil.AdminRequired()`（Session / `X-Access-Token`，`user.IsAdmin` + `token_admin`） |
| Logic 层 | `logics.go` 使用 `context.Context`，不依赖 `*gin.Context` |
| 数据源 | `db.DB(ctx)` 获取 GORM |
| 质量门禁 | 完成后 `go build ./...` 并通过本模块测试 |
---
## 3. 核心文件与上下文
### 路由注册
| 路径 | 职责 |
|---|---|
| `Wavelet/internal/router/router.go` | `apiGroup` → `v1.RegisterV1Routes` |
| `Wavelet/internal/router/v1/v1.go` | 汇总 User/Admin/OpenFlare 路由 |
| `Wavelet/internal/router/v1/openflare/v1.go` | `RegisterV1Routes` → `/api/v1/d/*` 控制台 |
| `Wavelet/internal/router/v1/openflare/openflare.go` | `RegisterRoutes` → `/api/v1/agent|relay|tunnel/*` 协议 |
| `Wavelet/internal/router/v1/openflare/register_*.go` | 各资源路由挂载 |
| `Wavelet/internal/apps/openflare/*/routers.go` | Handler + Swagger 注解 |
| `Wavelet/internal/apps/openflare/compat/response.go` | 协议层 legacy 信封（**仅** Agent/Relay/Tunnel） |
| `Wavelet/internal/apps/openflare/apiutil/` | 控制台 BindJSON、AdminRequired、RegisterCollection |
### 后台任务（Asynq）
| 任务名 | 说明 |
|---|---|
| `openflare:database_auto_cleanup` | 可观测数据自动清理（受 Option 开关控制） |
| `openflare:waf_ip_group_sync` | WAF IP 组周期同步 |
| `openflare:uptime_kuma_sync` | UptimeKuma 同步 |
| `openflare:ssl_renew` | ACME 证书自动续期 |
**启动链路**：`wavelet api` / `wavelet all` → `bootstrap.Init` → Asynq worker/scheduler 执行；任务定义见 `async_tasks.go`，调度种子见 `202606190013`。
### 数据库迁移
| 版本 | 内容 |
|---|---|
| `202606190001` | `of_options` |
| `202606190002` | `of_origins` |
| `202606190003` | `of_apply_logs` |
| `202606190004` | `of_proxy_routes` |
| `202606190005` | `of_nodes` |
| `202606190006` | `of_waf_*` |
| `202606190007` | `of_tls_*` |
| `202606190008` | `of_config_versions` |
| `202606190009` | `of_pages_*` |
| `202606190010` | 可观测性单表 |
| `202606190011` | `of_node_access_logs` 复合索引 |
| `202606190012` | `of_node_obs_frpc` |
| `202606190013` | OpenFlare Asynq 调度种子 |
| `202606190014` | Pages `upload_id` 字段 |
路径：`Wavelet/internal/db/migrator/goose/postgres/` 与 `sqlite/` 各一份。
### 近期修复要点（2026-06-19）
| 问题 | 根因 | 修复/处理 |
|---|---|---|
| Agent 已连接但节点显示「异常」 | 无激活 config version | 运维：发布并激活配置版本 |
| 节点详情无错误日志 | 可观测性表未迁移 | `202606190010` + `agent/observability.go` |
| WAF IP 组未下发 | Agent sync 未实装 | `agent/waf_ip_group.go`、`waf/ip_group_sync.go` |
| Pages 包下载 404 | Agent 路由缺失 | `pages/logics.go`、`agent/routers.go` |
| 访问日志查询空 | 单表查询层缺失 | `model/openflare_access_log.go`、`202606190011` |
| Relay/Tunnel 观测缺失 | heartbeat 未持久化 | `relay/observability.go`、`flared/observability.go`、`202606190012` |
### 依赖修复
`replace github.com/rain-kl/openflare => ../` 会引入根 `go.mod` 的 `gomodule/redigo v2.0.0+incompatible`，与 `gin-contrib/sessions/redistore` 不兼容。已在 `Wavelet/go.mod` 添加 `exclude` 并锁定 `redigo v1.9.3`。
---
## 4. 集成测试
| 测试包 | 场景 | 结果 |
|---|---|---|
| `integration/auth_option_test.go` | Access Token 鉴权、option 权限、热重载 | ✅ 5/5 |
| `integration/core_chain_test.go` | 源站→规则→发布→节点→apply-log | ✅ 6/6 |
| `integration/security_test.go` | WAF/TLS/域名/DNS | ✅ 7/7 |
| `integration/agent_protocol_test.go` | Agent/Relay/Tunnel 协议 | ✅ 5/5 |
```bash
cd Wavelet
go test ./internal/apps/openflare/... -count=1
go build ./...
```
---
## 5. 本地启动（Wavelet 后端）
### 配置
复制 `Wavelet/config.example.yaml` → `config.yaml`，关键项：
```yaml
app:
app_name: "openflare"
addr: ":3000"
database:
enabled: true
database: "openflare"
application_name: "openflare-server"
redis:
key_prefix: "openflare:"
```
### 启动命令
```bash
cd Wavelet
go run . all # 开发：API + Worker + Scheduler
go run . api # 生产：API 进程
go run . worker
go run . scheduler
```
### 当前联调方式
- **管理控制台**：`Wavelet/frontend`（`pnpm dev` 或 embed 构建产物），Session 鉴权，API 前缀 `/api/v1/d/*`
- **节点二进制**：连接 `/api/v1/agent/*`、`/api/v1/relay/*`、`/api/v1/tunnel/*`（legacy `{success,message,data}` 信封）
- **旧前端 `openflare-server/web`**：已无法对接当前后端（无 `/api/*` 控制台路由、无 `OpenFlare-Token` 桥接）
---
## 6. 待决策与遗留问题
| 项 | 说明 | 当前处理 |
|---|---|---|
| 观测数据 10 分片 → 单表 | 旧生产环境有 `node_*_XX` 分片表 | v1 单表；B5-3 ETL 脚本待建 |
| 微信登录 | Wavelet 无内置 | 旧 `/api/oauth/wechat*` 未保留；评估废弃或补 v1 适配 |
| 三级角色 Root(100) | 旧 `RootAuth` | 简化为 `is_admin` + Access Token `token_admin` |
| 节点「异常」展示 | 连接正常但无激活版本 | 属预期行为；需运维发布配置 |
| `make code-check` | 全仓库静态检查 | 阶段 5 待跑通 |
---
## 7. 下一步行动指南
1. **确认环境**：`cd Wavelet && go build ./... && go test ./internal/apps/openflare/... -count=1`
2. **跑质量门禁**：`make code-check`
3. **实现 B5-3**：`Wavelet/support-files/migration/` ETL 脚本
4. **API 回归**：对照实现计划 §12 端点表逐项验证
5. **联调验证**：`Wavelet/frontend` 登录 → 创建规则 → 发布并**激活** config version → Agent 心跳 → 检查节点状态
---
## 8. 参考文档
| 文档 | 用途 |
|---|---|
| [实现计划](./20260618-openflare-wavelet-backend-migration.md) | 模块清单、§12 端点对照 |
| [前端迁移计划](./20260618-openflare-wavelet-frontend-migration.md) | UI 迁移与验收 |
| [`Wavelet/AGENTS.md`](../../Wavelet/AGENTS.md) | 框架 Guardrails |
| 旧后端源码（对照用） | `openflare-server/internal/` |
| Changelog | [`docs/changelog/index.md`](../changelog/index.md) `[Unreleased]` |
docs/plan/handover-openflare-frontend-migration.md
-53
View File
@@ -1,53 +0,0 @@
# OpenFlare 前端迁移 — 任务拆分与 AI 委派
> **状态**：✅ 迁移完成（多角度验证通过；P2 可选打磨待办）
> **目标前端**：`Wavelet/frontend/`（Next.js 16 + shadcn/ui + Session 鉴权）
> **验证报告**：[`verify-frontend-routes.md`](./verify-frontend-routes.md)、[`verify-frontend-services.md`](./verify-frontend-services.md)、[`verify-frontend-ui.md`](./verify-frontend-ui.md)、[`verify-frontend-build.md`](./verify-frontend-build.md)
## 任务队列
| ID | 板块 | 状态 |
|---|---|---|
| F0 | 基建 | ✅ |
| F-NODE | 节点（含 Relay/Tunnel 详情） | ✅ |
| F-PROXY | 代理规则（含 6 Section 实装） | ✅ |
| F-CFG | 配置发布 + 应用日志 | ✅ |
| F-DASH | 总览仪表盘 | ✅（缺世界地图，P2） |
| F-WAF | WAF 规则组 + IP 组 | ✅ |
| F-WEB | 网站/证书/DNS | ✅ |
| F-PAGES | Pages 托管 | ✅ |
| F-ORIGIN | 源站 | ✅ |
| F-LOGS | 访问日志 | ✅ |
| F-PERF | 性能调优 | ✅ |
| F-ADMIN | Admin 运维设置扩展 | ✅ |
| F-AUTH | Wavelet 登录/用户复用 | ✅（原生，未改登录页） |
| F-ABOUT | About 页（FC-20） | ✅ |
| F-UPDATE | 服务升级 UI + UpdateService | ✅ |
## 验证结果摘要
| 门禁 | 结果 |
|---|---|
| `tsc --noEmit` | ✅ |
| `pnpm lint` | ✅ |
| `pnpm build:embed` | ✅（47 静态页） |
| 路由覆盖 FC-1~20 | ✅ 20/20 文件（FC-1 世界地图 P2） |
| Service 覆盖 | ✅ 100% |
| UI 规范 | ✅ PASS |
## P2 可选待办
1. **FC-1** 世界地图（当前用 geo 列表）
2. **UI 打磨** — proxy 列表 error 态、access-logs cleanup Zod、node-observability error
3. **废弃旧前端** — 移除 `openflare-server/web` 引用（阶段五）
4. **E2E** — Playwright 核心路径
## 验收命令
```bash
cd Wavelet/frontend
pnpm exec tsc --noEmit
pnpm lint
pnpm build:embed
pnpm dev
```
docs/plan/of-options-migration.md
-191
View File
@@ -1,191 +0,0 @@
# of_options 迁移到 w_system_configs 方案
## 背景
当前 OpenFlare 使用 `of_options` 表存储系统配置，维护了独立的 OptionMap 内存缓存和热重载机制。为了统一配置管理框架，需要将所有配置迁移到标准的 `w_system_configs` 表，复用现有的 SystemConfig 读取 API 和 Redis 缓存机制。
## 配置项分类
### 已存在于 w_system_configs，无需迁移
以下配置在新系统中已存在，不从 of_options 迁移：
- `PasswordLoginEnabled` → `password_login_enabled` (已存在)
- `CapLoginEnabled` → `cap_login_enabled` (已存在)
- `PasswordRegisterEnabled` → `password_register_enabled` (已存在)
- `EmailVerificationEnabled` → 映射到 `email_login_verification_enabled` (已存在)
- `ServerAddress` → `server_address` (已存在)
- `SMTPServer` → `smtp_host` (已存在，字段名不同)
- `SMTPPort` → `smtp_port` (已存在)
- `SMTPAccount` → `smtp_username` (已存在，字段名不同)
- `SMTPToken` → `smtp_password` (已存在，字段名不同)
### 旧系统冗余配置，直接删除
以下配置是旧系统遗留，当前系统不使用，不迁移：
- `SystemName` - 前端不再使用系统名称配置
- `Footer` - 前端不再使用页脚 HTML
- `HomePageLink` - 前端不再使用首页链接
- `About` - 前端不再使用关于信息
### 需要迁移的配置（全部 type=business）
**所有迁移的配置都设为 business 类型**。system 类型仅用于框架级配置（如 upload_allowed_extensions、disk_cache_max_size_mb 等）。
#### Agent 相关配置 (business, visibility=0)
| 原 Key (PascalCase) | 新 Key (snake_case) | 默认值 | 说明 |
|---------------------|---------------------|--------|------|
| AgentDiscoveryToken | agent_discovery_token | "" | Agent 发现令牌（敏感） |
| AgentHeartbeatInterval | agent_heartbeat_interval | 10000 | Agent 心跳间隔（毫秒） |
| AgentWebsocketUpgradeEnabled | agent_websocket_upgrade_enabled | true | Agent WebSocket 升级开关 |
| NodeOfflineThreshold | node_offline_threshold | 120000 | 节点离线阈值（毫秒） |
| AgentUpdateRepo | agent_update_repo | Rain-kl/OpenFlare | Agent 更新仓库 |
#### 系统功能配置 (business, visibility=0)
| 原 Key (PascalCase) | 新 Key (snake_case) | 默认值 | 说明 |
|---------------------|---------------------|--------|------|
| GeoIPProvider | geoip_provider | ipinfo | GeoIP 服务商 |
| DatabaseAutoCleanupEnabled | database_auto_cleanup_enabled | false | 数据库自动清理开关 |
| DatabaseAutoCleanupRetentionDays | database_auto_cleanup_retention_days | 30 | 数据库保留天数 |
#### UptimeKuma 集成配置 (business, visibility=0)
| 原 Key (PascalCase) | 新 Key (snake_case) | 默认值 | 说明 |
|---------------------|---------------------|--------|------|
| UptimeKumaEnabled | uptime_kuma_enabled | false | UptimeKuma 集成开关 |
| UptimeKumaUrl | uptime_kuma_url | "" | UptimeKuma URL |
| UptimeKumaUsername | uptime_kuma_username | "" | UptimeKuma 用户名 |
| UptimeKumaPassword | uptime_kuma_password | "" | UptimeKuma 密码（敏感） |
| UptimeKumaMonitorScope | uptime_kuma_monitor_scope | all | UptimeKuma 监控范围 |
| UptimeKumaSelectedSites | uptime_kuma_selected_sites | "" | UptimeKuma 选定站点 |
| UptimeKumaSyncInterval | uptime_kuma_sync_interval | 5 | UptimeKuma 同步间隔（分钟） |
| UptimeKumaInterval | uptime_kuma_interval | 60 | UptimeKuma 监控间隔（秒） |
| UptimeKumaRetry | uptime_kuma_retry | 0 | UptimeKuma 重试次数 |
| UptimeKumaRetryInterval | uptime_kuma_retry_interval | 60 | UptimeKuma 重试间隔（秒） |
| UptimeKumaTimeout | uptime_kuma_timeout | 48 | UptimeKuma 超时（秒） |
### OpenResty 配置 (type=business)
OpenResty 反向代理和缓存配置，全部为 business 类型，visibility=0：
| 原 Key (PascalCase) | 新 Key (snake_case) | 默认值 |
|---------------------|---------------------|--------|
| OpenRestyDefaultServerReturnStatus | openresty_default_server_return_status | 421 |
| OpenRestyWorkerProcesses | openresty_worker_processes | auto |
| OpenRestyWorkerConnections | openresty_worker_connections | 4096 |
| OpenRestyWorkerRlimitNofile | openresty_worker_rlimit_nofile | 65535 |
| OpenRestyEventsUse | openresty_events_use | epoll |
| OpenRestyEventsMultiAcceptEnabled | openresty_events_multi_accept_enabled | true |
| OpenRestyKeepaliveTimeout | openresty_keepalive_timeout | 20 |
| OpenRestyKeepaliveRequests | openresty_keepalive_requests | 1000 |
| OpenRestyClientHeaderTimeout | openresty_client_header_timeout | 15 |
| OpenRestyClientBodyTimeout | openresty_client_body_timeout | 15 |
| OpenRestyClientMaxBodySize | openresty_client_max_body_size | 64m |
| OpenRestyLargeClientHeaderBuffers | openresty_large_client_header_buffers | 4 16k |
| OpenRestySendTimeout | openresty_send_timeout | 30 |
| OpenRestyResolvers | openresty_resolvers | "" |
| OpenRestyProxyConnectTimeout | openresty_proxy_connect_timeout | 3 |
| OpenRestyProxySendTimeout | openresty_proxy_send_timeout | 60 |
| OpenRestyProxyReadTimeout | openresty_proxy_read_timeout | 60 |
| OpenRestyWebsocketEnabled | openresty_websocket_enabled | true |
| OpenRestyHTTP3Enabled | openresty_http3_enabled | true |
| OpenRestyProxyRequestBufferingEnabled | openresty_proxy_request_buffering_enabled | false |
| OpenRestyProxyBufferingEnabled | openresty_proxy_buffering_enabled | true |
| OpenRestyProxyBuffers | openresty_proxy_buffers | 16 16k |
| OpenRestyProxyBufferSize | openresty_proxy_buffer_size | 8k |
| OpenRestyProxyBusyBuffersSize | openresty_proxy_busy_buffers_size | 64k |
| OpenRestyGzipEnabled | openresty_gzip_enabled | true |
| OpenRestyGzipMinLength | openresty_gzip_min_length | 1024 |
| OpenRestyGzipCompLevel | openresty_gzip_comp_level | 5 |
| OpenRestyCacheEnabled | openresty_cache_enabled | false |
| OpenRestyCachePath | openresty_cache_path | "" |
| OpenRestyCacheLevels | openresty_cache_levels | 1:2 |
| OpenRestyCacheInactive | openresty_cache_inactive | 30m |
| OpenRestyCacheMaxSize | openresty_cache_max_size | 1g |
| OpenRestyCacheKeyTemplate | openresty_cache_key_template | $scheme$host$request_uri |
| OpenRestyCacheLockEnabled | openresty_cache_lock_enabled | true |
| OpenRestyCacheLockTimeout | openresty_cache_lock_timeout | 5s |
| OpenRestyCacheUseStale | openresty_cache_use_stale | error timeout updating http_500... |
| OpenRestyMainConfigTemplate | openresty_main_config_template | (长模板) |
**总计**：约 58 个配置需要迁移，全部为 business 类型。
## 迁移策略
### 1. 保持向后兼容
- 在迁移期间同时支持旧 API (`/api/v1/openflare/options`) 和新 API (`/api/v1/admin/system-configs`)
- 旧 API 内部委派到 SystemConfig 读写，不再直接操作 of_options 表
- 保留 `/api/v1/openflare/status` 接口，但从 SystemConfig 读取数据
### 2. 数据迁移顺序
1. 创建新的 ConfigKey 常量（已完成）
2. 创建 goose 迁移脚本，将 of_options 真正需要的配置复制到 w_system_configs（已完成）
3. 重构代码使用 repository.GetSystemConfigByKey / GetBoolByKey / GetIntByKey
4. 标记 of_options 表为 deprecated（保留一段时间用于回滚）
5. 后续版本完全删除 of_options 相关代码
### 3. 配置类型说明
**所有从 of_options 迁移的配置都设为 business 类型**：
- `type='business'`：业务配置，影响业务规则和功能行为
- `type='system'`：框架配置，仅用于框架级设置（如 upload_allowed_extensions、disk_cache_max_size_mb）
**不迁移的配置**：
- 已存在于 w_system_configs 的配置（如 password_login_enabled、smtp_host）
- 旧系统冗余配置（SystemName、Footer、HomePageLink、About）
### 4. 包级变量处理
原 `openflare_option.go` 中的包级变量（如 `SystemName`、`PasswordLoginEnabled`）将被移除。所有读取改为：
```go
// 旧方式（包级变量）
systemName := model.SystemName
enabled := model.PasswordLoginEnabled
// 新方式（repository 读取）
systemName, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeySystemName)
enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyPasswordLoginEnabled)
```
注意：对于已存在的配置，使用对应的新 key：
```go
// 已存在的配置使用现有 key
enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyPasswordLoginEnabled) // 不是 ConfigKeySystemName
```
### 5. 热重载机制
- 移除 `InitOptionMap` 和 `OptionMapRWMutex`
- SystemConfig 已通过 Redis 缓存实现热重载，更新后自动失效
## 实现步骤
1. ✅ 分析配置项并设计迁移方案（本文档）
2. 在 `system_configs.go` 添加所有 ConfigKey 常量
3. 创建 goose 迁移脚本（PostgreSQL + SQLite）
4. 重构所有业务代码使用 SystemConfig API
5. 更新 option 模块 API 和测试
6. 清理 of_options 遗留代码并验证
## 风险与注意事项
1. **敏感配置处理**：包含 Token/Password/Secret 的配置不应暴露给前端（visibility=0）
2. **类型转换**：of_options 将数值存为字符串，需要在读取时正确转换
3. **默认值一致性**：确保 SQL 迁移中的默认值与代码中的默认值一致
4. **模板配置**：`OpenRestyMainConfigTemplate` 是长文本，需要正确处理
5. **测试覆盖**：所有使用 OptionMap 的测试需要更新为使用 SystemConfig
## 后续清理计划
迁移完成后，在下一个主版本（如 v2.0）中完全移除：
- `internal/model/openflare_option.go`
- `internal/model/openflare_option_apply.go`
- `of_options` 表及相关迁移文件
- `internal/apps/openflare/option` 模块（或重构为 SystemConfig 的代理）
docs/plan/verify-frontend-build.md
-138
View File
@@ -1,138 +0,0 @@
# Wavelet Frontend Build Verification
**Date:** 2026-06-18
**Directory:** `/Users/ryan/DEV/Go/OpenFlare/Wavelet/frontend`
**Node/Next:** Next.js 16.2.7 (Turbopack)
## Summary
| Gate | Command | Exit Code | Result |
|------|---------|-----------|--------|
| TypeScript | `pnpm exec tsc --noEmit` | **0** | ✅ Pass |
| Lint | `pnpm lint` | **0** | ✅ Pass |
| Production build | `pnpm build:embed` | **0** | ✅ Pass |
**Overall:** All three gates pass. Static export completed with **47/47** pages generated.
---
## 1. TypeScript (`pnpm exec tsc --noEmit`)
- **Exit code:** `0`
- **Duration:** ~16.2s
- **Errors:** None
- **Warnings:** None
---
## 2. ESLint (`pnpm lint`)
- **Exit code:** `0`
- **Duration:** ~24.4s
- **Command:** `eslint` (no extra args)
- **Errors:** None
- **Warnings:** None
---
## 3. Production Build (`pnpm build:embed`)
**Production target:** `build:embed` — sets `NEXT_STANDALONE_EXPORT=true`, which enables `output: 'export'` in `next.config.ts` for static export embedded in the Go backend.
- **Exit code:** `0`
- **Duration:** ~72s (compile ~44s, TypeScript check ~20.1s, static generation ~2.2s)
### Build progress
- ✅ Compiled successfully
- ✅ TypeScript check passed during build
- ✅ Static page generation completed at **47/47** pages
### Warnings
```
⚠ Statically exporting a Next.js application via `next export` disables API routes and middleware.
This command is meant for static-only hosts, and is not necessary to make your application static.
Pages in your application without server-side data dependencies will be automatically statically exported by `next build`, including pages powered by `getStaticProps`.
Learn more: https://nextjs.org/docs/messages/api-routes-static-export
```
### Static pages (47 routes)
| Route |
|-------|
| `/` |
| `/_not-found` |
| `/admin/database` |
| `/admin/demo` |
| `/admin/files` |
| `/admin/logs` |
| `/admin/push` |
| `/admin/settings` |
| `/admin/system` |
| `/admin/tasks` |
| `/admin/users` |
| `/docs/api` |
| `/docs/how-to-use` |
| `/docs/privacy-policy` |
| `/docs/terms-of-service` |
| `/files` |
| `/home` |
| `/icon` |
| `/login` |
| `/openflare` |
| `/openflare/about` |
| `/openflare/access-logs` |
| `/openflare/apply-logs` |
| `/openflare/config-versions` |
| `/openflare/nodes` |
| `/openflare/nodes/detail` |
| `/openflare/origins` |
| `/openflare/origins/detail` |
| `/openflare/pages` |
| `/openflare/pages/detail` |
| `/openflare/performance` |
| `/openflare/proxy-routes` |
| `/openflare/proxy-routes/detail` |
| `/openflare/waf` |
| `/openflare/waf/ip-groups` |
| `/openflare/websites` |
| `/openflare/websites/certificates` |
| `/openflare/websites/detail` |
| `/openflare/websites/dns-accounts` |
| `/register` |
| `/settings` |
| `/settings/access-token` |
| `/settings/appearance` |
| `/settings/notifications` |
| `/settings/profile` |
| `/settings/security` |
All routes prerendered as static content (`○`). Middleware proxy is present but not exported in static mode (expected).
---
## Notes
- Initial `pnpm build:embed` attempt failed with "Another next build process is already running" due to a stale `.next/lock` from a concurrent build. Lock cleared and build re-run successfully.
- Previous verification on this date documented a `useSearchParams()` / missing `Suspense` failure on `/openflare/nodes`. That issue is no longer present in the current tree.
---
## CI Gate (recommended)
Run all three checks before merge:
```bash
cd Wavelet/frontend
pnpm exec tsc --noEmit
pnpm lint
pnpm build:embed
```
---
## Actions Taken
- Ran all three verification commands on 2026-06-18.
- No code changes applied; documentation updated with results.
docs/plan/verify-frontend-routes.md
-50
View File
@@ -1,50 +0,0 @@
# OpenFlare 前端路由验证报告
> **验证日期**：2026-06-18（复验）
> **对照**：`20260618-openflare-wavelet-frontend-migration.md` §6.1（FC-1 ~ FC-20）
> **扫描路径**：`Wavelet/frontend/app/(main)/openflare/**/page.tsx`
## 摘要
| 指标 | 结果 |
|---|---|
| 计划路由数（FC-1 ~ FC-20） | 20 |
| `page.tsx` 文件数 | 20 |
| **路由文件覆盖率** | **100%** |
| **严格完成**（路由存在且非占位） | **19/20（95%）** |
| **加权完成**（FC-1 计 0.5） | **97.5%** |
| FC-20 `/openflare/about` | ✅ 已实现 |
| 缺失路由 | **无** |
## 路由对照
| # | 计划路由 | 页面文件 | 状态 | 备注 |
|---|---|---|---|---|
| FC-1 | `/openflare` | `openflare/page.tsx` | ⚠️ partial | 仪表盘已实现；世界地图以 `GeoDistributionList` 国家列表替代 |
| FC-2 | `/openflare/nodes` | `openflare/nodes/page.tsx` | ✅ | |
| FC-3 | `/openflare/nodes/detail` | `openflare/nodes/detail/page.tsx` | ✅ | Edge / Relay / Tunnel |
| FC-4 | `/openflare/proxy-routes` | `openflare/proxy-routes/page.tsx` | ✅ | |
| FC-5 | `/openflare/proxy-routes/detail` | `openflare/proxy-routes/detail/page.tsx` | ✅ | 6 Section + 发布 |
| FC-6 | `/openflare/config-versions` | `openflare/config-versions/page.tsx` | ✅ | |
| FC-7 | `/openflare/waf` | `openflare/waf/page.tsx` | ✅ | |
| FC-8 | `/openflare/waf/ip-groups` | `openflare/waf/ip-groups/page.tsx` | ✅ | |
| FC-9 | `/openflare/websites` | `openflare/websites/page.tsx` | ✅ | |
| FC-10 | `/openflare/websites/detail` | `openflare/websites/detail/page.tsx` | ✅ | |
| FC-11 | `/openflare/websites/certificates` | `openflare/websites/certificates/page.tsx` | ✅ | |
| FC-12 | `/openflare/websites/dns-accounts` | `openflare/websites/dns-accounts/page.tsx` | ✅ | |
| FC-13 | `/openflare/pages` | `openflare/pages/page.tsx` | ✅ | |
| FC-14 | `/openflare/pages/detail` | `openflare/pages/detail/page.tsx` | ✅ | |
| FC-15 | `/openflare/origins` | `openflare/origins/page.tsx` | ✅ | |
| FC-16 | `/openflare/origins/detail` | `openflare/origins/detail/page.tsx` | ✅ | |
| FC-17 | `/openflare/access-logs` | `openflare/access-logs/page.tsx` | ✅ | 4 Tab |
| FC-18 | `/openflare/apply-logs` | `openflare/apply-logs/page.tsx` | ✅ | |
| FC-19 | `/openflare/performance` | `openflare/performance/page.tsx` | ✅ | |
| FC-20 | `/openflare/about` | `openflare/about/page.tsx` | ✅ | AboutService + 侧栏导航 |
## 子路由（不在侧栏顶级）
`/openflare/nodes/detail`、`proxy-routes/detail`、`pages/detail`、`websites/detail`、`websites/certificates`、`websites/dns-accounts`、`waf/ip-groups`、`origins/detail`
## 结论
§6.1 路由映射 **基本完成**（20/20 文件）。唯一路由级缺口为 FC-1 世界地图（可选 P2）；无缺失 `page.tsx`。
docs/plan/verify-frontend-services.md
-61
View File
@@ -1,61 +0,0 @@
# OpenFlare 前端 Service 层验证报告
> **验证日期**：2026-06-18（复验）
> **目录**：`Wavelet/frontend/lib/services/openflare/`
## 覆盖率摘要
| 维度 | 结果 |
|---|---|
| §7.1 计划服务文件 | **15 / 15 = 100%** |
| 业务 `/api/*` 端点 | **100%** |
| 待补 API | **0** |
## §7.1 对照结果
| 计划服务 | 实际文件 | 注册 | 方法覆盖 |
|---|---|---|---|
| dashboard | ✅ | `openflareDashboard` | ✅ |
| node | ✅ | `openflareNode` | ✅ 12 方法 |
| proxy-route | ✅ | `openflareProxyRoute` | ✅ |
| config-version | ✅ | `openflareConfigVersion` | ✅ |
| waf | ✅ | `openflareWaf` | ✅ |
| website | ✅ | `openflareWebsite` | ✅ |
| tls-certificate | ✅ | `openflareTls` | ✅ |
| dns-account | ✅ | `openflareDns` | ✅ |
| acme-account | ⚠️ 合并 | 经 `openflareTls` | `getDefaultAcmeAccount()` |
| pages | ✅ | `openflarePages` | ✅ |
| origin | ✅ | `openflareOrigin` | ✅ |
| access-log | ✅ | `openflareAccessLog` | ✅ |
| apply-log | ✅ | `openflareApplyLog` | ✅ |
| option | ✅ | `openflareOption` | ✅ |
| update | ✅ | `openflareUpdate` | ✅ 6 方法 |
| about | ✅ | `openflareAbout` | `getAboutContent()` |
## update.service.ts 复验
| 方法 | 端点 |
|---|---|
| `getLatestRelease(channel?)` | `GET /api/update/latest-release` |
| `upgradeServer(channel?)` | `POST /api/update/upgrade` |
| `uploadServerBinary(file, onProgress?)` | `POST /api/update/manual-upload` |
| `confirmManualServerUpgrade(token)` | `POST /api/update/manual-upgrade` |
| `createUpgradeLogsWebSocket()` | `WS /api/update/logs/ws` |
| `parseUpgradeStreamSnapshot(raw)` | WS 消息解析 |
已接入：`use-openflare-server-upgrade.ts`、`openflare-version-entry.tsx`、`openflare-ops.tsx`。
## 计划外（已实现）
- `status.service.ts` → `openflareStatus`
- `uptimekuma.service.ts` → `openflareUptimeKuma`
- `about.service.ts` → `openflareAbout`
- `legacy-base.service.ts`（基类）
## 待补 API
无。
## 结论
Service 层迁移 **完成**。所有计划内业务 API 均已由 Service 覆盖。
docs/plan/verify-frontend-ui.md
-40
View File
@@ -1,40 +0,0 @@
# OpenFlare 前端 UI 规范验收报告
> **验证日期**：2026-06-18（polish pass 复验）
> **范围**：`Wavelet/frontend/app/(main)/openflare/`
## 总体
| 维度 | 结果 |
|---|---|
| 标题 `h1 text-2xl font-semibold tracking-tight` | ✅ |
| 外壳 `py-6 px-1` | ✅ |
| shadcn 组件（无旧 UI / HeroUI） | ✅ |
| 单文件 ≤600 行 | ✅（最大 `access-logs/page.tsx` 558 行） |
| loading/empty/error | ✅ |
| RHF + Zod 表单（P1 Dialog） | ✅ |
**总体结论：PASS**
## 分模块
| 模块 | 结论 | 说明 |
|---|---|---|
| Dashboard | ✅ PASS | 标准壳与三态组件 |
| Nodes | ✅ PASS | `node-editor-dialog` Zod 已补 |
| Proxy detail | ✅ PASS | `ErrorInline` / `EmptyStateWithBorder` 已统一 |
| Proxy list | ⚠️ PASS* | 列表 error 仅 toast（P2） |
| WAF | ✅ PASS | `rule-entry-dialog` RHF+Zod 已补 |
| Websites/Certificates | ✅ PASS | `dns-account-create-dialog` Zod 已补 |
| Access logs | ✅ PASS | folds/ip-summary/ip-trend error 已补 |
| Config versions | ✅ PASS | `cleanup-dialog` Zod 已补 |
| About | ✅ PASS | 页面惯例完整 |
| Version upgrade dialog | ✅ PASS | Card/Badge/Markdown 惯例合规 |
## P2 可选改进
1. `proxy-routes/page-client.tsx` — 列表 error 改用 `ErrorInline`
2. `access-logs/components/cleanup-dialog.tsx` — 补 RHF+Zod
3. `access-logs/page.tsx` ip-trend — 改用 shadcn `Input`
4. `nodes/components/node-observability.tsx` — 改用 `ErrorInline`+重试
5. FC-1 世界地图 — 当前以国家列表替代
docs/reference/configuration.md
+247 -259
View File
@@ -1,149 +1,250 @@
# 配置项
你会学到：OpenFlare Server、前端构建和 Agent 支持哪些配置来源、配置项默认值是什么，以及常见部署组合应该如何配置。
你会学到：OpenFlare Server、前端构建、Agent、Relay、OpenFlared 支持哪些配置来源、有哪些配置字段和环境变量，以及它们的默认值和行为。
本文档汇总 OpenFlare `1.0.0` 当前支持的 Server 与 Agent 配置项，只保留仍然有效的启动、部署与运行参数。
本文档汇总了 OpenFlare 当前版本所支持的全部配置项。
---
## 配置来源
Server 支持三类配置来源：
### 1. Server 配置来源
- **配置文件**：启动时默认读取同级目录下的 `config.yaml`（可通过 `CONFIG_PATH` 环境变量指定）。
- **环境变量**：所有配置文件中的字段均支持通过大写蛇形（`UPPER_SNAKE_CASE`）的环境变量进行覆盖（环境变量优先级高于 `config.yaml`）。
- **系统运行时配置**：保存在关系数据库的 `w_system_configs` 表中。此类参数可通过管理后台图形界面或系统 API 热更新并动态生效。
1. 命令行参数。
2. 环境变量。
3. 数据库 `Option` 表中的运行时配置。
### 2. Agent / Relay / OpenFlared 配置来源
- **命令行参数**：通过 `-config` 指定配置文件（JSON 格式）。
- **配置文件**：例如 `agent.json`、`relay.json`、`flared.json`。
- **覆盖环境变量**：支持特定的环境变量来覆盖配置文件中的连接地址和 Token 凭证。
Agent 支持：
1. `-config` 命令行参数。
2. `agent.json` 配置文件。
3. 少量日志与配置覆盖相关环境变量。
Relay (中继端) 支持：
1. `-config` 命令行参数。
2. `relay.json` 配置文件。
3. 丰富的启动覆盖环境变量。
Client (内网客户端) 支持：
1. `-config` 命令行参数。
2. `flared.json` 配置文件。
3. 启动覆盖与日志环境变量。
---
## 配置文件位置
| 组件 | 默认位置 | 说明 |
| --- | --- | --- |
| Server SQLite | `openflare.db` | 可通过 `SQLITE_PATH` 修改 |
| Server 配置文件 | `./config.yaml` | 可通过 `CONFIG_PATH` 环境变量修改 |
| Server SQLite 库 | `openflare.db` | 可通过 `database.sqlite_path` / `SQLITE_PATH` 修改 |
| Agent 配置文件 | `./agent.json` | 可通过 `-config` 指定 |
| 一键安装 Agent 配置 | `/opt/openflare-agent/agent.json` | 安装脚本默认生成 |
| Agent 数据目录 | 配置文件所在目录下的 `data` | 可通过 `data_dir` 修改 |
| 一键安装 Agent 配置 | `/opt/openflare-agent/agent.json` | 安装脚本默认生成路径 |
| Agent 数据目录 | 配置文件同级 `data` | 可在配置文件中通过 `data_dir` 覆盖 |
| Relay 配置文件 | `./relay.json` | 可通过 `-config` 指定 |
| 一键安装 Relay 配置 | `/opt/openflare-relay/relay.json` | 安装脚本默认生成 |
| 一键安装 Relay 配置 | `/opt/openflare-relay/relay.json` | 安装脚本默认生成路径 |
| Client 配置文件 | `./flared.json` | 可通过 `-config` 指定 |
| 一键安装 Client 配置 | `/opt/openflared/flared.json` | 安装脚本默认生成 |
| 一键安装 Client 配置 | `/opt/openflared/flared.json` | 安装脚本默认生成路径 |
---
## Server 命令行参数
```bash
cd openflare-server
go run . --port 3000 --log-dir ./logs
# 启动 Server 时指定配置文件
CONFIG_PATH=/path/to/custom-config.yaml ./openflare-server all
```
| 参数 | 作用 | 默认值 |
| --- | --- | --- |
| `--port` | 指定 Server 监听端口 | `3000` |
| `--log-dir` | 指定日志目录 | 空 |
| `--version` | 输出当前版本后退出 | `false` |
| `--help` | 输出帮助信息后退出 | `false` |
运行支持的子服务指令（融合/单进程模式）：
- `all`：在一进程内启动所有服务（API + Worker + Scheduler，默认）。
- `api`：仅启动管理端与节点通信的 API 服务。
- `worker`：仅启动后台任务的 Worker 服务。
- `scheduler`：仅启动定时任务的 Scheduler 服务。
## Server 环境变量
---
| 环境变量 | 作用 | 默认值 |
| --- | --- | --- |
| `PORT` | Server 监听端口 | `3000` |
| `GIN_MODE` | Gin 运行模式 | 非 `debug` 时按 release |
| `LOG_LEVEL` | 日志等级 | `info` |
| `JWT_SECRET` | 管理端 API 登录令牌的 JWT 签名密钥，生产环境必须显式配置 | 启动时随机生成 |
| `SQLITE_PATH` | SQLite 数据库文件路径 | `openflare.db` |
| `DSN` | PostgreSQL DSN，设置后优先于 SQLite | 空 |
| `SQL_DSN` | 兼容旧命名的 PostgreSQL DSN，优先级低于 `DSN` | 空 |
| `REDIS_CONN_STRING` | Redis 连接串 | 空 |
| `AGENT_TOKEN` | 兼容旧部署的全局 Agent Token | 空 |
## Server 环境变量与配置文件对照
说明：
Server 的所有核心基础配置定义在 `config.yaml` 中，且均支持环境变量覆盖（变量优先级高于 YAML 配置文件）。
* `DSN` 与 `SQL_DSN` 同时存在时优先使用 `DSN`。
* `DSN` 或 `SQL_DSN` 与 `SQLITE_PATH` 同时存在时优先使用 PostgreSQL。
* 当目标 PostgreSQL 数据库为空且本地 `SQLITE_PATH` 文件存在时，Server 启动阶段会自动迁移 SQLite 数据，并在日志中输出按表迁移进度。
* `JWT_SECRET` 用于管理端 API 登录令牌的签名与验证，生产环境必须显式配置，避免重启后所有已登录令牌失效。
* `REDIS_CONN_STRING` 未配置时，相关能力回退为进程内实现。
### 1. 应用基本配置 (`app:`)
| 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `app.app_name` | `APP_NAME` | 应用程序标识名称 | `openflare` |
| `app.env` | `APP_ENV` | 运行环境（`development` / `testing` / `production`） | `production` |
| `app.addr` | `APP_ADDR` | 服务监听地址与端口 | `:3000` |
| `app.node_id` | `APP_NODE_ID` | Snowflake 算法的节点 ID（0-1023），多实例部署时必须唯一 | `1` |
| `app.api_prefix` | `APP_API_PREFIX` | 管理端与 API 的路由前缀 | `/api` |
| `app.graceful_shutdown_timeout` | `APP_GRACEFUL_SHUTDOWN_TIMEOUT` | 优雅停机等待超时（秒） | `30` |
| `app.session_cookie_name` | `APP_SESSION_COOKIE_NAME` | 会话 Cookie 的名称 | `openflare_session_id` |
| `app.session_secret` | `APP_SESSION_SECRET` | Session 会话签名的密钥，**生产环境必须配置为随机长字符串** | 无（随机） |
| `app.session_domain` | `APP_SESSION_DOMAIN` | 共享 Session 的 Cookie 作用域域名 | 空 |
| `app.session_age` | `APP_SESSION_AGE` | 浏览器 Session 的存活时间（秒） | `86400` (24h) |
| `app.session_http_only` | `APP_SESSION_HTTP_ONLY` | 是否启用 Cookie 的 HttpOnly 属性 | `false` |
| `app.session_secure` | `APP_SESSION_SECURE` | 是否启用 Cookie 的 Secure 属性（HTTPS 下使用） | `false` |
## 运行时 Option
### 2. 关系数据库配置 (`database:`)
| 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `database.enabled` | `DB_ENABLED` | 是否启用 PostgreSQL 数据库。设为 `false` 则回退到 SQLite | `true` |
| `database.sqlite_path` | `SQLITE_PATH` | PostgreSQL 禁用时，SQLite 数据库的文件路径 | `openflare.db` |
| `database.host` | `DB_HOST` | PostgreSQL 数据库连接地址 | `127.0.0.1` |
| `database.port` | `DB_PORT` | PostgreSQL 数据库端口 | `5432` |
| `database.username` | `DB_USERNAME` | PostgreSQL 数据库用户名 | `openflare` |
| `database.password` | `DB_PASSWORD` | PostgreSQL 数据库密码 | `replace-with-strong-password` |
| `database.database` | `DB_NAME` | PostgreSQL 数据库名 | `openflare` |
| `database.ssl_mode` | `DB_SSL_MODE` | PostgreSQL 的 SSL 模式 | `disable` |
| `database.time_zone` | `DB_TIMEZONE` | 数据库会话时区 | `UTC` |
| `database.log_level` | `DB_LOG_LEVEL` | GORM SQL 打印日志等级（`info` / `warn` / `error` / `silent`） | `info` |
| `database.max_idle_conn` | `DB_MAX_IDLE_CONN` | 数据库连接池最大空闲连接数 | `16` |
| `database.max_open_conn` | `DB_MAX_OPEN_CONN` | 数据库连接池最大打开连接数 | `128` |
以下配置由管理端设置页维护，可热更新：
### 3. Redis 配置 (`redis:`)
| 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `redis.enabled` | `REDIS_ENABLED` | 是否启用 Redis 服务。**系统异步队列和同步依赖它，必须开启** | `true` |
| `redis.addrs` | `REDIS_ADDR` | Redis 单机或集群连接地址数组（环境变量仅设置单地址） | `["127.0.0.1:6379"]` |
| `redis.username` | `REDIS_USERNAME` | Redis 账号名称（若有） | 空 |
| `redis.password` | `REDIS_PASSWORD` | Redis 访问密码 | 空 |
| `redis.db` | `REDIS_DB` | Redis 逻辑数据库编号 | `0` |
| `redis.key_prefix` | `REDIS_KEY_PREFIX` | 系统在 Redis 中使用的键前缀 | `openflare:` |
| `redis.pool_size` | `REDIS_POOL_SIZE` | Redis 连接池大小 | `100` |
| 配置项 | 作用 | 默认值 |
| --- | --- | --- |
| `AgentHeartbeatInterval` | Agent 心跳间隔（毫秒） | `10000` |
| `AgentWebsocketUpgradeEnabled` | 是否允许 Agent 在 HTTP 心跳成功后升级为 WebSocket | `true` |
| `NodeOfflineThreshold` | 节点离线阈值（毫秒） | `120000` |
| `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/OpenFlare` |
| `GeoIPProvider` | 节点/IP 归属解析方式 | `ipinfo` |
| `DatabaseAutoCleanupEnabled` | 是否启用每日自动清理观测数据 | `false` |
| `DatabaseAutoCleanupRetentionDays` | 自动清理保留天数，至少 1 天 | `30` |
| `UptimeKumaEnabled` | 是否启用 Uptime Kuma 自动同步 | `false` |
| `UptimeKumaUrl` | Uptime Kuma 实例地址 | 空 |
| `UptimeKumaUsername` | Uptime Kuma 登录用户名 | 空 |
| `UptimeKumaPassword` | Uptime Kuma 登录密码（写专，接口不回显） | 空 |
| `UptimeKumaMonitorScope` | 监控范围，支持 `all` (全部站点) 或 `selected` (选择站点) | `all` |
| `UptimeKumaSelectedSites` | 已选择监控站点的名称列表（英文逗号分隔） | 空 |
| `UptimeKumaSyncInterval` | 自动差分同步间隔（分钟） | `5` |
| `UptimeKumaInterval` | 监控心跳检测频率（秒） | `60` |
| `UptimeKumaRetry` | 监控最大重试次数 | `0` |
| `UptimeKumaRetryInterval` | 监控重试间隔时间（秒） | `60` |
| `UptimeKumaTimeout` | 监控请求超时断开时间（秒） | `48` |
### 4. ClickHouse 配置 (`clickhouse:`)
| 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `clickhouse.enabled` | `CLICKHOUSE_ENABLED` | 是否启用 ClickHouse。**系统节点指标与访问日志在此进行海量写入** | `true` |
| `clickhouse.hosts` | `CLICKHOUSE_HOST` | ClickHouse 集群连接地址数组（环境变量仅设置单地址） | `["127.0.0.1:9000"]` |
| `clickhouse.username` | `CLICKHOUSE_USERNAME` | ClickHouse 账号用户名 | `default` |
| `clickhouse.password` | `CLICKHOUSE_PASSWORD` | ClickHouse 密码 | `123456` |
| `clickhouse.database` | `CLICKHOUSE_NAME` | ClickHouse 存储的数据库名称 | `openflare` |
说明：
### 5. 系统日志配置 (`log:`)
| 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `log.level` | `LOG_LEVEL` | 全局日志记录等级（`debug` / `info` / `warn` / `error` / `fatal`） | `info` |
| `log.format` | `LOG_FORMAT` | 日志打印格式（`console` 易读控制台 / `json` 结构化） | `console` |
| `log.output` | `LOG_OUTPUT` | 日志输出渠道（`stdout` 标准输出 / `file` 文本文件） | `stdout` |
| `log.file_path` | - | 当 output 为 file 时日志的持久化路径 | `./logs/app.log` |
| `log.max_size` | - | 单个日志文件的最大空间（MB），超出自动切割轮转 | `100` |
| `log.max_age` | - | 历史切割日志文件最大保留天数 | `30` |
* `DatabaseAutoCleanupEnabled` 开启后，Server 会在每天凌晨 3 点自动清理 `node_access_logs`、`node_metric_snapshots`、`node_request_reports` 三类观测数据。
* `DatabaseAutoCleanupRetentionDays` 为统一保留天数，必须大于等于 1。
* 管理端支持手动清理时留空保留天数，以直接删除对应数据集的全部历史记录。
* `AgentUpdateRepo` 指向的 GitHub Release 需包含目标 Agent 二进制；自更新优先使用 GitHub Release API 返回的 `assets[].digest`（`sha256:...`）校验，旧版 Release 无 digest 时会回退读取同名 `.sha256` 侧车文件。
* 第三方登录不再通过 `GitHubOAuthEnabled`、`GitHubClientId`、`GitHubClientSecret` 作为主配置入口；这些旧 Option 仅用于升级时迁移默认 GitHub 认证源。
* 微信登录旧 Option 保留为兼容字段，但管理端不再提供微信登录配置入口。
* Turnstile 旧 Option 与后端校验能力保留，已有配置仍会生效。
### 6. 异步任务 Worker 队列配置 (`worker:`)
| 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `worker.concurrency` | `WORKER_CONCURRENCY` | 后台 Worker 进程同时消费任务的最大并发数 | `20` |
| `worker.strict_priority`| `WORKER_STRICT_PRIORITY` | 是否严格按队列优先级分配消费线程（否则为加权轮询） | `false` |
## OpenResty 参数
### 7. 链路追踪 OpenTelemetry 配置 (`otel:`)
| 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `otel.sampling_rate` | `OTEL_SAMPLING_RATE` | OTel 链路追踪全局采样率。默认 `0.0` 不采样，`1.0` 为全量追踪 | `0.0` |
| `otel.tracer_name` | `OTEL_TRACER_NAME` | 全局 OTel 埋点 Tracer 的实例化名称 | `github.com/Rain-kl/OpenFlare` |
OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前常用项包括：
---
* `OpenRestyWorkerProcesses`
* `OpenRestyWorkerConnections`
* `OpenRestyWorkerRlimitNofile`
* `OpenRestyKeepaliveTimeout`
* `OpenRestyProxyConnectTimeout`
* `OpenRestyProxySendTimeout`
* `OpenRestyProxyReadTimeout`
* `OpenRestyProxyBufferingEnabled`
* `OpenRestyGzipEnabled`
* `OpenRestyCacheEnabled`
* `OpenRestyCachePath`
* `OpenRestyCacheMaxSize`
## 运行时系统配置 (SystemConfig)
这类参数必须以结构化方式校验、保存并参与版本渲染。
这些配置项存储于关系型数据库中的 `w_system_configs` 表中。所有的配置项在修改后会主动通知 Redis 缓存失效以实现动态热更新，管理员可通过后台页面直接管理。
约束：
### 1. 基础与业务运行时配置
| 配置键 (Key) | 数据类型 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `site_name` | `string` | 管理端平台的展示名称 | `OpenFlare` |
| `server_address` | `string` | 管理端控制台的对外公网访问地址，用于组装 OAuth 回调与下载链接 | 空 |
| `password_login_enabled` | `bool` | 是否允许管理员通过常规用户名密码方式登录后台 | `true` |
| `registration_enabled` | `bool` | 是否允许自助注册新用户（默认禁止，需由 root 账户邀请或分发） | `false` |
| `password_register_enabled` | `bool` | 是否允许通过邮箱/密码方式在前端直接注册 | `false` |
| `oidc_login_enabled` | `bool` | 是否启用 OIDC (SSO) 第三方免密登录方案 | `false` |
| `max_api_keys_per_user` | `int` | 每个后台用户可生成的最大 API 密钥（API Token）数量 | `5` |
| `login_session_ttl_hours` | `int` | 用户会话在浏览器 Cookie 中的有效期（小时）。0 为随浏览器关闭清除 | `24` |
| `upload_allowed_extensions` | `string` | 允许用户上传的静态静态托管包文件扩展名（逗号分隔） | `zip,tar.gz,gz,tar,ssl,key,pem,txt,json` |
| `file_access_whitelist` | `json` | 允许免登录直接公开下载或访问的文件业务类型列表 (JSON 数组) | `["ssl_cert", "pages_release"]` |
| `disk_cache_max_size_mb` | `int` | 平台本地磁盘缓存的最大存储阈值（MB） | `1024` |
| `disk_cache_ttl_minutes` | `int` | 本地磁盘缓存对象的默认生存周期（分钟） | `1440` (24h) |
| `disk_cache_lru_enabled` | `bool` | 当本地磁盘缓存空间不足时是否启用 LRU 算法剔除最旧缓存 | `true` |
| `update_upstream_repository` | `string` | 系统检测自更新的 GitHub 仓库地址 | `Rain-kl/OpenFlare` |
| `storage_config` | `json` | 对象存储的结构化配置 (JSON)，支持本地磁盘与 AWS S3 兼容存储配置 | 本地存储模式 |
| `relay_frps_web_ui_enabled` | `bool` | 是否允许在中继节点上默认开启内嵌的 frps 流量监视面板 Web UI | `true` |
| `relay_frps_web_ui_port` | `int` | 中继节点 frps 监视面板所监听绑定的宿主机端口 | `7500` |
* 管理端不再暴露 `resolver` 配置。
* 规则上游统一渲染为 named `upstream` 并启用 keepalive。
* 单上游如带 base path 或 query，会在 `proxy_pass` 中补回原始 URI。
* 多上游仍要求每个上游都为纯 `scheme://host[:port]`，且同一规则内协议一致。
* `OpenRestyCacheEnabled` 用于启用缓存基础设施与全局默认参数；实际是否缓存、按 URL / 后缀 / 路径等命中策略由各条 `proxy_routes` 单独决定。
* 默认缓存 Key 为 `$scheme$host$request_uri`。
* 默认 `keepalive_timeout` 为 `20` 秒，默认 `proxy_connect_timeout` 为 `3` 秒。
* 默认事件模型为 `epoll`，并默认开启 `multi_accept`。
* HTTPS 监听默认使用独立 `http2 on;` 指令，避免新版 Nginx/OpenResty 对 `listen ... http2` 的弃用告警。
### 2. 人机安全校验 (PoW Captcha)
| 配置键 (Key) | 数据类型 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `cap_login_enabled` | `bool` | 是否在登录界面强制要求进行本地 PoW 算力防爆破人机验证 | `false` |
| `cap_auto_solve` | `bool` | 打开页面后是否由浏览器自动开始后台背景计算算力（无需用户手动点击）| `true` |
| `cap_challenge_count` | `int` | 人机验证所需的计算难题数。数量越大，计算要求时间越长（推荐 1～5） | `1` |
| `cap_challenge_difficulty`| `int`| 每次计算所需的 PoW 哈希前缀匹配难度。推荐数值在 3-5 之间 | `4` |
| `cap_challenge_ttl_seconds`| `int`| 难题下发后等待计算提交的最长有效时间（秒），超时自动作废 | `300` |
| `cap_token_ttl_seconds` | `int` | 完成计算并置换到登录凭证后的有效期（秒），限制需在规定时间内登录 | `600` |
### 3. SMTP 邮件推送配置
| 配置键 (Key) | 数据类型 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `smtp_host` | `string` | 发信 SMTP 邮件服务器的连接地址 | 空 |
| `smtp_port` | `int` | 发信 SMTP 服务的端口 (通常是 465 SSL 或 587 STARTTLS) | `465` |
| `smtp_username` | `string` | SMTP 账户发信邮箱名称 | 空 |
| `smtp_password` | `string` | SMTP 账户的授权密码或证书密钥（后台写入后加密隐藏，不可回显） | 空 |
| `email_login_verification_enabled` | `bool` | 是否在用户邮箱登录时发送一次性 6 位动态验证码进行二次认证 | `false` |
| `email_register_verification_enabled` | `bool` | 用户自助注册时是否必须强制验证邮箱真实性并收取注册验证码 | `false` |
### 4. 节点与 Agent 运维运行时参数
| 配置键 (Key) | 数据类型 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `agent_discovery_token` | `string` | 新节点首次一键接入并自动注册的全局通用验证发现 Token | 无（系统初始化生成） |
| `agent_heartbeat_interval`| `int` | 控制并向所有接入 Agent 周期下发的标准心跳检测间隔（毫秒） | `10000` (10s) |
| `agent_websocket_upgrade_enabled` | `bool` | 是否授权 Agent 在 HTTP 心跳握手成功后升级建立持久 WebSocket 实时连接 | `true` |
| `node_offline_threshold` | `int` | 在管理后台中判定节点失去心跳并标注为离线状态的无响应阈值（毫秒） | `120000` (120s) |
| `agent_update_repo` | `string` | Agent 节点更新下载自身二进制的 Release 仓库源 | `Rain-kl/OpenFlare` |
| `geoip_provider` | `string` | GeoIP 提供商，支持 `maxmind` 等，用于 WAF 防护时地域分析 | `maxmind` |
| `database_auto_cleanup_enabled` | `bool` | 是否在每天凌晨 3:00 自动清理过期观测历史日志（降低数据库空间） | `true` |
| `database_auto_cleanup_retention_days` | `int` | 自动清理观测数据（访问日志、度量曲线、审计等）的默认保留天数 | `30` |
### 5. Uptime Kuma 监控联动同步
| 配置键 (Key) | 数据类型 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `uptime_kuma_enabled` | `bool` | 是否在配置发布激活后自动同步生成 Uptime Kuma 对应的 HTTP 监控项 | `false` |
| `uptime_kuma_url` | `string` | Uptime Kuma 控制端实例的访问 URL (含端口与路径) | 空 |
| `uptime_kuma_username` | `string` | Uptime Kuma 后台用于同步接口调用认证的管理员账号名称 | 空 |
| `uptime_kuma_password` | `string` | Uptime Kuma 后台对应的登录密码（后台写入后加密隐藏，不可回显） | 空 |
| `uptime_kuma_monitor_scope`| `string` | 自动生成监控项的路由范围（支持 `all` 全选网站或 `selected` 选定部分） | `all` |
| `uptime_kuma_selected_sites`| `string` | 选定进行监控的代理网站 Site Name 名称列表（英文逗号分隔） | 空 |
| `uptime_kuma_sync_interval`| `int` | 向 Uptime Kuma 实例进行差异扫描并校准同步的频率间隔（分钟） | `5` |
| `uptime_kuma_interval` | `int` | 生成的 HTTP 监控对象发出 HTTP GET 探测的周期检测频率（秒） | `60` |
| `uptime_kuma_retry` | `int` | HTTP 监控对象在遭遇连接波动失败后的最大重试重连次数 | `0` |
| `uptime_kuma_retry_interval`| `int` | HTTP 监控对象失败重连重试的间隔停顿时间（秒） | `60` |
| `uptime_kuma_timeout` | `int` | 触发 HTTP GET 监控请求判定超时的断开限制时间（秒） | `48` |
### 6. OpenResty 核心主配置与渲染选项 (OpenResty Config)
| 配置键 (Key) | 数据类型 | 作用说明 | 默认值 |
| --- | --- | --- | --- |
| `openresty_default_server_return_status` | `int` | 默认未命中匹配路由的 HTTP 请求返回的响应状态码 | `444` (直接丢弃) |
| `openresty_worker_processes` | `string` | nginx `worker_processes` 参数设置。支持固定整数值或自动分配 `auto` | `auto` |
| `openresty_worker_connections` | `int` | nginx `worker_connections` 单进程最大连接承载限制 | `1024` |
| `openresty_worker_rlimit_nofile` | `int` | nginx `worker_rlimit_nofile` 能够打开的最大物理文件描述符限制 | `65535` |
| `openresty_events_use` | `string` | 绑定的事件轮询引擎（例如 Linux 下首选 `epoll`） | `epoll` |
| `openresty_events_multi_accept_enabled` | `bool` | 允许 worker 进程单次批量接受所有挂起的网络握手请求 | `true` |
| `openresty_keepalive_timeout` | `int` | nginx 连接保持连接复用的 `keepalive_timeout` 限制时长（秒） | `65` |
| `openresty_keepalive_requests` | `int` | 单一 TCP 连接复用过程中被允许的最大累计请求处理次数 | `100` |
| `openresty_client_header_timeout` | `int` | 接收客户端整个 Request Header 头信息的读取超时上限时长（秒） | `60` |
| `openresty_client_body_timeout` | `int` | 接收客户端 Request Body 载荷体的数据读取超时上限时长（秒） | `60` |
| `openresty_client_max_body_size` | `string` | 允许客户端请求上传的最大 Body 大小限制，通常需要单位如 `10m`/`50m` | `100m` |
| `openresty_large_client_header_buffers` | `string` | 复杂请求超大请求头的专属缓冲区数目与大小大小（如 `4 8k`） | `4 8k` |
| `openresty_send_timeout` | `int` | 向客户端推送 Response 数据回执单次传输最大的间隔超时时长（秒）| `60` |
| `openresty_resolvers` | `string` | 节点进行 DNS 域名动态解析所关联绑定的域名解析器地址与配置参数 | 空 |
| `openresty_proxy_connect_timeout` | `int` | 向后台代理源站发起 TCP 三次握手建连的最长超时上限时长（秒） | `30` |
| `openresty_proxy_send_timeout` | `int` | 向源站单次写入并发送请求流数据的最大写入操作间隔时长（秒） | `60` |
| `openresty_proxy_read_timeout` | `int` | 源站收到请求后返回数据，Agent 最大的等待数据返回间隔时长（秒） | `60` |
| `openresty_websocket_enabled` | `bool` | 是否在 HTTP 段中自动载入和渲染支持 WebSocket 协议的全局变量及头信息 | `true` |
| `openresty_http3_enabled` | `bool` | 是否在生成 nginx 监听描述中渲染支持 HTTP/3 QUIC 双栈监听能力 | `false` |
| `openresty_proxy_request_buffering_enabled`| `bool` | 是否将客户端 Request Body 先在网关做完全部读取缓存再向源站递交 | `false` |
| `openresty_proxy_buffering_enabled` | `bool` | 是否允许网关暂存源站的大量 Response 数据待全部解析后再转发给用户 | `true` |
| `openresty_proxy_buffers` | `string` | nginx 反代响应缓冲区的分配数量与单缓存大大小（如 `8 4k`） | `8 4k` |
| `openresty_proxy_buffer_size` | `string` | 存放源站返回 Response Header 头部信息的专属缓冲区限制 | `4k` |
| `openresty_proxy_busy_buffers_size` | `string` | 响应数据流返回过大时限制网关处于 Busy 状态的缓冲上限 | `8k` |
| `openresty_gzip_enabled` | `bool` | 是否在网关对符合条件的内容启用 gzip 编码实时压缩返回 | `true` |
| `openresty_gzip_min_length` | `int` | 触发 gzip 实时压缩的文件大小门槛。低于此大小无需压缩浪费 CPU | `1024` (1KB) |
| `openresty_gzip_comp_level` | `int` | gzip 压缩强度等级。支持 1-9，数字越大压缩率越高，越消耗算力 | `5` |
| `openresty_cache_enabled` | `bool` | 是否在全局配置中初始化代理缓存区域（Proxy Cache Path） | `false` |
| `openresty_cache_path` | `string` | 节点上代理缓存存放的临时物理目录路径 | `/var/cache/openresty` |
| `openresty_cache_levels` | `string` | 代理缓存的存储目录树层级分配设置 | `1:2` |
| `openresty_cache_inactive` | `string` | 缓存文件多长时间无人访问后将自动从磁盘上失效抹除的时间时长 | `7d` (7天) |
| `openresty_cache_max_size` | `string` | 代理缓存区域在节点上占用的最大可用物理磁盘额度 | `10g` (10GB) |
| `openresty_cache_key_template` | `string` | 默认生成代理缓存键的识别模板 | `$scheme$host$request_uri` |
| `openresty_cache_lock_enabled` | `bool` | 遭遇高并发请求击穿同一失效资源时是否对向源站发起建连排队加锁 | `true` |
| `openresty_cache_lock_timeout` | `string` | 抢夺代理缓存锁排队建连时排队等待的最长等待耗时限制 | `5s` |
| `openresty_cache_use_stale` | `string` | 当源站遇到特定报错（如502/504等）时是否直接向用户投递过期缓存 | `error timeout updating http_502 http_503 http_504` |
| `openresty_main_config_template` | `string` | 允许用户完全重写整个 OpenResty nginx.conf 的底层结构大骨架模板 | 空 (内置缺省骨架) |
---
## 前端构建环境变量
@@ -153,6 +254,8 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
| `NEXT_PUBLIC_APP_VERSION` | 前端展示版本号 | `dev` |
| `NEXT_DEV_BACKEND_URL` | 本地开发服务器代理的后端地址 | `http://127.0.0.1:3000` |
---
## Agent 环境变量
| 环境变量 | 作用 | 默认值 |
@@ -173,24 +276,24 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
| `OPENFLARE_MMDB_UPDATE_INTERVAL` | WAF GeoIP mmdb 更新间隔，可覆盖 `agent.json` | 空 |
| `OPENFLARE_MMDB_DOWNLOAD_URL` | WAF GeoIP mmdb 下载地址，可覆盖 `agent.json` | 空 |
## Agent 命令行参数
---
| 参数 | 作用 | 默认值 |
| --- | --- | --- |
| `-config` | 指定 Agent 配置文件路径 | `./agent.json` |
## Agent 命令行参数与配置字段
## Agent 配置字段
### 命令行参数
- `-config`：指定 Agent 配置文件路径，默认值为 `./agent.json`。
### 配置文件字段 (agent.json)
| 字段 | 作用 | 是否必填 | 默认值/行为 |
| --- | --- | --- | --- |
| `server_url` | 控制面地址 | 是 | 无 |
| `agent_token` | 节点专属认证 Token | 与 `discovery_token` 二选一 | 空 |
| `discovery_token` | 首次自动注册使用的全局 Token | 与 `agent_token` 二选一 | 空 |
| `node_name` | 节点名称 | 否 | 自动使用主机名 |
| `node_ip` | 节点 IP | 否 | 自动探测，优先通过第三方 API 获取真实出口公网 IP；失败时退回本机网卡探测 |
| `node_ip` | 节点 IP | 否 | 自动探测，优先使用公网出口 IP；失败时退回本机网卡探测 |
| `openresty_path` | OpenResty 二进制路径 | 否 | `openresty` |
| `openresty_observability_port` | 本地观测与 OpenResty 健康检查端口 | 否 | `18081` |
| `data_dir` | Agent 数据目录 | 否 | 配置文件所在目录下的 `data` |
| `data_dir` | Agent 数据目录 | 否 | 配置文件同级目录下的 `data` |
| `main_config_path` | OpenResty 主配置写入路径 | 否 | `data_dir/etc/nginx/nginx.conf` |
| `route_config_path` | 路由配置写入路径 | 否 | `data_dir/etc/nginx/conf.d/openflare_routes.conf` |
| `access_log_path` | OpenResty 访问日志路径 | 否 | `data_dir/var/log/openflare/access.log` |
@@ -201,7 +304,7 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
| `runtime_config_dir` | Agent 运行时配置写入目录，如 `pow_config.json` | 否 | `data_dir/etc/openflare` |
| `pages_dir` | Pages 静态部署包解压与当前部署目录 | 否 | `data_dir/var/lib/openflare/pages` |
| `mmdb_path` | WAF GeoIP mmdb 文件路径 | 否 | `data_dir/etc/openflare/GeoLite2-Country.mmdb` |
| `mmdb_update_interval` | WAF GeoIP mmdb 更新间隔 | 否 | `86400000` 毫秒 |
| `mmdb_update_interval` | WAF GeoIP mmdb 更新间隔 | 否 | `86400000` 毫秒 (24h) |
| `mmdb_download_url` | WAF GeoIP mmdb 下载地址 | 否 | 内置 GeoLite2 Country 下载地址 |
| `observability_buffer_path` | 观测补报缓冲文件路径 | 否 | `data_dir/var/lib/openflare/observability-buffer.json` |
| `observability_replay_minutes` | 自动补传最近观测窗口分钟数 | 否 | `15` |
@@ -209,41 +312,18 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒 |
| `request_timeout` | HTTP 请求超时 | 否 | `10000` 毫秒 |
说明：
---
* `agent_token` 与 `discovery_token` 不能同时为空。
* `heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串。
* Server 运行时配置 `AgentWebsocketUpgradeEnabled` 开启时，Agent 会在 HTTP 心跳成功后尝试升级为 WebSocket；连接失败或断开后自动退回 HTTP 心跳。
* 未配置 `openresty_path` 时默认调用 `openresty`。
* Agent 周期性健康检查会请求 `http://127.0.0.1:<openresty_observability_port>/openflare/stub_status`，不再通过高频 `openresty -t` 判断运行时健康；配置应用、启动恢复和 reload 前校验仍会执行 `openresty -t -c <main_config_path>`。
* Agent 会初始化并定期更新 `mmdb_path`，供 OpenResty WAF Lua 执行国家级地域规则；更新失败只记录警告，不阻断同步或 reload。
* 当激活配置引用 Pages 部署时，Agent 会在应用 OpenResty 配置前，将部署包下载、校验并解压到 `pages_dir`，OpenResty 通过该目录服务静态文件。
* 如果 `agent.json` 不存在，但 `OPENFLARE_SERVER_URL` 与 Token 等环境变量足够，Agent 可以直接启动；两者同时存在时环境变量优先。
* Agent 未配置 `node_ip` 时，会优先通过 `https://realip.cc` 获取真实出口公网 IP，适配 Docker/NAT 场景；该请求失败时，才退回本机网卡探测并优先选择公网 IPv4。
* Agent 自动探测到私网 `node_ip` 时，Server 会在注册/心跳阶段优先保留 Agent 直连来源的公网地址，避免 NAT/多网卡场景误登记内网网卡地址。
* 在管理端开启“锁定节点 IP”后，Server 会保留管理端填写的节点 IP，后续 Agent 注册、HTTP 心跳或 WebSocket 状态上报不会覆盖该字段；关闭锁定后，下一次上报可重新回填。
## Relay 环境变量与配置字段
## Relay 环境变量
### 环境变量
- `LOG_LEVEL`：Relay 日志等级，默认 `info`。
- 支持 `OPENFLARE_SERVER_URL`、`OPENFLARE_AGENT_TOKEN`、`OPENFLARE_DISCOVERY_TOKEN`、`OPENFLARE_NODE_NAME`、`OPENFLARE_NODE_IP`、`OPENFLARE_DATA_DIR`、`OPENFLARE_FRPS_PATH` 环境变量覆盖。
| 环境变量 | 作用 | 默认值 |
| --- | --- | --- |
| `LOG_LEVEL` | Relay 日志等级 | `info` |
| `OPENFLARE_SERVER_URL` | 控制面地址，可覆盖 `relay.json` | 空 |
| `OPENFLARE_AGENT_TOKEN` | 节点专属认证 Token，可覆盖 `relay.json` | 空 |
| `OPENFLARE_DISCOVERY_TOKEN` | 首次自动注册 Token，可覆盖 `relay.json` | 空 |
| `OPENFLARE_NODE_NAME` | 节点名称，可覆盖 `relay.json` | 空 |
| `OPENFLARE_NODE_IP` | 节点 IP，可覆盖 `relay.json` | 空 |
| `OPENFLARE_DATA_DIR` | Relay 数据目录，可覆盖 `relay.json` | 空 |
| `OPENFLARE_FRPS_PATH` | frps 二进制路径，可覆盖 `relay.json` | 空 |
## Relay 命令行参数
| 参数 | 作用 | 默认值 |
| --- | --- | --- |
| `-config` | 指定 Relay 配置文件路径 | `./relay.json` |
## Relay 配置字段
### 命令行参数
- `-config`：指定 Relay 配置文件路径，默认 `./relay.json`。
### 配置文件字段 (relay.json)
| 字段 | 作用 | 是否必填 | 默认值/行为 |
| --- | --- | --- | --- |
| `server_url` | 控制面地址 | 是 | 无 |
@@ -254,27 +334,21 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
| `frps_path` | frps 二进制路径 | 否 | `frps`（在系统 PATH 中寻找） |
| `data_dir` | Relay 运行时数据目录 | 否 | 配置文件所在目录下的 `data` |
| `state_path` | Relay 本地状态文件存储路径 | 否 | `data_dir/relay-state.json` |
| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒，支持 Go duration 字符串 |
| `request_timeout` | HTTP 请求超时 | 否 | `10000` 毫秒，支持 Go duration 字符串 |
| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒 |
| `request_timeout` | HTTP 请求超时 | 否 | `10000` 毫秒 |
## OpenFlared (Client) 环境变量
---
| 环境变量 | 作用 | 默认值 |
| --- | --- | --- |
| `LOG_LEVEL` | Client 日志等级 | `info` |
| `OPENFLARE_SERVER_URL` | 控制面地址，可覆盖 `flared.json` | 空 |
| `OPENFLARE_TUNNEL_TOKEN` | 隧道专属认证 Token，可覆盖 `flared.json` | 空 |
| `OPENFLARE_DATA_DIR` | Client 数据目录，可覆盖 `flared.json` | 空 |
| `OPENFLARE_FRPC_PATH` | frpc 二进制路径，可覆盖 `flared.json` | 空 |
## OpenFlared (Client) 环境变量与配置字段
## OpenFlared (Client) 命令行参数
### 环境变量
- `LOG_LEVEL`：Client 日志等级，默认 `info`。
- 支持 `OPENFLARE_SERVER_URL`、`OPENFLARE_TUNNEL_TOKEN`、`OPENFLARE_DATA_DIR`、`OPENFLARE_FRPC_PATH` 环境变量覆盖。
| 参数 | 作用 | 默认值 |
| --- | --- | --- |
| `-config` | 指定 Client 配置文件路径 | `./flared.json` |
## OpenFlared (Client) 配置字段
### 命令行参数
- `-config`：指定 Client 配置文件路径，默认 `./flared.json`。
### 配置文件字段 (flared.json)
| 字段 | 作用 | 是否必填 | 默认值/行为 |
| --- | --- | --- | --- |
| `server_url` | 控制面地址 | 是 | 无 |
@@ -282,103 +356,17 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
| `frpc_path` | frpc 二进制路径 | 否 | `frpc`（在系统 PATH 中寻找） |
| `data_dir` | Client 运行时数据目录 | 否 | 配置文件所在目录下的 `data` |
| `state_path` | Client 本地状态文件存储路径 | 否 | `data_dir/flared-state.json` |
| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒，支持 Go duration 字符串 |
| `sync_interval` | 配置拉取同步间隔 | 否 | `30000` 毫秒，支持 Go duration 字符串 |
| `request_timeout` | HTTP 请求超时 | 否 | `10000` 毫秒，支持 Go duration 字符串 |
## 常见配置组合
### 生产 Server + PostgreSQL
```bash
export JWT_SECRET='replace-with-a-long-random-string'
export DSN='postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable'
export GIN_MODE='release'
export LOG_LEVEL='info'
```
### 本地 Server + SQLite
```bash
export JWT_SECRET='dev-jwt-secret'
export SQLITE_PATH='./openflare-dev.db'
export LOG_LEVEL='debug'
go run .
```
### Agent + 默认 OpenResty
```json
{
"server_url": "http://your-server:3000",
"agent_token": "replace-with-node-auth-token",
"data_dir": "/opt/openflare-agent/data",
"openresty_path": "openresty",
"heartbeat_interval": 10000,
"request_timeout": 10000
}
```
### Agent + 自定义 OpenResty 路径
```json
{
"server_url": "http://your-server:3000",
"agent_token": "replace-with-node-auth-token",
"data_dir": "/var/lib/openflare-agent",
"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
"main_config_path": "/var/lib/openflare-agent/etc/nginx/nginx.conf",
"route_config_path": "/var/lib/openflare-agent/etc/nginx/conf.d/openflare_routes.conf",
"access_log_path": "/var/lib/openflare-agent/var/log/openflare/access.log",
"cert_dir": "/var/lib/openflare-agent/etc/nginx/certs",
"lua_dir": "/var/lib/openflare-agent/etc/nginx/lua",
"runtime_config_dir": "/var/lib/openflare-agent/etc/openflare",
"pages_dir": "/var/lib/openflare-agent/var/lib/openflare/pages",
"heartbeat_interval": 10000,
"request_timeout": 10000
}
```
### Relay (中继端) 默认配置
`relay.json`：
```json
{
"server_url": "http://your-server:3000",
"agent_token": "replace-with-relay-auth-token",
"frps_path": "frps",
"data_dir": "/opt/openflare-relay/data",
"heartbeat_interval": 10000,
"request_timeout": 10000
}
```
### OpenFlared (内网客户端) 默认配置
`flared.json`：
```json
{
"server_url": "http://your-server:3000",
"tunnel_token": "replace-with-tunnel-token",
"frpc_path": "frpc",
"data_dir": "/opt/openflared/data",
"heartbeat_interval": 10000,
"sync_interval": 30000,
"request_timeout": 10000
}
```
| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒 |
| `sync_interval` | 配置拉取同步间隔 | 否 | `30000` 毫秒 |
| `request_timeout` | HTTP 请求超时 | 否 | `10000` 毫秒 |
---
## 维护要求
以下内容变化时，必须同步更新本文档：
* Server 命令行参数。
* Server 环境变量。
* Agent 命令行参数与配置字段。
* Relay 命令行参数与配置字段。
* Client 命令行参数与配置字段。
* 任一配置项的默认值、用途或示例。
- Server 命令行参数。
- Server 环境变量。
- SystemConfig 数据库系统配置字段（新增、修改、废弃）。
- Agent / Relay / Client 的命令行参数与配置字段。
- 任何配置项的默认值、用途或配置示例。