[文档] 文档更新

2026-09-28 05:46:36 +08:00 · 2026-03-15 17:11:17 +08:00
parent 5858e30af6
commit b2eb4befba
11 changed files with 769 additions and 2232 deletions
@@ -7,7 +7,7 @@

 # OpenFlare

-轻量、自托管的反向代理控制面，用于管理 Nginx 配置发布、节点同步、TLS 证书与版本回滚。
+轻量、自托管的 OpenResty 控制面，用于管理反向代理规则、配置发布、节点同步、TLS 证书与基础可观测能力。

 </div>

@@ -26,39 +26,55 @@
  </a>
 </p>

-## 项目定位
+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) 开源。