diff --git a/README.en.md b/README.en.md index 5855bf8f..5dc6a46f 100644 --- a/README.en.md +++ b/README.en.md @@ -1,155 +1,219 @@ -

- 中文 | English -

- -
- -# OpenFlare - -_✨ control plane for reverse proxy management ✨_ - -
- -

- - license - - - release - - - release - - - GoReportCard - -

- -## Repository layout - -- `openflare_server`: Gin + GORM + SQLite control plane, including admin API, Agent API and Web UI -- `openflare_agent`: single-binary Go Agent for registration, heartbeat, config sync and OpenResty reload -- `docs`: design, development guidelines, implementation plan and deployment docs - -## Quick start - -### 1. Start the Server - -The fastest way is to run the published GHCR image with Docker Compose: - -```yaml -services: - openflare: - image: ghcr.io/rain-kl/openflare:latest - container_name: openflare - restart: unless-stopped - ports: - - "3000:3000" - environment: - SESSION_SECRET: replace-with-random-string - SQLITE_PATH: /data/openflare.db - GIN_MODE: release - volumes: - - openflare-data:/data - -volumes: - openflare-data: -``` - -```bash -docker compose up -d -``` - -Default URL: `http://localhost:3000` - -Notes: - -* Replace `SESSION_SECRET` with a random string -* Replace `latest` with a fixed version tag if needed, for example `ghcr.io/rain-kl/openflare:v0.3.0` -* SQLite data is persisted in the Docker volume `openflare-data` -* For source build and full deployment steps, see [docs/deployment.md](./docs/deployment.md) - -### 1.1 Server environment variables - -Common environment variables: - -| Variable | Description | Default behavior | -| --- | --- | --- | -| `PORT` | Server listen port | Defaults to `3000` | -| `GIN_MODE` | Gin runtime mode | Runs in release mode unless set to `debug` | -| `SESSION_SECRET` | Session signing secret; should be set explicitly in production | Falls back to the built-in default | -| `SQLITE_PATH` | SQLite database file path | Uses the built-in SQLite path | -| `SQL_DSN` | MySQL DSN; when set, MySQL is used instead of SQLite | Uses SQLite when unset | -| `REDIS_CONN_STRING` | Redis connection string for session/rate-limit related features | Redis is disabled when unset | -| `UPLOAD_PATH` | Upload directory path | Defaults to `upload` | -| `AGENT_TOKEN` | Legacy/global Agent token compatibility setting | Not required in the current default setup | - -Example: - -```bash -export SESSION_SECRET='replace-with-random-string' -export SQLITE_PATH='./openflare.db' -export GIN_MODE='release' -export PORT='3000' -``` - -### 2. Install Agent with Discovery Token - -Use this for first-time node bootstrap. The Agent will auto-register with `discovery_token` and exchange it for a node-specific `agent_token`. - -```bash -curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \ - --server-url http://your-server:3000 \ - --discovery-token YOUR_DISCOVERY_TOKEN -``` - -### 3. Install Agent with Agent Token - -Use this when the node has already been created in the control plane and you already have a dedicated `agent_token`. - -```bash -curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \ - --server-url http://your-server:3000 \ - --agent-token YOUR_AGENT_TOKEN -``` - -Notes: - -* Replace `--server-url` with your actual control plane address, for example `http://192.168.1.10:3000` -* On Linux, the installer defaults to `/opt/openflare-agent` and creates the `openflare-agent` systemd service -* Re-running the same command upgrades the Agent to the latest release - -## Delivery channels +

+ 中文 | English +

-Current release outputs: - -* Server binaries: GitHub Releases -* Server Docker image: GitHub Container Registry at `ghcr.io/rain-kl/openflare` -* Agent binaries: GitHub Releases +
+ OpenFlare logo + +# OpenFlare + +A lightweight, self-hosted OpenResty control plane for reverse proxy management, configuration rollout, node sync, TLS assets, and practical observability. + +
+ +

+ + license + + + release + + + ghcr + + + GoReportCard + +

+ +OpenFlare `1.0.0` is the current stable baseline. Phase six is complete and fully shipped; the repository documentation now focuses on the living system rather than historical implementation notes. + +## Why It Exists + +OpenFlare is built for a simple but recurring operational need: + +* manage domain-to-origin reverse proxy rules from one control plane +* publish immutable OpenResty configuration versions +* let Agents pull, validate, reload, and roll back safely +* manage certificates, domains, node credentials, and version state +* expose practical dashboards for traffic, node health, and rollout status + +It is not trying to be a CDN SaaS platform, a multi-tenant control plane, or a general-purpose logging system. + +## Core Capabilities + +* Versioned configuration with preview, publish, activate, and rollback +* Node onboarding with `discovery_token` or per-node `agent_token` +* Automated Agent apply flow with `openresty -t`, reload, and rollback +* Managed OpenResty templates, performance settings, and cache settings +* TLS certificate and domain management with exact and wildcard matching +* Request analytics, node snapshots, and health event reporting +* Controlled Server and Agent upgrade flows +* A production frontend built with Next.js App Router, React 19, and Tailwind CSS 4 + +## Architecture + +```text +OpenFlare Server (Gin + GORM + SQLite + Web UI) + | + | HTTP API / Config Pull + v +OpenFlare Agent (register / heartbeat / sync / apply / update) + | + v +Local OpenResty or Docker OpenResty + | + v +Origin +``` + +Responsibilities: + +* `openflare_server`: admin UI, management APIs, Agent APIs, rendering, rollout, and state storage +* `openflare_agent`: node registration, heartbeat, sync, local apply, validation, reload, rollback, and self-update +* `openflare_server/web`: the production admin frontend, exported statically and served by the Go server + +## UI Preview + +### Dashboard Overview + +![OpenFlare dashboard overview](./docs/assets/readme/dashboard-overview.png) + +### Node Detail and Install Command + +![OpenFlare node detail](./docs/assets/readme/node-detail.png) + +### Version Release Workflow + +![OpenFlare version release](./docs/assets/readme/version-release.png) + +## Quick Start + +### 1. Start the Server + +```yaml +services: + openflare: + image: ghcr.io/rain-kl/openflare:latest + restart: unless-stopped + ports: + - "3000:3000" + environment: + SESSION_SECRET: replace-with-random-string + SQLITE_PATH: /data/openflare.db + GIN_MODE: release + LOG_LEVEL: info + PORT: "3000" + volumes: + - openflare-data:/data + +volumes: + openflare-data: +``` + +```bash +docker compose up -d +``` + +Open `http://localhost:3000` + +Default credentials: + +* Username: `root` +* Password: `123456` + +### 2. Install an Agent + +First-time registration with `discovery_token`: + +```bash +curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \ + --server-url http://your-server:3000 \ + --discovery-token YOUR_DISCOVERY_TOKEN +``` + +Registration with a per-node `agent_token`: + +```bash +curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \ + --server-url http://your-server:3000 \ + --agent-token YOUR_AGENT_TOKEN +``` + +The installer writes to `/opt/openflare-agent` by default, creates `openflare-agent.service`, and can be re-run for reinstall or upgrade. + +### 3. Publish Your First Config + +1. Sign in and create a reverse proxy rule +2. Review the preview or diff +3. Activate the new version +4. Wait for Agents to pick it up on the next heartbeat + +Version numbers follow `YYYYMMDD-NNN`. Versions are immutable; rollback is implemented by reactivating an older version. + +## Repository Layout + +* `openflare_server`: monolithic control plane built with Gin, GORM, and SQLite +* `openflare_server/web`: admin frontend built with Next.js 15 App Router +* `openflare_agent`: Go Agent +* `scripts`: install and helper scripts +* `docs`: design, guidelines, deployment, and configuration docs + +## Local Development + +### Server + +```bash +cd openflare_server +export SESSION_SECRET='replace-with-random-string' +export SQLITE_PATH='./openflare.db' +go run . +``` + +### Frontend + +```bash +cd openflare_server/web +corepack enable +pnpm install +pnpm build +``` + +### Agent + +```bash +cd openflare_agent +go run ./cmd/agent -config /path/to/agent.json +``` + +### Useful Checks + +```bash +cd openflare_server +GOCACHE=/tmp/openflare-go-cache go test ./... +``` + +```bash +cd openflare_agent +GOCACHE=/tmp/openflare-go-cache go test ./... +``` + +## Admin Surface + +The admin UI currently covers: + +* reverse proxy rules +* config versions +* node management +* apply logs +* TLS certificates +* domain management +* user management +* settings +* version upgrades + +Swagger UI is available at `/swagger/index.html` after login. ## License -OpenFlare is licensed under the [Apache License 2.0](./LICENSE) and ships with a repository-level [NOTICE](./NOTICE). - -If you redistribute modified versions, keep the license text, copyright notices and any required NOTICE attributions. - -## Contributing - -Before contributing, please read the project docs listed below. - -Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion in this repository is provided under Apache License 2.0. - -## Documentation - -See: - -1. [docs/deployment.md](./docs/deployment.md) -2. [docs/design.md](./docs/design.md) -3. [docs/development-guidelines.md](./docs/development-guidelines.md) -4. [docs/development-plan.md](./docs/development-plan.md) - -Frontend notes: - -* The new admin frontend lives in `openflare_server/web` -* `pnpm` is the default package manager -* `pnpm build` exports static assets into `openflare_server/web/build` +OpenFlare is released under the [Apache License 2.0](./LICENSE). diff --git a/README.md b/README.md index 7143103a..0acd7259 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ # OpenFlare -轻量、自托管的反向代理控制面，用于管理 Nginx 配置发布、节点同步、TLS 证书与版本回滚。 +轻量、自托管的 OpenResty 控制面，用于管理反向代理规则、配置发布、节点同步、TLS 证书与基础可观测能力。 @@ -26,39 +26,55 @@

