OpenFlare/docs/guide/tunnel-usage.md

内网穿透与隧道使用

你会学到：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 快速运行：

   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 运行时，开箱即用，无需配置额外依赖：

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 配置文件：

   {
     "server_url": "http://<你的Server公网IP>:3000",
     "tunnel_token": "<刚才复制的TunnelToken>",
     "frpc_path": "/usr/local/bin/frpc",
     "data_dir": "./data"
   }
   

2. 执行启动命令：

   ./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 秒内即可自动恢复建连。