第21章 系统架构
第21章 系统架构
本文从技术角度介绍 Pangolin 的控制平面、节点、连接器和客户端是如何协同工作的。
开源
Pangolin 的每一层都是开源的,从控制平面服务器到站点连接器,再到终端用户客户端。每个组件在 GitHub 的 fosrl 组织下都有独立仓库,本页底部的组件参考中列出了这些仓库。
驱动 Pangolin Cloud 的软件同样开源。SaaS 控制平面运行的是与自托管 Pangolin 相同的代码库,代码存放在主仓库 fosrl/pangolin 中。
Pangolin 分为控制平面(负责配置、身份和编排)和数据平面(负责加密隧道、入口和流量中继)。对于公开资源,站点连接器会向 Pangolin 节点发起出站连接,这样节点就能以反向代理的方式把流量送入远程网络,而无需在远程网络开放入站端口。对于私有资源,客户端与站点点对点直连;只有在无法建立直连路径时,节点才作为中继参与数据传输。详见点对点与中继路径。
如果想了解站点、资源和客户端在产品层面的使用方式,请参阅 How Pangolin Works。本页重点介绍这些组件的具体实现以及流量在系统中的流转方式。
*Pangolin 整体架构图*
控制平面
控制平面就是 Pangolin 服务器应用。它将组织状态存储在数据库中,对外提供仪表盘和 REST API,处理认证与授权,并通过 WebSocket 实时向所有节点、站点连接器和客户端推送配置。
主要职责包括:
- 策略与身份——管理用户、角色、客户端、机器以及访问规则,决定每个主体能访问哪些资源 - 资源与站点定义——管理目标地址、路由偏好、证书和健康检查配置 - 编排——在创建或修改资源时协调隧道对端、DNS 记录和入口路由 - 遥测——收集连接状态、中继状态等运营信号,并在仪表盘中展示
你可以自己运行控制平面(自托管),也可以使用 Pangolin Cloud 由官方托管。两种方式下的编排模型是一样的:连接器和节点从控制平面拉取配置,而不是接受入站管理连接。
节点
节点是 Pangolin 部署的网络边缘。它接收来自公网的入站流量、管理 WireGuard 隧道,并在无法直连时中继客户端流量。
在自托管部署中,Pangolin 服务器默认以单节点方式运行。企业版集群可以在负载均衡器后部署多个节点,共享数据库状态。使用 Pangolin Cloud 时,你可以添加远程节点:由你自己运维基础设施,但仍从云端控制平面接收配置。
每个节点运行多个协作进程:
| 角色 | 工程代号 | 功能 | |---|---|---| | 入口/反向代理 | Traefik | 终结 TLS,路由 HTTP(S) 和协议感知的公开资源,把认证后的请求转发到隧道网络 | | 隧道管理器 | Gerbil | 维护站点连接器和客户端的 WireGuard 对端,基于 SNI 路由,并在打洞失败时中继 UDP 流量 | | 认证中间件 | Badger | Traefik 插件,通过 forward auth 对公开资源执行 Pangolin 认证 |
控制平面会写入这些进程所需的证书、Traefik 路由定义和 WireGuard 对端列表。节点不需要直接访问数据库,只需能与控制平面通信,并在公网侧开放监听端口即可。
- [节点的 DNS 与端口要求](#):必需的监听端口、防火墙规则和 DNS 记录 - [高可用集群](#):共享状态和故障转移的多节点企业部署 - [Pangolin Cloud 上的远程节点](#):使用云端控制平面管理的同时运行自己的节点
站点连接器
站点连接器运行在远程网络中(服务器、虚拟机、容器或设备上),是私有局域网与平台之间的桥梁。对于公开资源,它与 Pangolin 节点保持持久出站连接,使入口流量可以反向代理进局域网。对于私有资源,客户端直接与连接器点对点通信;只有在打洞失败时,节点才会作为中继参与数据路径。
主要的连接器是 Pangolin Site。站点会建立两类连接:
- 与控制平面的 WebSocket 连接,用于配置、健康检查和协调 - 与节点隧道管理器(Gerbil)的 WireGuard 隧道,用于传输加密数据
站点连接器默认全部拒绝(deny-by-default)。部署它并不会暴露网络中的主机,只有你明确定义并授权的资源才会被转发流量。连接器会在远程网络中解析后端目标并投递数据包。
Pangolin Sites 支持完整功能集:公开与私有资源、协议感知代理、多站点路由、健康检查,以及私有 HTTP 的边缘 TLS。其他连接器类型(local 和 basic WireGuard)用于特殊的自托管场景。
- [了解站点](#):站点类型、部署模式和连接器能力
客户端
客户端是运行在用户设备或机器上的端点代理。它们向控制平面认证、获取访问控制列表,并建立 WireGuard 隧道,让用户能够访问私有资源。
两类客户端共享同一套隧道技术栈:
- 用户设备——桌面和移动端的 GUI 应用,用户使用 Pangolin 账号或 SSO 登录 - 机器——面向服务器和自动化的 CLI 客户端,使用 ID 和 secret 认证
共享客户端技术栈(Olm)
所有 Pangolin 客户端都共享一个名为 Olm 的通用网络核心(工程代号)。Olm 承载了所有客户端依赖的 WireGuard 隧道逻辑、打洞与中继协商、路由安装和 DNS 覆盖。各平台应用只需嵌入或调用 Olm,无需重新实现这套技术栈。
Olm 在不同客户端中的承载方式:
- macOS 和 iOS——Olm 运行在平台的网络扩展(network extension)中 - Windows 和 Android——Olm 作为原生应用背后的隧道服务运行 - Pangolin CLI——以子进程方式启动 Olm,并通过本地 API 管理它 - Olm CLI——直接暴露 Olm,适用于最小化的机器客户端部署
Olm 是内部构建模块,不是面向用户的产品。为了获得最佳体验、完整支持和与操作系统网络 API 的深度集成,请使用为各操作系统打造的原生客户端。直接使用 Olm 仅限于高级机器客户端和自动化场景,详见 Olm。
客户端连接后会为每个授权目标安装路由。Pangolin 会自动选择正确的站点连接器,用户只需连接资源,无需直接指定站点。当资源分布在多个连接器上时,故障转移机制详见多站点路由。
- [了解客户端](#):用户设备、机器客户端以及授权方式 - [平台](#):在 Mac、Windows、Linux、iOS、iPadOS 和 Android 上安装、配置和更新客户端
点对点与中继路径
客户端到站点的流量并不总是经过你的节点。Pangolin 会为每条隧道协商最优路径。
同一网络(本地)
当客户端和站点连接器处于同一局域网时,它们会检测到这一点并通过局域网直接连接。站点会收集自身网络接口的地址,并从这些接口向客户端发送 UDP 测试包。流量留在本地网络内,完全绕过节点及其转发层,也不经过路由器或 ISP 出网。此功能需要 Pangolin 1.21 及以上版本的客户端和站点。
点对点直连(打洞)
默认情况下,控制平面会协调 NAT 打洞,让客户端和站点连接器建立直接的 WireGuard 点对点连接。流量随后在客户端和站点之间直接传输,不经过节点的转发层。这条路径通常延迟更低,也节省节点的带宽。
通过节点中继
当打洞失败(受限 NAT、对称 NAT 或 UDP 被封)时,客户端和站点会回退到经由节点隧道管理器(Gerbil)中继。Gerbil 默认监听 UDP 21820 端口,接收客户端的 WireGuard 数据包,并转发到站点连接器已有的隧道中。连接始终保持端到端加密,改变的只是网络路径。
站点连接器与节点的出站隧道使用单独的默认端口(UDP 51820)。中继是可选功能,如果你要求必须直连,可以按客户端禁用。
从站点代理出去
站点连接器(newt 或 cli)在用户态运行并终结 WireGuard 隧道。为了让客户端能够访问局域网中的任意目标,连接器会对数据包执行 SNAT 操作。这意味着数据包的源 IP 是站点连接器的 IP,而不是客户端的 IP。如果保留客户端的源 IP,这个地址会在局域网中丢失,因为目标资源不知道如何回包到客户端的内部网络 WireGuard IP。在排查连通性问题或配置站点网络防火墙规则时,理解这一点很重要。
- [NAT 穿越](#):同网检测、打洞与中继的对比、如何判断站点是本地/直连/中继路径,以及调优选项
流量路径
两条主要流量路径覆盖了绝大多数部署场景。
入站:公开资源
公开资源在节点的入口层接收来自互联网的流量。
互联网 → 节点入口(Traefik)→ 认证(Badger)→ 隧道(Gerbil)→ 站点连接器(Newt)→ 后端目标
HTTP、HTTPS、SSH、RDP 和 VNC 公开资源在流量进入隧道前先在节点上完成认证。TCP 和 UDP 公开资源绑定到节点端口,直接代理原始流量,不经过认证层。证书签发、路由配置和访问规则全部由控制平面驱动。
- [公开资源](#):协议类型、目标地址以及入口如何映射到后端
出站:通过客户端访问私有资源
私有资源只有在客户端连接并授权后才能访问。
客户端 ↔(局域网、点对点直连或经 Gerbil 中继)↔ 站点连接器(Newt)→ 远程网络中的目标
客户端为 IP、CIDR 或 FQDN 目标安装路由。站点连接器在远程局域网中解析并投递流量。对于私有 HTTP,TLS 可以在连接器上终结,让应用完全不暴露在公网上。
- [私有目标](#):IP、CIDR、FQDN 和别名目标如何被解析和路由
组件参考
Pangolin 的开源仓库与上述角色一一对应。这些代号在代码库和部署工具中被广泛使用。
| 组件 | 仓库 | 角色 | |---|---|---| | Pangolin | fosrl/pangolin | 控制平面服务器 | | Clients | fosrl/cli、fosrl/windows-linux、fosrl/apple、fosrl/android | 端点代理 | | Site Connector | fosrl/cli | 连接远程网络,支持公开与私有资源 | | Gerbil | fosrl/gerbil | 节点隧道管理器和中继 | | Badger | fosrl/badger | Traefik forward-auth 中间件 | | Newt | fosrl/newt | 共享站点网络技术栈 | | Olm | fosrl/olm | 共享客户端网络技术栈(隧道、NAT 穿越、DNS) |
有关本地开发环境搭建以及这些仓库在开发环境中的协作方式,请参阅 Contributing。
这个页面有帮助吗?