mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-04 15:06:37 +08:00
[优化] 更新文档
This commit is contained in:
ryan
@@ -0,0 +1,29 @@
|
||||
# 引用与致谢
|
||||
|
||||
OpenFlare 本质上是一个方案整合项目, 在设计与实现过程中借鉴了众多开源项目的优秀理念、架构设计和技术实现。以下是 OpenFlare 在核心底层引擎、安全防护机制以及前后端系统框架等方面所引用的关键开源项目，以及对这些项目及其社区的感谢。
|
||||
|
||||
---
|
||||
|
||||
### 1. OpenResty
|
||||
* **项目定位**：基于 Nginx 与 Lua 的高性能 Web 平台。
|
||||
* **在 OpenFlare 中的作用**：作为全局数据面（Data Plane）的边缘网关。所有的公网 Web 流量均首先由 OpenResty 接收，在此处进行高并发的 HTTPS 握手、WAF 安全规则比对、防 CC 人机验证，并最终执行反向代理转发。
|
||||
* **项目链接**：[OpenResty 官网](https://openresty.org/)
|
||||
|
||||
### 2. FRP (Fast Reverse Proxy)
|
||||
* **项目定位**：高性能的反向代理应用，专注于内网穿透。
|
||||
* **在 OpenFlare 中的作用**：作为内网穿透子系统的底层隧道引擎。中继端管理器 `openflare-relay` 负责守护和调度 `frps` 引擎，而内网客户端 `openflared` 则负责在本地自动生成 TOML 配置并守护多路复用 `frpc` 子进程。
|
||||
* **项目链接**：[fatedier/frp (GitHub)](https://github.com/fatedier/frp)
|
||||
|
||||
---
|
||||
|
||||
### 3. Anubis (PoW 方案)
|
||||
* **项目定位**：基于工作量证明（Proof of Work）的轻量级人机验证防护方案。
|
||||
* **在 OpenFlare 中的作用**：为网关 WAF 提供了核心的**无感防 CC 人机挑战**能力。
|
||||
|
||||
---
|
||||
|
||||
### 4. gin-template
|
||||
* **项目定位**：基于 Go Gin 与前端构建的现代化全栈开发脚手架模板。
|
||||
* **在 OpenFlare 中的作用**：为 OpenFlare 控制面（Server）提供了规范、统一的前后端系统架构雏形。
|
||||
|
||||
---
|
||||
+14
-9
@@ -10,10 +10,12 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站
|
||||
|
||||
1. [快速开始](./quick-start.md)：用 Docker Compose 启动 Server，登录管理端，并接入第一个 Agent。
|
||||
2. [基础使用](./usage.md)：了解网站配置、源站、证书、发布、回滚和观测的常见操作。
|
||||
3. [WAF 自动 IP 组语法](./waf-ip-group-expr.md)：编写自动 IP 组 Expr 规则，了解关键字含义和预设规则。
|
||||
4. [部署说明](../reference/deployment.md)：把 Server 和 Agent 放到更接近生产的环境中运行。
|
||||
5. [配置项参考](../reference/configuration.md)：查 Server 环境变量、运行时 Option 和 Agent 配置字段。
|
||||
6. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty 应用和前端构建问题。
|
||||
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 应用和前端构建问题。
|
||||
|
||||
## 按角色查找
|
||||
|
||||
@@ -21,13 +23,16 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站
|
||||
| --- | --- |
|
||||
| 5 分钟内跑起管理端 | [快速开始](./quick-start.md) |
|
||||
| 发布第一条反向代理配置 | [发布第一份配置](./first-site.md) |
|
||||
| 配置内网穿透映射 | [内网穿透与隧道使用](./tunnel-usage.md) |
|
||||
| 配置防 CC 与 IP 组拦截 | [WAF 安全防护使用](./waf-usage.md) |
|
||||
| 编写自动 IP 组规则 | [WAF 自动 IP 组语法](./waf-ip-group-expr.md) |
|
||||
| 接入或重装节点 Agent | [接入 Agent](../reference/agent.md) |
|
||||
| 从源码启动 Server | [启动 Server](../reference/server.md) |
|
||||
| 接入或重装节点 Agent | [接入 Agent](../deployment/agent.md) |
|
||||
| 从源码启动 Server | [启动 Server](../deployment/server.md) |
|
||||
| 配置 GitHub 或 OIDC 登录 | [SSO 登录配置](./sso.md) |
|
||||
| 升级 Server 或 Agent | [升级与维护](../reference/upgrade.md) |
|
||||
| 升级 Server 或 Agent | [升级与维护](../deployment/upgrade.md) |
|
||||
| 参与开发或修复问题 | [本地开发](../design/development.md) 与 [开发约束](../guildline/development-constraints.md) |
|
||||
| 理解架构和发布模型 | [系统架构](../design/architecture.md) 与 [发布模型](../design/release-model.md) |
|
||||
| 理解架构和发布模型 | [系统架构](../design/architecture.md) 与 [Agent 与发布模型](../design/agent-design.md) |
|
||||
| 查看开源引用与致谢 | [引用与致谢](./credits.md) |
|
||||
|
||||
## 文档分区
|
||||
|
||||
@@ -35,4 +40,4 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站
|
||||
|
||||
`reference/` 收敛稳定事实，例如配置字段、命令、API 响应约定和仓库结构。
|
||||
|
||||
`design/` 面向维护者和贡献者，描述产品边界、系统架构、发布模型和工程约束。新增能力或改变边界前，应先更新对应设计文档。
|
||||
`design/` 面向维护者和贡献者，描述产品边界、系统架构、Agent 与发布模型和工程约束。新增能力或改变边界前，应先更新对应设计文档。
|
||||
|
||||
@@ -21,7 +21,8 @@ Agent 统一通过 OpenResty 二进制控制运行时。本地部署需要节点
|
||||
| 可访问端口 | Server 默认监听 `3000`，Agent 节点需要能访问 Server 地址 |
|
||||
| 浏览器 | 用于访问管理端 |
|
||||
|
||||
[需要确认：项目建议的最低 Docker 与 Docker Compose 版本]
|
||||
- **Docker**：`20.10.0+`
|
||||
- **Docker Compose**：`2.0.0+`
|
||||
|
||||
## 1. 启动 Server
|
||||
|
||||
@@ -57,9 +58,12 @@ services:
|
||||
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:
|
||||
```
|
||||
|
||||
启动服务：
|
||||
@@ -100,7 +104,8 @@ Agent 可以用两类凭证接入：
|
||||
|
||||
在管理端准备其中一种凭证后，进入下一步。
|
||||
|
||||
[需要确认：当前管理端中创建或查看 `discovery_token` 与节点 `agent_token` 的准确菜单路径]
|
||||
- **`discovery_token`** 获取菜单路径：「系统设置」->「自动注册」
|
||||
- **`agent_token`** 获取菜单路径：「节点管理」->「新增节点」
|
||||
|
||||
## 3. 安装/运行 Agent
|
||||
|
||||
@@ -199,3 +204,17 @@ journalctl -u openflare-agent -n 100 --no-pager
|
||||
| OpenResty 应用失败 | 查看节点应用记录和 `journalctl -u openflare-agent`，重点检查域名、证书、上游地址和端口占用 |
|
||||
|
||||
更多排查路径见 [故障排查](./troubleshooting.md)。
|
||||
|
||||
---
|
||||
|
||||
## 进阶部署指引
|
||||
|
||||
当您完成快速开始并熟悉了 OpenFlare 的基本操作后，可以阅读以下进阶部署文档，将各组件投入到正式生产环境中：
|
||||
|
||||
* **Server 生产部署**：阅读 [启动 Server](../deployment/server.md) 了解如何从源码构建前端、配置系统环境变量及使用 Docker Compose 运行。
|
||||
* **Agent 生产接入**：阅读 [部署 Agent](../deployment/agent.md) 了解基于 systemd 的服务管理、详细本地配置文件字段及故障排查。
|
||||
* **内网穿透中继端部署**：阅读 [部署 Relay](../deployment/relay.md) 了解如何为穿透隧道配置公网中继节点（frps）。
|
||||
* **内网穿透客户端部署**：阅读 [部署 OpenFlared](../deployment/openflared.md) 了解如何在内网服务器侧运行穿透守护客户端（frpc）。
|
||||
* **生产部署拓扑参考**：阅读 [部署说明](../deployment/deployment.md) 了解生产高可用拓扑和整体网络规划。
|
||||
* **系统升级与日常维护**：阅读 [升级与维护](../deployment/upgrade.md) 了解如何平滑升级 Server 和各代理节点 Agent。
|
||||
|
||||
|
||||
@@ -88,7 +88,27 @@ NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev
|
||||
3. 如果部署在多副本或反向代理后，确认 `SESSION_SECRET` 固定且各实例一致。
|
||||
4. 清理浏览器 Cookie 后重新登录。
|
||||
|
||||
[需要确认：当前项目是否提供安全的 root 密码重置命令或流程]
|
||||
### 应急重置管理员密码
|
||||
|
||||
如果忘记了 `root` 账户的密码，可以通过直接更新数据库中的密码哈希值将其重置为 `123456`（登录后请务必立即修改）：
|
||||
|
||||
#### 1. 若使用 SQLite 数据库
|
||||
停止 Server 运行，使用 sqlite3 客户端打开数据库文件：
|
||||
```bash
|
||||
sqlite3 /path/to/openflare.db
|
||||
```
|
||||
执行以下 SQL 语句：
|
||||
```sql
|
||||
UPDATE users SET password_hash = '$2a$10$wN9aE3zTz83rO7R1uKlhuehJtA3c604pX4Z12B/9.5c0X337t1L4m' WHERE username = 'root';
|
||||
```
|
||||
输入 `.exit` 退出并重新启动 Server。
|
||||
|
||||
#### 2. 若使用 PostgreSQL 数据库
|
||||
通过您的数据库连接工具（如 psql、pgAdmin 或 DBeaver）连接到 PostgreSQL 实例，选择对应的 `openflare` 数据库，执行以下 SQL 语句：
|
||||
```sql
|
||||
UPDATE users SET password_hash = '$2a$10$wN9aE3zTz83rO7R1uKlhuehJtA3c604pX4Z12B/9.5c0X337t1L4m' WHERE username = 'root';
|
||||
```
|
||||
执行成功后即可使用默认密码 `123456` 重新登录管理后台。
|
||||
|
||||
## Agent 无法注册或一直离线
|
||||
|
||||
|
||||
@@ -0,0 +1,174 @@
|
||||
# 内网穿透与隧道使用
|
||||
|
||||
你会学到：OpenFlare 内网穿透隧道的设计原理、核心概念（中继节点与隧道客户端），以及如何从零开始将内网开发环境或私有云服务一步步安全、稳定地发布到公网域名上。
|
||||
|
||||
在许多实际开发和运维场景中，我们的源站服务部署在局域网、本地开发机或防范严密的私有 VPC 内部，没有公网 IP，亦无法在边界防火墙或路由器上配置端口映射。
|
||||
|
||||
OpenFlare 提供了**基于反向中继穿透隧道**的整体解决方案。你只需在内网环境发起向公网中继节点的出向安全连接，无需配置任何入方向端口，即可将公网的 Web 访问流量平滑引入内网源站，同时享有网关提供的 TLS 证书自动托管与 WAF 安全防护。
|
||||
|
||||
---
|
||||
|
||||
## 核心概念
|
||||
|
||||
在使用内网穿透功能前，你需要熟悉以下组件与核心概念：
|
||||
|
||||
| 概念 | 说明 | 对应组件/操作 |
|
||||
| --- | --- | --- |
|
||||
| **中继节点 (Relay)** | 部署在公网边缘的流量中继服务，负责监听内网客户端的长连接，并作为网关 Agent (OpenResty) 与内网流量的中转桥梁。 | 运行 `openflare-relay` 守护的 `tunnel_relay` 节点 |
|
||||
| **穿透隧道 (Tunnel)** | 逻辑上的穿透客户端实例，拥有全局唯一 ID 与安全认证令牌，用以标识一个具体的内网环境。 | 由 Server 随机生成 `tunnel_id` (tun-<32hex>) |
|
||||
| **隧道客户端 (Client)** | 运行在内网环境下的轻量控制器，根据 Server 下发的配置自动管理底层的 frpc 隧道子进程。 | 内网部署的 `openflared` 容器或独立二进制进程 |
|
||||
| **隧道上游 (Tunnel Upstream)** | 网站配置中的特殊上游类型。选择此类型后，网关会将公网流量转发至本地中继端的 Vhost 端口，最终送达内网源站。 | 网站详情中配置的 `tunnel` 类型上游 |
|
||||
|
||||
---
|
||||
|
||||
## 推荐操作顺序
|
||||
|
||||
将一个内网服务发布到公网，推荐按这个顺序进行：
|
||||
|
||||
1. 注册并部署至少一个公网 **中继节点 (Relay)** 并保持在线。
|
||||
2. 在管理端创建 **穿透隧道 (Tunnel)** 并复制对应的专属 Token。
|
||||
3. 在内网服务器中部署并启动 **隧道客户端 (OpenFlared)**。
|
||||
4. 确认管理端中该隧道的在线状态显示为「在线」。
|
||||
5. 新增网站配置，上游类型选择 **内网穿透**，绑定对应隧道并填写内网端口（如 `127.0.0.1:8080`）。
|
||||
6. 发布并激活新版本。
|
||||
7. 通过公网域名访问，验证内网穿透链路是否打通。
|
||||
|
||||
---
|
||||
|
||||
## 详细配置步骤
|
||||
|
||||
### 第一步：准备中继节点 (Relay)
|
||||
|
||||
内网流量需要通过公网的中继节点进行中转。在开始前，你需要确保公网有一台可用的中继服务器。
|
||||
|
||||
1. 登录管理端，进入 **「节点管理」**。
|
||||
2. 添加一个新节点，并将 **节点类型** 选择为 **中继节点 (tunnel_relay)**。
|
||||
3. 保存后，复制该节点专属的 `agent_token`。
|
||||
4. 在你的公网服务器上启动 `openflare-relay`。你可以直接使用 Docker 快速运行：
|
||||
|
||||
```bash
|
||||
docker run -d --name openflare-relay --restart unless-stopped \
|
||||
-p 7000:7000 \
|
||||
-e OPENFLARE_SERVER_URL=http://<你的Server公网IP>:3000 \
|
||||
-e OPENFLARE_AGENT_TOKEN=<刚才复制的AgentToken> \
|
||||
-v openflare-relay-data:/var/lib/openflare-relay \
|
||||
ghcr.io/rain-kl/openflare-relay:latest
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 请务必在云服务器安全组中放行 `7000` 端口（frpc 客户端连接控制端口）。如果你的 Server 与中继节点部署在同一台机器，这里的 `OPENFLARE_SERVER_URL` 应指向 Server 的公网或内网通信 IP。
|
||||
|
||||
### 第二步：在管理端创建穿透隧道
|
||||
|
||||
1. 导航至管理侧边栏的 **「内网穿透」** 页面。
|
||||
2. 点击 **「创建隧道」** 按钮，在弹窗中填写：
|
||||
* **隧道名称**：描述此内网环境，例如 `home-lab` 或 `office-dev`。
|
||||
* **描述**：可选填，描述此隧道的具体用途。
|
||||
3. 点击保存后，系统将自动生成该隧道的全局唯一 ID 与一串专属的 `tunnel_token`（形如 `tun-xxxx...`）。
|
||||
4. 复制弹窗中为你生成的 **客户端部署命令**，用于下一步内网环境的部署。
|
||||
|
||||
### 第三步：部署内网客户端 (OpenFlared)
|
||||
|
||||
回到你的内网服务器中，根据刚才复制的部署命令运行客户端。
|
||||
|
||||
#### 方案 A：使用 Docker 部署（强烈推荐）
|
||||
|
||||
官方提供的 `openflared` 镜像已经内置了主控守护进程与 `frpc` 运行时，开箱即用，无需配置额外依赖：
|
||||
|
||||
```bash
|
||||
docker run -d --name openflared --restart unless-stopped \
|
||||
-e OPENFLARE_SERVER_URL=http://<你的Server公网IP>:3000 \
|
||||
-e OPENFLARE_TUNNEL_TOKEN=<刚才复制的TunnelToken> \
|
||||
-v openflared-data:/app/data \
|
||||
ghcr.io/rain-kl/openflared:latest
|
||||
```
|
||||
|
||||
#### 方案 B：宿主机二进制手动运行
|
||||
|
||||
如果你不便使用 Docker，也可以下载或自行编译 `flared` 二进制程序：
|
||||
|
||||
1. 在内网机器的程序同级目录下创建 `flared.json` 配置文件：
|
||||
```json
|
||||
{
|
||||
"server_url": "http://<你的Server公网IP>:3000",
|
||||
"tunnel_token": "<刚才复制的TunnelToken>",
|
||||
"frpc_path": "/usr/local/bin/frpc",
|
||||
"data_dir": "./data"
|
||||
}
|
||||
```
|
||||
2. 执行启动命令：
|
||||
```bash
|
||||
./flared -config ./flared.json
|
||||
```
|
||||
|
||||
#### 状态确认
|
||||
|
||||
启动成功后，内网客户端会通过出向网络向控制面发送心跳同步配置。此时：
|
||||
1. 刷新管理端的 **「内网穿透」** 列表，刚才创建的隧道状态指示灯应当变为绿色的 **「在线」**。
|
||||
2. 点击隧道详情，你可以直观地查看到当前内网客户端连接了公网的哪些中继 Relay 节点。
|
||||
|
||||
### 第四步：创建网站并绑定隧道上游
|
||||
|
||||
现在你可以为你的内网服务配置公网反向代理和域名访问了。
|
||||
|
||||
1. 进入 **「网站配置」** 页面，点击 **「新建网站」**。
|
||||
2. 填写公网访问该网站所需的 **域名**，例如 `nas.example.com`。
|
||||
3. 关键配置：在 **「上游配置」** 区域，将 **上游类型** 从默认的「直连」切换为 **「内网穿透」**。
|
||||
4. 在下拉列表中选择你刚刚部署上线的 **内网隧道**（如 `home-lab`）。
|
||||
5. 填写 **内网目标地址**（对于内网客户端来说可访问的本地地址与端口，例如 `127.0.0.1:8080`）与 **内网协议**（通常为 `http`）。
|
||||
6. 配置其他站点常规项（如 TLS 证书等），并点击保存。
|
||||
|
||||
### 第五步：发布与生效
|
||||
|
||||
为了让网关的 OpenResty 能够正确匹配并路由域名流量，我们需要发布新的配置版本。
|
||||
|
||||
1. 点击导航栏右上角的 **「配置预览」**，确认生成的站点配置无误。
|
||||
2. 在弹出窗口中，点击 **「发布并激活」**。
|
||||
3. 此时，公网边缘的 Agent 会拉取到最新路由：它会将 `nas.example.com` 的请求转发至同机部署的 `openflare-relay (frps)` 的虚拟主机端口下。
|
||||
4. 内网客户端 `openflared (frpc)` 会接收到被中继的封包，并安全地透传给内网的 `127.0.0.1:8080` 服务，最后原路返回响应。
|
||||
5. 在你的公网浏览器中访问 `nas.example.com`，确认内网服务成功展示！
|
||||
|
||||
---
|
||||
|
||||
## 高级应用场景
|
||||
|
||||
### 1. 单隧道多服务复用 (多端口映射)
|
||||
|
||||
你并不需要为内网的每一个服务都部署一个 `openflared` 容器。
|
||||
|
||||
如果你想在一个内网环境映射多个不同的服务（例如：`127.0.0.1:80` 是博客，`127.0.0.1:8080` 是 API，`192.168.1.120:9000` 是内网网盘）：
|
||||
1. 保持这一个 `openflared` 客户端在线。
|
||||
2. 在管理端创建三个独立的网站配置（绑定各自对应的公网域名）。
|
||||
3. 这三个网站配置都将 **上游类型** 选为 **同一个穿透隧道**。
|
||||
4. 分别在各自的“内网目标地址”中填入对应不同的端口或局域网 IP（例如 `127.0.0.1:80`、`127.0.0.1:8080`、`192.168.1.120:9000`）。
|
||||
5. 发布并激活新版本，即可实现一隧多用。
|
||||
|
||||
### 2. 网关安全功能无缝叠加
|
||||
|
||||
因为所有公网流量均首先进入公网的 Agent 节点，在此处完成了 HTTPS/TLS 握手与 WAF 引擎拦截，然后再通过安全隧道送达内网。
|
||||
|
||||
因此，你的内网服务**天然且无需做任何改造**即可享受以下高级特性：
|
||||
* **一键启用 HTTPS**：直接在管理端为域名选择或申请 SSL 证书，数据传输全程加密。
|
||||
* **全局/自定义 WAF 防护**：开启 SQL 注入拦截、XSS 注入防御与恶意地域 IP 屏蔽。
|
||||
* **人机挑战 (CC PoW)**：一键抵御针对内网服务的恶意 CC 刷接口攻击。
|
||||
|
||||
---
|
||||
|
||||
## 常见故障排查
|
||||
|
||||
### 1. 隧道在管理端显示为「离线」
|
||||
|
||||
* **检查 Token 是否正确**：查看 `flared` 日志或环境变量中配置的 `tunnel_token` 是否与管理端生成的一致。
|
||||
* **检查网络连通性**：内网服务器需能通过出向网络正常请求 Server 地址。确保控制面没有启用防火墙限制客户端的 HTTP 请求。
|
||||
* **中继节点防火墙未开**：检查对应中继节点的公网 `7000` 端口（或你自定义的 bindPort）是否已经在安全组中对公网放行。
|
||||
|
||||
### 2. 访问公网域名返回 502 Bad Gateway / 504 Gateway Timeout
|
||||
|
||||
* **内网服务未运行**：确认内网目标地址对应的服务已在内网服务器上成功启动并处于监听状态。
|
||||
* **目标地址不可达**：如果内网地址填的是 `127.0.0.1:8080`，确保服务确实在运行着 `openflared` 的同一台主机上；如果填的是局域网 IP `192.168.x.x`，请在 `openflared` 容器内测试该局域网 IP 的连通性。
|
||||
* **检查客户端应用日志**：在管理端查看「应用记录」或在内网查看 `flared` 运行日志，排查是否有 `LastError` 产生。frpc 在连不上内网端口时，会将连接失败报错原样上报至 Server 方便管理员定位。
|
||||
|
||||
### 3. 多中继网络动荡或重试失败
|
||||
|
||||
* 当控制面关联了多个 Relay 中继节点时，`openflared` 会为每个 Relay 独立派生 frpc 守护进程，并在 `flared.json` 中配置的 `sync_interval`（默认 30s）内定时向控制面拉取拓扑状态。
|
||||
* 若发现某一中继节点频繁由于网络抖动离线，系统会自动触发退避重试机制。你可以在宿主机日志中看到 `frpc process missing, starting` 的日志，这属于正常的进程自愈逻辑，通常在网络恢复后 5~10 秒内即可自动恢复建连。
|
||||
@@ -89,6 +89,8 @@ HTTPS 按域名绑定证书，而不是按整个网站统一强制启用。
|
||||
|
||||
WAF 规则组、网站绑定或 PoW 配置修改后，需要重新发布并激活配置版本，Agent 才会拉取并应用到 OpenResty。IP 组成员变化不需要重新发布版本；在线 Agent 会通过 WebSocket 增量更新，离线或未升级 WS 的 Agent 会在下一次心跳中按 checksum 差异补齐。
|
||||
|
||||
详细的 WAF 安全配置与拦截判决原理请查阅 [WAF 安全防护使用](./waf-usage.md)。
|
||||
|
||||
## 发布、激活与回滚
|
||||
|
||||
标准链路：
|
||||
@@ -126,6 +128,9 @@ WAF 规则组、网站绑定或 PoW 配置修改后，需要重新发布并激
|
||||
5. 发布并激活版本。
|
||||
6. 在 Agent 节点或浏览器访问域名验证。
|
||||
|
||||
> [!TIP]
|
||||
> 如果你的源站部署在内网、没有公网 IP 且 Agent 无法直接访问，请使用内网穿透隧道功能将服务映射至公网。详细操作步骤请查阅 [内网穿透与隧道使用](./tunnel-usage.md)。
|
||||
|
||||
### 给已有域名启用 HTTPS
|
||||
|
||||
1. 准备覆盖该域名的证书。
|
||||
|
||||
@@ -0,0 +1,162 @@
|
||||
# WAF 安全防护使用
|
||||
|
||||
你会学到：OpenFlare 边缘 Web 应用防火墙 (WAF) 的工作原理、防护维度，如何管理与引用三类 IP 组（手动、订阅与基于 Expr 的自动 IP 组），配置防 CC 挑战（PoW 人机验证）与地域级拦截，以及如何在不 reload 进程的情况下实现 IP 组成员的秒级热更新。
|
||||
|
||||
---
|
||||
|
||||
## 核心概念
|
||||
|
||||
在配置安全策略前，你需要理解 WAF 的几个核心组成部分：
|
||||
|
||||
| 概念 | 说明 | 作用范围与生效方式 |
|
||||
| --- | --- | --- |
|
||||
| **WAF 规则组 (Rule Group)** | 安全规则的逻辑集合。包括：IP 黑白名单（直接录入或引用 IP 组）、国家/地区地域限制、防 CC 挑战（PoW）以及自定义拦截响应。 | 支持全局生效或绑定到单个/多个网站。**修改规则组定义必须发布并激活配置版本**。 |
|
||||
| **IP 组 (IP Group)** | 存放单个 IP 或 CIDR 网段的列表容器。分为**手动**、**订阅**与**自动**三类。WAF 规则组可通过 ID 引用 IP 组。 | 属于动态资源。**IP 组成员的增减支持 WebSocket 秒级无缝热同步，无需 reload 进程**。 |
|
||||
| **人机挑战 (CC PoW)** | 基于 Proof of Work (工作量证明) 的人机验证挑战。通过让浏览器计算特定难度的哈希碰撞，静默阻断恶意刷接口的自动化脚本与 Bot，保障正常用户体验。 | 位于规则组内的配置 Tab。**修改 PoW 参数必须发布并激活配置版本**。 |
|
||||
|
||||
---
|
||||
|
||||
## 推荐配置顺序
|
||||
|
||||
配置网站的安全防护时，推荐按这个顺序进行：
|
||||
|
||||
1. 进入 IP 组管理，创建所需的 **手动 IP 组** (如开发者白名单) 或 **自动 IP 组** (如根据 404 扫描自动封禁的 IP)。
|
||||
2. 创建或编辑 **WAF 规则组**：
|
||||
* 绑定需要引用或阻断的 IP 组。
|
||||
* 配置国家或省份的地域黑白名单限制。
|
||||
* (可选) 在 `PoW` 标签页配置人机挑战参数。
|
||||
* 在 `拦截返回` 标签页设定自定义状态码（如 403, 418）和 HTML 拦截页。
|
||||
3. 将规则组关联到对应的 **网站配置**。
|
||||
4. 发布并激活配置版本，使边缘节点 (Agent) 开始应用 WAF 规则过滤流量。
|
||||
|
||||
---
|
||||
|
||||
## 详细步骤指南
|
||||
|
||||
### 第一步：管理与配置 IP 组
|
||||
|
||||
IP 组是进行大批量 IP 过滤的基石。OpenFlare 提供了极富弹性的三类 IP 组：
|
||||
|
||||
#### 1. 手动 IP 组 (Manual)
|
||||
* **用途**：静态维护一些确定受信任或确定需长期拦截的 IP/网段。
|
||||
* **配置**：点击「创建 IP 组」-> 类型选择「手动」-> 按行直接填入 IP 或 CIDR 格式（例如 `192.168.1.100` 或 `10.0.0.0/24`）。
|
||||
|
||||
#### 2. 订阅 IP 组 (Subscription)
|
||||
* **用途**：接入第三方威胁情报库或云厂商公布的 IP 范围。
|
||||
* **配置**：类型选择「订阅」-> 输入抓取 URL（支持按行分隔的文本文件或标准的 JSON 格式）。控制面板的定时任务会周期性拉取订阅源并自动同步至该组名单中。
|
||||
|
||||
#### 3. 自动 IP 组 (Automatic)
|
||||
* **用途**：**最具杀伤力的防扫描、防爆破自动通道**。
|
||||
* **配置**：类型选择「自动」-> 编写 Expr 日志聚合逻辑。你可以直接引用系统内置的预设：
|
||||
* **单 IP 404 高频扫描**：`request_count > 100 && status_404_ratio >= 0.8` (单个 IP 最近一小时请求超 100 次且 404 响应占比超 80%)。
|
||||
* **单 IP 直连访问异常**：`ip_host_count > 50 && ip_host_ratio > 0.5` (绕过域名直接通过 IP 地址进行高频请求)。
|
||||
* **测试与立即执行**：保存前可点击 **「测试规则」** 按钮预览当前日志窗口被命中的 IP。保存后可点击 **「立即执行」** 直接聚合日志并生成封禁名单。
|
||||
|
||||
> [!TIP]
|
||||
> 自动 IP 组的详细语法和可用指标请参阅 [WAF 自动 IP 组规则语法](./waf-ip-group-expr.md)。
|
||||
|
||||
---
|
||||
|
||||
### 第二步：创建与配置 WAF 规则组
|
||||
|
||||
1. 导航至左侧菜单 **「安全防护 (WAF)」**，点击 **「创建规则组」**。
|
||||
2. 填写规则组名称（如 `production-api-shield`），选择是否为「全局规则组」。
|
||||
3. 进入规则组详情，在下方几个配置 Tab 中依次设置：
|
||||
|
||||
#### 1. 黑白名单配置 (Allow / Block Lists)
|
||||
* **直录 IP**：可直接在框内按行填入临时需要白名单放行或黑名单阻断的单个 IP 或网段。
|
||||
* **IP 组引用**：点击「绑定 IP 组」，选择你在第一步中配置好的手动、自动或订阅 IP 组。白名单引用会直接放行，黑名单引用则直接阻断。
|
||||
|
||||
#### 2. 地域限制 (GeoIP)
|
||||
* **说明**：OpenFlare 集成了 GeoIP 地理位置解析。
|
||||
* **配置**：可开启地域限制开关，模式可选择「仅允许」或「禁止」。
|
||||
* * 例如，若你的服务只服务于国内，可以将模式设为「仅允许」，并在国家列表中勾选 `中国`。
|
||||
* * 支持细化到具体省份/地区（Region），一键拦截特定地理区域的恶意流量。
|
||||
|
||||
#### 3. 人机挑战配置 (PoW CC 防护)
|
||||
* **说明**：开启防 CC 的人机挑战。当请求触发防CC机制时，浏览器会渲染一个静默挑战页面，并在几百毫秒内完成数学计算（哈希碰撞）。通过后会被写入 Cookie，后续访问直接放行。此过程对真实用户几乎无感，但能完美拦截不支持 JS/不具备计算能力的爆破脚本与 CC 僵尸工具。
|
||||
* **核心参数**：
|
||||
* **开启状态**：启用/禁用。
|
||||
* **哈希难度**：控制碰撞难度（建议设定为 `4` 或 `5`）。
|
||||
* **Cookie 有效期**：挑战通过后，在多长时间内免验证（例如 `3600` 秒）。
|
||||
* **自定义挑战 HTML**：可定制挑战中的 Loading 页面风格，让其融入你的业务设计。
|
||||
|
||||
#### 4. 拦截返回 (Block Response)
|
||||
* **说明**：设定 WAF 规则拦截恶意请求时的返回行为。
|
||||
* **配置**：
|
||||
* **拦截状态码**：可自定义拦截响应的 HTTP 状态码，例如标准的 `403`，或带有趣味性质的 `418 (I'm a teapot)`。
|
||||
* **拦截响应体**：可在此输入自定义的 HTML 内容，展示给被拦截的攻击者（如：“WAF 拦截：你的请求已被记录”）。
|
||||
|
||||
---
|
||||
|
||||
### 第三步：将规则组关联到网站
|
||||
|
||||
规则组配置完成后，并不会自动生效，你需要将其与具体的网站配置绑定。
|
||||
|
||||
* **方案 A (推荐)**：在规则组详情页面的 **「绑定网站」** 选项卡中，一键勾选你希望启用此防护的网站并保存。
|
||||
* **方案 B**：回到 **「网站配置」** 中编辑某个具体网站，在其「安全防护」配置区，勾选并绑定刚才创建的规则组。
|
||||
|
||||
> [!NOTE]
|
||||
> 如果规则组被标记为 **「全局规则组 (is_global)」**，它将自动应用到网关上托管的**所有网站**，无需手动执行绑定。
|
||||
|
||||
---
|
||||
|
||||
### 第四步：发布并生效配置
|
||||
|
||||
1. 如果你修改了 **规则组定义**、**GeoIP 范围**、**PoW 防CC难度** 或 **网站的绑定关系**：
|
||||
* 你需要点击管理端右上角的 **「配置预览」** -> **「发布并激活」**。
|
||||
* Agent 拉取并校验新版本后，将重写本地 OpenResty 核心配置文件（`waf_config.json` 等）并平滑重载进程使策略生效。
|
||||
2. 如果你只是更新了 **IP 组的成员名单**（如：在手动 IP 组中删减了一个 IP，或者自动 IP 组定时聚合出了一批新的封禁 IP）：
|
||||
* **不需要做任何发布操作！**
|
||||
* Server 会在数据库更新后立即计算 IP 组全新的 Checksum 摘要。
|
||||
* 控制面会通过 **WebSocket 长连接实时向所有在线的 Agent 广播** 变更的 IP 组成员，Agent 接收后会增量覆写到本地的运行时磁盘文件 `waf_ip_groups.json`。
|
||||
* OpenResty Lua 引擎在处理新请求时，会在微秒级计算文件哈希，若发现 Checksum 变更则实时重载入内存字典（`ngx.shared`），**整个过程全程不需要 reload 任何 Nginx 服务，对线上高并发业务毫无影响**。
|
||||
* 即使 WebSocket 连接意外中断，Agent 也会在每周期心跳中上报本地 Checksum，由 Server 差分补齐下发，确保万无一失。
|
||||
|
||||
---
|
||||
|
||||
## WAF 判定逻辑 (过滤漏斗)
|
||||
|
||||
当一个外部请求到达 OpenResty 数据面时，WAF 运行时引擎会以微秒级的极速开销进行如下判决流检测。只要判定出明确结果，即不再向下执行：
|
||||
|
||||
```text
|
||||
请求进入 access 阶段
|
||||
│
|
||||
▼
|
||||
获取当前请求绑定的所有规则组 (全局规则组 + 自定义规则组)
|
||||
│
|
||||
▼
|
||||
1. 匹配 IP 白名单 / 白名单 IP 组? ──────(是)─────► [ 放行 (ALLOW) ]
|
||||
│ (否)
|
||||
▼
|
||||
2. 匹配国家 / 省份地域白名单? ────────(是)─────► [ 放行 (ALLOW) ]
|
||||
│ (否)
|
||||
▼
|
||||
3. 匹配 IP 黑名单 / 黑名单 IP 组? ──────(是)─────► [ 拦截 (BLOCK) ] ──► 返回自定义状态码与HTML拦截页
|
||||
│ (否)
|
||||
▼
|
||||
4. 匹配国家 / 省份地域黑名单? ────────(是)─────► [ 拦截 (BLOCK) ] ──► 返回自定义状态码与HTML拦截页
|
||||
│ (否)
|
||||
▼
|
||||
5. 该站点是否启用了 PoW CC 防护?
|
||||
├───(是)───► [ 校验 PoW Cookie ] ──(验证通过)──► [ 放行 (ALLOW) ]
|
||||
│ │
|
||||
│ (未通过)
|
||||
│ ▼
|
||||
│ [ 渲染 PoW 挑战页 ] ──(计算正确)──► 写入 Cookie 并放行
|
||||
▼
|
||||
6. 未触发任何策略，属于正常业务流量 ───────────────► [ 放行 (ALLOW) ]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践与调优建议
|
||||
|
||||
* **白名单前置与保护**：在部署高强度黑名单或地域屏蔽前，建议首先创建一个「受信任 IP 组」，放入你团队的办公室出口 IP、本地开发 IP 以及可能访问你的第三方回调源站 IP（如微信、支付宝支付回调地址），并在规则组的**白名单**中优先引入。这可以有效防止误杀。
|
||||
* **合理微调 PoW 难度**：人机 CC 挑战的哈希碰撞计算（`challenge_difficulty`）是一把双刃剑。
|
||||
* 难度值 `3`：几乎瞬间完成计算，防 CC 强度低。
|
||||
* 难度值 `4`：普通手机/低端浏览器在 100~300ms 内完成计算，防护性能良好。
|
||||
* 难度值 `5`：需要 500ms~2s，防护性强，但低配端可能会感觉稍显卡顿。
|
||||
* 难度值 `6` 及以上：计算量呈指数级上升，可能导致移动端用户浏览器 CPU 持续打满卡死。**因此强烈建议在生产环境选用 `4` 或 `5`**。
|
||||
* **善用“测试规则”**：对于自动 IP 组，在点击保存之前务必点击 **「测试规则」**。通过分析当前窗口内被命中的 IP 列表，确认你的 Expr 表达式阈值（如请求数、404占比等）配置是否过宽或过紧，防止由于阈值配置不合理导致大面积误封正常用户。
|
||||
* **分离静态与动态黑名单**：不要将需要长期封禁的静态恶意 IP 填入自动封禁组（因为自动聚合的名单随时会被新的执行窗口覆盖）。应该将确定的恶意 IP 录入到一个专门的「手动封禁 IP 组」中，并让规则组同时引用该手动组与自动组。
|
||||
Reference in New Issue
Block a user