-## 项目定位 +OpenFlare `1.0.0` 是当前稳定基线。第六版开发工作已经完成，相关能力已并入正式版，仓库文档不再保留阶段性实施记录，而只维护当前有效的设计、约束和部署方式。 -OpenFlare 当前定位为内部自用的反向代理控制面，不面向外部租户提供 CDN SaaS 能力。 +## 为什么存在 -它解决的是一套更直接的运维问题： +OpenFlare 解决的是一类朴素但高频的运维问题： -* 在管理端维护域名到源站的反代规则 -* 生成完整 Nginx 配置并发布激活版本 +* 在一个管理端里维护域名到源站的反向代理规则 +* 生成完整 OpenResty 配置并以不可变版本发布 * 让节点侧 Agent 自动拉取、校验、reload 与失败回滚 -* 托管 TLS 证书、管理节点与版本状态 -* 用更统一的 Web UI 完成日常运维操作 +* 统一托管证书、域名、节点凭证与版本状态 +* 提供足够实用的总览、节点详情与访问分析能力 -当前明确不做多租户、复杂缓存平台、对象存储依赖、灰度分组发布等平台化扩展。详细边界见 [docs/design.md](./docs/design.md)。 +它不是 CDN SaaS，也不试图在 1.0 阶段演变成多租户平台、日志平台或通用调度系统。 ## 核心能力 -* 反向代理规则管理：一个域名对应一个源站地址，统一维护、统一发布 * 配置版本化：支持预览、发布、激活、历史回滚，版本不可变 * 节点接入：支持全局 `discovery_token` 首次接入，也支持节点专属 `agent_token` * Agent 自动应用：周期性同步、落盘、`openresty -t`、`openresty -s reload`、失败自动回滚 -* 节点观测：Agent 会向受管 OpenResty 注入 Lua 观测脚本，按 heartbeat 上报最近窗口请求、错误、UV 与连接指标 +* OpenResty 托管：统一管理主配置模板、性能参数、缓存参数与受管路由 * TLS 与域名管理：支持证书托管、域名资产维护、精确匹配与通配符匹配 -* 运维能力：配置变更摘要、Agent 运行参数下发、Agent 正式版自动更新与 preview 手动升级、Server 正式版 GitHub 自升级、Server preview 手动检查升级、Server 手动上传二进制确认升级 -* 管理端 UI：基于 Next.js App Router + React 19 + Tailwind CSS 4 的新版前端 +* 访问与节点观测：支持请求窗口聚合、状态码分布、来源分布、节点资源与健康事件展示 +* 版本运维：支持 Server 与 Agent 的正式版升级，以及受控的 preview 检查与手动升级 +* 管理端 UI：基于 Next.js App Router、React 19、Tailwind CSS 4 的正式前端 + +## 系统架构 + +```text +OpenFlare Server (Gin + GORM + SQLite + Web UI) + | + | HTTP API / Config Pull + v +OpenFlare Agent (register / heartbeat / sync / apply / update) + | + v +Local OpenResty or Docker OpenResty + | + v +Origin +``` + +职责划分： + +* `openflare_server`：管理端 UI、管理 API、Agent API、配置渲染、版本发布与状态存储 +* `openflare_agent`：节点注册、心跳、同步、本地写入、校验、reload、回滚、自更新 +* `openflare_server/web`：新版管理端前端，静态导出后由 Go Server 托管 ## 界面预览 -以下图片当前为占位文件，后续你可以直接替换同名文件： - -* `docs/assets/readme/dashboard-overview.svg` -* `docs/assets/readme/node-detail.svg` -* `docs/assets/readme/version-release.svg` - ### 仪表盘总览 ![OpenFlare dashboard overview](./docs/assets/readme/dashboard-overview.png) @@ -71,39 +87,9 @@ OpenFlare 当前定位为内部自用的反向代理控制面，不面向外部 ![OpenFlare version release](./docs/assets/readme/version-release.png) -## 系统架构 - -```text -OpenFlare Server (Gin + GORM + SQLite + Web UI) - | - | HTTP API / Config Pull - v -OpenFlare Agent (register / heartbeat / sync / apply / update) - | - v -Local Nginx or Docker Nginx - | - v -Origin -``` - -职责划分： - -* `openflare_server`：管理端 UI、管理 API、Agent API、配置渲染、发布与激活、状态存储 -* `openflare_agent`：节点注册、心跳、同步、本地文件写入、Nginx 校验、reload、回滚、自更新 -* `openflare_server/web`：新版管理端前端，静态导出后由 Go Server 托管 - -## 仓库结构 - -* `openflare_server`：Gin + GORM + SQLite 单体控制面 -* `openflare_server/web`：Next.js 15 App Router 管理端前端 -* `openflare_agent`：Go 单体 Agent -* `scripts`：安装脚本与辅助脚本 -* `docs`：设计、开发规范、部署、配置项等文档 - ## 快速开始 -### 1. 通过 Docker Compose 启动 Server +### 1. 启动 Server ```yaml services: @@ -136,9 +122,9 @@ docker compose up -d * 用户名：`root` * 密码：`123456` -### 2. 使用 Discovery Token 一键接入 Agent +### 2. 接入 Agent -适用于新节点首次接入，Agent 会自动注册并换取节点专属 `agent_token`。 +使用 `discovery_token` 首次接入： ```bash curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \ @@ -146,9 +132,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst --discovery-token YOUR_DISCOVERY_TOKEN ``` -### 3. 使用 Agent Token 一键接入 Agent - -适用于已经在管理端预创建节点、并拿到节点专属 `agent_token` 的场景。 +使用节点专属 `agent_token`： ```bash curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \ @@ -156,74 +140,24 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst --agent-token YOUR_AGENT_TOKEN ``` -说明： +安装脚本默认写入 `/opt/openflare-agent`，创建 `openflare-agent.service`，并可重复执行以重装或升级 Agent。 -* `--server-url` 替换为实际控制面地址，例如 `http://192.168.1.10:3000` -* 默认安装目录为 `/opt/openflare-agent` -* 脚本会创建 `openflare-agent.service` 并启动 systemd 服务 -* 重复执行安装命令可用于重装或升级 Agent 到最新 Release -* 重装时会先删除整个安装目录，再重新生成 `agent.json`、本地状态和二进制；旧数据不会保留 +### 3. 发布第一份配置 -## 典型使用流程 +1. 登录管理端并新增反代规则 +2. 在发布前查看预览或变更摘要 +3. 激活新版本 +4. 等待 Agent 在后续 heartbeat 中拉取并应用配置 -1. 启动 Server 并登录管理端 -2. 新增或编辑反代规则 -3. 预览配置或查看变更摘要 -4. 发布并激活新的配置版本 -5. Agent 在后续同步中拉取激活版本 -6. Agent 本地执行 `nginx -t` -7. 校验成功后执行 `nginx -s reload` -8. 若失败则自动回滚并上报最终结果 +版本号格式固定为 `YYYYMMDD-NNN`，历史版本不可变，回滚通过重新激活旧版本完成。 -版本号格式固定为 `YYYYMMDD-NNN`，历史版本不可变，回滚通过重新激活旧版本实现。 +## 仓库结构 -## 部署与交付 - -当前仓库的交付形式： - -* Server 二进制发布到 GitHub Releases -* Server Docker 镜像发布到 GitHub Container Registry：`ghcr.io/rain-kl/openflare` -* Agent 二进制发布到 GitHub Releases - -Docker 镜像工作流仅构建 `openflare_server`，并产出 `linux/amd64` 与 `linux/arm64` 多架构镜像。 - -## 常用配置 - -### Server 环境变量 - -| 环境变量 | 作用 | 默认值 | -| --- | --- | --- | -| `PORT` | Server 监听端口 | `3000` | -| `GIN_MODE` | Gin 运行模式 | 非 `debug` 时按 release | -| `SESSION_SECRET` | Session 签名密钥 | 启动时随机生成 | -| `SQLITE_PATH` | SQLite 数据库文件路径 | `openflare.db` | -| `SQL_DSN` | MySQL DSN，设置后优先于 SQLite | 空 | -| `UPLOAD_PATH` | 上传目录 | `upload` | - -### 前端构建变量 - -| 环境变量 | 作用 | 默认值 | -| --- | --- | --- | -| `NEXT_PUBLIC_API_BASE_URL` | 前端请求 API 的基础路径 | `/api` | -| `NEXT_PUBLIC_APP_VERSION` | 前端展示版本号 | `dev` | - -### Agent 核心配置 - -| 字段 | 作用 | -| --- | --- | -| `server_url` | 控制面地址 | -| `agent_token` | 节点专属认证 Token | -| `discovery_token` | 首次自动注册使用的全局 Token | -| `data_dir` | Agent 托管数据目录 | -| `cert_dir` | Agent 存放受管证书文件的目录 | -| `lua_dir` | Agent 存放受管 Lua 观测脚本的目录；启动时自动覆盖释放 | -| `openresty_observability_port` | Agent 读取 OpenResty Lua 本地观测指标的 loopback 端口 | -| `observability_buffer_path` | Agent 本地观测补报缓冲文件路径 | -| `observability_replay_minutes` | Agent 恢复 heartbeat 后允许自动补传的最近观测窗口分钟数 | -| `nginx_path` | 本机 Nginx 路径，设置后走本机模式 | -| `nginx_container_name` | Docker 模式下的 Nginx 容器名 | - -完整配置项说明见 [docs/app-config.md](./docs/app-config.md)。 +* `openflare_server`：Gin + GORM + SQLite 单体控制面 +* `openflare_server/web`：Next.js 15 App Router 管理端前端 +* `openflare_agent`：Go 单体 Agent +* `scripts`：安装脚本与辅助脚本 +* `docs`：设计、规范、部署与配置文档 ## 本地开发 @@ -294,22 +228,4 @@ GOCACHE=/tmp/openflare-go-cache go test ./... ## 开源协议 -本项目采用 [Apache License 2.0](./LICENSE) 开源，并附带仓库级 [NOTICE](./NOTICE)。 - -这意味着你可以在遵守 Apache 2.0 条款的前提下使用、修改和分发 OpenFlare；如果你分发修改版，请保留许可证、版权声明和必要的 NOTICE 信息。 - -## 贡献开发 - -参与开发前请先阅读： - -* [docs/design.md](./docs/design.md) -* [docs/development-guidelines.md](./docs/development-guidelines.md) -* [docs/frontend-development-guidelines.md](./docs/frontend-development-guidelines.md) - -约束摘要： - -* 超出设计边界的改动，先更新设计文档再编码 -* Server 继续保持单体结构，不为简单需求引入额外基础设施 -* 前端统一位于 `openflare_server/web`，请求层统一收敛到 `lib/api/` -* 新代码默认遵循当前正式基线，不回退到旧版 CRA / Semantic UI 结构 -* 除非贡献说明中另有明确约定，向本仓库提交的代码、文档或其他内容，默认按 Apache License 2.0 授权 +本项目采用 [Apache License 2.0](./LICENSE) 开源。 \ No newline at end of file diff --git a/docs/app-config.md b/docs/app-config.md index 0027c7d6..03b1d4a7 100644 --- a/docs/app-config.md +++ b/docs/app-config.md @@ -1,387 +1,151 @@ -# OpenFlare 配置项说明 - -本文档汇总当前 OpenFlare Server 与 Agent 在启动、部署和运行时支持的参数、环境变量与配置文件字段，并说明其作用、默认值和示例。 - ---- - -## 1. Server 配置 - -Server 当前支持两类启动配置： - -1. 命令行参数 -2. 环境变量 - -此外，部分运行时参数已迁入数据库 `Option` 表，可在管理端设置页中热更新，例如 Agent 运行参数与限流阈值。 - -第五版（0.5.x）继续复用 `Option` 表承载 OpenResty 性能优化参数与缓存参数，不单独引入新的配置中心。 - -### 1.1 Server 命令行参数 - -启动示例： - -```bash -cd openflare_server -go run . --port 3000 --log-dir ./logs -``` - -或在编译后二进制中使用： - -```bash -./openflare --port 3000 --log-dir ./logs -``` - -支持的命令行参数： - -| 参数 | 作用 | 默认值 | 示例 | -| --- | --- | --- | --- | -| `--port` | 指定 Server 监听端口 | `3000` | `--port 3000` | -| `--log-dir` | 指定日志目录；设置后会自动创建目录并写入日志 | 空，默认输出到 stdout | `--log-dir ./logs` | -| `--version` | 输出当前版本后退出 | `false` | `./openflare --version` | -| `--help` | 输出帮助信息后退出 | `false` | `./openflare --help` | - -说明： - -* 当同时设置 `PORT` 环境变量与 `--port` 时，运行时优先使用 `PORT` -* `--log-dir` 当前没有对应环境变量，适合源码运行或 systemd 方式部署时使用 - -### 1.2 Server 环境变量 - -源码启动示例： - -```bash -cd openflare_server -export SESSION_SECRET='replace-with-random-string' -export SQLITE_PATH='./openflare.db' -export GIN_MODE='release' -export LOG_LEVEL='info' -export PORT='3000' -go run . -``` - -Docker Compose 示例： - -```yaml -services: - openflare: - image: ghcr.io/rain-kl/openflare:latest - restart: unless-stopped - ports: - - "3000:3000" - environment: - SESSION_SECRET: replace-with-random-string - SQLITE_PATH: /data/openflare.db - GIN_MODE: release - LOG_LEVEL: info - PORT: "3000" - volumes: - - openflare-data:/data - -volumes: - openflare-data: -``` - -支持的环境变量： - -| 环境变量 | 作用 | 默认值 | 示例 | -| --- | --- | --- | --- | -| `PORT` | 指定 Server 实际监听端口 | `3000` | `PORT=3000` | -| `GIN_MODE` | 指定 Gin 运行模式；仅当值为 `debug` 时启用 debug，其余情况按 release 运行 | 非 `debug` 默认按 release 运行 | `GIN_MODE=release` | -| `LOG_LEVEL` | 指定系统日志等级；支持 `debug`/`info`/`warn`/`error`（`warning` 兼容为 `warn`） | `info` | `LOG_LEVEL=warn` | -| `SESSION_SECRET` | Session 签名密钥；生产环境必须显式设置，避免重启后会话失效 | 启动时随机生成 UUID | `SESSION_SECRET=replace-with-random-string` | -| `SQLITE_PATH` | SQLite 数据库文件路径 | `openflare.db` | `SQLITE_PATH=/data/openflare.db` | -| `SQL_DSN` | MySQL DSN；设置后优先使用 MySQL，而不是 SQLite | 未设置时使用 SQLite | `SQL_DSN=user:pass@tcp(127.0.0.1:3306)/openflare` | -| `REDIS_CONN_STRING` | Redis 连接串；设置后启用 Redis，用于 Session/限流相关能力 | 未设置时关闭 Redis | `REDIS_CONN_STRING=redis://default:pass@127.0.0.1:6379/0` | -| `UPLOAD_PATH` | 上传文件目录 | `upload` | `UPLOAD_PATH=/data/upload` | -| `AGENT_TOKEN` | 全局 Agent Token 兼容配置；当前默认部署不依赖该变量 | 空 | `AGENT_TOKEN=legacy-shared-token` | - -说明： - -* `SQL_DSN` 与 `SQLITE_PATH` 同时存在时，优先使用 `SQL_DSN` -* `SESSION_SECRET` 未固定时，每次重启都会生成新的随机值，已登录用户的 Cookie 会失效 -* `LOG_LEVEL` 未设置或设置为不支持的值时，将回退为 `info` -* `REDIS_CONN_STRING` 未配置时，相关能力将回退为进程内实现 -* `UPLOAD_PATH` 目录在启动时若不存在会自动创建 - -### 1.2.1 设置页可热更新的运行时配置 - -以下配置不依赖环境变量，保存在数据库 `Option` 表中，可在管理端设置页的「运维设置」中调整，并在保存后立即生效： - -| 配置项 | 作用 | 默认值 | -| --- | --- | --- | +# OpenFlare 配置项说明 + +本文档汇总 OpenFlare `1.0.0` 当前支持的 Server 与 Agent 配置项，只保留仍然有效的启动、部署与运行参数。 + +## 1. Server 配置 + +Server 支持三类配置来源： + +1. 命令行参数 +2. 环境变量 +3. 数据库 `Option` 表中的运行时配置 + +### 1.1 命令行参数 + +```bash +cd openflare_server +go run . --port 3000 --log-dir ./logs +``` + +| 参数 | 作用 | 默认值 | +| --- | --- | --- | +| `--port` | 指定 Server 监听端口 | `3000` | +| `--log-dir` | 指定日志目录 | 空 | +| `--version` | 输出当前版本后退出 | `false` | +| `--help` | 输出帮助信息后退出 | `false` | + +### 1.2 环境变量 + +| 环境变量 | 作用 | 默认值 | +| --- | --- | --- | +| `PORT` | Server 监听端口 | `3000` | +| `GIN_MODE` | Gin 运行模式 | 非 `debug` 时按 release | +| `LOG_LEVEL` | 日志等级 | `info` | +| `SESSION_SECRET` | Session 签名密钥 | 启动时随机生成 | +| `SQLITE_PATH` | SQLite 数据库文件路径 | `openflare.db` | +| `SQL_DSN` | MySQL DSN，设置后优先于 SQLite | 空 | +| `REDIS_CONN_STRING` | Redis 连接串 | 空 | +| `UPLOAD_PATH` | 上传目录 | `upload` | +| `AGENT_TOKEN` | 兼容旧部署的全局 Agent Token | 空 | + +说明： + +* `SQL_DSN` 与 `SQLITE_PATH` 同时存在时优先使用 `SQL_DSN` +* `SESSION_SECRET` 生产环境必须显式配置 +* `REDIS_CONN_STRING` 未配置时，相关能力回退为进程内实现 + +### 1.3 `Option` 表中的运行时配置 + +以下配置由管理端设置页维护，可热更新： + +| 配置项 | 作用 | 默认值 | +| --- | --- | --- | | `AgentHeartbeatInterval` | Agent 心跳间隔（毫秒） | `10000` | -| `NodeOfflineThreshold` | 节点离线判定阈值（毫秒） | `120000` | +| `NodeOfflineThreshold` | 节点离线阈值（毫秒） | `120000` | | `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/OpenFlare` | -| `GeoIPProvider` | 节点/IP 归属解析方式；支持 `disabled`、`mmdb`、`ip-api`、`geojs`、`ipinfo` | `ipinfo` | -| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口（秒） | `300` / `180` | -| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口（秒） | `300` / `180` | -| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口（秒） | `50` / `60` | -| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口（秒） | `50` / `60` | -| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 登录、注册、验证码等敏感接口限流次数 / 时间窗口（秒） | `100` / `1200` | - -说明： - -* 限流窗口上限不能超过 `RateLimitKeyExpirationDuration`，当前为 20 分钟 -* 限流按来源 IP 统计，若前置了 Nginx/CDN/LB，应正确透传真实客户端 IP -* `GeoIPProvider=mmdb` 时，Server 会按需下载并使用本地 MaxMind Country 数据库；其余非 `disabled` 选项会直接请求对应外部 GeoIP 服务 -* 管理端“日志 -> 访问记录”中的访客 IP 归属地入库固定使用 MaxMind mmdb，不跟随 `GeoIPProvider` 切换 - -### 1.2.2 第五版当前支持的 OpenResty 优化配置项 - -以下配置项当前已接入管理端「运维设置」，并统一保存在 `Option` 表中。它们会参与第五版后续的配置渲染与发布链路；当前阶段优先完成参数录入、默认值和校验能力。 - -| 配置项 | 作用 | 计划默认值 | -| --- | --- | --- | -| `OpenRestyWorkerProcesses` | `worker_processes` 配置；支持 `auto` 或正整数 | `auto` | -| `OpenRestyWorkerConnections` | `events { worker_connections }` 上限 | `4096` | -| `OpenRestyWorkerRlimitNofile` | `worker_rlimit_nofile` 上限 | `65535` | -| `OpenRestyEventsUse` | `events { use ... }` 指令；为空表示不显式渲染 | 空 | -| `OpenRestyEventsMultiAcceptEnabled` | 是否启用 `multi_accept on` | `false` | -| `OpenRestyKeepaliveTimeout` | `keepalive_timeout` 秒数 | `65` | -| `OpenRestyKeepaliveRequests` | `keepalive_requests` 上限 | `1000` | -| `OpenRestyClientHeaderTimeout` | `client_header_timeout` 秒数 | `15` | -| `OpenRestyClientBodyTimeout` | `client_body_timeout` 秒数 | `15` | -| `OpenRestySendTimeout` | `send_timeout` 秒数 | `30` | -| `OpenRestyProxyConnectTimeout` | `proxy_connect_timeout` 秒数 | `5` | -| `OpenRestyProxySendTimeout` | `proxy_send_timeout` 秒数 | `60` | -| `OpenRestyProxyReadTimeout` | `proxy_read_timeout` 秒数 | `60` | -| `OpenRestyWebsocketEnabled` | 是否自动注入 WebSocket 升级所需代理头 | `true` | -| `OpenRestyProxyRequestBufferingEnabled` | 是否启用 `proxy_request_buffering` | `false` | -| `OpenRestyProxyBufferingEnabled` | 是否启用 `proxy_buffering` | `true` | -| `OpenRestyProxyBuffers` | `proxy_buffers` 组合值，例如 `16 16k` | `16 16k` | -| `OpenRestyProxyBufferSize` | `proxy_buffer_size` | `8k` | -| `OpenRestyProxyBusyBuffersSize` | `proxy_busy_buffers_size` | `64k` | -| `OpenRestyGzipEnabled` | 是否启用 `gzip on` | `true` | -| `OpenRestyGzipMinLength` | `gzip_min_length` 字节数 | `1024` | -| `OpenRestyGzipCompLevel` | `gzip_comp_level` | `5` | -| `OpenRestyCacheEnabled` | 是否启用代理缓存 | `false` | -| `OpenRestyCachePath` | `proxy_cache_path` 目录 | 空 | -| `OpenRestyCacheLevels` | `proxy_cache_path levels=` 值 | `1:2` | -| `OpenRestyCacheInactive` | `proxy_cache_path inactive=` 时长 | `30m` | -| `OpenRestyCacheMaxSize` | `proxy_cache_path max_size=` 大小 | `1g` | -| `OpenRestyCacheKeyTemplate` | 缓存 Key 模板 | `$scheme$proxy_host$request_uri` | -| `OpenRestyCacheLockEnabled` | 是否启用 `proxy_cache_lock` | `true` | -| `OpenRestyCacheLockTimeout` | `proxy_cache_lock_timeout` 时长 | `5s` | -| `OpenRestyCacheUseStale` | `proxy_cache_use_stale` 场景列表 | `error timeout updating http_500 http_502 http_503 http_504` | - -说明： - -* 第五版第一批当前仅开放稳定、可校验、可回滚的常用性能项；更多指令后续按相同模式扩展 -* 所有大小、时长、布尔和整数参数都应在 Server 保存前完成校验 -* `OpenRestyCacheEnabled=false` 时，缓存目录与缓存参数应允许留空或回退到默认值 -* 任何包含路径的配置项都必须在 Agent 落盘前再次校验可写性与安全边界 - -### 1.3 前端构建环境变量 +| `GeoIPProvider` | 节点/IP 归属解析方式 | `ipinfo` | +| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口 | `300` / `180` | +| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口 | `300` / `180` | +| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口 | `50` / `60` | +| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口 | `50` / `60` | +| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 敏感接口限流次数 / 时间窗口 | `100` / `1200` | -新版管理端位于 `openflare_server/web`，构建时支持以下公开环境变量： - -| 环境变量 | 作用 | 默认值 | 示例 | -| --- | --- | --- | --- | -| `NEXT_PUBLIC_API_BASE_URL` | 前端请求后端 API 的基础路径；默认走同源 `/api` | `/api` | `NEXT_PUBLIC_API_BASE_URL=https://demo.example.com/api` | -| `NEXT_PUBLIC_APP_VERSION` | 构建时注入前端展示版本号 | `dev` | `NEXT_PUBLIC_APP_VERSION=v0.4.0` | -| `NEXT_DEV_BACKEND_URL` | 前端开发服务器通过反向代理转发 `/api/*` 时使用的后端地址；仅开发模式使用 | `http://127.0.0.1:3000` | `NEXT_DEV_BACKEND_URL=http://127.0.0.1:3300` | +### 1.4 OpenResty 参数 -说明： +OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前常用项包括： -* `NEXT_PUBLIC_*` 变量会在前端构建阶段读取，并打包进静态资源 -* `NEXT_DEV_BACKEND_URL` 仅在本地开发服务器模式下使用，不会进入静态导出产物 -* 推荐生产环境继续使用同源部署，优先保持 `NEXT_PUBLIC_API_BASE_URL=/api` -* `pnpm start` 会以开发模式启动前端，默认监听 `3001`，并通过 `NEXT_DEV_BACKEND_URL` 将 `/api/*` 代理到后端 - ---- - -## 2. Agent 配置 - -Agent 当前支持两类启动配置： - -1. 命令行参数 -2. `agent.json` 配置文件 - -当前 Agent 仅支持少量环境变量用于日志输出控制；核心启动行为仍由 `-config` 参数和配置文件字段决定。 +* `OpenRestyWorkerProcesses` +* `OpenRestyWorkerConnections` +* `OpenRestyWorkerRlimitNofile` +* `OpenRestyKeepaliveTimeout` +* `OpenRestyProxyConnectTimeout` +* `OpenRestyProxySendTimeout` +* `OpenRestyProxyReadTimeout` +* `OpenRestyProxyBufferingEnabled` +* `OpenRestyGzipEnabled` +* `OpenRestyCacheEnabled` +* `OpenRestyCachePath` +* `OpenRestyCacheMaxSize` -### 2.1.1 Agent 环境变量 +这类参数必须以结构化方式校验、保存并参与版本渲染。 -支持的环境变量： +### 1.5 前端构建环境变量 -| 环境变量 | 作用 | 默认值 | 示例 | +| 环境变量 | 作用 | 默认值 | +| --- | --- | --- | +| `NEXT_PUBLIC_API_BASE_URL` | 前端请求 API 的基础路径 | `/api` | +| `NEXT_PUBLIC_APP_VERSION` | 前端展示版本号 | `dev` | +| `NEXT_DEV_BACKEND_URL` | 本地开发服务器代理的后端地址 | `http://127.0.0.1:3000` | + +## 2. Agent 配置 + +Agent 当前支持： + +1. `-config` 命令行参数 +2. `agent.json` 配置文件 +3. 少量日志相关环境变量 + +### 2.1 Agent 环境变量 + +| 环境变量 | 作用 | 默认值 | +| --- | --- | --- | +| `LOG_LEVEL` | Agent 日志等级 | `info` | + +### 2.2 Agent 命令行参数 + +| 参数 | 作用 | 默认值 | +| --- | --- | --- | +| `-config` | 指定 Agent 配置文件路径 | `./agent.json` | + +### 2.3 Agent 配置字段 + +| 字段 | 作用 | 是否必填 | 默认值/行为 | | --- | --- | --- | --- | -| `LOG_LEVEL` | 指定 Agent 的 `slog` 日志等级；支持 `debug`/`info`/`warn`/`error`（`warning` 兼容为 `warn`） | `info` | `LOG_LEVEL=debug` | +| `server_url` | 控制面地址 | 是 | 无 | +| `agent_token` | 节点专属认证 Token | 与 `discovery_token` 二选一 | 空 | +| `discovery_token` | 首次自动注册使用的全局 Token | 与 `agent_token` 二选一 | 空 | +| `node_name` | 节点名称 | 否 | 自动使用主机名 | +| `node_ip` | 节点 IP | 否 | 自动探测 | +| `openresty_path` | 本机 OpenResty 路径 | 否 | 空，未设置时走 Docker 模式 | +| `openresty_container_name` | Docker 模式下的容器名 | 否 | `openflare-openresty` | +| `openresty_docker_image` | Docker 模式下的镜像 | 否 | `openresty/openresty:alpine` | +| `openresty_observability_port` | 本地观测端口 | 否 | `18081` | +| `docker_binary` | Docker 可执行文件名或路径 | 否 | `docker` | +| `data_dir` | Agent 数据目录 | 否 | 配置文件所在目录下的 `data` | +| `main_config_path` | OpenResty 主配置写入路径 | 否 | 本机模式建议显式配置 | +| `route_config_path` | 路由配置写入路径 | 否 | `data_dir/etc/nginx/conf.d/openflare_routes.conf` | +| `cert_dir` | 本机证书写入目录 | 否 | `data_dir/etc/nginx/certs` | +| `openresty_cert_dir` | OpenResty 读取证书目录 | 否 | 随运行模式变化 | +| `lua_dir` | 本机 Lua 脚本写入目录 | 否 | `data_dir/etc/nginx/lua` | +| `openresty_lua_dir` | OpenResty 读取 Lua 目录 | 否 | 随运行模式变化 | +| `observability_buffer_path` | 观测补报缓冲文件路径 | 否 | `data_dir/var/lib/openflare/observability-buffer.json` | +| `observability_replay_minutes` | 自动补传最近观测窗口分钟数 | 否 | `15` | +| `state_path` | Agent 本地状态文件路径 | 否 | `data_dir/var/lib/openflare/agent-state.json` | +| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒 | +| `request_timeout` | HTTP 请求超时 | 否 | `10000` 毫秒 | 说明： -* `LOG_LEVEL` 只影响 Agent 本地日志输出，不改变心跳、同步或配置行为 -* 未设置或设置为不支持的值时，将回退为 `info` +* `agent_token` 与 `discovery_token` 不能同时为空 +* `heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串 +* 未配置 `openresty_path` 时默认使用 Docker OpenResty 模式 -### 2.1 Agent 命令行参数 - -启动示例： - -```bash -cd openflare_agent -go run ./cmd/agent -config ./agent.json -``` - -或编译后二进制： - -```bash -./openflare-agent -config /path/to/agent.json -``` - -支持的命令行参数： - -| 参数 | 作用 | 默认值 | 示例 | -| --- | --- | --- | --- | -| `-config` | 指定 Agent 配置文件路径 | `./agent.json` | `-config /etc/openflare/agent.json` | - -### 2.2 Agent 配置文件示例 - -推荐最小配置： - -```json -{ - "server_url": "http://127.0.0.1:3000", - "discovery_token": "replace-with-global-discovery-token", - "data_dir": "./data", - "openresty_container_name": "openflare-openresty", - "openresty_docker_image": "openresty/openresty:alpine", - "openresty_observability_port": 18081, - "observability_replay_minutes": 15, - "heartbeat_interval": 10000, - "request_timeout": 10000 -} -``` - -使用节点专属 Token 的示例： - -```json -{ - "server_url": "http://127.0.0.1:3000", - "agent_token": "replace-with-node-auth-token", - "node_name": "node-01", - "node_ip": "192.168.1.20", - "data_dir": "./data", - "openresty_path": "/usr/local/openresty/nginx/sbin/openresty", - "main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf", - "route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf", - "cert_dir": "/usr/local/openresty/nginx/conf/certs", - "openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs", - "lua_dir": "/usr/local/openresty/nginx/conf/lua", - "openresty_lua_dir": "/usr/local/openresty/nginx/conf/lua", - "openresty_observability_port": 18081, - "observability_buffer_path": "./data/observability-buffer.json", - "observability_replay_minutes": 15, - "state_path": "./data/agent-state.json", - "heartbeat_interval": 10000, - "request_timeout": 10000 -} -``` - -### 2.3 Agent 配置字段 - -| 字段 | 作用 | 是否必填 | 默认值/行为 | 示例 | -| --- | --- | --- | --- | --- | -| `server_url` | 控制面地址，Agent 所有注册、心跳、同步请求都会发往这里 | 是 | 无 | `http://127.0.0.1:3000` | -| `agent_token` | 节点专属认证 Token | 与 `discovery_token` 二选一 | 空 | `node-token-xxx` | -| `discovery_token` | 全局发现 Token，用于节点首次自动注册 | 与 `agent_token` 二选一 | 空 | `discovery-token-xxx` | -| `node_name` | 节点名称 | 否 | 自动使用主机名 | `node-01` | -| `node_ip` | 节点 IP | 否 | 自动探测第一个可用 IPv4 | `192.168.1.20` | -| `openresty_path` | 本机 OpenResty 可执行文件路径；设置后按本机 OpenResty 模式运行 | 否 | 空；未设置时按 Docker OpenResty 模式处理 | `/usr/local/openresty/nginx/sbin/openresty` | -| `openresty_container_name` | Docker 模式下的 OpenResty 容器名 | 否 | `openflare-openresty` | `openflare-openresty` | -| `openresty_docker_image` | Docker 模式下用于初始化/管理的 OpenResty 镜像 | 否 | `openresty/openresty:alpine` | `openresty/openresty:alpine` | -| `openresty_observability_port` | Agent 注入的 OpenResty 本地观测端口；用于 heartbeat 前读取 Lua 窗口指标和 `stub_status`，默认仅监听 `127.0.0.1` | 否 | `18081` | `18081` | -| `docker_binary` | Docker 可执行文件名或路径 | 否 | `docker` | `/usr/bin/docker` | -| `data_dir` | Agent 数据目录，用于存储托管配置、证书和状态文件 | 否 | 配置文件所在目录下的 `data` 子目录 | `./data` | -| `main_config_path` | 第五版主配置接管时 OpenResty 主配置文件写入路径 | 第五版本机模式建议必填 | Docker 模式可使用受管默认路径；本机模式建议显式设置 | `/usr/local/openresty/nginx/conf/nginx.conf` | -| `route_config_path` | 路由配置文件写入路径 | 否 | 默认为 `data_dir` 下托管路径 | `/etc/nginx/conf.d/openflare_routes.conf` | -| `cert_dir` | Agent 在本机写入受管证书文件的目录 | 否 | 默认为 `data_dir` 下托管 certs 目录 | `./data/etc/nginx/certs` | -| `openresty_cert_dir` | OpenResty 实际读取受管证书文件的目录 | 否 | 本机模式默认等于 `cert_dir`；Docker 模式默认 `/etc/nginx/openflare-certs` | `/usr/local/openresty/nginx/conf/certs` | -| `lua_dir` | Agent 在本机写入受管 Lua 观测脚本的目录；每次启动都会覆盖释放 | 否 | 默认为 `data_dir` 下托管 lua 目录 | `./data/etc/nginx/lua` | -| `openresty_lua_dir` | OpenResty 实际读取受管 Lua 观测脚本的目录 | 否 | 本机模式默认等于 `lua_dir`；Docker 模式默认 `/etc/nginx/openflare-lua` | `/usr/local/openresty/nginx/conf/lua` | -| `observability_buffer_path` | Agent 本地观测补报缓冲文件路径；用于在 server 短暂离线时按时间窗口落盘待补传数据 | 否 | 默认为 `data_dir` 下托管观测缓冲文件 | `./data/var/lib/openflare/observability-buffer.json` | -| `observability_replay_minutes` | Agent 恢复心跳后允许批量补传的最近观测窗口时长（分钟） | 否 | `15` | `30` | -| `state_path` | Agent 本地状态文件路径 | 否 | 默认为 `data_dir` 下托管状态文件 | `./data/agent-state.json` | -| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒 | `10000` | -| `request_timeout` | HTTP 请求超时时间 | 否 | `10000` 毫秒 | `10000` | - -说明： - -* `agent_token` 与 `discovery_token` 不能同时为空 -* `heartbeat_interval`、`request_timeout` 支持两种写法： - * 毫秒整数，例如 `10000` - * Go duration 字符串，例如 `"30s"` -* `node_name` 与 `node_ip` 未填写时会自动探测；若自动探测失败，配置校验会报错 -* 未配置 `openresty_path` 时，默认为 Docker OpenResty 模式 -* `openresty_observability_port` 默认仅绑定本地回环地址；若节点本机已有端口冲突，可改为其他未占用端口 -* `observability_replay_minutes` 只控制“允许补传最近多少分钟的窗口”；超出该窗口的历史观测会在本地自动裁剪 -* 配置保存时，`agent_version`、`nginx_version` 由程序运行时维护，不需要写入 JSON -* 第五版主配置接管完成后，本机模式下应优先通过 `main_config_path` 由 Agent 写入受管主配置，而不是依赖节点手工维护 include 规则 - -### 2.4 Agent 托管路径默认值 - -当未显式设置以下字段时，Agent 会根据 `data_dir` 自动生成托管路径： - -| 字段 | 默认值 | -| --- | --- | -| `main_config_path` | 第五版 Docker 模式默认可落在 `data_dir/etc/nginx/nginx.conf`；本机模式建议显式配置 | -| `route_config_path` | `data_dir/etc/nginx/conf.d/openflare_routes.conf` | -| `cert_dir` | `data_dir/etc/nginx/certs` | -| `lua_dir` | `data_dir/etc/nginx/lua` | -| `observability_buffer_path` | `data_dir/var/lib/openflare/observability-buffer.json` | -| `state_path` | `data_dir/var/lib/openflare/agent-state.json` | - -Docker OpenResty 模式下： - -| 字段 | 默认值 | -| --- | --- | -| `openresty_cert_dir` | `/etc/nginx/openflare-certs` | -| `openresty_lua_dir` | `/etc/nginx/openflare-lua` | +## 3. 维护要求 -补充说明： +以下内容变化时，必须同步更新本文档： -* Agent 会在每次启动时把受管 Lua 观测脚本覆盖释放到 `lua_dir`，不再由 Server 随配置版本下发 -* OpenResty 通过 `openresty_lua_dir` 读取这些本地脚本，并在每次 heartbeat 前通过 `http://127.0.0.1:/openflare/observability` 读取最近窗口请求指标 -* 若 server 短暂离线，Agent 会把最近窗口观测先写入 `observability_buffer_path`，待 heartbeat 恢复后按时间窗口批量补传最近 `observability_replay_minutes` 分钟的数据 -* 同一端口还会暴露仅本机可访问的 `stub_status`，用于采集 OpenResty 活动连接数 - -### 2.5 Agent 启动示例 - -#### Docker OpenResty 模式 - -适用于节点本机不直接管理宿主机 OpenResty，而是通过 Docker 容器运行 OpenResty。 - -```json -{ - "server_url": "http://127.0.0.1:3000", - "discovery_token": "replace-with-global-discovery-token", - "data_dir": "./data" -} -``` - -#### 本机 OpenResty 模式 - -适用于节点已经安装了宿主机 OpenResty，且 Agent 直接执行 `openresty -t` 与 `openresty -s reload`。 - -```json -{ - "server_url": "http://127.0.0.1:3000", - "agent_token": "replace-with-node-auth-token", - "openresty_path": "/usr/local/openresty/nginx/sbin/openresty", - "main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf", - "route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf", - "cert_dir": "/usr/local/openresty/nginx/conf/certs", - "openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs", - "lua_dir": "/usr/local/openresty/nginx/conf/lua", - "openresty_lua_dir": "/usr/local/openresty/nginx/conf/lua" -} -``` - ---- - -## 3. 配置维护要求 - -当以下内容发生变化时，应同步更新本文档： - -* Server 新增/删除命令行参数 -* Server 新增/删除环境变量 -* Agent 新增/删除命令行参数 -* Agent 新增/删除配置文件字段 -* 任一配置项的默认值、示例或用途发生变化 +* Server 命令行参数 +* Server 环境变量 +* Agent 命令行参数 +* Agent 配置字段 +* 任一配置项的默认值、用途或示例 diff --git a/docs/deployment.md b/docs/deployment.md index f931570f..fd24d194 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,64 +1,37 @@ -# OpenFlare 部署说明 - -本文档仅保留当前可用基线的最小部署方式，并补充第五版（0.5.x）开发期间与 OpenResty 主配置接管相关的联调约束。 - ---- - -## 1. 前置条件 - +# OpenFlare 部署说明 + +本文档只保留 OpenFlare `1.0.0` 的当前部署基线、联调入口与升级方式。 + +## 1. 前置条件 + ### 1.1 Server * Go 1.24+ * Node.js 18+ * 可写 SQLite 文件目录 - + ### 1.2 Agent * Go 1.23+ * 对 Agent 数据目录有写权限 -* 若使用独立 OpenResty 模式：可执行 `openresty -t` 与 `openresty -s reload` -* 若使用 Docker 模式：具备 Docker 执行权限 -* 第五版主配置接管模式下，Agent 对 OpenResty 主配置目标路径必须具备写权限 - ---- - -## 2. Server 启动 - +* 本机模式下可执行 `openresty -t` 与 `openresty -s reload` +* Docker 模式下具备 Docker 执行权限 + +## 2. 启动 Server + ### 2.1 构建前端 -```bash -cd openflare_server/web -corepack enable -pnpm install -pnpm build -``` - -说明： - -* 前端使用 Next.js 静态导出模式构建 -* `pnpm build` 会生成供 Go Server 托管的 `openflare_server/web/build` 目录 -* 如需覆盖默认接口地址，可在构建前设置 `NEXT_PUBLIC_API_BASE_URL` - -### 2.1.1 本地前端热更新开发 - -在本地联调时，可单独启动前端开发服务器： - ```bash cd openflare_server/web corepack enable pnpm install -pnpm dev +pnpm build ``` -说明： +`pnpm build` 会生成供 Go Server 托管的静态产物。 -* `pnpm dev` 默认以 Next.js 开发模式启动，监听 `http://127.0.0.1:3001` -* 开发服务器会通过同源代理把 `/api/*` 的 HTTP 与 WebSocket 请求统一转发到 `NEXT_DEV_BACKEND_URL`，默认指向 `http://127.0.0.1:3000` -* 如需改后端地址，可在启动前设置 `NEXT_DEV_BACKEND_URL` -* 这种模式用于本地热更新开发；正式运行和交付仍以 `pnpm build` 后由 Go Server 托管为准 +### 2.2 源码启动 -### 2.2 启动服务 - ```bash cd openflare_server export SESSION_SECRET='replace-with-random-string' @@ -66,109 +39,66 @@ export SQLITE_PATH='./openflare.db' export LOG_LEVEL='info' go run . ``` - -说明： - -* 默认不依赖全局 `AGENT_TOKEN` -* 节点接入凭证由数据库维护：节点专属 `agent_token` + 全局 `discovery_token` -* 默认监听端口为 `3000` -* `LOG_LEVEL` 支持 `debug` / `info` / `warn` / `error` - -### 2.3 使用 docker-compose 启动 Server - -适用于直接使用已发布的 Server 镜像部署控制面。 - -示例 `docker-compose.yml`： - -```yaml -services: - openflare: - image: ghcr.io/rain-kl/openflare:latest - container_name: openflare - restart: unless-stopped - ports: - - "3000:3000" - environment: - SESSION_SECRET: replace-with-random-string - SQLITE_PATH: /data/openflare.db - GIN_MODE: release - volumes: - - openflare-data:/data - -volumes: - openflare-data: -``` - -启动命令： - -```bash -docker compose up -d -``` - -说明： - -* `SESSION_SECRET` 必须替换为随机字符串 -* SQLite 数据文件持久化到 Docker volume `openflare-data` -* 镜像默认监听容器内 `3000` 端口 -* 若要固定版本，可将 `latest` 替换为具体 tag，例如 `ghcr.io/rain-kl/openflare:v0.3.0` - -版本升级说明： - -* Root 用户可在管理端顶栏点击「版本」默认检查正式版 GitHub Release -* 若需尝试 preview 版本，可在同一弹窗中手动检查 preview 发布并选择是否升级 -* 当前运行的是 Release 二进制且二进制目录可写时，可直接在弹窗内触发 Server 自升级 -* Server 自升级会下载匹配当前平台的 `openflare-server-*` 资产，替换当前二进制并自动重启进程 -* 也可在同一弹窗中手动上传 Server 二进制，服务端先检测上传文件版本，前端确认后再执行替换与重启 -* 节点 Agent 默认仅跟随正式版自动更新；如需 preview 版本，可在节点详情中手动检查 preview 发布并下发更新 - -### 2.4 首次登录 - -访问 `http://localhost:3000` - -默认账号： - -* 用户名：`root` -* 密码：`123456` - -### 2.5 Swagger 文档使用 - -登录管理端后，访问：`http://localhost:3000/swagger/index.html` - -使用说明： - -* Swagger UI 受管理端登录态保护，未登录不可直接访问 -* 可在浏览器中查看当前 Server API 与 Agent API 定义，并直接发起调试请求 -* 当 Server API 新增或变更时，需要同步更新 Swag 注解并重新生成 `openflare_server/docs` - -如需在本地重新生成 Swagger 文档，先安装 `swag`： - -```bash -go install github.com/swaggo/swag/cmd/swag@latest -``` - -安装后请确保 Go 的二进制目录已加入 `PATH`，常见目录为： - -* Linux / macOS：`$HOME/go/bin` -* Windows：`%USERPROFILE%\go\bin` - -如需在本地重新生成 Swagger 文档，可在 `openflare_server` 目录执行： - -```bash -swag init -g main.go -o docs -``` - ---- - -## 3. Agent 配置 - -当前支持两种接入模式。 - -### 3.1 节点专属 `agent_token` - -```json -{ - "server_url": "http://127.0.0.1:3000", - "agent_token": "replace-with-node-auth-token", + +默认监听 `3000` 端口。 + +### 2.3 Docker Compose 启动 + +```yaml +services: + openflare: + image: ghcr.io/rain-kl/openflare:latest + container_name: openflare + restart: unless-stopped + ports: + - "3000:3000" + environment: + SESSION_SECRET: replace-with-random-string + SQLITE_PATH: /data/openflare.db + GIN_MODE: release + LOG_LEVEL: info + volumes: + - openflare-data:/data + +volumes: + openflare-data: +``` + +```bash +docker compose up -d +``` + +### 2.4 首次登录 + +访问 `http://localhost:3000` + +默认账号： + +* 用户名：`root` +* 密码：`123456` + +### 2.5 Swagger + +登录管理端后访问：`http://localhost:3000/swagger/index.html` + +如需在本地重新生成文档： + +```bash +go install github.com/swaggo/swag/cmd/swag@latest +cd openflare_server +swag init -g main.go -o docs +``` + +## 3. Agent 配置 + +当前支持两种接入模式。 + +### 3.1 使用节点专属 `agent_token` + +```json +{ + "server_url": "http://127.0.0.1:3000", + "agent_token": "replace-with-node-auth-token", "data_dir": "./data", "openresty_container_name": "openflare-openresty", "openresty_docker_image": "openresty/openresty:alpine", @@ -177,100 +107,9 @@ swag init -g main.go -o docs "heartbeat_interval": 10000, "request_timeout": 10000 } -``` - -### 3.2 全局 `discovery_token` - -```json -{ - "server_url": "http://127.0.0.1:3000", - "discovery_token": "replace-with-global-discovery-token", - "data_dir": "./data", - "openresty_container_name": "openflare-openresty", - "openresty_docker_image": "openresty/openresty:alpine", - "openresty_observability_port": 18081, - "observability_replay_minutes": 15, - "heartbeat_interval": 10000, - "request_timeout": 10000 -} -``` - -说明： - -* `agent_version` 由 Agent 代码内常量提供，升级时同步修改代码 -* 为兼容现有 Agent / Server API，运行时版本仍通过 `openresty_version` 字段上报，但其值现在表示 OpenResty 版本 -* 时间字段使用毫秒整数 -* `agent_token` 与 `discovery_token` 至少填写一个 -* 若 `agent_token` 为空且 `discovery_token` 存在，Agent 会自动注册并写回新的专属 `agent_token` -* `node_name` 与 `node_ip` 可省略，未填写时自动探测 -* 未配置 `openresty_path` 时，默认使用 Docker OpenResty 容器 -* Agent 会在受管 OpenResty 中注入 Lua 观测脚本，并通过 `openresty_observability_port` 对本机暴露最近窗口指标与 `stub_status` -* Agent 还会把最近 `observability_replay_minutes` 分钟内未成功上报的观测窗口落盘到本地缓冲文件，待 server 恢复后自动批量补传 - -### 3.3 第五版新增部署约束 - -第五版开发完成后，OpenResty 主配置将进入 Agent 受管范围。部署与联调时应满足： - -* 本机 OpenResty 模式需要为 Agent 显式提供主配置文件写入路径 -* Docker OpenResty 模式需要保证主配置、路由配置和证书目录位于同一套受管挂载路径中 -* Docker OpenResty 模式会额外挂载一个仅本机可访问的 `127.0.0.1:` 观测端口，用于 Agent 在 heartbeat 前抓取 Lua 窗口指标 -* Docker / 本机两种模式都会在 `data_dir/var/lib/openflare/observability-buffer.json` 保留最近待补传窗口；若节点磁盘是临时盘，重启后该缓冲也会丢失 -* 节点现存手工维护的主配置如继续保留，必须先迁移为 Server 渲染模板的等价配置，再切换到受管模式 -* 主配置切换前必须预留回滚副本，并通过一次 `openresty -t` 失败演练验证回滚 - ---- - -## 4. Agent 启动 - -### 4.1 直接运行 - -```bash -cd openflare_agent -export LOG_LEVEL='info' -go run ./cmd/agent -config /path/to/agent.json ``` - -### 4.2 编译后二进制运行 - -```bash -cd openflare_agent -go build -o openflare-agent ./cmd/agent -export LOG_LEVEL='info' -./openflare-agent -config /path/to/agent.json -``` - ---- - -## 5. 最小联调步骤 - -### 5.1 准备节点接入 - -二选一： - -* 在管理端预创建节点并复制专属 `agent_token` -* 在管理端查看全局 `discovery_token` 并写入节点配置 - -### 5.2 创建规则并发布 - -1. 在管理端新增一条启用中的反代规则 -2. 在发布前查看预览或变更摘要 -3. 生成并激活新版本 - -### 5.3 验证 Agent 应用 - -预期行为： -1. Agent 完成心跳 -2. 自动注册模式下完成 Token 置换 -3. 心跳响应返回激活版本摘要；若版本或 checksum 不一致，则拉取激活版本 -4. 写入主配置、路由配置与必要证书文件 -5. 执行 `openresty -t` -6. 执行 `openresty -s reload` -7. 上报应用结果 - -### 5.3.1 Docker OpenResty 模式最小验证 - -建议使用最小 `agent.json`： +### 3.2 使用全局 `discovery_token` ```json { @@ -279,242 +118,102 @@ export LOG_LEVEL='info' "data_dir": "./data", "openresty_container_name": "openflare-openresty", "openresty_docker_image": "openresty/openresty:alpine", - "openresty_observability_port": 18081 + "openresty_observability_port": 18081, + "observability_replay_minutes": 15, + "heartbeat_interval": 10000, + "request_timeout": 10000 } ``` -验证点： +说明： -1. 首次启动后确认 `data/etc/nginx/nginx.conf`、`data/etc/nginx/conf.d/openflare_routes.conf`、`data/etc/nginx/certs` 与 `data/etc/nginx/lua` 已由 Agent 创建 -2. 确认容器实际挂载了主配置、路由目录、证书目录和 Lua 目录 -3. 确认宿主机本地可访问 `http://127.0.0.1:18081/openflare/observability` 与 `http://127.0.0.1:18081/openflare/stub_status` -3. 在管理端发布一次新版本后，确认节点 `current_version` 追平激活版本 -4. 在节点详情查看“当前目标版本”与“最近应用”，确认主配置/路由配置快照和 checksum 已可见 +* `agent_token` 与 `discovery_token` 至少填写一个 +* 未配置 `openresty_path` 时默认使用 Docker OpenResty +* Agent 会暴露本机观测端口并在 server 恢复后补传最近窗口数据 -推荐检查命令： +## 4. 启动 Agent + +### 4.1 直接运行 ```bash -docker inspect openflare-openresty -docker exec openflare-openresty openresty -t +cd openflare_agent +export LOG_LEVEL='info' +go run ./cmd/agent -config /path/to/agent.json ``` -说明： +### 4.2 编译后二进制运行 -* `docker inspect` 重点确认主配置文件、`conf.d` 目录、证书目录和 Lua 目录都来自 Agent 受管路径 -* 观测端口默认只绑定 `127.0.0.1`；若节点已有冲突，可在 `agent.json` 中调整 `openresty_observability_port` -* 若容器名使用默认值，请将上述命令中的名称替换为 `openflare-openresty` - -### 5.3.2 本机 OpenResty 模式最小验证 - -建议显式提供以下路径： - -```json -{ - "server_url": "http://127.0.0.1:3000", - "agent_token": "replace-with-node-auth-token", - "openresty_path": "/usr/local/openresty/nginx/sbin/openresty", - "main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf", - "route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf", - "cert_dir": "/usr/local/openresty/nginx/conf/certs", - "openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs", - "lua_dir": "/usr/local/openresty/nginx/conf/lua", - "openresty_lua_dir": "/usr/local/openresty/nginx/conf/lua", - "openresty_observability_port": 18081 -} +```bash +cd openflare_agent +go build -o openflare-agent ./cmd/agent +export LOG_LEVEL='info' +./openflare-agent -config /path/to/agent.json ``` -验证点： +## 5. 最小联调步骤 -1. 发布前先备份 `main_config_path` 与 `route_config_path` -2. 首次发布后执行 `openresty -t`，确认主配置已由 Server 模板接管且 include 指向 Agent 写入的路由文件 -3. 确认本机可访问 `http://127.0.0.1:18081/openflare/observability` 与 `http://127.0.0.1:18081/openflare/stub_status` -4. 再次发布修改后的规则或 OpenResty 参数，确认 `openresty -s reload` 成功且节点版本更新 -5. 在节点详情与应用记录页确认主配置 checksum、路由配置 checksum 和支持文件数已上报 - -### 5.4 验证管理端状态 - -管理端应能看到： - -* 节点在线状态 -* 节点当前版本 -* 最近一次应用结果 -* 自动注册后节点已绑定专属 `agent_token` - -### 5.5 验证失败回滚 - -人为制造 `openresty -t` 失败后再次发布，预期： +1. 在管理端准备 `agent_token` 或 `discovery_token` +2. 启动 Agent 并确认节点上线 +3. 新增一条启用中的反代规则 +4. 生成并激活新版本 +5. 确认 Agent 拉取配置、执行 `openresty -t`、reload 并上报结果 -* Agent 回滚旧配置 -* 主配置与路由配置一起回滚 -* 节点 `last_error` 更新 -* 应用记录中出现失败记录 +预期管理端可看到： -### 5.5.1 建议的失败演练方式 +* 节点在线状态 +* 节点当前版本 +* 最近一次应用结果 +* 自动注册后的专属 `agent_token` -建议只在测试节点进行，避免直接污染生产节点。 +## 6. 升级说明 -本机 OpenResty 模式： +* Root 用户可在管理端顶栏检查并升级 Server 正式版 +* 如需尝试 preview 版本，可手动检查对应发布 +* 节点 Agent 默认只跟随正式版自动更新；preview 升级需要手动触发 +* 也可通过上传 Server 二进制的方式执行确认升级 -1. 先备份当前 `agent.json` -2. 将 `openresty_path` 临时改为一个包装脚本，在收到 `-t` 时固定返回非零，其余参数转发到真实 `openresty` -3. 触发一次新版本发布，确认应用失败、主配置与路由配置回滚、节点 `last_error` 更新 -4. 恢复真实 `openresty_path` 后再次发布，确认节点重新追平版本 +## 7. 常用验证命令 -Docker OpenResty 模式： +### 7.1 Server -1. 在测试节点上保留默认受管路径 -2. 临时将 `openresty_docker_image` 指向一个不包含 `openresty` 运行时的错误镜像标签，或在测试环境用包装镜像让 `openresty -t` 固定失败 -3. 再次发布，确认节点应用失败但 `data/etc/nginx/nginx.conf` 与 `data/etc/nginx/conf.d/openflare_routes.conf` 已回滚为旧版本 -4. 恢复正确镜像后重新发布，确认节点恢复健康 +```bash +cd openflare_server +GOCACHE=/tmp/openflare-go-cache go test ./... +``` -说明： +### 7.2 Agent -* 第五版的失败演练重点不在“如何制造错误”，而在确认失败后旧主配置、旧路由配置和支持文件都会被一起恢复 -* 若不方便做真实环境演练，至少应运行 Agent 回归测试，覆盖主配置写入、Docker 挂载与失败回滚 - ---- - -## 6. 常用验证命令 - -### 6.1 Server - -```bash -cd openflare_server -GOCACHE=/tmp/openflare-go-cache go test ./... -``` - -### 6.2 Agent - -```bash -cd openflare_agent -GOCACHE=/tmp/openflare-go-cache go test ./... -``` - -### 6.3 前端 - -```bash -cd openflare_server/web -pnpm build -``` - -### 6.4 发布工作流 - -当前仓库维护两套独立的 Release 工作流： - -* GitHub 使用 [.github/workflows/release.yml](.github/workflows/release.yml)，保留制品上传/下载分阶段流程 -* Gitea 使用 [.gitea/workflows/release.yml](.gitea/workflows/release.yml)，在单个 Job 内完成前端构建、服务端/Agent 多平台编译与 Release 发布，避免依赖 Gitea 目前不兼容的 `upload-artifact@v4`、`download-artifact@v4` - -Docker 镜像发布使用 [.github/workflows/docker-image.yml](.github/workflows/docker-image.yml)： - -* 仅构建 `openflare_server` 服务端镜像 -* 发布到 GitHub Container Registry（`ghcr.io//:`） -* 单个工作流通过分架构原生构建再合并 manifest 的方式产出 `linux/amd64` 与 `linux/arm64` 多架构镜像，避免 `arm64` 长时间模拟编译 - ---- - -## 7. Agent 一键部署（V3） - -### 7.1 curl 安装 - -在目标机器上运行： - -```bash -curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \ - --server-url http://your-server:3000 \ - --discovery-token YOUR_DISCOVERY_TOKEN -``` - -支持参数： - -| 参数 | 说明 | 默认值 | -| ------------------- | -------------------- | --------------------- | -| `--server-url` | Server 地址（必填） | - | -| `--discovery-token` | 全局 Discovery Token | - | -| `--agent-token` | 节点专属 Token | - | -| `--install-dir` | 安装目录 | `/opt/openflare-agent` | -| `--repo` | GitHub Release 仓库 | `Rain-kl/OpenFlare` | -| `--no-service` | 不创建 systemd 服务 | - | - -安装脚本会： +```bash +cd openflare_agent +GOCACHE=/tmp/openflare-go-cache go test ./... +``` -1. 从 GitHub Releases 下载最新 Agent 二进制（`openflare-agent-{os}-{arch}`） -2. 若检测到已存在安装目录，会先停止运行中的 `openflare-agent` 服务并删除整个安装目录 -3. 先下载到临时文件，再写入全新的安装目录，避免覆盖运行中进程导致写入失败 -4. 生成 `agent.json` 配置文件 -5. 创建 systemd 服务 `openflare-agent.service` -6. 启动并启用自启 +### 7.3 Frontend -说明： +```bash +cd openflare_server/web +pnpm build +``` -* 脚本可重复执行，用于重装或升级到最新 Release -* 若检测到已运行的 `openflare-agent` systemd 服务，会先停止服务、清空安装目录，再重新安装 -* 重装会删除旧的 `agent.json`、本地状态、缓存数据和旧二进制，因此节点会按新的 Token 或 Discovery Token 重新接入 - -### 7.2 管理端生成部署命令 - -在管理端 **系统设置 → 运维设置** 中查看已生成的一键部署命令，直接复制到目标节点执行。 - -### 7.3 Agent 自动更新 - -Agent 自动更新默认为关闭。 - -在管理端 **节点管理** 页面中可以： - -* 为单个节点开启「自动更新」 -* 为单个节点点击「立即更新」，下发一次性更新指令 - -节点在收到对应心跳响应后，会检查 GitHub Releases，发现新版本时自动下载并重启。 - ---- - -## 8. Agent 二进制命名规则 - -GitHub Release 中的 Agent 二进制命名格式： - -* `openflare-agent-linux-amd64` -* `openflare-agent-linux-arm64` -* `openflare-agent-darwin-arm64` - ---- - -## 9. 运维设置热更新（V3） - -以下参数可通过管理端 **运维设置** 修改，修改后通过心跳响应下发到 Agent，无需重启： - -| 参数 | 说明 | Agent 字段 | -| ---------------------- | -------------------- | ------------------ | -| AgentHeartbeatInterval | 心跳间隔（毫秒） | heartbeat_interval | -| NodeOfflineThreshold | 节点离线阈值（毫秒） | - | -| AgentUpdateRepo | 自动更新仓库 | update_repo | - -节点管理页下发的字段： - -| 参数 | 说明 | Agent 字段 | -| ---------------------- | ------------------ | ----------- | -| Node.AutoUpdateEnabled | 节点是否自动更新 | auto_update | -| Node.UpdateRequested | 节点一次性更新请求 | update_now | - ---- - -## 10. 第五版性能优化联调重点 - -第五版联调时，至少补以下验证： - -* 调整连接类参数后，能成功生成新版本并由 Agent 应用 -* 启用或关闭代理缓存后，主配置预览、diff 与实际落盘一致 -* 缓存目录、缓存大小、失效时间等参数非法时，Server 拒绝保存 -* 主配置渲染异常或 `openresty -t` 失败时，Agent 不应留下半更新状态 -* 本机模式与 Docker 模式都要验证一次主配置接管 - ---- - -## 11. 当前已知限制 - -* Docker 模式仍是 MVP 级封装 -* 联调以手工步骤为主 - ---- - -## 12. 文档维护要求 - -当部署方式、配置字段、节点接入方式或联调流程变化时，同步更新本文档。 +## 8. Agent 一键部署 + +```bash +curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \ + --server-url http://your-server:3000 \ + --discovery-token YOUR_DISCOVERY_TOKEN +``` + +支持参数： + +* `--server-url` +* `--discovery-token` +* `--agent-token` +* `--install-dir` +* `--repo` +* `--no-service` + +安装脚本会下载最新 Agent、生成 `agent.json`、创建 `openflare-agent.service` 并启动服务。 + +## 9. 文档维护要求 + +部署方式、升级方式、接入模式或联调流程变化时，同步更新本文档和 `README.md`。 diff --git a/docs/design.md b/docs/design.md index 59903281..b0f9cc40 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,108 +1,63 @@ # OpenFlare 设计基线 -## 1. 文档目的 +本文档定义 OpenFlare `1.0.0` 之后仍然有效的产品边界、系统结构与长期约束。第六版已经完成并并入正式版；过程性设计不再在这里维护。 -本文档只保留 OpenFlare 当前有效的产品边界、系统结构与稳定约束。 +## 1. 产品定位 -当前状态： +OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景，解决反向代理配置、节点同步、证书托管与基础观测的统一管理问题。 -* 第一版、第二版、第三版均已完成 -* 前端改造已完成，`openflare_server/web` 新版工程已成为正式基线 -* 第五版（0.5.x）已完成，OpenResty 反代、缓存性能优化与主配置接管已落地 -* 第六版（0.6.x）已立项，目标聚焦节点流量数据采集、访问分析与数据看板升级 -* 已完成阶段的实现细节以代码与 Git 历史为准，不再在本文档中维护过程性设计 - ---- - -## 2. 产品定位 - -OpenFlare 当前定位为内部自用的反向代理控制面，不面向外部租户提供 CDN SaaS 能力。 - -当前核心能力： +当前稳定能力包括： * 反代规则管理 * 配置预览、发布、激活与回滚 * Agent 注册、心跳、同步、应用结果上报 -* Agent 上报 OpenResty 运行健康状态与错误摘要 -* OpenResty 配置写入、校验、reload 与失败回滚 -* Server 向 Agent 下发受限运行指令（当前仅支持 OpenResty 重启） -* Server 统一管理 OpenResty 主配置模板与性能优化参数 -* 反向代理链路的连接、缓冲、超时、压缩与缓存性能优化 -* HTTPS/TLS 路由支持 -* 证书托管与域名管理 -* 节点侧请求数据采集、随 heartbeat 批量上报与服务端聚合分析 -* 节点系统画像采集与展示，包括操作系统、内核、架构、CPU、内存、磁盘与在线时长 -* 节点实时资源快照、网络流量快照与 24 小时趋势展示 -* 节点健康事件归并与异常摘要展示 -* 管理端总览大盘与节点详情页的数据看板升级 -* 首页总览展示整套系统的可用性、容量、流量、异常与配置追平状态 -* 节点管理、节点专属 `agent_token`、全局 `discovery_token` -* 配置变更摘要 -* Agent 运行参数下发 -* Agent 自我更新、一键部署、正式版默认更新与手动 preview 更新 -* Server 版本检查、正式版默认自升级、手动 preview 检查升级与手动上传二进制确认升级 -* 新版管理端 UI、主题切换与统一交互框架 +* OpenResty 主配置模板、性能参数与缓存参数托管 +* HTTPS/TLS 与域名资产管理 +* 节点请求聚合、资源快照、健康事件与看板展示 +* 节点管理、令牌体系、部署与更新链路 +* 基于 Next.js 的正式管理端前端 默认工作方式： * 所有节点消费同一份全局激活版本 -* 控制面保存配置与状态，不直接 SSH 管理机器 -* Agent 是节点侧唯一落地入口 +* Server 保存配置与状态，不直接 SSH 管理节点 +* Agent 是节点侧唯一受控落地入口 ---- - -## 3. 范围边界 +## 2. 范围边界 当前明确不做： * 多租户 -* WAF、限流防护平台化、Bot 管理 -* 节点分组、灰度百分比发布、按节点差异化下发 -* Redis、消息队列、对象存储、Prometheus 等新基础设施前置依赖 -* 平台化缓存产品能力、分层缓存、mid-tier +* CDN SaaS 化能力 +* GeoDNS、全球调度、智能选路 +* WAF、Bot 管理、限流平台化 +* 灰度百分比发布、按节点差异化配置 +* 对象存储、消息队列、Prometheus、ClickHouse、Kafka 等前置基础设施 +* 通用日志检索平台、APM、调用链系统、任意 BI 报表 * 证书自动签发与自动续期 -* 审批流、审计中台、Purge 平台化能力 * 平台化抽象对象，如 `zone`、`origin_pool`、`policy`、`deployment` -第五版边界补充： +边界补充： -* 允许在 OpenResty 单节点层面引入受控的代理缓存能力，但只服务于当前反代链路优化，不扩展为独立缓存产品 -* 主配置文件由 Server 统一生成并由 Agent 受控落地，不开放节点侧手改后再回传合并 -* 性能优化参数统一在 Server 配置，不支持按节点分叉不同性能模板 -* 第五版不开放任意自定义 Nginx/OpenResty 片段上传，不提供任意指令执行入口, 但是需要保留拓展能力, 为后续开放准备 -* 允许在管理端提供 OpenResty 主配置模板编辑能力，但模板必须保留 OpenFlare 预留占位符，确保性能参数、证书目录与受管路由 include 继续由 Server 统一渲染 +* OpenResty 代理缓存只作为当前反代链路优化能力存在，不扩展为独立缓存产品 +* 主配置文件由 Server 统一渲染并由 Agent 受控写入，不支持节点侧手工编辑后回传合并 +* 节点观测聚焦运营与运维排障所需的摘要、趋势和受控窗口数据，不提供长期日志托管 -第六版边界补充： +新增能力如果超出上述边界，先更新本文档，再进入实现。 -* 节点通过 heartbeat 上报最近周期内的请求明细、资源占用快照和网络流量快照，Server 负责入库、聚合与看板展示 -* 第六版参考轻量探针产品的常见数据分层方式，将节点观测拆分为“静态系统画像、周期资源快照、窗口流量聚合、健康异常事件”四类数据，而不是持续向 `nodes` 主表堆叠字段 -* 第六版的数据分析目标聚焦当前反代链路的运营观测：QPS、访问次数、访问人数、访问来源分布、访问趋势、状态码分布，以及节点级 CPU、内存、存储、磁盘 IO、入站/出站流量 -* 首页总览需要能回答“系统整体是否健康、容量是否逼近阈值、流量是否异常、是否存在配置未追平节点”这四类核心问题，可借鉴 WAF/安全大屏的信息组织方式，但不扩展为安全运营平台 -* 世界地图看板仅用于展示节点分布与节点状态，不扩展为 GeoDNS、调度、路由编排或全球流量调度系统 -* 为了支持世界地图看板，允许节点维护低频地图元数据，如位置名、纬度和经度；这类字段仍属于控制面摘要信息，可保留在 `nodes` -* 节点详情页聚焦系统信息、实时资源、网络流量、24 小时趋势和目标版本，不继续堆积低价值静态字段 -* 在不引入 Prometheus、ClickHouse、Kafka 等新基础设施前提下完成第六版；数据采集、聚合与查询继续落在现有 Server/SQLite 基线内 -* 原始请求数据不作为长期日志平台对外开放；第六版允许保留受控时间窗口内的明细，用于聚合分析、趋势计算、节点详情辅助排查，以及管理端“日志”页面查看最近时间窗口内的访问记录 -* 第六版不做完整 APM、调用链追踪、日志检索平台、任意 SQL 分析接口或自定义报表系统 +## 3. 技术基线 -新增能力超出上述边界时，必须先更新本文档，再进入实现。 - ---- - -## 4. 技术基线 - -### 4.1 Server +### 3.1 Server `openflare_server` 继续作为单体控制面： * Gin * GORM * SQLite -* 现有 OpenFlare 登录体系 +* 现有登录与 Session 体系 * 托管 `openflare_server/web` 静态构建产物 -* 托管 OpenResty 主配置模板、性能参数与缓存参数 -### 4.2 Agent +### 3.2 Agent `openflare_agent` 继续作为 Go 单体程序： @@ -110,22 +65,18 @@ OpenFlare 当前定位为内部自用的反向代理控制面，不面向外部 * 节点本地执行 * `openresty_path` 优先 * 未配置 `openresty_path` 时默认使用 Docker OpenResty -* 生成资源默认落在 `./data`，可由 `data_dir` 覆盖 -* 负责接管 OpenResty 主配置文件与受管 include 文件 -### 4.3 Frontend +### 3.3 Frontend -`openflare_server/web` 作为正式管理端前端基线： +`openflare_server/web` 是正式前端基线： * Next.js App Router * React 19 * TypeScript * Tailwind CSS -* 静态导出，继续由 Go Server 托管 +* 静态导出后由 Go Server 托管 ---- - -## 5. 总体架构 +## 4. 总体架构 ```text OpenFlare Server (Gin + SQLite + Web UI) @@ -135,56 +86,36 @@ OpenFlare Server (Gin + SQLite + Web UI) OpenFlare Agent (register / heartbeat / sync / apply / update) | v - Local OpenResty or Docker OpenResty +Local OpenResty or Docker OpenResty | v - Origin +Origin ``` 职责分工： -* Server 负责配置、版本、节点、设置、管理端 UI 以及 OpenResty 主配置模板渲染 -* Agent 负责本地落盘、校验、reload、回滚、自更新，不负责维护独立于 Server 的主配置真相 -* Agent 负责本机观测数据的轻量采集、窗口聚合与体积控制，不直接承担长期历史查询职责 +* Server 负责配置、版本、节点、设置、证书、管理端 UI 与聚合查询 +* Agent 负责本地写入、校验、reload、回滚、自更新与轻量采集 * 发布通过“生成完整版本并激活”完成 * 历史版本不可变 -* Agent 常规轮询以 heartbeat 为主；heartbeat 响应返回当前激活版本的 `version` 与 `checksum` 摘要，Agent 仅在发现不一致时再拉取完整配置 +* heartbeat 响应返回激活版本摘要，Agent 仅在不一致时拉取完整配置 -第六版观测分层： - -* `nodes` 只承担节点身份、接入凭证、配置状态、运行控制状态等控制面字段 -* `nodes` 允许附带少量低频地图展示字段，如位置名、纬度和经度，用于总览世界看板真实落点 -* `node_system_profiles` 承担低频变化的节点系统画像，如操作系统、内核、架构、CPU 型号、逻辑核数、内存总量、磁盘布局、启动时间与 Agent 能力声明 -* `node_metric_snapshots` 承担周期性运行快照，如 CPU、负载、内存、文件系统占用、磁盘 IO、OpenResty 连接数与入站/出站吞吐 -* `node_request_reports` 承担最近心跳窗口内的请求批次或受控明细，不作为长期日志平台 -* `traffic_analytics_rollups` 承担分钟级、小时级的访问聚合结果，支持总览维度、节点维度和域名维度查询 -* `node_health_events` 承担状态变化与异常事件，如节点离线、OpenResty 不健康、配置未追平、资源逼近阈值、错误率突增 - -第六版 heartbeat 扩展思路： - -* `profile`：低频系统画像，仅在首次注册、显著变化或周期性校准时上报 -* `snapshot`：每次 heartbeat 附带的实时资源快照 -* `traffic_report`：当前窗口的请求聚合结果与必要 TopN 分布 -* `health_events`：当前窗口内新增或恢复的异常事件 - ---- - -## 6. 核心对象 +## 5. 核心对象 当前有效实体： -* `proxy_routes`：域名到源站的反向代理规则 -* `config_versions`：完整发布快照与渲染结果 -* `nodes`：节点状态、版本、凭证与 Agent 设置相关状态 -* `node_system_profiles`：节点系统画像与硬件/软件事实信息 -* `apply_logs`：节点应用版本结果 -* `tls_certificates`：托管证书与私钥 -* `managed_domains`：域名资产及默认证书关系 -* `node_request_reports`：节点通过 heartbeat 批量上报的请求明细或请求批次 -* `node_access_logs`：节点最近时间窗口内的受控访问明细，仅保留用于管理端排查的必要字段 -* `node_metric_snapshots`：节点实时资源、磁盘 IO 与网络流量快照 -* `traffic_analytics_rollups`：按时间窗口聚合后的访问指标，用于总览与节点详情看板 -* `node_health_events`：节点运行状态变化、阈值异常与配置偏差事件 +* `proxy_routes` +* `config_versions` +* `nodes` +* `node_system_profiles` +* `apply_logs` +* `tls_certificates` +* `managed_domains` +* `node_request_reports` +* `node_access_logs` +* `node_metric_snapshots` +* `traffic_analytics_rollups` +* `node_health_events` 稳定约束： @@ -194,24 +125,11 @@ OpenFlare Agent (register / heartbeat / sync / apply / update) * `config_versions` 必须保存完整快照、渲染结果与 `checksum` * 全局同时只能有一个激活版本 * 回滚通过重新激活旧版本实现 -* 激活版本中的 OpenResty 渲染结果必须包含主配置与路由配置的统一快照 -* 域名与证书匹配同时支持精确匹配与通配符匹配 -* 节点专属 `agent_token` 必须可立即失效 -* `nodes` 不承担高频观测事实存储；高频运行时字段必须进入快照、聚合或事件表 -* OpenResty 性能优化参数与缓存参数统一由 Server 设置管理，不允许节点侧形成额外配置源 -* OpenResty 主配置模板允许编辑，但必须保留系统要求的占位符，不能绕过结构化参数校验与受管 include 注入 -* Agent 只应用受控主配置文件，不提供任意配置片段拼接入口 -* 节点请求数据必须随 heartbeat 按批次上报，Server 不主动反向拉取节点日志文件 -* 指标看板使用服务端聚合结果，不在前端重复做大规模统计计算 -* 节点资源快照与请求明细必须能按时间排序并绑定节点，保证 24 小时趋势与节点详情可回放 -* 管理端日志页只展示受控保留窗口内的必要访问字段，如原始来源 IP、来源地区、访问域名、路径、命中的节点与响应状态码，不演变为通用日志检索平台 -* 原始请求明细、聚合统计与节点基础状态必须在时间窗口上可对齐 -* 首页总览的系统状态必须基于统一服务端口径生成，不能由多个历史列表接口在前端临时拼装推导 -* 健康事件必须支持“触发中/已恢复”状态，避免首页异常永远累积 +* `nodes` 只承载控制面状态与低频摘要，不承载高频观测事实 +* 指标、趋势和访问分析优先使用服务端聚合结果，而不是前端临时统计 +* 访问明细只保留受控时间窗口，不演变成通用日志平台 ---- - -## 7. 发布模型 +## 6. 发布模型 标准链路： @@ -222,96 +140,48 @@ OpenFlare Agent (register / heartbeat / sync / apply / update) 发布规则： 1. 读取全部启用的 `proxy_routes` -2. 读取 Server 侧受管 OpenResty 性能参数与缓存参数 +2. 读取 Server 侧 OpenResty 主配置与结构化参数 3. 渲染完整 OpenResty 配置 4. 计算 `checksum` 5. 写入 `config_versions` 6. 切换激活版本 -7. Agent 在后续同步中发现并应用 +7. Agent 在后续 heartbeat 中发现并应用 -版本规则： +版本号格式固定为 `YYYYMMDD-NNN`。 -* 版本号格式：`YYYYMMDD-NNN` -* 版本不可变 -* 节点只拉取当前激活版本 +## 7. 模块边界 ---- - -## 8. 模块边界 - -### 8.1 `openflare_server` +### 7.1 `openflare_server` 负责： * 管理端 UI 与 API * Agent API -* 数据存储 -* 配置渲染 -* OpenResty 主配置模板管理 -* OpenResty 性能参数与缓存参数管理 -* 发布与激活 -* 节点状态与设置管理 +* 配置渲染与版本发布 +* 数据存储与聚合查询 +* OpenResty 主配置模板、性能参数与缓存参数管理 -### 8.2 `openflare_agent` +### 7.2 `openflare_agent` 负责： * 首次注册与凭证置换 * 周期性心跳与同步 -* 运行参数接收 -* 采集最近周期内的请求明细、资源占用和网络流量 -* 主配置文件、路由配置与必要证书文件写入 +* 主配置、路由配置、证书与 Lua 资源写入 * 执行 `openresty -t` / `openresty -s reload` * 失败回滚 -* 自我更新 -* 应用结果上报 +* 节点观测采集与结果上报 -### 8.3 `openflare_server/web` +### 7.3 `openflare_server/web` 负责： * 管理端页面、布局、交互与主题 -* 总览世界地图、访问分析看板与节点详情监控视图 -* 规则、版本、节点、证书、域名、用户、设置、性能等页面 +* 总览、节点详情、规则、版本、节点、证书、域名、用户与设置页面 * 统一请求层与前端状态管理 ---- - -## 9. 接口域 - -管理端接口当前覆盖： - -* `proxy-routes` -* `config-versions` -* `nodes` -* `apply-logs` -* `tls-certificates` -* `managed-domains` -* `users` -* `settings` -* `update` - -Agent 接口当前覆盖： - -* 注册 -* 心跳 -* 获取激活版本 -* 上报应用结果 -* 通过心跳回传 OpenResty 健康状态并接收受限运行指令 - -统一约束： - -* 管理端与 Agent API 均使用 JSON -* Agent API 固定放在 `/api/agent/*` -* Agent 鉴权统一使用 `X-Agent-Token` -* OpenResty 性能优化相关配置通过现有设置域统一管理，不新增节点直连配置入口 - ---- - -## 10. 文档维护原则 - -后续只维护当前有效基线： +## 8. 文档维护原则 * 产品范围或系统边界变化时更新本文档 -* 已完成阶段的步骤不再回填为长期计划 +* 已完成阶段不再以“版本计划”形式回填 * 新阶段开始前，先补设计，再进入实现 diff --git a/docs/development-guidelines.md b/docs/development-guidelines.md index 83bb4612..dc05bfe2 100644 --- a/docs/development-guidelines.md +++ b/docs/development-guidelines.md @@ -1,24 +1,12 @@ # OpenFlare 开发规范 -## 1. 适用范围 +本文档描述 OpenFlare `1.0.0` 正式版之后的开发基线。 -本规范适用于当前代码基线下的所有 Server、Agent 与管理端前端开发工作。 +超出 [docs/design.md](./design.md) 边界的需求，必须先更新设计文档。 -当前状态： +## 1. 技术基线 -* 第一版、第二版、第三版已完成 -* `docs/design.md` 是当前系统边界的唯一设计基线 -* `openflare_server/web` 新版前端已完成迁移并成为正式基线 -* 第五版（0.5.x）已完成 -* 第六版（0.6.x）以节点流量数据采集、访问分析与看板升级为主线 - -超出设计边界的需求，必须先更新 [docs/design.md](./design.md)。 - ---- - -## 2. 技术基线 - -### 2.1 Server +### 1.1 Server `openflare_server` 继续作为单体控制面： @@ -26,15 +14,9 @@ * Gin * GORM * SQLite -* 现有 OpenFlare 登录体系 +* 现有登录体系 -约束： - -* 默认不引入 Redis、MQ、对象存储等新基础设施 -* 不为未确认的平台化能力预埋复杂抽象 -* OpenResty 性能参数、缓存参数与主配置模板优先复用现有 `Option` 体系管理，不为单一版本额外引入配置中心 - -### 2.2 Agent +### 1.2 Agent `openflare_agent` 继续作为 Go 单体程序： @@ -43,11 +25,10 @@ * 节点本地执行 * `openresty_path` 优先 * 无 `openresty_path` 时默认 Docker OpenResty -* 生成资源默认写入 `./data`，由 `data_dir` 统一覆盖 -### 2.3 Frontend +### 1.3 Frontend -新版前端基线以当前 `openflare_server/web` 实现为准： +前端基线以 `openflare_server/web` 为准： * Next.js 15 App Router * React 19 @@ -55,40 +36,36 @@ * Tailwind CSS 4 * TanStack Query * React Hook Form + Zod -* Zustand（仅限轻量客户端状态） -* 静态导出并由 Go Server 托管 +* Zustand 仅用于轻量客户端状态 -前端详细约束统一以 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md) 为准；本文件只保留跨项目层面的强约束。 +前端细则见 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md)。 ---- +## 2. 分层与目录约束 -## 3. 分层与目录约束 - -### 3.1 Server +### 2.1 Server * `controller/`：参数解析、调用 service、返回响应 -* `service/`：业务逻辑、校验、渲染、事务编排 +* `service/`：业务逻辑、校验、事务编排、渲染 * `model/`：模型定义与持久化 * `router/`：路由注册 * `middleware/`：认证、鉴权、限流等横切逻辑 -* `common/`：配置、全局运行时状态与初始化入口 -* `utils/`：纯工具函数与通用 helper；按功能聚合，多个同类 helper 应拆到对应子目录 +* `common/`：配置、全局状态与初始化入口 +* `utils/`：纯工具函数与通用 helper 禁止： * 在 `controller/` 堆积业务逻辑 -* 在 `middleware/` 中实现业务流程 +* 在 `middleware/` 实现业务流程 * 为简单需求新增平台层抽象 -* 在 `common/` 混放不依赖全局状态的纯工具实现 -### 3.2 Agent +### 2.2 Agent 保持现有模块边界： * `config` * `heartbeat` * `sync` -* `openresty`（保留目录名，内部负责 OpenResty 运行时管理） +* `openresty` * `state` * `httpclient` * `protocol` @@ -99,29 +76,25 @@ * 每个模块职责单一 * 外部命令调用集中封装 * 状态落盘与配置落盘分离 -* 主配置文件写入、备份、校验、回滚与受管 include 写入应归并到 OpenResty 运行时管理模块 -### 3.3 Frontend +### 2.3 Frontend -前端分层与目录必须与当前工程保持一致： +前端分层保持： -* `app/`：路由、布局、页面组装 -* `features/`：业务模块 -* `components/`：跨模块复用组件 -* `lib/`：请求、环境、工具、常量 -* `store/`：少量跨页面 UI 状态 -* `types/`：共享类型 +* `app/` +* `features/` +* `components/` +* `lib/` +* `store/` +* `types/` 要求： * 页面路由与布局放在 `app/` * API 请求统一收敛到 `lib/api/` * 业务逻辑优先放在 `features/` -* 不重新引入旧版 CRA / Semantic UI 结构 ---- - -## 4. 数据模型规范 +## 3. 数据模型规范 当前有效实体： @@ -137,42 +110,30 @@ * `node_metric_snapshots` * `traffic_analytics_rollups` * `node_health_events` -* `options`（运行时参数与 OpenResty 调优参数继续复用现有配置表，不扩展为独立新实体） +* `options` 通用约束： * 不新增平台化对象，除非设计文档明确要求 -* `proxy_routes` 仍保持一条域名对应一个 `origin_url` +* `proxy_routes` 维持一条域名对应一个 `origin_url` * `config_versions` 必须保存完整快照与渲染结果 * 全局同时只能有一个激活版本 * 回滚通过重新激活旧版本实现 -* 第五版新增的 OpenResty 性能参数必须由 Server 统一保存与校验，并参与版本渲染 -* 域名证书匹配必须同时支持精确匹配与通配符匹配 -* 节点专属 `agent_token` 必须可立即失效 -* `nodes` 只保留控制面与摘要状态，不直接承接第六版新增的高频资源字段、完整系统画像和大块统计结果 -* `nodes` 允许保留世界地图展示所需的少量低频字段，如位置名、纬度和经度；这类字段不得演变成高频观测事实承载体 -* `node_system_profiles` 负责存储低频变化的节点事实信息；只有需要列表摘要展示的极少数字段可以回写到 `nodes` -* 第六版新增的请求明细、资源快照和聚合统计必须按节点与时间窗口关联 -* `node_metric_snapshots` 必须是追加式时间序列快照，不通过覆盖 `nodes` 当前值替代历史 -* `traffic_analytics_rollups` 必须区分时间粒度与统计范围，优先存储窗口聚合而不是无限制保留原始逐请求明细 -* `node_access_logs` 仅保留管理端排查所需的受控访问字段与短期保留窗口，不承担全文检索或长期归档职责 -* `node_health_events` 必须具备事件类型、严重级别、首次触发时间、最近触发时间和恢复时间，便于首页总览做异常归并 -* 访问分析优先复用现有 Server/SQLite 基线，不为第六版引入新的时序数据库或消息队列 -* 聚合统计与原始明细的保留策略必须明确，避免无限制累积 +* `nodes` 只保留控制面状态与低频摘要 +* 观测数据必须按节点与时间窗口关联 +* 快照与聚合结果采用追加式模型，不覆盖历史 +* 原始访问明细必须有受控保留策略 ---- +## 4. API 与鉴权规范 -## 5. API 与鉴权规范 - -### 5.1 API +### 4.1 API * 管理端与 Agent API 统一使用 JSON * 成功与失败都必须返回清晰 `message` -* 列表接口返回稳定字段 * Agent API 固定放在 `/api/agent/*` -* 第六版总览页与节点详情页优先新增专用聚合接口，不继续依赖多个旧列表接口在前端拼装 +* 总览与节点详情优先使用专用聚合接口 -统一响应结构保持现有风格： +统一响应结构： ```json { @@ -182,61 +143,38 @@ } ``` -### 5.2 鉴权 +### 4.2 鉴权 管理端： -* 继续复用 OpenFlare 登录、角色与 session +* 继续复用现有登录、角色与 Session Agent： * 正式请求统一使用节点专属 `agent_token` * 首次接入可使用全局 `discovery_token` * 请求头统一使用 `X-Agent-Token` -* Agent 认证逻辑不得与用户登录态混用 禁止： -* 将本地 OpenResty 操作暴露为远程执行接口 -* 用通用 shell/命令执行方式替代受限节点操作接口 +* 暴露远程 shell 或任意命令执行入口 * 在日志中打印完整 Token -* 为性能优化需求开放任意 OpenResty 文本片段上传或任意指令下发 -* 允许绕过系统占位符约束直接保存不可渲染的 OpenResty 主配置模板 +* 允许绕过占位符约束保存不可渲染的主配置模板 ---- - -## 6. 发布与运行规范 +## 5. 发布与运行规范 发布逻辑必须保持以下事实： * 发布时读取全部启用的 `proxy_routes` -* 发布时同时读取 Server 侧 OpenResty 主配置参数、反代性能参数与缓存参数 +* 同时读取 OpenResty 主配置参数、反代性能参数与缓存参数 * 生成完整 OpenResty 配置 * 计算 `checksum` * 写入 `config_versions` * 通过切换 `is_active` 激活版本 -Go 版本基线约束： - -* 当 `go.mod` 中的 Go 主版本或次版本发生变化时，必须同步检查并更新所有相关构建入口，至少包括 Docker 构建使用的基础镜像版本以及 GitHub Actions 中的 release / docker 发布工作流 -* 版本升级后必须确保本地构建、Docker 构建与发布工作流使用一致的 Go 版本，避免因为 `go.mod`、`Dockerfile` 与 CI 工作流版本漂移导致发布失败 - -第五版新增要求： - -* “完整 OpenResty 配置”至少包括主配置文件与路由配置文件 -* 主配置文件的真相源在 Server，Agent 只负责受控写入、校验与回滚 -* 性能优化参数必须通过结构化字段渲染，禁止直接拼接未经校验的自由文本 -* 新增参数命名统一采用 `OpenResty...` 前缀，布尔值、整数、大小单位和时间单位必须在更新入口做校验 -* 主配置模板编辑必须保留系统要求的占位符，由 Server 在发布与预览时再渲染为最终 `nginx.conf` - -版本号格式保持： - -```text -YYYYMMDD-NNN -``` - -限制： +版本约束： +* 版本号格式固定为 `YYYYMMDD-NNN` * 不在线修改历史版本 * 不做按节点分组的差异化版本 * 预览与 diff 是只读能力，不产生发布记录 @@ -244,135 +182,26 @@ YYYYMMDD-NNN Agent 必须满足： * 启动后读取或生成本地 `node_id` -* 未显式配置 `node_name` 时自动获取主机名 -* 未显式配置 `node_ip` 时自动探测本机 IP * 周期性心跳与同步 -* 常规同步判定优先通过 heartbeat 响应中的激活版本 `version` / `checksum` 摘要完成；仅在 Agent 本地状态与摘要不一致时，再请求完整激活配置 -* heartbeat 请求体允许携带最近周期内的系统画像变更、资源快照、磁盘 IO 快照、入站/出站流量快照、访问聚合批次和健康事件 +* 常规同步优先依据 heartbeat 返回的版本摘要判断 * 发现新版本时先备份旧文件 -* 写入新的主配置、路由配置与必要证书文件 +* 写入主配置、路由配置与必要证书文件 * 先执行 `openresty -t` * 成功后执行 `openresty -s reload` * 失败时自动回滚并上报最终结果 -* 周期性向 Server 回传 OpenResty 当前健康状态与最近运行错误摘要 -* 支持自动注册与 Token 置换 -* 支持接收 Server 下发运行参数 -* 支持接收 Server 下发的受限运行指令，当前仅允许 OpenResty 重启 -* 支持自我更新，但失败不影响心跳与同步 -* 主配置接管模式下，必须保证主配置与受管 include 一起回滚，不能只回滚其中一部分 -* 请求明细采集失败、聚合失败或单次 heartbeat 上报失败时，不得阻断后续心跳与配置同步主链路 -* 节点侧指标采集必须优先读取 OpenResty 与本机运行时状态，不允许引入任意 shell 采集脚本拼接执行 -* 大批量请求上报必须具备批次边界和体积控制，避免单次 heartbeat 无限制膨胀 -* 节点侧应优先做窗口聚合后再上报，避免把逐请求原始日志持续搬运到 Server -* 低频系统画像应支持变更检测，避免每次 heartbeat 重复上报大块静态信息 -* UV、来源分布、状态码分布等统计应在节点侧或服务端按窗口聚合，禁止前端再对原始明细做重型计算 -第六版新增规范： +## 6. 测试与交付要求 -* 总览页默认展示世界地图节点分布、核心访问指标、趋势图和关键异常，不再以多个对称摘要卡片作为唯一主结构 -* 总览页必须能直接展示系统整体运行状况，至少覆盖节点在线率、OpenResty 健康、配置追平状态、容量风险与流量异常 -* 总览页异常区优先展示可行动的问题，如离线节点、配置落后节点、资源逼近阈值节点、错误率异常节点 -* 世界地图看板如需真实落点，应优先消费节点上维护的低频位置元数据，不在前端引入不可控的临时地理解析逻辑 -* 节点详情页第一屏至少覆盖系统信息、实时资源占用、网络流量与 24 小时历史趋势 -* 系统信息卡片除现有 Agent 版本、Nginx 版本、当前配置外，新增操作系统、CPU 型号、在线时长 -* 实时资源卡片展示 CPU、内存、存储占用，优先以仪表盘或等效高密度可视化呈现 -* 网络流量卡片展示经过 OpenResty 的入站和出站流量，并按 KB/MB/GB 自动换算 -* 节点详情页保留“当前目标版本”等高价值运维信息，但应下移到趋势区之后，避免抢占首屏 -* 节点详情页需要区分“静态画像”和“实时状态”，禁止把二者混在一组无层次字段列表中 +* 关键业务逻辑必须有单元测试或等效回归测试 +* Agent 主链路修改必须验证同步、应用与回滚 +* 前端页面至少覆盖加载态、空态、错误态与成功反馈 +* Go 版本调整时，同步检查 `go.mod`、Dockerfile 与 CI 工作流 -第六版实现约束补充： +## 7. 文档维护要求 -* 优先新增 `dashboard` / `node detail` 聚合 service，避免在旧 `node` service 上不断打补丁叠加查询逻辑 -* SQLite 查询应优先围绕“节点 + 时间窗口 + 粒度”建立索引与查询入口，避免首页每次全表扫描历史快照 -* TopN 榜单、来源分布、状态码分布等复杂结果允许以受控 JSON 结构写入聚合表，但必须保证字段稳定可测试 -* 异常阈值判断必须收敛在服务端统一实现，前端只负责展示，不复制阈值逻辑 -* 测试至少覆盖 heartbeat 扩展兼容性、聚合正确性、异常恢复状态切换和关键 dashboard 查询口径 - ---- - -## 7. 前端约束 - -前端新增开发必须遵循 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md)，其中以下要求属于项目级强约束： - -* 页面与布局放在 `app/`，业务逻辑放在 `features/` -* 请求统一通过 `lib/api/` -* 构建产物必须保持可被 Go Server 静态托管 -* 主题能力必须覆盖布局、基础组件与业务页面 -* 不引入新的大型 UI 框架与旧式页面结构 - ---- - -## 8. 代码风格与日志 - -### 8.1 Go - -* 错误必须显式处理 -* 函数尽量单一职责 -* 输入校验放在边界层 -* 业务枚举使用明确常量 -* 不写无意义注释 - -### 8.2 命名 - -* 统一使用 `route`、`version`、`node`、`agent` -* 不混用 `client`、`edge`、`worker` 指代 Agent - -### 8.3 日志 - -必须覆盖关键事件： - -* 发布成功/失败 -* Agent 注册 -* 心跳异常 -* 配置下载失败 -* OpenResty 校验或 reload 成功/失败 -* 回滚触发 - -要求： - -* Server 与 Agent 统一使用 `slog` 输出结构化日志 -* 日志足够定位问题 -* 不打印敏感凭证完整值 - ---- - -## 9. 测试与验收 - -基线回归至少覆盖： - -* 路由校验与渲染 -* 激活版本切换 -* 节点在线状态判定 -* 证书导入与匹配 -* 自定义请求头渲染 -* OpenResty 主配置渲染 -* OpenResty 性能参数与缓存参数校验 -* Agent 同步、回滚、本地状态读写 -* 自动注册与 Token 置换 -* Agent 设置下发与更新链路 -* 预览与 diff 的只读行为 - -新增需求时： - -* 先补单元测试或服务层测试 -* 再补联调验证步骤 -* 涉及发布链路、Agent 链路、鉴权链路的改动，必须补回归测试 -* 涉及 OpenResty 主配置或缓存行为的改动，必须补 `openresty -t` 校验场景与失败回滚场景 - ---- - -## 10. 文档维护 - -出现以下情况必须同步更新文档： +当以下内容变化时，必须同步更新对应文档： * 产品范围或系统边界变化：更新 `docs/design.md` -* 开发约束、接口约定、前后端分层变化：更新本文件 -* 前端目录分层、请求层、主题体系变化：更新 `docs/frontend-development-guidelines.md` -* 部署方式变化：更新 `docs/deployment.md` 和 `README.md` -* 环境变量或配置项变化：更新 `docs/app-config.md` - -## 11. Swagger 约束 - -* Server 提供 Swagger UI 入口：`/swagger/index.html` -* Swagger UI 仅对已登录的管理端用户开放 -* 新增或修改 API 时，必须同步更新 Swag 注解并重新生成 `openflare_server/docs` +* 开发约束、接口约定、测试基线变化：更新本文档 +* 前端工程约束变化：更新 `docs/frontend-development-guidelines.md` +* 配置项或部署方式变化：更新 `docs/app-config.md`、`docs/deployment.md` 与 `README.md` diff --git a/docs/development-plan.md b/docs/development-plan.md index 6cbcd026..f10fe92f 100644 --- a/docs/development-plan.md +++ b/docs/development-plan.md @@ -1,264 +1,50 @@ # OpenFlare 开发计划 -## 1. 当前状态 +## 1. 当前结论 -当前结论： +* 第一版至第六版的主线能力已经全部完成 +* `1.0.0` 是当前正式基线 +* 已完成阶段的过程性任务以代码、测试与 Git 历史为准 +* 新工作优先以缺陷修复、可维护性改进、文档与测试补强为主 -* 第一版至第五版主线能力均已完成 -* 已完成阶段的过程性任务不再继续展开维护 -* 当前主线切换到第六版（0.6.x） +## 2. 当前优先级 -第六版主目标： +当前开发应优先关注： -* 为节点增加请求数据采集、资源采集与 heartbeat 上报能力 -* 在 Server 侧完成访问分析、趋势计算与聚合查询 -* 改造管理端总览页与节点详情页，提升信息密度、数据层次和监控可读性 -* 建立可持续扩展的观测数据分层，避免在旧节点模型和旧首页接口上继续补丁式堆功能 +1. 稳定性 +2. 升级与回滚链路可靠性 +3. 文档准确性 +4. 测试覆盖补强 +5. 在既有边界内的小步迭代 -第六版当前进展（按当前代码基线）： +## 3. 变更准入原则 -* 已完成 heartbeat 扩展协议与观测数据分层落地，节点已支持上报 `profile`、`snapshot`、`traffic_report`、`health_events` -* 已完成 Server 侧观测模型、入库链路与查询接口，节点观测已拆分为系统画像、资源快照、窗口流量聚合、健康事件 -* 已完成 Agent 侧真实请求窗口聚合采集，当前通过受管 OpenResty Lua 观测脚本与本地指标端口输出窗口聚合结果，不再依赖访问日志增量读取 -* 已完成节点详情观测接口与页面第一轮改造，当前已支持系统画像、实时资源、运行状态、24 小时趋势、状态码分布、Top Domain 与健康事件时间线 -* 已完成首页总览专用聚合接口与首页第一轮改造，当前已支持系统运行总览、风险态势、峰值摘要、24 小时趋势、节点健康列表与活动异常 -* 已完成首页风险态势到节点页的轻量筛选联动，支持从总览跳转到节点页查看离线节点、OpenResty 异常节点与配置落后节点 -* 已完成首页总览首屏重构第一版，当前已具备全球态势板、系统健康摘要、请求/容量/网络/磁盘趋势、来源分布、状态码分布与 Top Domain 看板 -* 当前世界板已先接入全球来源信号与节点健康覆盖，节点真实地理点位仍待后续补充地域元数据后进一步完善 -* 已完成节点详情页第二轮重构，当前首屏已支持系统画像、实时资源、网络流量三块核心卡，以及 24 小时 CPU/请求/网络/磁盘 IO 趋势、请求结构分布、健康事件时间线与运维模块下移 -* 首页大盘的进一步态势化增强与告警规则联动仍处于后续阶段 +新需求进入实现前，按以下顺序判断： ---- +1. 是否符合 [docs/design.md](./design.md) 的产品边界 +2. 是否符合 [docs/development-guidelines.md](./development-guidelines.md) 与前端规范 +3. 是否会破坏现有发布、同步、回滚或升级主链路 +4. 是否需要同步更新部署、配置或 README 文档 -## 2. 已完成范围压缩归档 +如果答案包含“超出边界”或“引入新基础设施”，先修改设计文档，再开始实现。 -已完成能力统一归档为以下几类： +## 4. 当前验收标准 -* 反代规则、配置版本、预览、发布、激活、回滚 -* Agent 注册、心跳、同步、应用、失败回滚 -* HTTPS/TLS、证书托管、域名管理 -* 节点管理、令牌体系、部署与更新链路 -* OpenResty 性能优化、缓存配置与主配置托管 -* 新版管理端前端、主题与统一交互框架 +任何合入正式基线的改动，至少应满足： -归档原则： +* 不破坏 Agent 心跳、同步、发布与回滚主链路 +* 不破坏现有 OpenResty 主配置托管模型 +* 不降低总览、节点详情与访问分析的既有可用性 +* 有与风险相称的测试或联调验证 +* 文档与代码保持一致 -* 第一版至第五版的实施细节以代码与 Git 历史为准 -* 本文件只维护当前有效主线，不再保留已完成阶段的过程性拆分 -* `docs/improve_plan.md` 继续作为并行整理清单存在，但不覆盖第六版主线优先级 +## 5. 后续维护方式 ---- +后续规划不再按“大版本阶段文档”维护，而采用以下方式： -## 3. 第六版范围 +* 产品边界变动：更新 `docs/design.md` +* 工程约束变动：更新 `docs/development-guidelines.md` +* 前端工程变动：更新前端相关规范文档 +* 部署与配置变动：更新 `README.md`、`docs/deployment.md`、`docs/app-config.md` -### 3.1 第六版要做 - -1. 节点数据采集与上报 - * Agent 在每次 heartbeat 时上报最近周期内的请求数据 - * Agent 同步上报节点系统画像、CPU/内存/存储快照、磁盘 IO、OpenResty 入站/出站流量 - * 新增在线时长、操作系统、内核、架构、CPU 型号、逻辑核数、总内存、磁盘布局等节点维度信息 - * 采集节点健康事件，覆盖离线、OpenResty 不健康、配置未追平、资源逼近阈值和错误率异常 - -2. 服务端访问分析 - * 基于请求数据计算当前节点 QPS、访问次数、访问人数 - * 统计访问来源分布、访问趋势、状态码分布等核心指标 - * 支持总览维度与节点维度两套查询视图 - * 生成系统整体健康摘要，回答“是否健康、是否有风险、问题集中在哪些节点” - -3. 总览页改造 - * 首屏新增世界地图看板，用于展示全部节点分布与在线状态 - * 调整总览信息结构，不再以单一“四卡摘要”作为主布局 - * 增加趋势、分布、Top 榜单、容量风险和异常信号展示 - * 引入类似 WAF/安全运营面板的信息组织方式，但聚焦 OpenFlare 当前系统健康与流量状态 - -4. 节点详情页改造 - * 第一行重构为三块核心卡片：系统信息、实时资源占用、网络流量监控 - * 第二行展示最近 24 小时历史趋势，至少覆盖 CPU、网络、磁盘 IO - * 第三行接续当前目标版本与应用记录等运维信息 - * 清理低价值、重复、信息密度低的展示模块 - -5. 架构可扩展性治理 - * 将节点观测拆分为静态画像、动态快照、窗口聚合、健康事件四类数据 - * 为总览页和节点详情页建立专用聚合接口，不继续依赖旧列表接口临时拼装 - * 控制原始数据保留窗口和聚合粒度，避免后期查询、存储和维护成本失控 - -### 3.2 第六版不做 - -* 不引入 Prometheus、ClickHouse、Kafka、ElasticSearch 等新基础设施 -* 不建设通用日志检索平台、APM 平台、调用链追踪平台 -* 不扩展为 GeoDNS、全球流量调度、节点智能选路系统 -* 不做任意自定义报表、任意维度 OLAP 查询或外部 BI 接入 - ---- - -## 4. 第六版实施顺序 - -建议按以下顺序推进： - -1. 定义数据模型与 heartbeat 扩展协议 - * 明确系统画像结构、请求数据批次结构、资源快照结构、聚合结果结构与健康事件结构 - * 补齐保留策略、体积限制和失败回退规则 - -2. 完成 Agent 采集链路 - * 采集请求窗口聚合 - * 采集系统画像与运行时性能指标 - * 采集 OpenResty 入站/出站流量 - * 归并节点健康事件并挂入 heartbeat 上报 - -3. 完成 Server 入库与分析链路 - * 接收并校验 heartbeat 扩展数据 - * 入库存储系统画像、原始批次、资源快照和健康事件 - * 生成总览页与节点详情页所需聚合统计与系统健康摘要 - -4. 完成总览页改造 - * 世界地图看板 - * 系统健康摘要区 - * 核心访问指标区 - * 访问趋势与来源分布区 - * 节点状态、配置追平与异常摘要区 - -5. 完成节点详情页改造 - * 系统信息卡片 - * 实时仪表盘与网络流量卡片 - * 24 小时趋势图 - * 下移并重组当前目标版本、健康事件与应用记录 - -6. 补齐回归验证 - * Agent 心跳主链路 - * 聚合统计正确性 - * 健康事件触发/恢复正确性 - * 总览页与节点详情页的亮暗主题和空态/错误态 - ---- - -## 5. 第六版分阶段计划 - -### 5.1 阶段一：采集协议与存储落地 - -目标： - -* 打通“节点采集 -> heartbeat 上报 -> Server 接收 -> 入库”主链路 - -当前状态： - -* 已完成 - -任务： - -* 扩展 Agent heartbeat payload -* 新增系统画像、请求数据批次、资源快照和健康事件模型 -* 为请求明细、性能快照和聚合统计建立查询入口 -* 控制单次 heartbeat 体积，避免影响现有同步稳定性 - -验收标准： - -* 节点可随 heartbeat 成功上报系统画像、请求数据与性能快照 -* heartbeat 扩展失败不影响配置同步主链路 -* Server 能按节点和时间窗口查询到原始上报数据与健康事件 - -### 5.2 阶段二：服务端分析与指标计算 - -目标： - -* 形成总览页和节点详情页可直接消费的数据接口 - -当前状态： - -* 已完成 -* 已落地总览级与节点级聚合接口、当前窗口摘要、状态码/域名/来源分布、系统健康摘要与异常节点清单 -* 已落地最近 24 小时 CPU、内存、网络、磁盘 IO 趋势聚合，并统一总览页与节点详情页的统计口径 - -任务： - -* 计算当前节点 QPS、访问次数、访问人数 -* 计算访问来源分布、访问趋势、状态码分布 -* 生成最近 24 小时 CPU、网络、磁盘 IO 趋势数据 -* 统一总览级与节点级查询口径 -* 生成整体健康摘要与异常节点清单 - -验收标准： - -* 同一时间窗口下总览与节点详情的数据口径一致 -* 核心统计字段可被测试覆盖，避免明显统计偏差 -* 24 小时趋势查询在现有基线上可接受，不出现明显不可用卡顿 -* 首页可直接定位离线、异常、配置落后和容量风险节点 - -### 5.3 阶段三：总览页改造 - -目标： - -* 让总览页从“摘要入口页”升级为“运营与状态看板页” - -当前状态： - -* 已完成 -* 已完成全球态势板、节点真实地图落点、系统健康摘要、峰值摘要、24 小时请求/容量/网络/磁盘趋势、来源分布、状态码分布、Top Domain、Top 节点榜单、处置建议、节点健康列表、活动异常与节点页筛选联动 -* 页面已覆盖首页级加载态、错误态，以及地图/趋势/分布图自身空态，满足第六版当前总览页交付范围 - -任务： - -* 实现世界地图节点看板 -* 重构首屏布局，减少对称摘要卡片堆叠 -* 增加系统健康摘要、趋势图、来源分布、状态码分布、节点异常摘要 -* 为地图、趋势和分布图补齐加载态、空态和错误态 - -验收标准： - -* 总览首屏可直接看到全部节点分布 -* 总览页能展示比旧版更多的实时、趋势与健康信息 -* 页面在桌面和移动端都能稳定显示 - -### 5.4 阶段四：节点详情页改造 - -目标： - -* 让节点详情页回到运维排障视角，提升信息密度和首屏价值 - -当前状态： - -* 已完成 -* 已完成系统画像、实时资源、网络流量三块核心卡，以及诊断摘要、24 小时 CPU/请求/网络/磁盘 IO 趋势、请求结构分布、Top Domain、健康事件时间线与运维模块下移 -* 页面已覆盖首屏识别、资源判断、流量判断与后续排障所需的关键模块，满足第六版当前节点详情页交付范围 - -任务： - -* 第一行实现系统信息、实时资源占用、网络流量三块核心卡片 -* 系统信息新增操作系统、内核、架构、CPU 型号、在线时长 -* 网络流量卡片展示 OpenResty 入站/出站流量，自适应单位 -* 第二行实现最近 24 小时 CPU、网络、磁盘 IO 趋势图 -* 第三行承接当前目标版本、OpenResty 健康、健康事件与应用记录等现有高价值模块 -* 移除低价值重复信息 - -验收标准： - -* 节点详情首屏信息密度明显高于旧版 -* 第一屏即可完成系统识别、资源判断和流量判断 -* 趋势图可用于观察节点最近 24 小时性能变化 - ---- - -## 6. 第六版执行原则 - -第六版执行时遵循： - -* 先遵守 `docs/design.md` 的系统边界 -* 再遵守 `docs/development-guidelines.md` 与 `docs/frontend-development-guidelines.md` -* 数据采集优先走 heartbeat 批量上报，不新增独立常驻推流通道 -* 前端优先消费服务端聚合结果，不在浏览器做重型统计 -* 优先建设新的观测聚合链路，不继续在旧 `nodes` 列表接口与旧首页卡片上补丁式叠加字段 -* 总览页与节点详情页都必须同时覆盖加载态、空态、错误态和亮暗主题 -* 若第六版实现过程中需要新增基础设施或改变保留策略，必须先更新设计文档 - ---- - -## 7. 第六版总体验收标准 - -完成第六版时至少满足： - -* Agent 能在 heartbeat 中稳定上报请求数据、系统信息和性能快照 -* Server 能基于上报数据计算 QPS、访问次数、访问人数、访问来源分布、访问趋势、状态码统计 -* Server 能稳定生成系统健康摘要、异常节点清单和配置追平状态 -* 总览页包含世界地图看板，并替换旧版以摘要卡片为主的单调结构 -* 节点详情页包含系统信息卡、实时资源占用卡、网络流量卡、健康事件区与最近 24 小时趋势图 -* 节点详情页保留当前目标版本等关键运维信息，但整体层级比旧版更清晰 -* 第六版不破坏现有 Agent 心跳、同步、发布、回滚主链路 +如果未来出现明确的新阶段目标，再单独新增专项计划文档；不要把已完成的历史计划继续堆回本文件。 diff --git a/docs/frontend-development-guidelines.md b/docs/frontend-development-guidelines.md index bc80792f..4bd1b10c 100644 --- a/docs/frontend-development-guidelines.md +++ b/docs/frontend-development-guidelines.md @@ -1,56 +1,36 @@ # OpenFlare 前端开发规范 -## 1. 适用范围 +本文档约束 `openflare_server/web` 的正式前端工程。它描述的是 `1.0.0` 之后仍然有效的结构、请求层、组件、样式、状态管理与测试基线。 -本文档约束 `openflare_server/web` 新版前端的工程结构、请求层、组件设计、样式体系、状态管理与测试方式。 +## 1. 技术基线 -当前状态： +默认技术栈： -* 前端改造已完成 -* 本文档描述的是现行正式基线，不再维护迁移期约束 - ---- - -## 2. 技术基线 - -前端默认技术栈： - -* Next.js 15（App Router） +* Next.js 15 App Router * React 19 * TypeScript 5 * Tailwind CSS 4 * TanStack Query * React Hook Form + Zod -* Zustand（仅限轻量客户端状态） +* Zustand * ESLint + Prettier * Vitest + Testing Library + Playwright * pnpm -本地开发模式： - -* `pnpm start`：启动独立前端开发服务器，默认监听 `3001`，支持热更新 -* 开发服务器默认把 `/api/*` 反向代理到 `http://127.0.0.1:3000` -* 如需改后端地址，可设置 `NEXT_DEV_BACKEND_URL` -* `pnpm build`：继续用于静态导出，产物交给 Go Server 托管 - 要求： -* 默认使用 TypeScript，不新增 JS 页面模块 -* 默认使用函数组件，不新增 class 组件 -* 默认使用 App Router，不新建 Pages Router 结构 -* 默认使用 Tailwind CSS 与现有设计 token 体系 +* 默认使用 TypeScript +* 默认使用函数组件 +* 默认使用 App Router * 前端必须支持 `light`、`dark`、`system` 三种主题模式 禁止： -* 新增 Semantic UI 依赖 -* 新增大型 UI 框架，破坏当前组件基线 -* 在新模块中继续使用 jQuery 风格 DOM 操作 -* 将页面逻辑堆积为单个超大组件 +* 引入 Semantic UI +* 新增大型 UI 框架破坏现有组件基线 +* 使用 jQuery 风格 DOM 操作 ---- - -## 3. 目录与分层 +## 2. 目录与分层 推荐目录： @@ -68,28 +48,14 @@ tests/ 职责约束： -* `app/`：定义路由、组织布局、组装页面 +* `app/`：路由、布局、页面组装 * `features/`：按业务域组织模块 * `components/`：跨 feature 复用组件 * `lib/`：请求客户端、环境变量、工具函数、常量 * `store/`：少量跨页面 UI 状态 * `types/`：共享类型定义 -禁止： - -* 在 `app/` 页面文件里堆积复杂请求逻辑 -* 把服务端主数据放进 Zustand -* 将同一业务拆出多套平行结构 - ---- - -## 4. 路由与页面 - -路由命名要求： - -* 使用英文小写 -* 资源页保持现有单数命名 -* 保持与当前路径结构一致 +## 3. 路由与页面 页面文件只负责： @@ -103,26 +69,16 @@ tests/ * 编写复杂表单校验逻辑 * 维护大量彼此耦合的局部状态 -后台页面优先采用统一结构： +## 4. 数据请求与类型 -1. 标题区 -2. 操作区 -3. 筛选区 -4. 内容区 -5. 详情区或弹层 - ---- - -## 5. 数据请求与类型 - -### 5.1 请求层 +### 4.1 请求层 所有 API 请求必须统一经过 `lib/api/`。 要求： * 统一处理 `success/message/data` 响应结构 -* 统一处理鉴权失效、网络异常、通用错误消息 +* 统一处理鉴权失效、网络异常和通用错误消息 * 统一维护资源接口与请求路径 禁止： @@ -130,101 +86,7 @@ tests/ * 在页面组件中直接调用 `fetch('/api/...')` * 在多个组件中重复拼接同一接口路径 -### 5.2 Query - -适用场景： - -* 列表查询 -* 详情查询 -* 配置读取 -* 依赖后端的分页、筛选、刷新操作 - -要求： - -* 使用稳定的 query key -* 变更成功后按资源粒度失效缓存 -* 列表刷新不要依赖分散的手工 `setState` - -### 5.3 类型 - -要求： - -* 开启 TypeScript 严格模式 -* 禁止滥用 `any` -* API 响应、表单输入、业务实体必须有明确类型 -* 枚举、状态、日期字段建立明确类型边界 - ---- - -## 6. 表单与交互 - -统一使用： - -* React Hook Form -* Zod - -交互要求： - -* 必填项明确标识 -* 提交中不可重复点击 -* 保存成功有明确反馈 -* 服务端错误映射到表单或全局提示 - -高风险操作适用场景： - -* 发布配置 -* 激活版本 -* 删除节点 -* 删除证书 -* 重置 Token -* 触发更新 - -要求： - -* 必须有二次确认 -* 必须展示操作对象名称 -* 必须明确成功与失败反馈 - ---- - -## 7. 样式与主题 - -样式原则： - -* 统一使用 Tailwind CSS 与现有 token 体系 -* 优先复用已有基础组件与布局组件 -* 页面视觉风格统一、层级清晰、留白一致 - -主题要求： - -* 同时支持 `light`、`dark`、`system` -* 用户手动选择后必须持久化 -* 刷新、重新进入页面、路由切换后保持一致 -* 首屏尽量避免主题闪烁 -* 布局层、导航层、基础卡片、表单容器必须先满足双主题 - -禁止： - -* 大量硬编码颜色值 -* 同一状态在不同页面使用不同颜色语义 -* 仅验证单一主题后直接交付 - ---- - -## 8. 组件与状态管理 - -组件分层： - -* 基础组件：按钮、输入框、表格、对话框、标签、卡片 -* 业务组件：节点状态卡、版本激活按钮、证书上传表单 -* 页面组合组件：页面头部、筛选面板、详情弹层 - -复用原则： - -* 先抽象稳定结构，再抽象复杂行为 -* 业务组件优先放在 feature 内，确认跨域复用后再上移 - -状态分类： +### 4.2 状态分层 * 服务端状态：TanStack Query * 页面临时状态：组件内部 `useState` @@ -232,13 +94,45 @@ tests/ 不推荐： -* 用 Zustand 保存服务端列表数据 +* 用 Zustand 保存服务端主数据 * 用 Context 代替完整数据层方案 -* 页面里堆叠过多耦合本地状态 ---- +### 4.3 类型 -## 9. 反馈、测试与交付 +要求： + +* 开启 TypeScript 严格模式 +* 禁止滥用 `any` +* API 响应、表单输入、业务实体必须有明确类型 + +## 5. 表单与交互 + +统一使用： + +* React Hook Form +* Zod + +高风险操作必须： + +* 二次确认 +* 展示操作对象名称 +* 明确成功与失败反馈 + +## 6. 样式与主题 + +样式原则： + +* 统一使用 Tailwind CSS 与现有 token 体系 +* 优先复用已有基础组件与布局组件 +* 保持视觉层级、留白与语义颜色一致 + +主题要求： + +* 同时支持 `light`、`dark`、`system` +* 用户选择必须持久化 +* 首屏尽量避免主题闪烁 + +## 7. 测试与交付 每个页面至少具备： @@ -256,5 +150,5 @@ tests/ 交付要求： * 构建产物保持可静态导出 -* 构建结果保持可被 Go Server 托管 -* 新页面与新组件默认同时通过亮色与暗色模式验收 +* 构建结果可被 Go Server 托管 +* 新页面默认通过亮色与暗色模式验收 diff --git a/docs/frontend-revamp-plan.md b/docs/frontend-revamp-plan.md deleted file mode 100644 index e5c0f9b9..00000000 --- a/docs/frontend-revamp-plan.md +++ /dev/null @@ -1,68 +0,0 @@ -# OpenFlare 前端改造说明 - -## 1. 当前状态 - -前端改造已完成，`openflare_server/web` 的 Next.js 新版工程已经成为正式管理端基线。 - -当前结论： - -* 旧版 CRA + Semantic UI 方案已退出基线 -* 新版前端继续由 Go Server 以静态资源方式托管 -* 前端改造过程中的阶段计划、迁移顺序与风险清单不再继续维护 - ---- - -## 2. 当前前端基线 - -新版管理端位于 `openflare_server/web`，当前基线为： - -* Next.js 15 App Router -* React 19 -* TypeScript -* Tailwind CSS 4 -* TanStack Query -* React Hook Form + Zod -* Zustand（仅限轻量客户端状态） -* Vitest + Playwright - -工程与运行方式： - -* `next build` 后生成静态导出产物 -* 构建后通过现有流程交由 `openflare_server` 托管 -* 登录态继续兼容现有 Session/Cookie 体系 - ---- - -## 3. 当前结构约束 - -新版前端保持以下结构： - -* `app/`：路由与布局 -* `features/`：业务模块 -* `components/`：复用组件 -* `lib/`：请求、环境、工具、常量 -* `store/`：少量跨页面 UI 状态 -* `tests/`：前端测试 - -当前已覆盖的主要页面包括： - -* 首页 -* 反代规则 -* 配置版本 -* 节点管理 -* 应用记录 -* 网站 -* 用户管理 -* 设置 -* 性能 -* 登录、注册、重置密码、GitHub OAuth、关于页 - ---- - -## 4. 后续维护原则 - -后续不再按“前端改造专项”推进，而按正式前端工程进行维护： - -* 新前端开发统一遵循 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md) -* 涉及项目级约束时，同时遵循 [docs/development-guidelines.md](./development-guidelines.md) -* 若后续再次调整前端架构、部署模式或技术基线，再新增专项计划文档 diff --git a/docs/improve_plan.md b/docs/improve_plan.md deleted file mode 100644 index a5cdfddc..00000000 --- a/docs/improve_plan.md +++ /dev/null @@ -1,217 +0,0 @@ -# OpenFlare 整理维护期改进计划 - -## 1. 背景 - -项目当前已具备可用的 Server / Agent / OpenResty 控制链路，接下来进入整理维护期。 -这一阶段不再以新增大功能为主，而是集中处理三类问题： - -* 架构层面的通信与存储开销 -* 代码质量、可维护性与复用度 -* 高风险安全问题与供应链风险 - -本计划遵循当前基线： - -* 不改变 Server 统一生成配置、Agent 受控落盘的核心边界 -* 优先通过收敛实现、减少重复、补齐校验和测试来提升系统质量 - ---- - -## 2. 目标 - -### 2.1 总目标 - -在不扩大产品边界的前提下，把 OpenFlare 从“功能可用”推进到“长期可维护、风险可控、成本可预测”。 - -### 2.2 具体目标 - -* 降低 Agent 与 Server 的无效通信和无谓数据库写入 -* 降低节点列表、配置发布、日志输出等热点路径的额外开销 -* 用更明确的校验、错误处理和回归测试提升健壮性 -* 优先清除高危安全风险，特别是认证绕过、路径穿越、远程执行链路和更新链路信任问题 - ---- - -## 3. 现状评估 - -### 3.1 架构与性能现状 - -当前通信链路已经有一个正确方向： - -* 心跳接口只返回 `version/checksum` 摘要 -* Agent 仅在版本或 checksum 不一致时才拉取完整配置 - -这意味着“全量配置频繁下发”已经被避免，基础设计没有明显错误。但仍有几个维护期值得优化的点： - -* 心跳会持续触发数据库写入，即使多数运行字段没有变化 -* 节点列表查询存在按节点逐条读取最近应用日志的模式，节点数增大后会出现明显的 N+1 查询开销 -* Agent 与 Server 在心跳、同步、HTTP 请求等路径上存在较多 `info` 级别日志，线上节点数增多后会放大 I/O 与排障噪音 -* Active Config 仍是整包返回，后续可继续收敛为“元数据 + 必要文件”的更细粒度同步模式 - -### 3.2 代码质量现状 - -当前代码总体结构清晰，但已经出现维护期典型问题： - -* 控制器层大量重复 `success/message/data` 响应拼装，错误返回风格不够统一 -* 部分边界校验仍分散在控制器、服务和运行时路径里，难以形成稳定约束 -* 一些实现已经接近“自造轮子”，例如日志文件处理、更新校验、静态安全检查流程，还没有引入成熟工具链 - -### 3.3 安全现状 - -维护期内优先处理以下高风险或高敏感问题： - -* Agent 写入 `support_files` 时缺少对目标路径必须位于 `support_dir` 内的强约束，存在路径穿越风险 -* 手动上传 Server 二进制后会执行 `--version` 检测，属于高敏感执行链路，必须进一步加固 - ---- - -## 4. 优先级策略 - -### 4.1 P0：先止血 - -这部分先处理，未完成前不建议继续做中期重构。 - -1. 修复 Agent 证书/附属文件写入路径穿越风险 -2. 补齐相关回归测试，确保问题不会回归 - -### 4.2 P1：高收益优化 - -在 P0 完成后推进。 - -1. 减少心跳导致的数据库写放大 -2. 消除节点列表的 N+1 查询 -3. 降低高频路径日志噪音 -4. 收敛重复日志与响应封装实现 - -### 4.3 P2：维护性增强 - -在 P1 稳定后持续推进。 - -1. 引入静态分析、安全扫描、依赖漏洞扫描到日常流程 -2. 梳理通用校验与错误模型 -3. 评估可以替换自研实现的成熟库 -4. 补充基准测试、容量指标和回归清单 - ---- - -## 5. 分项计划 - -### 5.1 工作流一：安全治理 - -#### 5.1.1 目标 - -先解决高危风险，再补齐防线。 - -#### 5.1.2 任务 - -* 为 Agent 支持文件写入增加安全路径校验 - * 拒绝绝对路径 - * 拒绝 `..` 跳目录 - * 通过 `filepath.Rel` 或安全辅助函数确认最终路径仍位于 `support_dir` 内 - * `writeSupportFiles`、`restore`、未来新增的写文件入口全部复用同一套安全函数 -* 收紧手动上传升级链路 - * 明确只允许 root 用户 - * 增加二次确认信息和文件摘要展示 - - -#### 5.1.3 验收标准 - -* 构造 `../`、绝对路径、混合分隔符路径时，Agent 必须拒绝写入 - -### 5.2 工作流二：架构与性能优化 - -#### 5.2.1 目标 - -在不改变总体架构的前提下，减少高频开销。 - -#### 5.2.2 任务 - -* 优化心跳写库策略 - * 将“状态变化字段”与“仅 last_seen_at 更新时间”区分处理 - * 仅在 IP、版本、OpenResty 状态、错误信息变化时更新对应字段 - * 节点状态的离线判定优先在查询层或内存逻辑中计算，避免频繁写回数据库 -* 优化节点列表查询 - * 将“最近一次 apply_log”改为批量查询或子查询一次取回 - * 避免 `ListNodeViews` 中对每个节点单独查询最近日志 -* 优化配置同步链路 - * 保留当前“心跳摘要 + 版本不一致再拉全量配置”的模型 - * 为后续版本预留“支持文件 manifest/checksum”能力，避免未来证书文件较多时重复传输整包内容 - * 评估为 Agent 全量配置接口启用 gzip 压缩 -* 优化日志成本 - * 将心跳成功、HTTP 请求成功、无变更同步等高频日志降为 `debug` - * 保留发布、应用失败、回滚、认证失败等关键事件为 `info/warn/error` - -#### 5.2.3 验收标准 - -* 在节点数量增长时，节点列表查询不再出现明显线性附加 SQL 次数 -* 心跳高频场景下数据库写入量明显下降 -* 默认 `info` 日志聚焦关键事件，不再持续刷出无变更同步日志 - -### 5.3 工作流三：代码质量与可维护性 - -#### 5.3.1 目标 - -减少重复代码，让后续维护成本下降。 - -#### 5.3.2 任务 - -* 统一 API 响应与错误处理 - * 提供统一响应助手函数 - * 让控制器层只负责参数解析、调用 service、返回统一结构 -* 收敛校验逻辑 - * 将路径、模板占位符、OpenResty 参数、上传文件等校验集中封装 - * 避免同一规则散落在多个层级 -* 清理“功能可跑但长期难维护”的实现 - * 减少控制器内重复 JSON decode 与错误返回样板代码 - * 减少 service 中过长函数 - * 对高频路径补充更精确的单元测试和表驱动测试 - -#### 5.3.3 可优先引入的成熟开源能力 - -* `staticcheck` - * 作为 Go 静态分析主工具 -* `govulncheck` - * 用于 Go 依赖漏洞扫描 -* `gosec` - * 用于高危安全模式扫描 -* `gitleaks` 或 `trufflehog` - * 用于仓库敏感信息扫描 - -说明： - -* 这里优先引入“工程工具”和“稳定基础库” -* 不建议为了维护期而大规模替换 Web 框架、ORM、HTTP 框架等核心依赖 - -#### 5.3.4 验收标准 - -* 控制器响应风格统一，重复样板代码减少 -* 新增规则优先通过统一校验函数落地，而不是散落在多个入口 - ---- - -## 6. 建议实施顺序 - -### 第一阶段：安全止血 - -* 修复路径穿越风险 -* 清理敏感示例配置 -* 为更新链路加校验 -* 接入 `gosec`、`govulncheck`、密钥扫描 - -### 第二阶段：热点路径优化 - -* 优化心跳写库 -* 优化节点列表查询 -* 调整日志级别 -* 补充压力下的基线数据 - -### 第三阶段：代码收敛 - -* 统一 API 响应帮助函数 -* 收敛校验与错误模型 -* 补充回归测试模板 - -### 第四阶段：延伸优化 - -* 评估配置接口压缩与更细粒度 manifest 同步 -* 评估手动上传升级链路的更安全替代实现 -* 根据实际运行数据决定是否继续做更细的持久化优化 diff --git a/openflare_server/.gitignore b/openflare_server/.gitignore index 6320cd24..82f0c3ac 100644 --- a/openflare_server/.gitignore +++ b/openflare_server/.gitignore @@ -1 +1 @@ -data \ No newline at end of file +/data/