mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-04 07:06:36 +08:00
[优化] 文档更新
This commit is contained in:
ryan
+48
-79
@@ -1,100 +1,69 @@
|
||||
# 发布第一份配置
|
||||
|
||||
你会学到：如何创建第一条网站配置、绑定源站与证书、发布配置版本，并确认 Agent 已经应用。
|
||||
你会学到：如何以最简单的方式创建第一条反向代理规则、发布配置版本，并确认 Agent 已经拉取并应用配置。
|
||||
|
||||
OpenFlare 的发布链路以完整配置版本为中心。你在管理端修改网站配置后，需要发布并激活新版本，Agent 才会在后续 heartbeat 中拉取并应用。
|
||||
OpenFlare 的发布链路以“不可变配置版本”为核心。你在管理端修改规则后，需要发布并激活新版本，在线的 Agent 才会自动同步并应用。
|
||||
|
||||
---
|
||||
|
||||
## 发布前检查
|
||||
|
||||
确认以下条件已经满足：
|
||||
在开始发布前，请确保以下条件已满足：
|
||||
|
||||
| 项目 | 期望 |
|
||||
| 检查项 | 状态要求 |
|
||||
| --- | --- |
|
||||
| Server | 可以登录管理端 |
|
||||
| Agent | 至少一个节点在线 |
|
||||
| 源站 | Agent 节点可以访问源站地址 |
|
||||
| 域名 | 域名已经解析到 OpenResty 节点，或准备通过本地 hosts / curl Host 头验证 |
|
||||
| HTTPS | 如需 HTTPS，证书已上传或托管 |
|
||||
| **Server** | 控制面板已正常启动，且能顺利登录管理端 |
|
||||
| **Agent** | 至少有一个 Agent 节点处于在线状态（可在「节点管理」中确认） |
|
||||
| **源站** | 确认你的后端源站服务可从 Agent 宿主机正常访问 |
|
||||
| **域名/测试** | 域名已完成 DNS 解析，或者准备好在客户端使用本地 hosts / curl 命令行 Host 头进行测试 |
|
||||
|
||||
## 创建网站配置
|
||||
---
|
||||
|
||||
在管理端新增网站配置时至少需要：
|
||||
## 步骤一：创建首个网站配置
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| 网站名称 | 业务唯一标识；未显式填写时可使用主域名 |
|
||||
| 域名 | 至少一个域名，第一项视为主域名 |
|
||||
| 源站地址 | 合法的 `http://` 或 `https://` 上游地址 |
|
||||
| 启用状态 | 只有启用的网站配置会参与发布渲染 |
|
||||
为了快速验证，我们首先部署一个最基础的 HTTP 反代站点：
|
||||
|
||||
示例：
|
||||
1. 登录控制面板，进入 **「网站配置」**，点击 **「创建网站」**。
|
||||
2. 填写最基础的站点配置：
|
||||
* **网站名称**：输入简易标识（如 `first-app`）。
|
||||
* **域名 (Domains)**：输入用于测试的域名（如 `first.example.com`）。**第一项默认作为主域名**。
|
||||
3. 配置上游源站（Upstream）：
|
||||
* **源站类型**：选择「标准反代」。
|
||||
* **源站地址**：勾选手动输入并填入后端服务地址（如 `http://10.0.0.10:8080` 或测试专用的 `http://httpbin.org`）。
|
||||
4. 点击保存，完成网站创建。
|
||||
|
||||
| 字段 | 示例 |
|
||||
| --- | --- |
|
||||
| 网站名称 | `app` |
|
||||
| 域名 | `app.example.com` |
|
||||
| 源站地址 | `http://10.0.0.20:8080` |
|
||||
> [!TIP]
|
||||
> **关于 HTTPS 与证书准备**
|
||||
> 本节仅引导快速部署基础 HTTP 规则。若你需要导入已有的 SSL 证书或通过 ACME 协议向 Let's Encrypt 自动申请证书并开启 443 端口 HTTPS 代理，请前往 [新建反代配置](./proxy-config.md) 查阅详细步骤。
|
||||
|
||||
同一个域名只能属于一个网站配置。同一网站内的流量限制、反向代理和缓存配置按站点共享。
|
||||
---
|
||||
|
||||
## 绑定证书
|
||||
## 步骤二：预览并发布配置版本
|
||||
|
||||
HTTPS 证书按域名绑定。没有绑定证书的域名不会被自动放入 `443 ssl` server 块。
|
||||
新增的网站配置仍保存在 Server 的数据库中，处于草稿状态，需要通过发布版本分发到数据面：
|
||||
|
||||
如果一个网站包含多个域名，发布渲染会按证书分组生成 HTTPS 配置，并确保所有域名仍属于同一站点快照。
|
||||
1. 点击控制面板右上角的 **「配置预览」** 按钮，系统会展示本次新增路由的物理配置文件 Diff 差异。
|
||||
2. 确认渲染出的配置内容正确无误后，点击 **「发布并激活」**。
|
||||
3. 控制面将生成一个唯一的配置版本号（格式为 `YYYYMMDD-NNN`）。
|
||||
|
||||
## 发布与激活
|
||||
---
|
||||
|
||||
标准链路：
|
||||
## 步骤三：验证 Agent 生效状态
|
||||
|
||||
```text
|
||||
修改规则 -> 预览 / 查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
|
||||
```
|
||||
发布成功后，控制面会立即通过 WebSocket 通知在线 Agent（若 WebSocket 离线，则会在 Agent 的心跳中作为差分感知）：
|
||||
|
||||
发布时 Server 会读取全部启用的网站配置、OpenResty 主配置模板、性能参数与缓存参数，渲染完整 OpenResty 配置，计算 `checksum`，写入 `config_versions`，再切换激活版本。
|
||||
|
||||
## 验证结果
|
||||
|
||||
发布后在管理端确认：
|
||||
|
||||
| 位置 | 期望结果 |
|
||||
| --- | --- |
|
||||
| 节点列表 | 节点在线 |
|
||||
| 节点详情 | 当前版本与激活版本一致 |
|
||||
| 应用记录 | 最近一次应用成功 |
|
||||
| 版本页面 | 新版本处于激活状态 |
|
||||
|
||||
在节点上确认 Agent 日志：
|
||||
|
||||
```bash
|
||||
journalctl -u openflare-agent -n 100 --no-pager
|
||||
```
|
||||
|
||||
用域名访问：
|
||||
|
||||
```bash
|
||||
curl -I http://app.example.com
|
||||
```
|
||||
|
||||
如果域名还没有正式解析，可以临时指定 Host 头访问节点 IP：
|
||||
|
||||
```bash
|
||||
curl -I -H 'Host: app.example.com' http://NODE_IP
|
||||
```
|
||||
|
||||
HTTPS 验证：
|
||||
|
||||
```bash
|
||||
curl -I https://app.example.com
|
||||
```
|
||||
|
||||
## 回滚
|
||||
|
||||
如果目标版本应用失败并回滚，Agent 会在本地阻断同一 `version + checksum` 的重复应用，直到控制面激活版本或 checksum 发生变化。
|
||||
|
||||
回滚到旧版本：
|
||||
|
||||
1. 打开配置版本页面。
|
||||
2. 找到上一个确认可用的历史版本。
|
||||
3. 重新激活该版本。
|
||||
4. 查看节点应用记录，确认 Agent 应用成功。
|
||||
1. **管理端验证**：进入「节点管理」-> 点击节点进入详情，检查**当前版本号**是否已成功变为刚刚发布的最新激活版本，且「应用记录」显示为成功。
|
||||
2. **边缘节点验证**：你可以在 Agent 节点宿主机上通过日志检查应用情况：
|
||||
```bash
|
||||
# 如果是 Docker 部署的 Agent
|
||||
docker logs openflare-agent
|
||||
|
||||
# 如果是本地 systemd 部署的 Agent
|
||||
journalctl -u openflare-agent -n 50 --no-pager
|
||||
```
|
||||
3. **连通性测试**：
|
||||
在客户端电脑上，使用 `curl` 携带测试 Host 请求 Agent 节点的 IP 地址进行最终验证：
|
||||
```bash
|
||||
curl -I -H "Host: first.example.com" http://AGENT_NODE_IP
|
||||
```
|
||||
若返回的状态码与后端源站响应一致，即代表你的第一条反代规则已成功在边缘节点落地生效！
|
||||
|
||||
+14
-8
@@ -9,13 +9,16 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站
|
||||
如果你第一次接触 OpenFlare，按下面顺序阅读：
|
||||
|
||||
1. [快速开始](./quick-start.md)：用 Docker Compose 启动 Server，登录管理端，并接入第一个 Agent。
|
||||
2. [基础使用](./usage.md)：了解网站配置、源站、证书、发布、回滚和观测的常见操作。
|
||||
3. [内网穿透与隧道使用](./tunnel-usage.md)：学习部署 Relay 与 Client，实现安全、无公网 IP 反向穿透。
|
||||
4. [WAF 安全防护使用](./waf-usage.md)：掌握 IP 黑白名单、自动 IP 组 Expr 自动聚合、地域限制与 PoW CC 防护。
|
||||
5. [WAF 自动 IP 组语法](./waf-ip-group-expr.md)：编写自动 IP 组 Expr 规则，了解关键字含义和预设规则。
|
||||
6. [部署说明](../deployment/deployment.md)：把 Server 和 Agent 放到更接近生产的环境中运行。
|
||||
7. [配置项参考](../reference/configuration.md)：查 Server 环境变量、运行时 Option 和 Agent 配置字段。
|
||||
8. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty 应用和前端构建问题。
|
||||
2. [发布第一份配置](./first-site.md)：快速新建一条最基础的 HTTP 反代站点规则，并验证节点生效状态。
|
||||
3. [新建反代配置](./proxy-config.md)：一步一步了解如何从证书导入与申请开始，配置 HTTPS 加密与上游源站管理。
|
||||
4. [Pages 静态托管使用](./pages-usage.md)：了解静态项目 ZIP 上传限制、SPA Fallback、以及内置 API 反向代理配置。
|
||||
5. [内网穿透与隧道使用](./tunnel-usage.md)：部署 Relay 与 Client，实现安全、无公网 IP 反向穿透。
|
||||
6. [WAF 安全防护使用](./waf-usage.md)：配置 WAF 规则组，掌握 IP 黑白名单、自动/订阅 IP 组、地域限制与 PoW CC 防护。
|
||||
7. [WAF 自动 IP 组语法](./waf-ip-group-expr.md)：编写自动 IP 组 Expr 规则，了解关键字含义和预设规则。
|
||||
8. [Uptime Kuma 监控同步](./uptime-kuma.md)：配置并使用 Uptime Kuma 自动差分同步和监控范围控制。
|
||||
9. [SSO 登录配置](./sso.md)：配置 GitHub 或 OIDC 实现第三方单点登录 (SSO) 接入。
|
||||
10. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty 应用和前端构建问题。
|
||||
11. [引用与致谢](./credits.md)：查看系统依赖的优秀开源项目与社区致谢清单。
|
||||
|
||||
## 按角色查找
|
||||
|
||||
@@ -23,14 +26,17 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站
|
||||
| --- | --- |
|
||||
| 5 分钟内跑起管理端 | [快速开始](./quick-start.md) |
|
||||
| 发布第一条反向代理配置 | [发布第一份配置](./first-site.md) |
|
||||
| 配置域名证书与高级反代 | [新建反代配置](./proxy-config.md) |
|
||||
| 托管单页应用或静态网站 | [Pages 静态托管使用](./pages-usage.md) |
|
||||
| 配置内网穿透映射 | [内网穿透与隧道使用](./tunnel-usage.md) |
|
||||
| 配置防 CC 与 IP 组拦截 | [WAF 安全防护使用](./waf-usage.md) |
|
||||
| 编写自动 IP 组规则 | [WAF 自动 IP 组语法](./waf-ip-group-expr.md) |
|
||||
| 自动同步监测站点状态 | [Uptime Kuma 监控同步](./uptime-kuma.md) |
|
||||
| 接入或重装节点 Agent | [接入 Agent](../deployment/agent.md) |
|
||||
| 从源码启动 Server | [启动 Server](../deployment/server.md) |
|
||||
| 配置 GitHub 或 OIDC 登录 | [SSO 登录配置](./sso.md) |
|
||||
| 升级 Server 或 Agent | [升级与维护](../deployment/upgrade.md) |
|
||||
| 参与开发或修复问题 | [本地开发](../design/development.md) 与 [开发约束](../guildline/development-constraints.md) |
|
||||
| 参与开发或修复问题 | [启动 Server](../deployment/server.md) 与 [开发约束](../guideline/development-constraints.md) |
|
||||
| 理解架构和发布模型 | [系统架构](../design/architecture.md) 与 [Agent 与发布模型](../design/agent-design.md) |
|
||||
| 查看开源引用与致谢 | [引用与致谢](./credits.md) |
|
||||
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
# Pages 静态托管使用
|
||||
|
||||
你会学到：如何在 OpenFlare 中使用 Pages 静态托管功能部署前端项目（如 React、Vue 等 SPA 或 VitePress、Hugo 等静态站点），配置单页应用 (SPA) Fallback 路由以及接口反向代理 (API Proxy)，并理解不可变部署与 Agent 侧原子切换的底层逻辑。
|
||||
|
||||
---
|
||||
|
||||
## 核心机制与工作流
|
||||
|
||||
OpenFlare Pages 提供受 Cloudflare Pages 启发的 **Direct Upload (直接上传)** 静态网站托管服务。它与常规代理站点的不同之处在于，数据面的边缘节点 (Agent) 会将静态文件拉取并解压到节点本地，直接通过本地的 OpenResty 提供高性能的静态文件服务，无需维护额外的 Nginx 宿主机静态目录同步。
|
||||
|
||||
```text
|
||||
[ 管理员 / CI ] ────── 1. 上传 ZIP 压缩包 ──────► [ OpenFlare Server ]
|
||||
│
|
||||
[ 访客浏览器 ] ◄────── 4. 访问页面 / 静态资源 ────────── [ Agent 节点 / OpenResty ]
|
||||
▲
|
||||
│
|
||||
2. 检查 Checksum 并拉取 ZIP
|
||||
3. 解压并原子切换 current 链接
|
||||
```
|
||||
|
||||
1. **直接上传部署包**：在控制面上传预构建好的网站 `.zip` 压缩包，Server 会生成一条带有唯一 SHA-256 校验和 (Checksum) 的不可变部署记录。
|
||||
2. **发布与推送**：在路由配置中将源站类型 (Upstream Type) 设为 `Pages 静态托管` 并绑定项目。发布配置版本后，Server 会广播给所有 Agent 节点。
|
||||
3. **安全拉取与部署**：Agent 节点识别到新配置引用了新的 Pages 部署，增量下载 ZIP 包，校验 Checksum 保证一致性，并在本地解压、完成原子目录切换，重载 OpenResty 使服务生效。
|
||||
|
||||
---
|
||||
|
||||
## 第一步：上传部署包与创建 Pages 项目
|
||||
|
||||
1. 登录管理端控制面板，进入左侧导航 **「静态托管 (Pages)」**，点击 **「创建项目」**。
|
||||
2. 填写项目基本信息：
|
||||
* **项目名称**：业务名称（如 `我的前端应用`）。
|
||||
* **项目标识 (Slug)**：URL 友好的唯一英文标识（如 `my-react-app`），将作为存储目录的文件夹名。
|
||||
3. 设定站点目录结构与入口：
|
||||
* **入口文件名**：默认为 `index.html`。
|
||||
* **静态资源根路径 (RootDir)**：如果你的打包产物在压缩包的子目录下（例如打包出来的 zip 里包含一个 `dist/` 目录），则需要在这里填入子路径（如 `dist`）。若打包产物直接在 zip 根目录，留空即可。
|
||||
4. **上传 ZIP 压缩包**：
|
||||
* 上传你的项目静态资源打包生成的 `.zip` 文件。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **部署包安全限制规范**
|
||||
> 为了保障控制面和边缘节点的系统安全与性能，上传的部署包必须满足以下硬性指标，否则会被系统拒绝：
|
||||
> * **大小限制**：ZIP 压缩包体积不得超过 **25 MiB**，解压后的总文件大小不得超过 **100 MiB**。
|
||||
> * **数量限制**：解压后的文件总数不得超过 **1,000 个**。
|
||||
> * **软链接拦截**：ZIP 包内禁止包含任何软链接 (Symbolic Link)，防御软链接劫持攻击。
|
||||
> * **Zip-Slip 防御**：压缩包中所有文件路径会被强制规范化，禁止使用 `..` 或以 `/` 开头，防止解压路径穿越攻击。
|
||||
> * **入口文件检查**：你指定的入口文件（在静态资源根路径下，如 `dist/index.html`）**必须在压缩包中存在**。
|
||||
|
||||
---
|
||||
|
||||
## 第二步：配置高级路由规则
|
||||
|
||||
在项目详情的配置页面中，你可以根据前端项目类型开启以下高级特性：
|
||||
|
||||
### 1. 单页应用 (SPA) Fallback 路由
|
||||
对于使用 React Router、Vue Router 等进行前端路由的单页应用 (SPA)，当用户直接刷新类似 `/profile/settings` 的子路径时，边缘节点本地并不存在该物理文件，会导致 404 错误。
|
||||
* **配置方式**：在项目设置中开启 **「SPA Fallback」**，并将路径设为入口文件（如 `/index.html`）。
|
||||
* **生效逻辑**：开启后，如果访客请求的静态资源在物理上不存在，OpenResty 会自动降级重定向渲染入口文件，将路由交由前端 JavaScript 接管，避免 404 报错。
|
||||
|
||||
### 2. 内置 API 反向代理
|
||||
为了避免前端请求后端 API 时遭遇跨域 (CORS) 限制，Pages 托管支持在同一个域名下直通后端 API。
|
||||
* **配置方式**：
|
||||
* **API 代理路径 (APIProxyPath)**：匹配的 URL 前缀（如 `/api`）。
|
||||
* **后端服务地址 (APIProxyPass)**：后端 API 的源站地址（如 `http://10.0.0.5:8080`）。
|
||||
* **重写规则 (APIProxyRewrite)**：可选。如果需要剥离前缀或重写路径，可使用正则匹配。例如：
|
||||
* 剥离前缀：将请求 `/api/users` 重写为 `/users` 发送给后端，配置为 `^/api/(.*)$ /$1`。
|
||||
* **生效逻辑**：所有以 `/api` 开头的请求会被直接转发至后端服务，而其他请求则继续由静态托管服务处理。
|
||||
|
||||
---
|
||||
|
||||
## 第三步：绑定代理路由并发布
|
||||
|
||||
Pages 项目配置并上传好部署包后，需要绑定到对外公开的域名上才能被访客访问。
|
||||
|
||||
1. 导航至左侧菜单 **「网站配置」**，创建或编辑一个代理站点。
|
||||
2. 在「路由规则」中修改或添加一条路由：
|
||||
* **源站类型 (Upstream Type)**：选择 **「Pages 静态托管」**。
|
||||
* **绑定 Pages 项目**：选择你刚才创建的项目，并指定要激活的部署版本（默认会自动关联最新上传成功的部署）。
|
||||
3. 点击右上角 **「配置预览」** -> 确认无误后点击 **「发布并激活」**。
|
||||
|
||||
## 运维与回滚
|
||||
|
||||
* **不可变部署与回滚**：每次在 Pages 项目下上传 `.zip` 文件，系统都会产生一个全新且唯一的部署版本。如果在历史部署列表中将上一版本设为激活并重新发布，可实现边缘节点的秒级回滚。
|
||||
* **原子切换与自愈**：边缘节点（Agent）在拉取静态资源包时，会执行校验与流式解压，并通过原子切换物理目录来保障服务的无缝过渡。同时，Agent 会定时清理不再引用的历史部署包。
|
||||
|
||||
> [!TIP]
|
||||
> 关于不可变部署、目录结构设计、增量拉取和安全防逃逸校验等底层架构与自愈细节，请参阅 [Pages 静态托管设计](../design/pages-design.md)。
|
||||
@@ -0,0 +1,102 @@
|
||||
# 新建反代配置
|
||||
|
||||
你会学到：如何一步一步在 OpenFlare 中从零新建并发布一个反向代理网站配置。本指南将指导你如何完成证书导入与申请、源站定义、路由规则配置、版本发布以及连通性验证。
|
||||
|
||||
---
|
||||
|
||||
## 推荐操作流程
|
||||
|
||||
在网关控制面中，建议遵循以下步骤新增反代规则：
|
||||
|
||||
```text
|
||||
[ 步骤 1. 证书管理 ] ──► [ 步骤 2. 源站定义 (可选) ] ──► [ 步骤 3. 新增网站配置 ]
|
||||
│
|
||||
[ 步骤 5. 验证访问 ] ◄── [ 步骤 4. 发布与激活版本 ] ◄───────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第一步：证书准备（导入与申请）
|
||||
|
||||
在使用 HTTPS 安全加密流量前，你需要先配置对应的 TLS 证书。OpenFlare 支持以下两种证书获取方式：
|
||||
|
||||
### 1. 手动导入已有证书
|
||||
如果你已经有第三方的证书（如腾讯云、阿里云申请的免费/收费证书，或者自签证书）：
|
||||
1. 导航至左侧菜单 **「证书管理」**，点击 **「导入证书」**。
|
||||
2. 填入证书名称（如 `my-domain-cert`）。
|
||||
3. 复制并粘贴你的 **证书内容 (PEM 格式公钥)** 以及 **证书私钥 (KEY 格式)**，点击保存。
|
||||
|
||||
### 2. 通过 ACME 协议自动申请
|
||||
OpenFlare 集成了 ACME 客户端，支持自动向 Let's Encrypt 申请并到期续签证书：
|
||||
1. **添加 ACME 账户**：进入「证书管理」->「ACME 账户」->「创建账户」，填入你的联系邮箱。
|
||||
2. **添加 DNS 账户 (用于 DNS-01 验证)**：进入「证书管理」->「DNS 账户」->「创建账户」，选择你的 DNS 托管商（当前仅 Cloudflare）并填入 API Token 凭证。
|
||||
3. **申请证书**：在「证书管理」中点击「申请证书」：
|
||||
* 选择配置好的 ACME 账户和 DNS 账户。
|
||||
* 输入需要托管证书的域名（支持通配符，如 `*.example.com`）。
|
||||
* 点击申请，系统将自动配置 DNS 挑战码并向 CA 申请证书，且会在到期前 30 天自动触发续期。
|
||||
|
||||
---
|
||||
|
||||
## 第二步：准备上游源站（可选）
|
||||
|
||||
源站（Origin）代表被代理的后端真实服务地址。虽然在新建网站时可以直接填写 IP，但推荐先在源站库中进行注册，以便后续复用与维护：
|
||||
|
||||
1. 进入左侧导航 **「源站管理」**，点击 **「创建源站」**。
|
||||
2. 填写源站名称（如 `production-api`）。
|
||||
3. 填入合法的上游地址（如 `http://10.0.0.10:8080`），点击保存。
|
||||
|
||||
---
|
||||
|
||||
## 第三步：新建网站配置
|
||||
|
||||
证书和源站就绪后，即可创建核心网站代理路由：
|
||||
|
||||
1. 进入左侧导航 **「网站配置」**，点击 **「创建网站」**。
|
||||
2. 填写网站基本配置：
|
||||
* **网站名称**：业务唯一标识（如 `app-portal`）。
|
||||
* **域名 (Domains)**：输入该站点绑定的域名列表。**第一项将自动视为主域名**。
|
||||
3. 配置上游源站（Upstream）：
|
||||
* **源站类型**：选择「标准反代」。
|
||||
* **源站地址**：从下拉框中选择第二步创建的源站；或者勾选手动输入并填入 `http://10.0.0.20:9000`。
|
||||
4. **绑定证书启用 HTTPS**：
|
||||
* 在域名列表中，点击域名旁边的配置按钮或 HTTPS 切换开关。
|
||||
* 勾选「启用 HTTPS」，并从证书下拉列表中选择第一步准备好的证书。
|
||||
* *注意：未绑定证书的域名只会保留 80 端口 HTTP 服务，不会被写入 443 端口代理中。*
|
||||
5. 点击保存创建配置。
|
||||
|
||||
---
|
||||
|
||||
## 第四步：发布并生效配置
|
||||
|
||||
你在管理端新增的网站配置仅保存在 Server 数据库中，**不会立即生效**。必须生成配置版本快照并分发到 Agent 边缘节点：
|
||||
|
||||
1. 点击控制面板右上角的 **「配置预览」** 按钮。
|
||||
2. 检查配置文件的 Diff 差异，确认你刚刚新增的 `server` 块以及证书绑定规则无误。
|
||||
3. 点击 **「发布并激活」** 按钮。
|
||||
4. **Agent 落地机制**：
|
||||
* 数据面的 Agent 节点在心跳中发现激活的版本 Checksum 变更，会自动拉取完整的 OpenResty 配置文件和证书包到本地。
|
||||
* 自动在本地执行配置校验（类似于 `openresty -t`），确认无语法错误后，执行平滑重载（`reload`）。
|
||||
* *如果重载或校验失败，Agent 会安全阻断并回滚至上一稳定版本，保证节点高可用。*
|
||||
|
||||
---
|
||||
|
||||
## 第五步：连通性与回滚验证
|
||||
|
||||
### 1. 验证访问
|
||||
你可以通过以下方式验证新配置是否生效：
|
||||
* **浏览器访问**：直接在浏览器输入 `https://your-domain.com` 查看是否成功代理后端。
|
||||
* **命令行验证**（推荐）：使用 `curl` 探测：
|
||||
```bash
|
||||
curl -I https://your-domain.com
|
||||
```
|
||||
* **绕过 DNS 校验**：若你的域名尚未正式解析，可以临时指定 `Host` 请求头请求 Agent 节点物理 IP：
|
||||
```bash
|
||||
curl -I -H "Host: your-domain.com" https://AGENT_NODE_IP --insecure
|
||||
```
|
||||
|
||||
### 2. 一键秒级回滚
|
||||
如果发布的新配置导致了线上业务异常：
|
||||
1. 导航至左侧 **「配置版本」** 菜单。
|
||||
2. 在历史列表中找到发布前的上一个稳定版本。
|
||||
3. 点击 **「激活此版本」**。
|
||||
4. 所有在线 Agent 节点将在秒级自动重载回历史配置，实现秒级避险。
|
||||
@@ -164,34 +164,15 @@ journalctl -u openflare-agent -f
|
||||
|
||||
如果没有 systemd，脚本会输出手动启动命令。
|
||||
|
||||
## 4. 发布第一份配置
|
||||
## 4. 后续步骤
|
||||
|
||||
在管理端完成以下操作：
|
||||
完成控制面板启动和 Agent 节点接入后，你已经成功搭建好了 OpenFlare 网关的基础运行环境。接下来你可以按顺序继续阅读以下两份指南，开始部署你的第一个反代站点：
|
||||
|
||||
1. 新增网站配置，填写网站名称、域名和源站地址。
|
||||
2. 确认网站配置处于启用状态。
|
||||
3. 发布前查看预览或变更摘要。
|
||||
4. 发布并激活新版本。
|
||||
5. 等待 Agent 在后续 heartbeat 中发现版本并应用。
|
||||
1. **发布第一个网站**：
|
||||
* 请参阅 [发布第一份配置](./first-site.md)。它将引导你以最简单的方式（使用纯 HTTP）发布你的第一条代理规则，并验证节点落地状态。
|
||||
2. **完整配置反向代理（HTTPS 与源站管理）**：
|
||||
* 请参阅 [新建反代配置](./proxy-config.md)。它将指导你从证书导入与申请开始，配置域名 HTTPS 证书绑定、源站管理并预览发布。
|
||||
|
||||
版本号格式为 `YYYYMMDD-NNN`。历史版本不可变，回滚通过重新激活旧版本完成。
|
||||
|
||||
## 5. 验证是否成功
|
||||
|
||||
在管理端确认：
|
||||
|
||||
| 位置 | 期望结果 |
|
||||
| --- | --- |
|
||||
| 节点列表 | Agent 节点在线 |
|
||||
| 节点详情 | 当前版本与激活版本一致 |
|
||||
| 应用记录 | 最近一次应用成功 |
|
||||
| 版本页面 | 新版本处于激活状态 |
|
||||
|
||||
在 Agent 节点确认：
|
||||
|
||||
```bash
|
||||
journalctl -u openflare-agent -n 100 --no-pager
|
||||
```
|
||||
|
||||
## 常见失败原因
|
||||
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
# Uptime Kuma 监控同步
|
||||
|
||||
你会学到：如何启用并配置 Uptime Kuma 自动同步集成，控制监测站点的同步范围与心跳探测参数，以及 OpenFlare 与 Uptime Kuma 差分同步的底层原理。
|
||||
|
||||
---
|
||||
|
||||
## 功能概述
|
||||
|
||||
在边缘多节点运维中，及时了解各个代理站点的可用性至关重要。为了避免手动在监控系统中重复录入站点信息，OpenFlare 提供了与开源监控服务 **Uptime Kuma** 的深度集成。
|
||||
|
||||
启用集成后，OpenFlare 会启动一个后台同步调度器，自动将管理端配置的代理站点同步为 Uptime Kuma 中的 HTTP 监控任务。支持检测范围过滤、差分属性更新以及对下线站点的自动清理。
|
||||
|
||||
---
|
||||
|
||||
## 第一步：在系统设置中配置集成
|
||||
|
||||
1. 登录管理端控制面板，进入左侧导航 **「系统设置」** -> **「Uptime Kuma 集成」**（或通过控制台中的集成配置入口）。
|
||||
2. 配置以下核心连接参数：
|
||||
* **启用状态 (Enabled)**：开启集成开关。
|
||||
* **实例地址 (Instance URL)**：你的 Uptime Kuma 服务地址。例如 `http://192.168.1.100:3001` 或 `https://kuma.example.com`（必须包含协议前缀 `http://` 或 `https://`）。
|
||||
* **用户名 (Username)** 与 **密码 (Password)**：具有管理权限的 Uptime Kuma 账户凭证，用于 API 鉴权。
|
||||
|
||||
---
|
||||
|
||||
## 第二步：控制监控范围与心跳参数
|
||||
|
||||
在集成面板中，你可以对监控范围和具体探测行为进行细粒度控制：
|
||||
|
||||
### 1. 监控范围 (Monitor Scope)
|
||||
* **全部站点 (All)**：默认选项。OpenFlare 将自动同步所有**已启用**的代理路由站点。当新站点被创建且启用，或者旧站点被停用时，监控列表将自动增删。
|
||||
* **选择站点 (Selected)**：仅监控指定站点。选择此模式后，可以点击 **「选择监控站点」** 弹出框。在弹出框内可以通过搜索过滤站点并进行勾选。被取消勾选或未勾选的站点将不会被同步（若已存在则会被自动清理）。
|
||||
|
||||
### 2. 监测频率与心跳设置
|
||||
你可以为自动生成的监控项指定统一的探测参数：
|
||||
* **同步间隔 (Sync Interval)**：自动差分同步的频率（分钟），默认为 `5` 分钟。即控制面每 5 分钟与 Uptime Kuma 进行一次状态比对。
|
||||
* **心跳检测频率 (Interval)**：Uptime Kuma 探测站点的频率（秒），默认为 `60` 秒。
|
||||
* **最大重试次数 (Retry)**：探测失败后，判定为 Down 之前的最大重试次数，默认为 `0`。
|
||||
* **重试间隔时间 (Retry Interval)**：重试之间的等待秒数，默认为 `60` 秒。
|
||||
* **请求超时时间 (Timeout)**：探测请求判定为超时的秒数，默认为 `48` 秒。
|
||||
|
||||
---
|
||||
|
||||
## 同步与清理机制
|
||||
|
||||
* **专属标签隔离**：所有自动创建的监控项均会绑定 `OpenFlare` 专属标签（紫蓝色）。同步和清理程序仅操作带有该标签的监控任务，**绝不干扰或破坏你在 Uptime Kuma 中手动创建的其他监控项**。
|
||||
* **差分增量同步**：同步程序会周期性对比监控元数据。当检测到域名或心跳配置变更时，仅执行差分更新，避免中断历史统计数据；当站点停用或移出范围时，会自动执行监控下线清理。
|
||||
|
||||
> [!TIP]
|
||||
> 关于 Uptime Kuma 监控同步的 Socket.IO 控制流、防污染标签模型及差分比对算法细节，请参阅 [Uptime Kuma 监控同步设计](../design/kuma-design.md)。
|
||||
@@ -1,171 +0,0 @@
|
||||
# 基础使用
|
||||
|
||||
你会学到：OpenFlare 中网站配置、源站、证书、版本、节点和观测分别是什么，以及日常使用时应按什么顺序操作。
|
||||
|
||||
OpenFlare 不直接在线修改节点上的 Nginx/OpenResty 配置。你在管理端修改的是控制面数据；只有发布并激活新版本后，Agent 才会拉取完整配置并应用到节点。
|
||||
|
||||
## 核心概念
|
||||
|
||||
| 概念 | 说明 |
|
||||
| --- | --- |
|
||||
| 网站配置 | 反向代理配置的聚合对象，一条网站配置可以绑定一个或多个域名 |
|
||||
| 主域名 | `domains` 列表中的第一个域名，用作该网站的主要展示域名 |
|
||||
| 源站 | 被反向代理访问的上游地址，例如 `http://10.0.0.10:8080` |
|
||||
| 配置版本 | 一次发布生成的完整 OpenResty 配置快照，历史版本不可变 |
|
||||
| 激活版本 | 当前全局生效的配置版本，所有节点默认消费同一份激活版本 |
|
||||
| Agent | 节点侧进程，负责注册、心跳、同步、校验、reload 和失败回滚 |
|
||||
|
||||
## 推荐操作顺序
|
||||
|
||||
日常发布一条反向代理配置时，推荐按这个顺序：
|
||||
|
||||
1. 确认至少有一个 Agent 节点在线。
|
||||
2. 新增或选择源站地址。
|
||||
3. 新增网站配置，填写域名、源站和站点级配置。
|
||||
4. 如需 HTTPS，上传或选择证书，并按域名绑定。
|
||||
5. 预览配置或查看变更摘要。
|
||||
6. 发布并激活新版本。
|
||||
7. 在节点详情和应用记录中确认应用结果。
|
||||
|
||||
## 创建网站配置
|
||||
|
||||
网站配置至少需要：
|
||||
|
||||
| 字段 | 要求 |
|
||||
| --- | --- |
|
||||
| 网站名称 | 业务唯一标识；未显式填写时通常可使用主域名 |
|
||||
| 域名 | 至少一个域名，第一项为主域名；任一域名全局只能属于一个网站 |
|
||||
| 源站地址 | 合法的 `http://` 或 `https://` 地址 |
|
||||
| 启用状态 | 只有启用的网站配置会参与发布渲染 |
|
||||
|
||||
示例：
|
||||
|
||||
| 字段 | 示例 |
|
||||
| --- | --- |
|
||||
| 网站名称 | `docs` |
|
||||
| 域名 | `docs.example.com` |
|
||||
| 源站地址 | `http://10.0.0.10:8080` |
|
||||
| 回源 Host | `docs.internal.example.com` |
|
||||
|
||||
上游地址规则：
|
||||
|
||||
* 单上游可以携带 base path 或 query，例如 `https://app.example.com/base?from=openflare`。
|
||||
* 多上游用于负载均衡时，每个上游必须是纯 `scheme://host[:port]`。
|
||||
* 多上游在同一规则内应使用一致协议。
|
||||
|
||||
## 管理源站
|
||||
|
||||
源站是轻量目录，用来复用常见上游地址。网站配置关联源站后，仍会保存可渲染的 `origin_url` 快照，确保历史配置版本可以独立回放。
|
||||
|
||||
推荐做法：
|
||||
|
||||
* 把经常复用的内部服务地址维护为源站。
|
||||
* 修改源站目录后，检查已发布的网站配置是否需要同步更新源站快照。
|
||||
* 发布前使用预览或 diff 确认渲染结果。
|
||||
|
||||
## 托管 Pages 静态站点
|
||||
|
||||
Pages 用于托管已经构建完成的静态资源包。当前阶段只支持 Direct Upload，不执行 Git 构建、边缘函数或 SSR。
|
||||
|
||||
操作顺序：
|
||||
|
||||
1. 进入 **Pages** 页面，点击 **新建 Pages 项目**。
|
||||
2. 填写项目名称、标识、描述；如为前端 history 路由应用，启用 **SPA fallback** 并填写回退路径，默认是 `/index.html`，也可以设置为 `/app.html` 等站点内绝对路径。
|
||||
3. 创建后回到 Pages 项目列表，点击项目进入详情。
|
||||
4. 在项目详情中上传 zip 静态资源包，并激活某个部署。
|
||||
5. 新建或编辑网站规则，将回源方式切换为 **Pages 静态站点**，选择该 Pages 项目。
|
||||
6. 发布并激活配置版本，Agent 会下载部署包、校验 checksum、解压到本地 Pages 目录，再由 OpenResty 本地服务静态文件。
|
||||
|
||||
Pages 项目只有在启用且存在激活部署后，才会出现在网站规则的 Pages 项目选择列表中。
|
||||
|
||||
## 启用 HTTPS
|
||||
|
||||
HTTPS 按域名绑定证书，而不是按整个网站统一强制启用。
|
||||
|
||||
操作顺序：
|
||||
|
||||
1. 在证书管理中上传或托管证书。
|
||||
2. 进入网站配置，为需要 HTTPS 的域名选择证书。
|
||||
3. 未绑定证书的域名会保留 HTTP，不会被自动放入 `443 ssl` server 块。
|
||||
4. 发布并激活新版本。
|
||||
|
||||
如果一个网站包含多个域名，Server 发布时会按证书分组渲染 HTTPS 配置，同时保持这些域名属于同一份网站快照。
|
||||
|
||||
## 配置 WAF 与 PoW
|
||||
|
||||
安全防护统一从管理端侧边栏的 **WAF** 入口进入：
|
||||
|
||||
* WAF 页面维护全局规则组和自定义规则组。全局规则组始终应用到全部网站；自定义规则组可以在规则组内一键选择网站，也可以在网站详情的 `WAF` 分区绑定。
|
||||
* 点击 WAF 页面中的 **管理 IP 组** 可以进入独立 IP 组页面。手动 IP 组直接维护 IP/IP 段；自动 IP 组使用 Expr 规则按单个 IP 聚合请求日志并定时更新名单；订阅 IP 组可从远程文本或 JSON 源定时同步。
|
||||
* 自动 IP 组页面提供两个预设：单个 IP 请求数大于 100 且 404 占比不低于 80%；单个 IP 通过 IP 地址访问次数大于 50 且该访问占比大于 50%。保存前可点击 **测试规则** 查看当前日志窗口命中的 IP，保存后可点击 **立即执行** 更新组内名单，语法见 [WAF 自动 IP 组规则语法](./waf-ip-group-expr.md)。
|
||||
* 在 WAF 规则组的黑白名单中，IP 维度既可以直接添加 IP/IP 段，也可以引用已有 IP 组。发布时版本只携带 IP 组引用 ID；Agent 会按 checksum 差异同步 IP 组成员，并在 Server 通过 WebSocket 广播 IP 组更新时实时落地到节点。
|
||||
* `PoW` 是规则组内的一个配置 Tab，位于 `黑白名单` 与 `拦截返回` 之间，复用站点已有 PoW 执行逻辑，可将当前 PoW 配置应用到全部网站或当前规则组绑定的网站。
|
||||
* 网站详情页不再单独编辑 PoW 规则，只展示全局 WAF 规则组并绑定自定义 WAF 规则组。PoW 的启用范围和规则内容应回到 WAF 页面统一维护。
|
||||
|
||||
WAF 规则组、网站绑定或 PoW 配置修改后，需要重新发布并激活配置版本，Agent 才会拉取并应用到 OpenResty。IP 组成员变化不需要重新发布版本；在线 Agent 会通过 WebSocket 增量更新，离线或未升级 WS 的 Agent 会在下一次心跳中按 checksum 差异补齐。
|
||||
|
||||
详细的 WAF 安全配置与拦截判决原理请查阅 [WAF 安全防护使用](./waf-usage.md)。
|
||||
|
||||
## 发布、激活与回滚
|
||||
|
||||
标准链路：
|
||||
|
||||
```text
|
||||
修改配置 -> 预览 / diff -> 发布 -> 生成完整版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
|
||||
```
|
||||
|
||||
发布时 Server 会读取全部启用的网站配置、OpenResty 主配置模板、性能参数、缓存参数和证书资源，生成完整配置并计算 `checksum`。
|
||||
|
||||
回滚不是修改历史版本，而是重新激活旧版本。Agent 发现激活版本变化后，会按普通同步流程拉取并应用。
|
||||
|
||||
## 查看节点与观测
|
||||
|
||||
节点页面适合回答三个问题：
|
||||
|
||||
| 问题 | 查看位置 |
|
||||
| --- | --- |
|
||||
| 节点是否在线 | 节点列表或节点详情 |
|
||||
| 当前运行哪个版本 | 节点详情中的当前版本 |
|
||||
| 最近一次应用是否成功 | 应用记录 |
|
||||
|
||||
节点 IP 默认由 Agent 注册和后续心跳自动回填。若在管理端填写或修改 IP，节点编辑会默认开启“锁定节点 IP”；开启后 Agent 上报不会覆盖该 IP。关闭锁定后，下一次 Agent 心跳或 WebSocket 状态上报会重新按自动逻辑更新。
|
||||
|
||||
访问分析和资源快照用于基础观测。OpenFlare 只保留受控时间窗口内的访问明细，不定位为通用日志平台。如果需要长期日志检索，应接入独立日志系统。
|
||||
|
||||
## 常见场景
|
||||
|
||||
### 新增一个内部服务反代
|
||||
|
||||
1. 确认源站服务可从 Agent 节点访问。
|
||||
2. 在管理端新增网站配置。
|
||||
3. 填写域名，例如 `app.example.com`。
|
||||
4. 填写源站，例如 `http://10.0.0.20:8080`。
|
||||
5. 发布并激活版本。
|
||||
6. 在 Agent 节点或浏览器访问域名验证。
|
||||
|
||||
> [!TIP]
|
||||
> 如果你的源站部署在内网、没有公网 IP 且 Agent 无法直接访问，请使用内网穿透隧道功能将服务映射至公网。详细操作步骤请查阅 [内网穿透与隧道使用](./tunnel-usage.md)。
|
||||
|
||||
### 给已有域名启用 HTTPS
|
||||
|
||||
1. 准备覆盖该域名的证书。
|
||||
2. 在证书管理中上传或创建证书记录。
|
||||
3. 回到网站配置，为对应域名选择证书。
|
||||
4. 发布并激活版本。
|
||||
5. 用浏览器或 `curl -I https://your-domain` 验证证书链和状态码。
|
||||
|
||||
### 回滚一次失败发布
|
||||
|
||||
1. 打开配置版本页面。
|
||||
2. 找到上一个已知可用版本。
|
||||
3. 重新激活该版本。
|
||||
4. 查看节点应用记录，确认 Agent 已应用旧版本。
|
||||
5. 修正配置后再发布新版本。
|
||||
|
||||
## 推荐实践
|
||||
|
||||
* 生产环境必须显式配置 `JWT_SECRET`，并优先使用 PostgreSQL。
|
||||
* 修改网站配置后先看预览或 diff，再发布。
|
||||
* 每次发布后检查节点详情与应用记录。
|
||||
* 多节点部署时保持 Agent 到 Server 的网络路径稳定。
|
||||
* 不在节点上手动修改 OpenFlare 托管的 OpenResty 配置文件；下次发布会覆盖这些文件。
|
||||
+16
-2
@@ -42,8 +42,22 @@ IP 组是进行大批量 IP 过滤的基石。OpenFlare 提供了极富弹性的
|
||||
* **配置**：点击「创建 IP 组」-> 类型选择「手动」-> 按行直接填入 IP 或 CIDR 格式（例如 `192.168.1.100` 或 `10.0.0.0/24`）。
|
||||
|
||||
#### 2. 订阅 IP 组 (Subscription)
|
||||
* **用途**：接入第三方威胁情报库或云厂商公布的 IP 范围。
|
||||
* **配置**：类型选择「订阅」-> 输入抓取 URL（支持按行分隔的文本文件或标准的 JSON 格式）。控制面板的定时任务会周期性拉取订阅源并自动同步至该组名单中。
|
||||
* **用途**：接入第三方开源威胁情报库、云厂商公布的官方网段（如 Cloudflare, GitHub Action IP 列表），或团队内部统一维护的动态 IP 源。
|
||||
* **配置参数**：
|
||||
* **订阅 URL**：必须是合法的 `http` 或 `https` 链接。
|
||||
* **订阅格式**：支持 `Text` 与 `JSON` 两种数据格式：
|
||||
* **Text 格式**：纯文本格式。按行分隔读取 IP/CIDR，会自动过滤掉以 `#` 开头的注释行和空白行。
|
||||
* **JSON 格式**：当订阅源是一个结构化的 JSON 响应时，需要编写 **映射规则 (Mapping Rule)** 从 JSON 数据中提取 IP 列表。
|
||||
* **映射规则**：使用类似 JSONPath 的轻量点语法定位 IP 数组，支持以 `[]` 展开数组。例如：
|
||||
* 若 JSON 结构为 `{"data": {"ips": ["1.1.1.1", "2.2.2.2"]}}`，则映射规则填写 `$.data.ips[]`（或 `data.ips[]`）。
|
||||
* 若 JSON 根节点本身即为字符串数组（如 `["1.1.1.1", "2.2.2.2"]`），映射规则留空或填写 `$` 即可。
|
||||
* **同步间隔 (分钟)**：该订阅组自动同步的周期，默认为 `1440` 分钟（24小时），允许范围为 `5` 至 `43200` 分钟。
|
||||
* **安全限额与同步频率**：
|
||||
* 为防止恶意或超大订阅源造成系统负担，单次抓取上限限制为 **2 MiB**，网络拉取超时为 15 秒。
|
||||
* Server 默认每 5 分钟在后台扫描一次到期的订阅 IP 组并拉取同步。
|
||||
|
||||
> [!TIP]
|
||||
> 关于 WAF 的动态 IP 组异步差分同步模型（WebSocket 实时热同步、不触发 Nginx Reload 机制）以及高性能 Lua 缓存方案等底层设计细节，请参阅 [WAF 设计](../design/waf-design.md)。
|
||||
|
||||
#### 3. 自动 IP 组 (Automatic)
|
||||
* **用途**：**最具杀伤力的防扫描、防爆破自动通道**。
|
||||
|
||||
Reference in New Issue
Block a user