mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-29 22:06:38 +08:00
ryan
600a7acdfb
- 删除未经验证的环境要求（Docker 版本号、浏览器条目）与括号废话 - 故障排查改为真实处理路径（升级→重新发布→强制同步→重建 Agent→提交 issue），删除仅开发时用的排障章节 - 删除设计文档中的测试与验收、实现检查清单、贡献者阅读建议等开发内容 - 修正与代码不符的事实：reset-passwd 命令名、证书续签窗口 7 天、Pages 检查间隔 1440 分钟、Relay vhost 端口 8080、SSO 仅支持 OIDC 等 - 去除口语化表述与无意义括号，改写「不是…而是…」句式 - 同步修正文档站链接锚点，构建验证通过
173 lines
10 KiB
Markdown
173 lines
10 KiB
Markdown
# 内网穿透与隧道使用
|
||
|
||
你会学到：OpenFlare 内网穿透隧道的设计原理、核心概念（中继节点与隧道客户端），以及如何从零开始将内网开发环境或私有云服务一步步安全、稳定地发布到公网域名上。
|
||
|
||
在许多实际开发和运维场景中，源站服务部署在局域网、本地开发机或私有 VPC 内部，没有公网 IP，也无法在边界防火墙或路由器上配置端口映射。
|
||
|
||
OpenFlare 提供了**基于反向中继穿透隧道**的整体解决方案。你只需在内网环境发起向公网中继节点的出向安全连接，无需配置任何入方向端口，即可将公网的 Web 访问流量引入内网源站，同时享有网关提供的 TLS 证书自动托管与 WAF 安全防护。
|
||
|
||
---
|
||
|
||
## 核心概念
|
||
|
||
在使用内网穿透功能前，你需要熟悉以下组件与核心概念：
|
||
|
||
| 组件 | 说明 | 对应实体 |
|
||
| --- | --- | --- |
|
||
| **中继节点（Relay）** | 部署在公网边缘的流量中继服务，负责监听内网客户端的长连接，并作为网关 Agent（OpenResty）与内网流量的中转桥梁 | 运行 `openflare-relay` 守护的 `tunnel_relay` 节点 |
|
||
| **穿透隧道（Tunnel）** | 逻辑上的穿透客户端实例，拥有全局唯一 ID 与安全认证令牌，用以标识一个具体的内网环境 | 在「节点管理」中创建的 `tunnel_client` 节点，分配专属 Tunnel Token |
|
||
| **隧道客户端（Client）** | 运行在内网环境下的轻量控制器，根据 Server 下发的配置自动管理底层的 frpc 隧道子进程 | 内网部署的 `openflared` 容器或独立二进制进程 |
|
||
| **隧道上游（Tunnel Upstream）** | 路由规则中的特殊反代类型。选择此类型后，网关会将公网流量转发至本地中继端的 Vhost 端口，最终送达内网源站 | 在「规则管理」详情页中配置的反向代理类型，选择回源方式为「内网穿透（Tunnel）」并绑定对应 Tunnel 节点 |
|
||
|
||
---
|
||
|
||
## 推荐操作顺序
|
||
|
||
将一个内网服务发布到公网，推荐按这个顺序进行：
|
||
|
||
1. 注册并部署至少一个公网 **中继节点（Relay）** 并保持在线。
|
||
2. 进入 **「节点管理」**，新建一个类型为 **Tunnel 节点（tunnel_client）** 的节点，获取专属 Token。
|
||
3. 在内网服务器中部署并启动 **隧道客户端（OpenFlared）**。
|
||
4. 确认管理端中该 Tunnel 节点的状态显示为「在线」。
|
||
5. 在 **「规则管理」** 页面新增或编辑规则，在「反向代理」选项卡中选择回源方式为 **「内网穿透（Tunnel）」**，绑定对应 Tunnel 节点并填写内网服务端口（如 `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 客户端连接控制端口，默认 `relay_bind_port`）。如果你的 Server 与中继节点部署在同一台机器，这里的 `OPENFLARE_SERVER_URL` 应指向 Server 的公网或内网通信 IP。
|
||
|
||
### 第二步：在管理端创建 Tunnel 节点
|
||
|
||
1. 导航至管理侧边栏的 **「节点管理」** 页面。
|
||
2. 点击 **「新增节点」** 按钮，在弹窗中选择节点类型为 **「Tunnel 节点（tunnel_client）」**。
|
||
3. 填入节点名称与描述，点击保存。
|
||
4. 在节点列表中点击进入刚才创建的 Tunnel 节点详情页，你可以找到专属的 **Tunnel Token** 及相应的客户端一键部署命令。
|
||
|
||
### 第三步：部署内网客户端（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. 刷新管理端的 **「节点管理」** 列表，刚才创建的 Tunnel 节点状态指示灯应当变为绿色的 **「在线」**。
|
||
2. 点击节点进入详情页，你可以直观地查看到当前内网客户端连接了公网的哪些中继 Relay 节点。
|
||
|
||
### 第四步：配置请求路由并绑定隧道上游
|
||
|
||
现在你可以为你的内网服务配置公网反向代理和域名访问了。
|
||
|
||
1. 首先进入 **「网站管理」->「域名列表」** 录入你想要公开访问的域名。
|
||
2. 进入 **「规则管理」** 页面，点击 **「新建规则」** 或编辑已有规则。
|
||
3. 在下方 **「反向代理」** 选项卡下，将 **回源方式** 切换为 **「内网穿透（Tunnel）」**。
|
||
4. 从下拉列表中选择刚才部署在线的 **Tunnel 节点**。
|
||
5. 填写 **内网目标地址**（对于内网客户端来说可访问的本地地址与端口，例如 `127.0.0.1:8080`）与 **内网协议**（通常为 `http`）。
|
||
6. 配置其他站点常规项，并点击保存。
|
||
|
||
### 第五步：发布与生效
|
||
|
||
为了让网关的 OpenResty 能够正确匹配并路由域名流量，我们需要发布新的配置版本。
|
||
|
||
1. 点击导航栏右上角的 **「预览并发布」**，确认生成的站点配置无误。
|
||
2. 在弹出窗口中，点击 **「确认发布」**。
|
||
3. 此时，公网边缘的 Agent 会拉取到最新路由：它会将请求转发至同机部署的 `openflare-relay（frps）` 的虚拟主机端口下。
|
||
4. 内网客户端 `openflared（frpc）` 会接收到被中继的封包，并安全地透传给内网的 `127.0.0.1:8080` 服务，最后原路返回响应。
|
||
5. 在你的公网浏览器中访问对应域名，确认内网服务成功展示。
|
||
|
||
---
|
||
|
||
## 高级应用场景
|
||
|
||
### 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 地址。
|
||
* **中继节点防火墙未开**：检查对应中继节点的公网 `7000` 端口（或自定义的 `relay_bind_port`）是否已经在安全组中对公网放行。
|
||
|
||
### 2. 访问公网域名返回 502 Bad Gateway / 504 Gateway Timeout
|
||
|
||
* **内网服务未运行**：确认内网目标地址对应的服务已在内网服务器上成功启动并处于监听状态。
|
||
* **目标地址不可达**：如果内网地址填的是 `127.0.0.1:8080`，确保服务确实在运行着 `openflared` 的同一台主机上；如果填的是局域网 IP `192.168.x.x`，请在 `openflared` 容器内测试该局域网 IP 的连通性。
|
||
* **检查节点状态与日志**：在管理端查看 Tunnel 节点详情与「应用记录」，排查是否有异常状态；frpc 进程异常时会在内网宿主机 `flared` 日志中记录详细报错。
|
||
|
||
### 3. 多中继网络动荡或重试失败
|
||
|
||
* 当控制面关联了多个 Relay 中继节点时，`openflared` 会为每个 Relay 独立派生 frpc 守护进程，并在 `flared.json` 中配置的 `sync_interval`（默认 30s）内定时向控制面拉取拓扑状态。
|
||
* 若某一中继节点频繁由于网络抖动离线，系统会自动触发指数退避重试（初始 1 秒，上限 60 秒）。你可以在宿主机日志中看到 `frpc process missing, starting` 的日志，这属于正常的进程自愈逻辑，网络恢复后会自动重新建连。
|