From 2d6cc908f5fe60ce37f1b4b55e812804b66e2948 Mon Sep 17 00:00:00 2001 From: ryan Date: Sat, 9 May 2026 18:07:35 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 82 +++---- README.md | 110 ++------- docs/.vitepress/config.ts | 8 +- docs/app-config.md | 170 -------------- docs/config.ts | 1 + docs/design.md | 181 --------------- docs/design/development.md | 284 ++++++++++++++++++++++-- docs/design/index.md | 82 ++++++- docs/development-guidelines.md | 232 ------------------- docs/development-plan.md | 61 ----- docs/en/config.ts | 1 + docs/en/guide/deployment.md | 102 +++++++++ docs/en/guide/index.md | 9 +- docs/frontend-development-guidelines.md | 128 ----------- docs/{ => guide}/deployment.md | 246 ++++++++++---------- docs/guide/index.md | 9 +- docs/reference/configuration.md | 135 +++++++++-- 17 files changed, 763 insertions(+), 1078 deletions(-) delete mode 100644 docs/app-config.md delete mode 100644 docs/design.md delete mode 100644 docs/development-guidelines.md delete mode 100644 docs/development-plan.md create mode 100644 docs/en/guide/deployment.md delete mode 100644 docs/frontend-development-guidelines.md rename docs/{ => guide}/deployment.md (64%) diff --git a/AGENTS.md b/AGENTS.md index 809c5544..9b5050e7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,41 +1,41 @@ -# AGENTS.md - -本文件是 OpenFlare 的 AI 接手入口，不承载详细设计、规范和计划。接手项目时，先按顺序阅读以下文档： - -1. [docs/design.md](./docs/design.md) - 作用：理解当前 MVP 的产品范围、系统边界、核心对象和整体架构。 - -2. [docs/development-guidelines.md](./docs/development-guidelines.md) - 作用：理解当前开发规范，包括技术基线、分层约束、数据模型边界、API 约定、Agent 约束、测试要求。 - -3. [docs/development-plan.md](./docs/development-plan.md) - 作用：理解当前开发阶段、实施顺序、阶段目标和验收标准。 - -4. [docs/frontend-development-guidelines.md](./docs/frontend-development-guidelines.md) - 作用：理解新版前端的技术选型、目录分层、组件规范、请求层、状态管理、样式和测试约束。 - -5. [docs/deployment.md](./docs/deployment.md) - 作用：理解当前的部署方式和联调步骤，确保开发过程中产出的功能能够成功部署和验证。 - -6. [docs/app-config.md](./docs/app-config.md) - 作用：系统启动时支持的环境变量和配置项说明，确保开发过程中新增的配置项能够正确使用和文档化。 - - -## 执行要求 - -* 如果实现内容超出 `docs/design.md` 的范围，先修改设计文档，再继续编码。 -* 如果实现方式违反 `docs/development-guidelines.md`，应优先调整方案，而不是绕过规范。 -* 如果需求与当前开发阶段冲突，优先遵守 `docs/development-plan.md` 的阶段顺序。 -* 如果任务涉及前端改造或管理端 UI，必须同时阅读 `docs/frontend-development-guidelines.md`。 - - -## 文档维护要求 - -当以下内容发生变化时，应同步更新对应文档： - -* 产品启动配置部署方式发生变化时: 更新 `docs/deployment.md`和 `README.md` -* 产品范围或系统边界变化：更新 `docs/design.md` -* 开发约束、代码规范、接口约定变化：更新 `docs/development-guidelines.md` -* 阶段目标、顺序、验收标准变化：更新 `docs/development-plan.md` -* 前端目录分层、组件规范、样式体系、测试基线变化：更新 `docs/frontend-development-guidelines.md` -* 环境变量或配置项变化：更新 `docs/app-config.md` +# AGENTS.md + +本文件是 OpenFlare 的 AI 接手入口，不承载详细设计、规范和计划。接手项目时，先按顺序阅读以下 VitePress 文档源文件： + +1. [docs/design/index.md](./docs/design/index.md) + 作用：理解当前 MVP 的产品范围、系统边界、核心对象和长期约束。 + +2. [docs/design/architecture.md](./docs/design/architecture.md) + 作用：理解 Server、Agent、OpenResty 与前端的职责边界。 + +3. [docs/design/release-model.md](./docs/design/release-model.md) + 作用：理解配置发布、激活、回滚与 Agent 应用模型。 + +4. [docs/design/development.md](./docs/design/development.md) + 作用：理解当前开发规范、阶段原则、分层约束、数据模型边界、API 约定、Agent 约束、前端规范与测试要求。 + +5. [docs/guide/deployment.md](./docs/guide/deployment.md) + 作用：理解当前部署方式、Agent 接入、升级、卸载和联调步骤。 + +6. [docs/reference/configuration.md](./docs/reference/configuration.md) + 作用：理解系统启动时支持的环境变量、命令行参数、运行时配置项和 Agent 配置字段。 + +线上文档入口：https://open-flare.pages.dev + +## 执行要求 + +* 如果实现内容超出 [产品边界](./docs/design/index.md)，先修改设计文档，再继续编码。 +* 如果实现方式违反 [开发约束](./docs/design/development.md)，应优先调整方案，而不是绕过规范。 +* 如果需求与当前阶段原则冲突，优先遵守 [开发约束](./docs/design/development.md) 中的变更准入与验收标准。 +* 如果任务涉及前端改造或管理端 UI，必须同时遵守 [开发约束](./docs/design/development.md) 中的前端规范。 + +## 文档维护要求 + +当以下内容发生变化时，应同步更新对应 VitePress 页面： + +* 产品范围或系统边界变化：更新 `docs/design/index.md` +* 系统结构、模块职责变化：更新 `docs/design/architecture.md` +* 发布、同步、回滚模型变化：更新 `docs/design/release-model.md` +* 开发约束、代码规范、接口约定、阶段原则、测试基线变化：更新 `docs/design/development.md` +* 产品启动、部署、升级、联调方式变化：更新 `docs/guide/deployment.md` 和 `README.md` +* 环境变量、命令行参数、运行时配置、Agent 配置变化：更新 `docs/reference/configuration.md` diff --git a/README.md b/README.md index a0d46694..305a02b4 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,5 @@ -

- 中文 | English -

-
-[//]: # ( OpenFlare logo) - # OpenFlare 轻量、自托管的 OpenResty 控制面，用于管理反向代理规则、配置发布、节点同步、TLS 证书与基础可观测能力。 @@ -24,66 +18,28 @@

-> [!NOTE] -> 当前项目处于快速迭代期，设计与实现均不稳定，请确保使用最新版本并关注更新日志。 - > [!WARNING] -> 使用 root 用户初次登录系统后，务必修改默认密码 `123456`，并且确保关闭新用户注册功能。 +> 使用 `root` 用户初次登录系统后，务必修改默认密码 `123456`，并按需关闭新用户注册功能。 -## 为什么存在 +## 文档 -OpenFlare 解决的是一类朴素但高频的运维问题： +**https://open-flare.pages.dev** -* 在一个管理端里维护域名到源站的反向代理规则 -* 生成完整 OpenResty 配置并以不可变版本发布 -* 让节点侧 Agent 自动拉取、校验、reload 与失败回滚 -* 统一托管证书、域名、节点凭证与版本状态 -* 提供足够实用的总览、节点详情与访问分析能力 +常用入口： + +* [快速开始](https://open-flare.pages.dev/guide/quick-start) +* [部署说明](https://open-flare.pages.dev/guide/deployment) +* [配置项参考](https://open-flare.pages.dev/reference/configuration) +* [系统设计](https://open-flare.pages.dev/design/) ## 核心能力 -* 配置版本化：支持预览、发布、激活、历史回滚 -* Agent 自动应用：周期性同步、落盘、`openresty -t`、`openresty -s reload`、失败自动回滚 -* OpenResty 托管：统一管理主配置模板、性能参数、缓存参数与受管路由 -* TLS 与域名管理：支持证书托管、域名资产维护、精确匹配与通配符匹配 -* 访问与节点观测：支持请求窗口聚合、状态码分布、来源分布、节点资源与健康事件展示 -* 网站防护: 支持 POW, 限流功能 - -## 系统架构 - -```text -OpenFlare Server (Gin + GORM + SQLite/PostgreSQL + 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 托管 - -## 界面预览 - -### 仪表盘总览 - -![OpenFlare dashboard overview](./docs/assets/readme/dashboard-overview.png) - -### 节点详情 - -![OpenFlare node detail](./docs/assets/readme/node-detail.png) - -### 配置新增 - -![OpenFlare version release](./docs/assets/readme/proxy-route-detail.png) +* 反向代理网站配置与多域名绑定 +* 配置预览、发布、激活与历史回滚 +* Agent 自动注册、心跳、同步、校验、reload 与失败回滚 +* OpenResty 主配置、性能参数、缓存参数与 Lua 资源托管 +* TLS 证书、域名资产、节点凭证与版本状态管理 +* 请求聚合、访问分析、资源快照、健康事件与节点详情 ## 快速开始 @@ -179,42 +135,20 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/unin 版本号格式固定为 `YYYYMMDD-NNN`，历史版本不可变，回滚通过重新激活旧版本完成。 -## 仓库结构 -* `openflare_server`：Gin + GORM + SQLite/PostgreSQL 单体控制面 -* `openflare_server/web`：Next.js 15 App Router 管理端前端 -* `openflare_agent`：Go 单体 Agent -* `scripts`：安装脚本与辅助脚本 -* `docs`：设计、规范、部署与配置文档 +## 界面预览 -## 本地开发 +### 仪表盘总览 -### Server +![OpenFlare dashboard overview](./docs/assets/readme/dashboard-overview.png) -```bash -cd openflare_server -export SESSION_SECRET='replace-with-random-string' -export SQLITE_PATH='./openflare.db' -# 可选：设置 DSN 或 SQL_DSN 后切换到 PostgreSQL。 -# 如果 PostgreSQL 为空且 ./openflare.db 存在，启动时会自动迁移 SQLite 数据。 -# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable' -go run . -``` +### 节点详情 -### Frontend +![OpenFlare node detail](./docs/assets/readme/node-detail.png) -```bash -cd openflare_server/web -pnpm install -pnpm dev -``` +### 配置新增 -### Agent - -```bash -cd openflare_agent -go run ./cmd/agent -config /path/to/agent.json -``` +![OpenFlare version release](./docs/assets/readme/proxy-route-detail.png) ## 管理端与接口 diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index f110161a..418ff3e7 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -12,13 +12,7 @@ export default defineConfig({ 'zh/**', 'components/**', 'snippets/**', - 'design.md', - 'website-configuration-redesign.md', - 'development-plan.md', - 'development-guidelines.md', - 'frontend-development-guidelines.md', - 'deployment.md', - 'app-config.md' + 'website-configuration-redesign.md' ], markdown: { diff --git a/docs/app-config.md b/docs/app-config.md deleted file mode 100644 index c84b0bdf..00000000 --- a/docs/app-config.md +++ /dev/null @@ -1,170 +0,0 @@ -# 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` | -| `DSN` | PostgreSQL DSN，设置后优先于 SQLite | 空 | -| `SQL_DSN` | 兼容旧命名的 PostgreSQL DSN，优先级低于 `DSN` | 空 | -| `REDIS_CONN_STRING` | Redis 连接串 | 空 | -| `UPLOAD_PATH` | 上传目录 | `upload` | -| `AGENT_TOKEN` | 兼容旧部署的全局 Agent Token | 空 | - -说明： - -* `DSN` 与 `SQL_DSN` 同时存在时优先使用 `DSN` -* `DSN` 或 `SQL_DSN` 与 `SQLITE_PATH` 同时存在时优先使用 PostgreSQL -* 当目标 PostgreSQL 数据库为空且本地 `SQLITE_PATH` 文件存在时，Server 启动阶段会自动迁移 SQLite 数据，并在日志中输出按表迁移进度 -* `SESSION_SECRET` 生产环境必须显式配置 -* `REDIS_CONN_STRING` 未配置时，相关能力回退为进程内实现 - -### 1.3 `Option` 表中的运行时配置 - -以下配置由管理端设置页维护，可热更新： - -| 配置项 | 作用 | 默认值 | -| --- | --- | --- | -| `AgentHeartbeatInterval` | Agent 心跳间隔（毫秒） | `10000` | -| `NodeOfflineThreshold` | 节点离线阈值（毫秒） | `120000` | -| `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/OpenFlare` | -| `GeoIPProvider` | 节点/IP 归属解析方式 | `ipinfo` | -| `RegisterEnabled` | 是否允许新用户注册 | `false` | -| `PasswordRegisterEnabled` | 是否允许通过密码方式注册 | `true` | -| `DatabaseAutoCleanupEnabled` | 是否启用每日自动清理观测数据 | `false` | -| `DatabaseAutoCleanupRetentionDays` | 自动清理保留天数（至少 1 天） | `30` | -| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口 | `300` / `180` | -| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口 | `300` / `180` | -| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口 | `50` / `60` | -| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口 | `50` / `60` | -| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 敏感接口限流次数 / 时间窗口 | `100` / `1200` | - -说明： - -* `DatabaseAutoCleanupEnabled` 开启后，Server 会在每天凌晨 3 点自动清理 `node_access_logs`、`node_metric_snapshots`、`node_request_reports` 三类观测数据 -* `DatabaseAutoCleanupRetentionDays` 为统一保留天数，必须大于等于 1；管理端支持手动清理时留空保留天数，以直接删除对应数据集的全部历史记录 - -### 1.4 OpenResty 参数 - -OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前常用项包括： - -* `OpenRestyWorkerProcesses` -* `OpenRestyWorkerConnections` -* `OpenRestyWorkerRlimitNofile` -* `OpenRestyKeepaliveTimeout` -* `OpenRestyProxyConnectTimeout` -* `OpenRestyProxySendTimeout` -* `OpenRestyProxyReadTimeout` -* `OpenRestyProxyBufferingEnabled` -* `OpenRestyGzipEnabled` -* `OpenRestyCacheEnabled` -* `OpenRestyCachePath` -* `OpenRestyCacheMaxSize` - -这类参数必须以结构化方式校验、保存并参与版本渲染。 - -* 管理端不再暴露 `resolver` 配置；规则上游统一渲染为 named `upstream` 并启用 keepalive，单上游如带 base path 或 query，会在 `proxy_pass` 中补回原始 URI。 -* 多上游仍要求每个上游都为纯 `scheme://host[:port]`，且同一规则内协议一致，避免在负载均衡模式下引入不可预测的 URI 差异。 -* `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` 的弃用告警。 -### 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 配置字段 - -| 字段 | 作用 | 是否必填 | 默认值/行为 | -| --- | --- | --- | --- | -| `server_url` | 控制面地址 | 是 | 无 | -| `agent_token` | 节点专属认证 Token | 与 `discovery_token` 二选一 | 空 | -| `discovery_token` | 首次自动注册使用的全局 Token | 与 `agent_token` 二选一 | 空 | -| `node_name` | 节点名称 | 否 | 自动使用主机名 | -| `node_ip` | 节点 IP | 否 | 自动探测，优先选择公网 IPv4；仅无公网地址时退回可用内网地址 | -| `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` 毫秒 | - -说明： - -* `agent_token` 与 `discovery_token` 不能同时为空 -* `heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串 -* 未配置 `openresty_path` 时默认使用 Docker OpenResty 模式 -* Agent 自动探测到私网 `node_ip` 时，Server 会在注册/心跳阶段优先保留 Agent 直连来源的公网地址，避免 NAT/多网卡场景误登记内网网卡地址 - -## 3. 维护要求 - -以下内容变化时，必须同步更新本文档： - -* Server 命令行参数 -* Server 环境变量 -* Agent 命令行参数 -* Agent 配置字段 -* 任一配置项的默认值、用途或示例 diff --git a/docs/config.ts b/docs/config.ts index acc09154..fcafd177 100644 --- a/docs/config.ts +++ b/docs/config.ts @@ -68,6 +68,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { items: [ { text: '概览', link: '' }, { text: '快速开始', link: 'quick-start' }, + { text: '部署说明', link: 'deployment' }, { text: '启动 Server', link: 'server' }, { text: '接入 Agent', link: 'agent' }, { text: '发布第一份配置', link: 'first-site' }, diff --git a/docs/design.md b/docs/design.md deleted file mode 100644 index 173b9b38..00000000 --- a/docs/design.md +++ /dev/null @@ -1,181 +0,0 @@ -# OpenFlare 设计基线 - -本文档定义 OpenFlare `1.0.0` 之后仍然有效的产品边界、系统结构与长期约束。第六版已经完成并并入正式版；过程性设计不再在这里维护。 - -## 1. 产品定位 - -OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景，解决反向代理配置、节点同步、证书托管与基础观测的统一管理问题。 - -当前稳定能力包括： - -* 反代规则管理 -* 网站级配置与多域名绑定 -* 源站管理与复用 -* 配置预览、发布、激活与回滚 -* Agent 注册、心跳、同步、应用结果上报 -* OpenResty 主配置模板、性能参数与缓存参数托管 -* HTTPS/TLS 与域名资产管理 -* 节点请求聚合、资源快照、健康事件与看板展示 -* 节点管理、令牌体系、部署与更新链路 -* 基于 Next.js 的正式管理端前端 - -默认工作方式： - -* 所有节点消费同一份全局激活版本 -* Server 保存配置与状态，不直接 SSH 管理节点 -* Agent 是节点侧唯一受控落地入口 - -## 3. 技术基线 - -### 3.1 Server - -`openflare_server` 继续作为单体控制面： - -* Gin -* GORM -* SQLite / PostgreSQL -* 现有登录与 Session 体系 -* 托管 `openflare_server/web` 静态构建产物 - -### 3.2 Agent - -`openflare_agent` 继续作为 Go 单体程序： - -* 单二进制 -* 节点本地执行 -* `openresty_path` 优先 -* 未配置 `openresty_path` 时默认使用 Docker OpenResty - -### 3.3 Frontend - -`openflare_server/web` 是正式前端基线： - -* Next.js App Router -* React 19 -* TypeScript -* Tailwind CSS -* 静态导出后由 Go Server 托管 - -## 4. 总体架构 - -```text -OpenFlare Server (Gin + SQLite/PostgreSQL + Web UI) - | - | HTTP API / Config Pull - v -OpenFlare Agent (register / heartbeat / sync / apply / update) - | - v -Local OpenResty or Docker OpenResty - | - v -Origin -``` - -职责分工： - -* Server 负责配置、版本、节点、设置、证书、管理端 UI 与聚合查询 -* Agent 负责本地写入、校验、reload、回滚、自更新与轻量采集 -* 发布通过“生成完整版本并激活”完成 -* 历史版本不可变 -* heartbeat 响应返回激活版本摘要，Agent 仅在不一致时拉取完整配置 - -## 5. 核心对象 - -当前有效实体： - -* `proxy_routes` -* `origins` -* `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` - -稳定约束： - -* `proxy_routes` 从“单域名规则”升级为“网站配置”聚合对象；一条记录对应一个网站，可绑定一个或多个域名，并共享一组站点级配置 -* `proxy_routes.site_name` 是网站的业务唯一标识；新建时默认取 `domains[0]`，后续允许独立维护，不随域名改动自动重写 -* `proxy_routes.domains` 至少包含一个域名，且 `domains[0]` 作为主域名；任一域名全局只能属于一个 `proxy_routes` -* 为兼容历史数据，迁移期可保留 `proxy_routes.domain` 作为 `domains[0]` 的镜像字段，但业务读写与后续扩展必须以 `site_name` + `domains` 为准 -* `origins` 只保存源站地址、展示名与备注，不承载协议、端口、路径、权重或健康检查策略 -* `proxy_routes` 可选关联一个 `origins` 记录，用于复用源站地址；规则仍保存完整 `origin_url` 快照以参与渲染与版本快照 -* `proxy_routes` 至少包含一个上游地址；为兼容历史数据保留 `origin_url` 主上游字段，也允许在同一规则内补充多个上游做负载均衡 -* `proxy_routes` 上游统一渲染为带 keepalive 的 named `upstream`；单上游可附带 base path 或 query 并在 `proxy_pass` 中追加，多上游仍限定为纯 `scheme://host[:port]` -* `proxy_routes.origin_host` 为可选字段，用于回源时覆盖 `Host` 请求头；未设置时默认透传访问域名 -* 网站级流量限制、反向代理与缓存配置当前按站点共享，不在同一网站内做域名级差异化配置；但 HTTPS 允许在同一站点内按域名绑定证书 -* `proxy_routes.domain_cert_ids` 用于记录与 `domains` 平行的域名证书绑定；值为 `0` 表示该域名不启用 HTTPS，仅保留 HTTP -* 发布渲染时，带证书的域名按证书分组输出独立 `443 ssl` `server` 块；未绑定证书的域名不得被自动带入 HTTPS -* 发布渲染时必须将 `proxy_routes.domains` 中的全部域名一并纳入同一站点配置，避免同站点在版本快照中被拆散 -* 所有上游地址都必须为合法 `http://` 或 `https://` -* `config_versions` 必须保存完整快照、渲染结果与 `checksum` -* 全局同时只能有一个激活版本 -* 回滚通过重新激活旧版本实现 -* `nodes` 只承载控制面状态与低频摘要，不承载高频观测事实 -* 指标、趋势和访问分析优先使用服务端聚合结果，而不是前端临时统计 -* 访问明细只保留受控时间窗口，不演变成通用日志平台 - -## 6. 发布模型 - -标准链路： - -```text -修改规则 -> 预览/查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果 -``` - -发布规则： - -1. 读取全部启用的 `proxy_routes` -2. 读取 Server 侧 OpenResty 主配置与结构化参数 -3. 渲染完整 OpenResty 配置 -4. 计算 `checksum` -5. 写入 `config_versions` -6. 切换激活版本 -7. Agent 在后续 heartbeat 中发现并应用 - -版本号格式固定为 `YYYYMMDD-NNN`。 - -## 7. 模块边界 - -### 7.1 `openflare_server` - -负责： - -* 管理端 UI 与 API -* Agent API -* 配置渲染与版本发布 -* 数据存储与聚合查询 -* OpenResty 主配置模板、性能参数与缓存参数管理 - -### 7.2 `openflare_agent` - -负责： - -* 首次注册与凭证置换 -* 周期性心跳与同步 -* 主配置、路由配置、证书与 Lua 资源写入 -* 执行 `openresty -t` / `openresty -s reload` -* 失败回滚 -* 对已失败并回退的目标版本做本地熔断，直到控制面出现新的激活版本 -* 节点观测采集与结果上报 - -### 7.3 `openflare_server/web` - -负责： - -* 管理端页面、布局、交互与主题 -* 总览、节点详情、规则、版本、节点、证书、域名、用户与设置页面 -* 统一请求层与前端状态管理 - -## 8. 文档维护原则 - -* 产品范围或系统边界变化时更新本文档 -* 已完成阶段不再以“版本计划”形式回填 -* 新阶段开始前，先补设计，再进入实现 -* 涉及网站级规则改造的详细需求与实施顺序，见 [docs/website-configuration-redesign.md](./website-configuration-redesign.md) diff --git a/docs/design/development.md b/docs/design/development.md index 265190f1..164ac22f 100644 --- a/docs/design/development.md +++ b/docs/design/development.md @@ -1,35 +1,287 @@ # 开发约束 -OpenFlare `1.0.0` 之后的开发优先关注稳定性、升级与回滚链路可靠性、文档准确性、测试覆盖补强，以及既有边界内的小步迭代。 +本文档融合原开发规范、前端规范与开发计划，是 OpenFlare `1.0.0` 之后的工程约束入口。 + +## 当前结论 + +* 第一版至第六版的主线能力已经全部完成。 +* `1.0.0` 是当前正式基线。 +* 已完成阶段的过程性任务以代码、测试与 Git 历史为准。 +* 新工作优先以缺陷修复、可维护性改进、文档与测试补强为主。 + +当前开发优先级： + +1. 稳定性。 +2. 升级与回滚链路可靠性。 +3. 文档准确性。 +4. 测试覆盖补强。 +5. 在既有边界内的小步迭代。 ## 变更准入 新需求进入实现前，按以下顺序判断： -1. 是否符合产品边界。 -2. 是否符合后端、Agent 与前端开发规范。 -3. 是否会破坏发布、同步、回滚或升级主链路。 -4. 是否需要同步更新部署、配置或 README 文档。 +1. 是否符合 [产品边界](./)。 +2. 是否符合本文档的后端、Agent 与前端约束。 +3. 是否会破坏现有发布、同步、回滚或升级主链路。 +4. 是否需要同步更新部署、配置、README 或文档站页面。 如果需求超出边界或引入新基础设施，应先更新设计文档，再开始实现。 +任何合入正式基线的改动，至少应满足： + +* 不破坏 Agent 心跳、同步、发布与回滚主链路。 +* 不破坏现有 OpenResty 主配置托管模型。 +* 不降低总览、节点详情与访问分析的既有可用性。 +* 有与风险相称的测试或联调验证。 +* 文档与代码保持一致。 + +## 技术基线 + +Server： + +* Go 1.24+ +* Gin +* GORM +* SQLite / PostgreSQL +* 现有登录体系 + +Agent： + +* Go 1.24+ +* 单二进制 +* 节点本地执行 +* `openresty_path` 优先 +* 无 `openresty_path` 时默认 Docker OpenResty + +Frontend： + +* Next.js 15 App Router +* React 19 +* TypeScript 5 +* Tailwind CSS 4 +* TanStack Query +* React Hook Form + Zod +* Zustand 仅用于轻量客户端状态 +* ESLint + Prettier +* Vitest + Testing Library + Playwright +* pnpm + +## Server 分层 + +| 目录 | 职责 | +| --- | --- | +| `controller/` | 参数解析、调用 service、返回响应 | +| `service/` | 业务逻辑、校验、事务编排、渲染 | +| `model/` | 模型定义与持久化 | +| `router/` | 路由注册 | +| `middleware/` | 认证、鉴权、限流等横切逻辑 | +| `common/` | 配置、全局状态与初始化入口 | +| `utils/` | 纯工具函数与通用 helper | + +禁止在 `controller/` 堆积业务逻辑，禁止在 `middleware/` 实现业务流程，禁止为简单需求新增平台层抽象。 + +## Agent 分层 + +Agent 保持现有模块边界： + +* `config` +* `heartbeat` +* `sync` +* `openresty` / `nginx` +* `state` +* `httpclient` +* `protocol` +* `internal/updater` + +要求： + +* 每个模块职责单一。 +* 外部命令调用集中封装。 +* 状态落盘与配置落盘分离。 + +## Frontend 分层 + +推荐目录： + +```text +app/ +components/ +features/ +lib/ +hooks/ +store/ +types/ +styles/ +tests/ +``` + +职责约束： + +* `app/`：路由、布局、页面组装。 +* `features/`：按业务域组织模块。 +* `components/`：跨 feature 复用组件。 +* `lib/`：请求客户端、环境变量、工具函数、常量。 +* `store/`：少量跨页面 UI 状态。 +* `types/`：共享类型定义。 + +页面文件只负责获取路由参数、组织页面结构、调用 feature 组件；不应手写复杂 API 细节、复杂表单校验逻辑或维护大量彼此耦合的局部状态。 + +## 数据模型规范 + +当前有效实体： + +* `proxy_routes` +* `origins` +* `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` +* `options` + +通用约束： + +* 不新增平台化对象，除非设计文档明确要求。 +* `origins` 仅作为可复用源站地址目录，字段保持轻量。 +* `proxy_routes` 以“网站配置”作为聚合边界，必须包含唯一 `site_name` 与非空 `domains` 列表。 +* `proxy_routes.domains` 中的每个域名都必须全局唯一，列表第一项视为主域名。 +* `proxy_routes` 继续允许保存一个或多个上游地址用于负载均衡，但不引入独立 `origin_pool`。 +* 遗留 `domain` 字段只能作为 `domains[0]` 的兼容镜像；新代码不得继续以该字段作为唯一业务输入。 +* `proxy_routes` 如关联 `origins`，必须同时保存可直接渲染的 `origin_url`。 +* 上游统一使用 named `upstream` + keepalive；单上游如带 base path 或 query，应在 `proxy_pass` 上补回 URI，多上游仅允许纯 `scheme://host[:port]`。 +* 流量限制、反向代理与缓存配置当前都归属站点级 `proxy_routes`。 +* HTTPS 证书绑定必须通过与 `domains` 平行的 `domain_cert_ids` 逐域名保存；未绑定证书的域名不得参与 HTTPS 渲染。 +* `config_versions` 必须保存完整快照与渲染结果。 +* 全局同时只能有一个激活版本。 +* 回滚通过重新激活旧版本实现。 +* `nodes` 只保留控制面状态与低频摘要。 +* 观测数据必须按节点与时间窗口关联，快照与聚合结果采用追加式模型。 +* 原始访问明细必须有受控保留策略。 + ## 数据库迁移 -任何涉及表结构、索引、列类型、分表规则或内部持久化元数据的修改，都必须同步提升数据库版本号，并补充从上一版本升级到新版本的显式迁移方法。 +任何涉及表结构、索引、列类型、分表规则或内部持久化元数据的修改，都必须同步提升数据库版本号。 -迁移必须包含升级后的校验逻辑。迁移失败或校验失败时，启动流程必须中止，且不得提升数据库版本记录。 +数据库版本号定义在 `openflare_server/model`，不得只依赖 `AutoMigrate` 隐式升级存量数据库。 -## 前端约束 +每次提升数据库版本号时，必须补充从上一版本升级到新版本的显式迁移方法。迁移方法必须包含升级后的校验逻辑；只有校验通过，才能写入新的数据库版本记录。 -前端以 `openflare_server/web` 为准： +新包启动后必须先检查数据库当前版本，再按顺序逐步升级到目标版本；禁止跳过中间升级步骤直接写目标版本。 -* 页面路由与布局放在 `app/`。 -* API 请求统一收敛到 `lib/api/`。 -* 业务逻辑优先放在 `features/`。 -* 服务端状态使用 TanStack Query。 -* 表单使用 React Hook Form 与 Zod。 -* 主题必须支持 `light`、`dark`、`system`。 +空库初始化可以直接建立当前版本结构，但初始化完成后仍必须执行同版本校验，并落库当前数据库版本。 + +如果迁移失败或校验失败，启动流程必须中止，且不得提升数据库版本记录。涉及数据库版本变更的提交，必须补充对应的迁移测试或等效回归测试。 + +## API 与鉴权 + +管理端与 Agent API 统一使用 JSON。成功与失败都必须返回清晰 `message`： + +```json +{ + "success": true, + "message": "", + "data": {} +} +``` + +约定： + +* Agent API 固定放在 `/api/agent/*`。 +* 总览与节点详情优先使用专用聚合接口。 +* 管理端变更类接口统一使用 `POST`；只读接口使用 `GET`。 +* 管理端继续复用现有登录、角色与 Session。 +* Agent 正式请求统一使用节点专属 `agent_token`。 +* 首次接入可使用全局 `discovery_token`。 +* Agent 请求头统一使用 `X-Agent-Token`。 + +禁止暴露远程 shell 或任意命令执行入口，禁止在日志中打印完整 Token，禁止绕过占位符约束保存不可渲染的主配置模板。 + +## 发布与运行 + +发布逻辑必须保持： + +* 发布时读取全部启用的 `proxy_routes`。 +* 同时读取 OpenResty 主配置参数、反代性能参数与缓存参数。 +* 生成完整 OpenResty 配置。 +* 计算 `checksum`。 +* 写入 `config_versions`。 +* 通过切换 `is_active` 激活版本。 + +版本约束： + +* 版本号格式固定为 `YYYYMMDD-NNN`。 +* 不在线修改历史版本。 +* 不做按节点分组的差异化版本。 +* 预览与 diff 是只读能力，不产生发布记录。 + +Agent 必须满足： + +* 启动后读取或生成本地 `node_id`。 +* 周期性心跳与同步。 +* 常规同步优先依据 heartbeat 返回的版本摘要判断。 +* 发现新版本时先备份旧文件。 +* 写入主配置、路由配置与必要证书文件。 +* 写入新配置后以运行态恢复为目标执行激活，Docker 模式优先重建容器并确认容器保持运行。 +* 新配置激活失败时必须先尝试用目标配置恢复运行，再回滚到旧配置并重新拉起 OpenResty。 +* 回滚后 OpenResty 恢复正常时上报警告；回滚后仍无法恢复运行时上报失败。 +* 某个目标 `version + checksum` 一旦应用失败并回退，Agent 必须在本地状态中阻断该目标的重复应用。 + +## 前端请求、状态与类型 + +所有 API 请求必须统一经过 `lib/api/`： + +* 统一处理 `success/message/data` 响应结构。 +* 统一处理鉴权失效、网络异常和通用错误消息。 +* 统一维护资源接口与请求路径。 + +状态分层： + +* 服务端状态：TanStack Query。 +* 页面临时状态：组件内部 `useState`。 +* 跨页面 UI 状态：Zustand。 + +要求开启 TypeScript 严格模式，禁止滥用 `any`，API 响应、表单输入、业务实体必须有明确类型。 + +## 表单、交互、样式与主题 + +表单统一使用 React Hook Form 与 Zod。 + +高风险操作必须二次确认、展示操作对象名称，并明确成功与失败反馈。 + +样式原则： + +* 统一使用 Tailwind CSS 与现有 token 体系。 +* 优先复用已有基础组件与布局组件。 +* 保持视觉层级、留白与语义颜色一致。 + +主题要求： + +* 同时支持 `light`、`dark`、`system`。 +* 用户选择必须持久化。 +* 首屏尽量避免主题闪烁。 ## 测试与交付 -关键业务逻辑必须有单元测试或等效回归测试。任何正式基线改动至少应保证不破坏 Agent 心跳、同步、发布与回滚主链路。 +* 关键业务逻辑必须有单元测试或等效回归测试。 +* Agent 主链路修改必须验证同步、应用与回滚。 +* 前端页面至少覆盖加载态、空态、错误态与成功反馈。 +* Go 版本调整时，同步检查 `go.mod`、Dockerfile 与 CI 工作流。 + +## 后续维护方式 + +后续规划不再按“大版本阶段文档”维护，而采用以下方式： + +* 产品边界变动：更新 [产品边界](./)。 +* 工程约束变动：更新本文档。 +* 部署与配置变动：更新 [部署说明](../guide/deployment.md)、[配置项](../reference/configuration.md) 与 README。 + +如果未来出现明确的新阶段目标，再单独新增专项计划文档；不要把已完成的历史计划继续堆回本文档。 + +当前专项“网站级规则与配置界面改造”的模型边界已纳入 [产品边界](./)，执行时仍按数据模型、接口、前端页面、迁移测试与文档联动的顺序推进。 diff --git a/docs/design/index.md b/docs/design/index.md index 4e88e009..125eaee3 100644 --- a/docs/design/index.md +++ b/docs/design/index.md @@ -7,15 +7,93 @@ OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组 | 能力 | 说明 | | --- | --- | | 反代规则管理 | 以网站配置为聚合边界，支持多域名与源站配置 | -| 配置版本 | 支持预览、发布、激活、历史回滚 | -| Agent 同步 | 支持注册、心跳、同步、应用结果上报 | +| 网站级配置 | 一条规则对应一个网站，可绑定一个或多个域名，并共享站点级配置 | +| 源站管理 | 维护轻量源站目录，并允许网站保存可渲染的源站快照 | +| 配置版本 | 支持预览、发布、激活、不可变历史与回滚 | +| Agent 同步 | 支持注册、心跳、同步、应用结果上报与自更新 | | OpenResty 托管 | 管理主配置模板、性能参数、缓存参数与 Lua 资源 | | HTTPS/TLS | 托管证书与域名资产，并按域名绑定证书 | | 基础观测 | 聚合节点请求、资源快照、健康事件和访问分析 | | 节点管理 | 节点状态、令牌体系、部署与更新链路 | +| 管理端前端 | 基于 Next.js 的正式管理端 | 默认工作方式： * 所有节点消费同一份全局激活版本。 * Server 保存配置与状态，不直接 SSH 管理节点。 * Agent 是节点侧唯一受控落地入口。 + +## 核心对象 + +当前有效实体： + +* `proxy_routes` +* `origins` +* `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` + +## 网站配置约束 + +`proxy_routes` 从“单域名规则”升级为“网站配置”聚合对象。一条记录对应一个网站，可绑定一个或多个域名，并共享一组站点级配置。 + +约束： + +* `proxy_routes.site_name` 是网站的业务唯一标识。 +* `proxy_routes.domains` 至少包含一个域名，且 `domains[0]` 作为主域名。 +* 任一域名全局只能属于一个 `proxy_routes`。 +* 迁移期可保留 `proxy_routes.domain` 作为 `domains[0]` 的镜像字段，但业务读写与后续扩展必须以 `site_name` + `domains` 为准。 +* 网站级流量限制、反向代理与缓存配置当前按站点共享，不在同一网站内做域名级差异化配置。 +* HTTPS 允许在同一站点内按域名绑定证书。 + +## 源站约束 + +`origins` 只保存源站地址、展示名与备注，不承载协议、端口、路径、权重或健康检查策略。 + +`proxy_routes` 可选关联一个 `origins` 记录，用于复用源站地址；规则仍保存完整 `origin_url` 快照以参与渲染与版本快照。 + +上游约束： + +* `proxy_routes` 至少包含一个上游地址。 +* 为兼容历史数据保留 `origin_url` 主上游字段，也允许在同一规则内补充多个上游做负载均衡。 +* 上游统一渲染为带 keepalive 的 named `upstream`。 +* 单上游可附带 base path 或 query 并在 `proxy_pass` 中追加。 +* 多上游限定为纯 `scheme://host[:port]`。 +* `proxy_routes.origin_host` 为可选字段，用于回源时覆盖 `Host` 请求头。 +* 所有上游地址都必须为合法 `http://` 或 `https://`。 + +## HTTPS 约束 + +`proxy_routes.domain_cert_ids` 用于记录与 `domains` 平行的域名证书绑定；值为 `0` 表示该域名不启用 HTTPS，仅保留 HTTP。 + +发布渲染时： + +* 带证书的域名按证书分组输出独立 `443 ssl` `server` 块。 +* 未绑定证书的域名不得被自动带入 HTTPS。 +* 必须将 `proxy_routes.domains` 中的全部域名一并纳入同一站点配置，避免同站点在版本快照中被拆散。 + +## 版本与观测约束 + +* `config_versions` 必须保存完整快照、渲染结果与 `checksum`。 +* 全局同时只能有一个激活版本。 +* 回滚通过重新激活旧版本实现。 +* `nodes` 只承载控制面状态与低频摘要，不承载高频观测事实。 +* 指标、趋势和访问分析优先使用服务端聚合结果，而不是前端临时统计。 +* 访问明细只保留受控时间窗口，不演变成通用日志平台。 + +## 文档维护原则 + +* 产品范围或系统边界变化时更新本文档。 +* 开发约束、代码规范、接口约定变化时更新 [开发约束](./development.md)。 +* 部署方式变化时更新 [部署说明](../guide/deployment.md) 与 README。 +* 配置项变化时更新 [配置项参考](../reference/configuration.md)。 +* 已完成阶段不再以“版本计划”形式回填。 +* 新阶段开始前，先补设计，再进入实现。 diff --git a/docs/development-guidelines.md b/docs/development-guidelines.md deleted file mode 100644 index 14f5444d..00000000 --- a/docs/development-guidelines.md +++ /dev/null @@ -1,232 +0,0 @@ -# OpenFlare 开发规范 - -本文档描述 OpenFlare `1.0.0` 正式版之后的开发基线。 - -超出 [docs/design.md](./design.md) 边界的需求，必须先更新设计文档。 - -## 1. 技术基线 - -### 1.1 Server - -`openflare_server` 继续作为单体控制面： - -* Go 1.24+ -* Gin -* GORM -* SQLite / PostgreSQL -* 现有登录体系 - -### 1.2 Agent - -`openflare_agent` 继续作为 Go 单体程序： - -* Go 1.24+ -* 单二进制 -* 节点本地执行 -* `openresty_path` 优先 -* 无 `openresty_path` 时默认 Docker OpenResty - -### 1.3 Frontend - -前端基线以 `openflare_server/web` 为准： - -* Next.js 15 App Router -* React 19 -* TypeScript -* Tailwind CSS 4 -* TanStack Query -* React Hook Form + Zod -* Zustand 仅用于轻量客户端状态 - -前端细则见 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md)。 - -## 2. 分层与目录约束 - -### 2.1 Server - -* `controller/`：参数解析、调用 service、返回响应 -* `service/`：业务逻辑、校验、事务编排、渲染 -* `model/`：模型定义与持久化 -* `router/`：路由注册 -* `middleware/`：认证、鉴权、限流等横切逻辑 -* `common/`：配置、全局状态与初始化入口 -* `utils/`：纯工具函数与通用 helper - -禁止： - -* 在 `controller/` 堆积业务逻辑 -* 在 `middleware/` 实现业务流程 -* 为简单需求新增平台层抽象 - -### 2.2 Agent - -保持现有模块边界： - -* `config` -* `heartbeat` -* `sync` -* `openresty` -* `state` -* `httpclient` -* `protocol` -* `internal/updater` - -要求： - -* 每个模块职责单一 -* 外部命令调用集中封装 -* 状态落盘与配置落盘分离 - -### 2.3 Frontend - -前端分层保持： - -* `app/` -* `features/` -* `components/` -* `lib/` -* `store/` -* `types/` - -要求： - -* 页面路由与布局放在 `app/` -* API 请求统一收敛到 `lib/api/` -* 业务逻辑优先放在 `features/` - -## 3. 数据模型规范 - -当前有效实体： - -* `proxy_routes` -* `origins` -* `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` -* `options` - -通用约束： - -* 不新增平台化对象，除非设计文档明确要求 -* `origins` 仅作为可复用源站地址目录，字段保持轻量；协议、端口、路径与查询参数继续归属具体 `proxy_routes` -* `proxy_routes` 以“网站配置”作为聚合边界，必须包含唯一 `site_name` 与非空 `domains` 列表；数据库内部 `id` 可继续作为技术主键，但不能替代 `site_name` 的业务唯一性 -* `proxy_routes.domains` 中的每个域名都必须全局唯一；列表第一项视为主域名，创建时若未显式填写 `site_name`，则默认使用主域名 -* `proxy_routes` 继续允许保存一个或多个上游地址用于负载均衡，但不引入独立 `origin_pool` -* 迁移期如保留遗留 `domain` 字段，只能作为 `domains[0]` 的兼容镜像；新代码不得继续以该字段作为唯一业务输入 -* `proxy_routes` 如关联 `origins`，必须同时保存可直接渲染的 `origin_url`；源站地址变更时，由 service 负责同步更新引用该源站的规则快照 -* `proxy_routes` 的上游统一使用 named `upstream` + keepalive；单上游如带 base path 或 query，应在 `proxy_pass` 上补回 URI，多上游仅允许纯 `scheme://host[:port]` -* `proxy_routes.origin_host` 为可选字段，仅用于覆盖回源 `Host` 请求头，不引入新的平台化对象 -* 流量限制、反向代理与缓存配置当前都归属站点级 `proxy_routes`，同一网站内不拆分域名级差异配置 -* HTTPS 的启停仍由站点级 `proxy_routes` 控制，但证书绑定必须通过与 `domains` 平行的 `domain_cert_ids` 记录逐域名保存；未绑定证书的域名不得参与 HTTPS 渲染 -* `proxy_routes.cert_ids` 仅作为站点级证书集合与兼容镜像，必须由 `domain_cert_ids` 推导生成；`cert_id` 继续作为首个已使用证书的兼容镜像 -* `config_versions` 必须保存完整快照与渲染结果 -* 全局同时只能有一个激活版本 -* 回滚通过重新激活旧版本实现 -* `nodes` 只保留控制面状态与低频摘要 -* 观测数据必须按节点与时间窗口关联 -* 快照与聚合结果采用追加式模型，不覆盖历史 -* 原始访问明细必须有受控保留策略 - -### 3.1 数据库版本与迁移 - -* 任何涉及表结构、索引、列类型、分表规则或内部持久化元数据的修改，都必须同步提升数据库版本号 -* 数据库版本号定义在 `openflare_server/model`，不得只依赖 `AutoMigrate` 隐式升级存量数据库 -* 每次提升数据库版本号时，必须补充从上一版本升级到新版本的显式迁移方法 -* 迁移方法必须包含升级后的校验逻辑；只有校验通过，才能写入新的数据库版本记录 -* 新包启动后必须先检查数据库当前版本，再按顺序逐步升级到目标版本；禁止跳过中间升级步骤直接写目标版本 -* 空库初始化可以直接建立当前版本结构，但初始化完成后仍必须执行同版本校验，并落库当前数据库版本 -* 数据库版本元数据属于内部控制信息，必须保存在独立内部表中，不能混入业务配置表 -* 如果迁移失败或校验失败，启动流程必须中止，且不得提升数据库版本记录 -* 涉及数据库版本变更的提交，必须补充对应的迁移测试或等效回归测试 - -## 4. API 与鉴权规范 - -### 4.1 API - -* 管理端与 Agent API 统一使用 JSON -* 成功与失败都必须返回清晰 `message` -* Agent API 固定放在 `/api/agent/*` -* 总览与节点详情优先使用专用聚合接口 -* 管理端变更类接口统一使用 `POST`；只读接口使用 `GET` - -统一响应结构： - -```json -{ - "success": true, - "message": "", - "data": {} -} -``` - -### 4.2 鉴权 - -管理端： - -* 继续复用现有登录、角色与 Session - -Agent： - -* 正式请求统一使用节点专属 `agent_token` -* 首次接入可使用全局 `discovery_token` -* 请求头统一使用 `X-Agent-Token` - -禁止： - -* 暴露远程 shell 或任意命令执行入口 -* 在日志中打印完整 Token -* 允许绕过占位符约束保存不可渲染的主配置模板 - -## 5. 发布与运行规范 - -发布逻辑必须保持以下事实： - -* 发布时读取全部启用的 `proxy_routes` -* 同时读取 OpenResty 主配置参数、反代性能参数与缓存参数 -* 生成完整 OpenResty 配置 -* 计算 `checksum` -* 写入 `config_versions` -* 通过切换 `is_active` 激活版本 - -版本约束： - -* 版本号格式固定为 `YYYYMMDD-NNN` -* 不在线修改历史版本 -* 不做按节点分组的差异化版本 -* 预览与 diff 是只读能力，不产生发布记录 - -Agent 必须满足： - -* 启动后读取或生成本地 `node_id` -* 周期性心跳与同步 -* 常规同步优先依据 heartbeat 返回的版本摘要判断 -* 发现新版本时先备份旧文件 -* 写入主配置、路由配置与必要证书文件 -* 写入新配置后以运行态恢复为目标执行激活，Docker 模式优先重建容器并确认容器保持运行 -* 新配置激活失败时必须先尝试用目标配置恢复运行，再回滚到旧配置并重新拉起 OpenResty -* 回滚后 OpenResty 恢复正常时上报警告；回滚后仍无法恢复运行时上报失败 -* 某个目标 `version + checksum` 一旦应用失败并回退，Agent 必须在本地状态中阻断该目标的重复应用；只有远端激活版本或 checksum 发生变化时，才允许再次尝试 - -## 6. 测试与交付要求 - -* 关键业务逻辑必须有单元测试或等效回归测试 -* Agent 主链路修改必须验证同步、应用与回滚 -* 前端页面至少覆盖加载态、空态、错误态与成功反馈 -* Go 版本调整时，同步检查 `go.mod`、Dockerfile 与 CI 工作流 - -## 7. 文档维护要求 - -当以下内容变化时，必须同步更新对应文档： - -* 产品范围或系统边界变化：更新 `docs/design.md` -* 开发约束、接口约定、测试基线变化：更新本文档 -* 前端工程约束变化：更新 `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 deleted file mode 100644 index f8d74b41..00000000 --- a/docs/development-plan.md +++ /dev/null @@ -1,61 +0,0 @@ -# OpenFlare 开发计划 - -## 1. 当前结论 - -* 第一版至第六版的主线能力已经全部完成 -* `1.0.0` 是当前正式基线 -* 已完成阶段的过程性任务以代码、测试与 Git 历史为准 -* 新工作优先以缺陷修复、可维护性改进、文档与测试补强为主 - -## 2. 当前优先级 - -当前开发应优先关注： - -1. 稳定性 -2. 升级与回滚链路可靠性 -3. 文档准确性 -4. 测试覆盖补强 -5. 在既有边界内的小步迭代 - -## 3. 变更准入原则 - -新需求进入实现前，按以下顺序判断： - -1. 是否符合 [docs/design.md](./design.md) 的产品边界 -2. 是否符合 [docs/development-guidelines.md](./development-guidelines.md) 与前端规范 -3. 是否会破坏现有发布、同步、回滚或升级主链路 -4. 是否需要同步更新部署、配置或 README 文档 - -如果答案包含“超出边界”或“引入新基础设施”，先修改设计文档，再开始实现。 - -## 4. 当前验收标准 - -任何合入正式基线的改动，至少应满足： - -* 不破坏 Agent 心跳、同步、发布与回滚主链路 -* 不破坏现有 OpenResty 主配置托管模型 -* 不降低总览、节点详情与访问分析的既有可用性 -* 有与风险相称的测试或联调验证 -* 文档与代码保持一致 - -## 5. 后续维护方式 - -后续规划不再按“大版本阶段文档”维护，而采用以下方式： - -* 产品边界变动：更新 `docs/design.md` -* 工程约束变动：更新 `docs/development-guidelines.md` -* 前端工程变动：更新前端相关规范文档 -* 部署与配置变动：更新 `README.md`、`docs/deployment.md`、`docs/app-config.md` - -如果未来出现明确的新阶段目标，再单独新增专项计划文档；不要把已完成的历史计划继续堆回本文件。 - -## 6. 当前专项计划 - -已确认需要推进“网站级规则与配置界面改造”专项，详细需求、实施顺序与验收标准见 [docs/website-configuration-redesign.md](./website-configuration-redesign.md)。 - -本专项的执行顺序固定为： - -1. 先完成数据模型与配置渲染兼容方案 -2. 再调整接口、校验与版本 diff 语义 -3. 然后改造规则列表与网站配置子页面 -4. 最后补齐迁移、回归测试与文档联动 diff --git a/docs/en/config.ts b/docs/en/config.ts index b502726c..9aaf1867 100644 --- a/docs/en/config.ts +++ b/docs/en/config.ts @@ -40,6 +40,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { items: [ { text: 'Overview', link: '' }, { text: 'Quick Start', link: 'quick-start' }, + { text: 'Deployment', link: 'deployment' }, { text: 'Run Server', link: 'server' }, { text: 'Connect Agent', link: 'agent' }, { text: 'Publish First Site', link: 'first-site' }, diff --git a/docs/en/guide/deployment.md b/docs/en/guide/deployment.md new file mode 100644 index 00000000..13d96379 --- /dev/null +++ b/docs/en/guide/deployment.md @@ -0,0 +1,102 @@ +# Deployment + +This page summarizes the OpenFlare deployment baseline, integration flow, upgrade entry points, and Agent install scripts. + +## Requirements + +Server: + +* Go 1.24+ +* Node.js 18+ +* Writable SQLite directory or reachable PostgreSQL instance + +Agent: + +* Go 1.24+ +* Writable Agent data directory +* Local mode requires `openresty -t` and `openresty -s reload` +* Docker mode requires Docker access + +## Docker Compose + +PostgreSQL is recommended for production: + +```yaml +services: + postgres: + image: postgres:17-alpine + restart: unless-stopped + environment: + POSTGRES_DB: openflare + POSTGRES_USER: openflare + POSTGRES_PASSWORD: replace-with-strong-password + volumes: + - postgres-data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U openflare -d openflare"] + interval: 10s + timeout: 5s + retries: 5 + + openflare: + image: ghcr.io/rain-kl/openflare:latest + container_name: openflare + restart: unless-stopped + depends_on: + postgres: + condition: service_healthy + ports: + - "3000:3000" + environment: + SESSION_SECRET: replace-with-random-string + SQLITE_PATH: /data/openflare.db + DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable + GIN_MODE: release + LOG_LEVEL: info + volumes: + - openflare-data:/data + +volumes: + postgres-data: + openflare-data: +``` + +```bash +docker compose up -d +``` + +Open `http://localhost:3000`. The default account is `root` / `123456`; change the password immediately. + +## Agent Install + +Using `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 +``` + +Using 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 \ + --agent-token YOUR_AGENT_TOKEN +``` + +Supported options include `--server-url`, `--discovery-token`, `--agent-token`, `--install-dir`, `--repo`, and `--no-service`. + +## Validation + +1. Prepare `agent_token` or `discovery_token` in the console. +2. Start Agent and confirm the node is online. +3. Add an enabled reverse proxy site. +4. Publish and activate a new version. +5. Confirm Agent pulls, validates, reloads, and reports the result. + +## Uninstall Agent + +```bash +curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash +``` diff --git a/docs/en/guide/index.md b/docs/en/guide/index.md index fbdea93d..81d0bfab 100644 --- a/docs/en/guide/index.md +++ b/docs/en/guide/index.md @@ -5,7 +5,8 @@ This section helps operators take OpenFlare from first boot to the first working Suggested order: 1. [Quick Start](./quick-start.md): run Server with Docker Compose and complete the first login. -2. [Run Server](./server.md): learn source startup, frontend build, and Swagger access. -3. [Connect Agent](./agent.md): use `agent_token` or `discovery_token` to bring a node online. -4. [Publish First Site](./first-site.md): create a site configuration, publish it, and verify node application. -5. [Upgrade and Maintenance](./upgrade.md): understand upgrade, uninstall, validation, and maintenance entry points. +2. [Deployment](./deployment.md): review production deployment, Agent install, validation, and upgrade. +3. [Run Server](./server.md): learn source startup, frontend build, and Swagger access. +4. [Connect Agent](./agent.md): use `agent_token` or `discovery_token` to bring a node online. +5. [Publish First Site](./first-site.md): create a site configuration, publish it, and verify node application. +6. [Upgrade and Maintenance](./upgrade.md): understand upgrade, uninstall, validation, and maintenance entry points. diff --git a/docs/frontend-development-guidelines.md b/docs/frontend-development-guidelines.md deleted file mode 100644 index efe125a8..00000000 --- a/docs/frontend-development-guidelines.md +++ /dev/null @@ -1,128 +0,0 @@ -# OpenFlare 前端开发规范 - -本文档约束 `openflare_server/web` 的正式前端工程。它描述的是 `1.0.0` 之后仍然有效的结构、请求层、组件、样式、状态管理与测试基线。 - -## 1. 技术基线 - -默认技术栈： - -* Next.js 15 App Router -* React 19 -* TypeScript 5 -* Tailwind CSS 4 -* TanStack Query -* React Hook Form + Zod -* Zustand -* ESLint + Prettier -* Vitest + Testing Library + Playwright -* pnpm - -要求： - -* 默认使用 TypeScript -* 默认使用函数组件 -* 默认使用 App Router -* 前端必须支持 `light`、`dark`、`system` 三种主题模式 - - -## 2. 目录与分层 - -推荐目录： - -```text -app/ -components/ -features/ -lib/ -hooks/ -store/ -types/ -styles/ -tests/ -``` - -职责约束： - -* `app/`：路由、布局、页面组装 -* `features/`：按业务域组织模块 -* `components/`：跨 feature 复用组件 -* `lib/`：请求客户端、环境变量、工具函数、常量 -* `store/`：少量跨页面 UI 状态 -* `types/`：共享类型定义 - -## 3. 路由与页面 - -页面文件只负责： - -* 获取路由参数 -* 组织页面结构 -* 调用 feature 组件 - -页面不应负责： - -* 手写复杂 API 细节 -* 编写复杂表单校验逻辑 -* 维护大量彼此耦合的局部状态 - -## 4. 数据请求与类型 - -### 4.1 请求层 - -所有 API 请求必须统一经过 `lib/api/`。 - -要求： - -* 统一处理 `success/message/data` 响应结构 -* 统一处理鉴权失效、网络异常和通用错误消息 -* 统一维护资源接口与请求路径 - -禁止： - -* 在页面组件中直接调用 `fetch('/api/...')` -* 在多个组件中重复拼接同一接口路径 - -### 4.2 状态分层 - -* 服务端状态：TanStack Query -* 页面临时状态：组件内部 `useState` -* 跨页面 UI 状态：Zustand - -不推荐： - -* 用 Zustand 保存服务端主数据 -* 用 Context 代替完整数据层方案 - -### 4.3 类型 - -要求： - -* 开启 TypeScript 严格模式 -* 禁止滥用 `any` -* API 响应、表单输入、业务实体必须有明确类型 - -## 5. 表单与交互 - -统一使用： - -* React Hook Form -* Zod - -高风险操作必须： - -* 二次确认 -* 展示操作对象名称 -* 明确成功与失败反馈 - -## 6. 样式与主题 - -样式原则： - -* 统一使用 Tailwind CSS 与现有 token 体系 -* 优先复用已有基础组件与布局组件 -* 保持视觉层级、留白与语义颜色一致 - -主题要求： - -* 同时支持 `light`、`dark`、`system` -* 用户选择必须持久化 -* 首屏尽量避免主题闪烁 diff --git a/docs/deployment.md b/docs/guide/deployment.md similarity index 64% rename from docs/deployment.md rename to docs/guide/deployment.md index fbcb1256..a4f6cf61 100644 --- a/docs/deployment.md +++ b/docs/guide/deployment.md @@ -1,51 +1,25 @@ -# OpenFlare 部署说明 +# 部署说明 -本文档只保留 OpenFlare `1.0.0` 的当前部署基线、联调入口与升级方式。 +本文档说明 OpenFlare `1.0.0` 之后的部署基线、联调入口、升级方式与 Agent 一键部署流程。 -## 1. 前置条件 +## 前置条件 -### 1.1 Server +Server： * Go 1.24+ * Node.js 18+ * 可写 SQLite 文件目录，或可访问的 PostgreSQL 实例 -### 1.2 Agent +Agent： * Go 1.24+ * 对 Agent 数据目录有写权限 * 本机模式下可执行 `openresty -t` 与 `openresty -s reload` * Docker 模式下具备 Docker 执行权限 -## 2. 启动 Server +## Docker Compose 启动 Server -### 2.1 构建前端 - -```bash -cd openflare_server/web -corepack enable -pnpm install -pnpm build -``` - -`pnpm build` 会生成供 Go Server 托管的静态产物。 - -### 2.2 源码启动 - -```bash -cd openflare_server -export SESSION_SECRET='replace-with-random-string' -export SQLITE_PATH='./openflare.db' -export LOG_LEVEL='info' -# 可选：设置后优先使用 PostgreSQL。 -# 如果 PostgreSQL 为空且本地 SQLite 文件存在，启动时会自动迁移数据。 -# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable' -go run . -``` - -默认监听 `3000` 端口。 - -### 2.3 Docker Compose 启动 +推荐生产部署使用 PostgreSQL： ```yaml services: @@ -91,20 +65,43 @@ volumes: docker compose up -d ``` -### 2.4 首次登录 +首次访问 `http://localhost:3000`，默认账号为 `root` / `123456`。登录后请立即修改默认密码。 -访问 `http://localhost:3000` +## 源码启动 Server -默认账号： +先构建管理端前端： -* 用户名：`root` -* 密码：`123456` +```bash +cd openflare_server/web +corepack enable +pnpm install +pnpm build +``` -### 2.5 Swagger +再启动 Server： -登录管理端后访问：`http://localhost:3000/swagger/index.html` +```bash +cd openflare_server +export SESSION_SECRET='replace-with-random-string' +export SQLITE_PATH='./openflare.db' +export LOG_LEVEL='info' +# 可选：设置后优先使用 PostgreSQL。 +# 如果 PostgreSQL 为空且本地 SQLite 文件存在，启动时会自动迁移数据。 +# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable' +go run . +``` -如需在本地重新生成文档： +默认监听 `3000` 端口。 + +## Swagger + +登录管理端后访问： + +```text +http://localhost:3000/swagger/index.html +``` + +本地重新生成 Swagger： ```bash go install github.com/swaggo/swag/cmd/swag@v1.16.4 @@ -112,11 +109,11 @@ cd openflare_server swag init -g main.go -o docs ``` -## 3. Agent 配置 +## Agent 接入模式 -当前支持两种接入模式。 +Agent 支持两种接入模式。 -### 3.1 使用节点专属 `agent_token` +使用节点专属 `agent_token`： ```json { @@ -132,7 +129,7 @@ swag init -g main.go -o docs } ``` -### 3.2 使用全局 `discovery_token` +使用全局 `discovery_token`： ```json { @@ -150,13 +147,44 @@ swag init -g main.go -o docs 说明： -* `agent_token` 与 `discovery_token` 至少填写一个 -* 未配置 `openresty_path` 时默认使用 Docker OpenResty -* Agent 会暴露本机观测端口并在 server 恢复后补传最近窗口数据 +* `agent_token` 与 `discovery_token` 至少填写一个。 +* 未配置 `openresty_path` 时默认使用 Docker OpenResty。 +* Agent 会暴露本机观测端口并在 Server 恢复后补传最近窗口数据。 -## 4. 启动 Agent +## 一键部署 Agent -### 4.1 直接运行 +使用 `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 +``` + +使用节点专属 `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 +``` + +支持参数： + +| 参数 | 说明 | +| --- | --- | +| `--server-url` | Server 地址 | +| `--discovery-token` | 首次自动注册 Token | +| `--agent-token` | 节点专属 Token | +| `--install-dir` | 安装目录 | +| `--repo` | 下载 Agent 的仓库 | +| `--no-service` | 不创建系统服务 | + +安装脚本会下载最新 Agent、生成 `agent.json`、创建 `openflare-agent.service` 并启动服务。 + +## 手动启动 Agent + +源码运行： ```bash cd openflare_agent @@ -164,7 +192,7 @@ export LOG_LEVEL='info' go run ./cmd/agent -config /path/to/agent.json ``` -### 4.2 编译后二进制运行 +编译后二进制运行： ```bash cd openflare_agent @@ -173,71 +201,9 @@ export LOG_LEVEL='info' ./openflare-agent -config /path/to/agent.json ``` -## 5. 最小联调步骤 +## 卸载 Agent -1. 在管理端准备 `agent_token` 或 `discovery_token` -2. 启动 Agent 并确认节点上线 -3. 新增一条启用中的反代规则 -4. 生成并激活新版本 -5. 确认 Agent 拉取配置、执行 `openresty -t`、reload 并上报结果 - -预期管理端可看到： - -* 节点在线状态 -* 节点当前版本 -* 最近一次应用结果 -* 自动注册后的专属 `agent_token` - -## 6. 升级说明 - -* Root 用户可在管理端顶栏检查并升级 Server 正式版 -* 如需尝试 preview 版本，可手动检查对应发布 -* 节点 Agent 默认只跟随正式版自动更新；preview 升级需要手动触发 -* 也可通过上传 Server 二进制的方式执行确认升级 - -## 7. 常用验证命令 - -### 7.1 Server - -```bash -cd openflare_server -GOCACHE=/tmp/openflare-go-cache go test ./... -``` - -### 7.2 Agent - -```bash -cd openflare_agent -GOCACHE=/tmp/openflare-go-cache go test ./... -``` - -### 7.3 Frontend - -```bash -cd openflare_server/web -pnpm build -``` - -## 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` 并启动服务。 - -如需彻底卸载 Agent 并清空本地数据，可执行： +如需彻底卸载 Agent 并清空本地数据： ```bash curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash @@ -245,14 +211,52 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/unin 支持参数： -* `--install-dir` -* `--service-name` +| 参数 | 说明 | +| --- | --- | +| `--install-dir` | Agent 安装目录 | +| `--service-name` | systemd 服务名 | 卸载脚本会先停止 Agent、移除 `openflare-agent.service`、删除整个安装目录，再根据卸载前保存的 `agent.json` 判断 OpenResty 安装方式： -* Docker 模式：删除对应容器，并尝试移除 OpenResty 镜像 -* 本机 `openresty_path` 模式：不改动本机 OpenResty，仅提示用户手动卸载 +* Docker 模式：删除对应容器，并尝试移除 OpenResty 镜像。 +* 本机 `openresty_path` 模式：不改动本机 OpenResty，仅提示用户手动卸载。 -## 9. 文档维护要求 +## 最小联调步骤 -部署方式、升级方式、接入模式或联调流程变化时，同步更新本文档和 `README.md`。 +1. 在管理端准备 `agent_token` 或 `discovery_token`。 +2. 启动 Agent 并确认节点上线。 +3. 新增一条启用中的反代规则。 +4. 生成并激活新版本。 +5. 确认 Agent 拉取配置、执行 `openresty -t`、reload 并上报结果。 + +预期管理端可看到节点在线状态、节点当前版本、最近一次应用结果，以及自动注册后的专属 `agent_token`。 + +## 升级说明 + +* Root 用户可在管理端顶栏检查并升级 Server 正式版。 +* 如需尝试 preview 版本，可手动检查对应发布。 +* 节点 Agent 默认只跟随正式版自动更新；preview 升级需要手动触发。 +* 也可通过上传 Server 二进制的方式执行确认升级。 + +## 常用验证命令 + +Server： + +```bash +cd openflare_server +GOCACHE=/tmp/openflare-go-cache go test ./... +``` + +Agent： + +```bash +cd openflare_agent +GOCACHE=/tmp/openflare-go-cache go test ./... +``` + +Frontend： + +```bash +cd openflare_server/web +pnpm build +``` diff --git a/docs/guide/index.md b/docs/guide/index.md index 97f8a97e..ce722b56 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -5,9 +5,10 @@ 推荐阅读顺序： 1. [快速开始](./quick-start.md)：用 Docker Compose 启动 Server，并完成首次登录。 -2. [启动 Server](./server.md)：了解源码启动、前端构建和 Swagger 入口。 -3. [接入 Agent](./agent.md)：选择 `agent_token` 或 `discovery_token`，让节点上线。 -4. [发布第一份配置](./first-site.md)：创建网站配置，发布并确认节点应用。 -5. [升级与维护](./upgrade.md)：了解升级、卸载、验证和日常维护入口。 +2. [部署说明](./deployment.md)：查看生产部署、Agent 一键安装、联调与升级。 +3. [启动 Server](./server.md)：了解源码启动、前端构建和 Swagger 入口。 +4. [接入 Agent](./agent.md)：选择 `agent_token` 或 `discovery_token`，让节点上线。 +5. [发布第一份配置](./first-site.md)：创建网站配置，发布并确认节点应用。 +6. [升级与维护](./upgrade.md)：了解升级、卸载、验证和日常维护入口。 如果你要参与开发，先阅读 [设计](../design/) 与 [开发约束](../design/development.md)，再进入代码修改。 diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index adb448c1..4218c77e 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -1,7 +1,28 @@ # 配置项 +本文档汇总 OpenFlare `1.0.0` 当前支持的 Server 与 Agent 配置项，只保留仍然有效的启动、部署与运行参数。 + +## 配置来源 + +Server 支持三类配置来源： + +1. 命令行参数。 +2. 环境变量。 +3. 数据库 `Option` 表中的运行时配置。 + +Agent 支持： + +1. `-config` 命令行参数。 +2. `agent.json` 配置文件。 +3. 少量日志相关环境变量。 + ## Server 命令行参数 +```bash +cd openflare_server +go run . --port 3000 --log-dir ./logs +``` + | 参数 | 作用 | 默认值 | | --- | --- | --- | | `--port` | 指定 Server 监听端口 | `3000` | @@ -24,7 +45,70 @@ | `UPLOAD_PATH` | 上传目录 | `upload` | | `AGENT_TOKEN` | 兼容旧部署的全局 Agent Token | 空 | -`DSN` 与 `SQL_DSN` 同时存在时优先使用 `DSN`。配置 PostgreSQL 后，Server 优先使用 PostgreSQL；当目标 PostgreSQL 为空且本地 SQLite 文件存在时，启动阶段会自动迁移 SQLite 数据。 +说明： + +* `DSN` 与 `SQL_DSN` 同时存在时优先使用 `DSN`。 +* `DSN` 或 `SQL_DSN` 与 `SQLITE_PATH` 同时存在时优先使用 PostgreSQL。 +* 当目标 PostgreSQL 数据库为空且本地 `SQLITE_PATH` 文件存在时，Server 启动阶段会自动迁移 SQLite 数据，并在日志中输出按表迁移进度。 +* `SESSION_SECRET` 生产环境必须显式配置。 +* `REDIS_CONN_STRING` 未配置时，相关能力回退为进程内实现。 + +## 运行时 Option + +以下配置由管理端设置页维护，可热更新： + +| 配置项 | 作用 | 默认值 | +| --- | --- | --- | +| `AgentHeartbeatInterval` | Agent 心跳间隔（毫秒） | `10000` | +| `NodeOfflineThreshold` | 节点离线阈值（毫秒） | `120000` | +| `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/OpenFlare` | +| `GeoIPProvider` | 节点/IP 归属解析方式 | `ipinfo` | +| `RegisterEnabled` | 是否允许新用户注册 | `false` | +| `PasswordRegisterEnabled` | 是否允许通过密码方式注册 | `true` | +| `DatabaseAutoCleanupEnabled` | 是否启用每日自动清理观测数据 | `false` | +| `DatabaseAutoCleanupRetentionDays` | 自动清理保留天数，至少 1 天 | `30` | +| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口 | `300` / `180` | +| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口 | `300` / `180` | +| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口 | `50` / `60` | +| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口 | `50` / `60` | +| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 敏感接口限流次数 / 时间窗口 | `100` / `1200` | + +说明： + +* `DatabaseAutoCleanupEnabled` 开启后，Server 会在每天凌晨 3 点自动清理 `node_access_logs`、`node_metric_snapshots`、`node_request_reports` 三类观测数据。 +* `DatabaseAutoCleanupRetentionDays` 为统一保留天数，必须大于等于 1。 +* 管理端支持手动清理时留空保留天数，以直接删除对应数据集的全部历史记录。 + +## OpenResty 参数 + +OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前常用项包括： + +* `OpenRestyWorkerProcesses` +* `OpenRestyWorkerConnections` +* `OpenRestyWorkerRlimitNofile` +* `OpenRestyKeepaliveTimeout` +* `OpenRestyProxyConnectTimeout` +* `OpenRestyProxySendTimeout` +* `OpenRestyProxyReadTimeout` +* `OpenRestyProxyBufferingEnabled` +* `OpenRestyGzipEnabled` +* `OpenRestyCacheEnabled` +* `OpenRestyCachePath` +* `OpenRestyCacheMaxSize` + +这类参数必须以结构化方式校验、保存并参与版本渲染。 + +约束： + +* 管理端不再暴露 `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` 的弃用告警。 ## 前端构建环境变量 @@ -34,31 +118,19 @@ | `NEXT_PUBLIC_APP_VERSION` | 前端展示版本号 | `dev` | | `NEXT_DEV_BACKEND_URL` | 本地开发服务器代理的后端地址 | `http://127.0.0.1:3000` | -## 运行时 Option +## Agent 环境变量 -以下配置由管理端设置页维护，可热更新： - -| 配置项 | 作用 | 默认值 | +| 环境变量 | 作用 | 默认值 | | --- | --- | --- | -| `AgentHeartbeatInterval` | Agent 心跳间隔，毫秒 | `10000` | -| `NodeOfflineThreshold` | 节点离线阈值，毫秒 | `120000` | -| `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/OpenFlare` | -| `GeoIPProvider` | 节点/IP 归属解析方式 | `ipinfo` | -| `RegisterEnabled` | 是否允许新用户注册 | `false` | -| `PasswordRegisterEnabled` | 是否允许通过密码方式注册 | `true` | -| `DatabaseAutoCleanupEnabled` | 是否启用每日自动清理观测数据 | `false` | -| `DatabaseAutoCleanupRetentionDays` | 自动清理保留天数 | `30` | -| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口 | `300` / `180` | -| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口 | `300` / `180` | -| `UploadRateLimitNum` / `UploadRateLimitDuration` | 上传接口限流次数 / 时间窗口 | `50` / `60` | -| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | 下载接口限流次数 / 时间窗口 | `50` / `60` | -| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | 敏感接口限流次数 / 时间窗口 | `100` / `1200` | +| `LOG_LEVEL` | Agent 日志等级 | `info` | -OpenResty 性能参数与缓存参数也保存在 Option 表，常用项包括 `OpenRestyWorkerProcesses`、`OpenRestyWorkerConnections`、`OpenRestyProxyConnectTimeout`、`OpenRestyProxyReadTimeout`、`OpenRestyCacheEnabled`、`OpenRestyCachePath` 与 `OpenRestyCacheMaxSize`。 +## Agent 命令行参数 -## Agent 配置 +| 参数 | 作用 | 默认值 | +| --- | --- | --- | +| `-config` | 指定 Agent 配置文件路径 | `./agent.json` | -Agent 支持 `-config` 命令行参数、`agent.json` 配置文件和 `LOG_LEVEL` 环境变量。 +## Agent 配置字段 | 字段 | 作用 | 是否必填 | 默认值/行为 | | --- | --- | --- | --- | @@ -66,7 +138,7 @@ Agent 支持 `-config` 命令行参数、`agent.json` 配置文件和 `LOG_LEVEL | `agent_token` | 节点专属认证 Token | 与 `discovery_token` 二选一 | 空 | | `discovery_token` | 首次自动注册使用的全局 Token | 与 `agent_token` 二选一 | 空 | | `node_name` | 节点名称 | 否 | 自动使用主机名 | -| `node_ip` | 节点 IP | 否 | 自动探测 | +| `node_ip` | 节点 IP | 否 | 自动探测，优先选择公网 IPv4；仅无公网地址时退回可用内网地址 | | `openresty_path` | 本机 OpenResty 路径 | 否 | 空，未设置时走 Docker 模式 | | `openresty_container_name` | Docker 模式下的容器名 | 否 | `openflare-openresty` | | `openresty_docker_image` | Docker 模式下的镜像 | 否 | `openresty/openresty:alpine` | @@ -76,11 +148,28 @@ Agent 支持 `-config` 命令行参数、`agent.json` 配置文件和 `LOG_LEVEL | `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` 毫秒 | -`heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串。 +说明： + +* `agent_token` 与 `discovery_token` 不能同时为空。 +* `heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串。 +* 未配置 `openresty_path` 时默认使用 Docker OpenResty 模式。 +* Agent 自动探测到私网 `node_ip` 时，Server 会在注册/心跳阶段优先保留 Agent 直连来源的公网地址，避免 NAT/多网卡场景误登记内网网卡地址。 + +## 维护要求 + +以下内容变化时，必须同步更新本文档： + +* Server 命令行参数。 +* Server 环境变量。 +* Agent 命令行参数。 +* Agent 配置字段。 +* 任一配置项的默认值、用途或示例。