OPNsense WireGuard 远程接入：双端配置、访问边界与握手诊断

WireGuard 是使用现代密码学的 VPN 协议，最初用于 Linux 内核，如今已有跨平台实现。官方介绍把简洁、性能与较低配置复杂度作为设计目标；实际吞吐仍取决于硬件、网络路径与工作负载。本文解决的是手机或笔记本从外部网络接入家庭、办公网络的场景：OPNsense 上提供一个 WireGuard 实例，每台客户端拥有独立的 peer、地址和密钥。

本文译编自 OPNsense / Deciso B.V. 的 WireGuard Road Warrior Setup，并合并官方 WireGuard 状态诊断与配置备份恢复内容。原页没有个人作者署名。核对日期为 2026 年 10 月 5 日，研究页原记录为 26.7.4_1；本文按 26.7 系列的 Source NAT 菜单与当日文档整理，不把该历史记录称为当前最新版。未接入设备、生成密钥或执行任何配置。

先安排地址、权限和回退入口

先决定客户端只访问内网，还是也通过隧道访问互联网。只访问内网时，不应顺手把全部流量路由到 VPN；全隧道时，则要一并规划出口、防火墙、DNS 和 IPv6。示例使用服务端隧道地址 10.10.10.1/24、客户端地址 10.10.10.2/32。这些网段必须与现有 LAN、其他隧道和客户端所处网络不冲突，每台客户端地址唯一。

变更前保留独立于本 VPN 的控制台或管理路径，在 System → Configuration → Backups 导出配置，并使用强密码保护 XML。配置可能含私钥等敏感信息，不能作为普通日志公开传递。备份可以包含 RRD 统计。回退和接口恢复要在可直接管理设备的条件下进行，避免依赖正在修改的远程隧道。

1. 创建服务端实例

进入 VPN → WireGuard → Instances，点击加号创建实例。未列出的选项保持默认，以下值按实际网络调整：

实例的隧道地址使用 CIDR，并为所有客户端预留足够大小的子网。IPv4 使用私有地址。本场景不要把服务端实例地址设为 IPv4 /32 或 IPv6 /128；这与下一步给单个客户端指定 /32、/128 不是一回事。

保存实例，再点击页面的 Save；重新打开实例，复制其公钥，供客户端配置使用。不要把私钥当公钥传过去。

2. 为每个客户端建立 peer

先在客户端 WireGuard 应用生成独立密钥对，取得其公钥。然后进入 VPN → WireGuard → Peers，新建并启用 peer，名称如 Phone，填写该客户端公钥。Allowed IPs 填客户端唯一的隧道主机地址，例如 10.10.10.2/32；IPv6 则使用实例子网里的唯一 /128。

保存并 Apply，再回到 Instances 打开 HomeWireGuard，在 Peers 下拉框选中刚建的 peer，保存并 Apply。其他客户端重复这一流程，不能共享私钥或复用同一隧道地址。移动客户端通常不要求服务端预先填写固定远端 Endpoint，服务端的 peer 配置与客户端连接服务端的 Endpoint 不要倒置。

VPN → WireGuard → Peer generator 也可生成客户端配置。若客户端需要用隧道上的 Unbound 解析器，生成器里的 DNS 可设为 10.10.10.1；这属于客户端配置，不是上一节要求留空的服务端实例 DNS 字段。官方通用说明提醒：并发生成多个 peer 时，尚未保存的地址可能重复，要逐个核实。

生成器默认只在防火墙保留客户端公钥，保存客户端私钥是可选且默认关闭的功能。打开该功能才能日后重建配置和二维码，但也意味着防火墙配置及备份会额外保留客户端私钥。没有保存私钥的 peer，不能凭公钥恢复原私钥或原二维码。二维码本身包含敏感配置，应按私钥对待。

3. 启用或重启 WireGuard

进入 VPN → WireGuard → General，勾选启用并 Apply。若已经启用，原文建议通过取消勾选、Apply，再勾选、Apply 来重启。此操作会中断既有隧道，执行前应安排变更窗口并确认独立管理通道可用。

4. 分配接口，并按需安排出口 NAT

只访问 OPNsense 后方的本地 IP 或子网时，接口分配和出站 NAT 并不是建立隧道的硬性要求。不过分配接口有实际好处：自动创建隧道子网别名，方便写规则；把各个 wgX 实例的规则分别组织；在自动规则适用的 IPv4 场景中，生成出网所需的 Source NAT 规则。

在 Interfaces → Assignments 选择真实的 WireGuard 设备，原文举例为 wg1，不要仅凭序号猜测。添加描述 HomeWireGuard 并保存。打开新接口，勾选 Enable 与 Lock，IPv4、IPv6 Configuration Type 都设为 None。IP 来自实例的 Tunnel Address，不要再在接口上重复配置。保存、Apply changes，然后按前述方式重启 WireGuard。

若 Unbound 注册所有接口，需要重新加载 Unbound，才能把新 WireGuard 接口纳入监听与访问配置。复杂路由或多隧道负载分配可以给接口增加网关，并使用 Dynamic gateway policy；这超出本移动接入教程范围，不能只为“让隧道工作”随意增加网关。

仅当客户端要访问本地网络之外的目的地，才进一步检查 Source NAT。已分配接口且适用自动 NAT 的 IPv4 通常不需手工再加；IPv6 若使用 GUA，通常不需要 NAT；使用 ULA 出公网时才需要相应的出口转换方案。应在实际规则列表中确认自动生成结果，尤其是已有手工规则模式或升级迁移后的设备。

确需手工规则时，在 Firewall → NAT → Source NAT (Outbound) 选择 Hybrid Source NAT rule generation，保存并应用，再添加下列规则：

保存、Apply changes，按原文流程重启 WireGuard。没有分配接口时，显式填写隧道子网，如 10.10.10.0/24，或在 Firewall → Aliases 创建明确别名。原文不建议依赖通用 WireGuard net，即便只有一个实例与一个 peer，也可能出现不符合预期的行为。

5. 分别放行外层握手和内层业务

第一条规则在 Firewall → Rules → WAN：Action 为 Pass，Quick 勾选，Direction 为 in，Protocol 为 UDP，Destination 为 WAN address，目标端口等于实例监听端口。源和目标均不反选。原文移动接入示例的 Source 为 any；若客户端出口地址固定，可进一步限定来源。IP 版本选择 IPv4 或 IPv4+IPv6，取决于客户端如何到达服务端，它与隧道内部允许哪种 IP 流量是两项设置。保存并应用。

第二类规则在分配出的 HomeWireGuard 接口上，控制已解密的业务流量。Action 为 Pass、Quick 勾选、方向 in；源是该实例的隧道子网或更窄的客户端地址，目标是授权访问的服务或网段。

与原文的安全改写：原文为了通用演示使用 Protocol any、目标可为 any、端口 any。本文不把这一组合作为生产基线。例如只允许该手机访问业务服务器 192.168.1.20 的 HTTPS，则规则可以限定源 10.10.10.2/32、目标 192.168.1.20/32、TCP 443。若同时使用 10.10.10.1 的 DNS，另外明确放行到该地址的 UDP/TCP 53。其他服务逐项增加，不要为排障永久放开所有内网和防火墙管理端口。

若未分配接口，这些业务规则应写在启用 WireGuard 后自动出现的 WireGuard 组，并显式选择源隧道地址或自建别名。IPv4 和 IPv6 都要分别检查路由与授权，客户端的 AllowedIPs 不能代替服务器防火墙规则。

6. 用 MSS 规则处理 TCP 头部开销

进入 Firewall → Settings → Normalization 新建规范化规则。原文把 Interface 设为 WireGuard (Group)，Direction 为 Any，Protocol、Source、Destination 和 Destination port 为 any。针对所承载的 IP 版本设置 Max MSS：

保存规则。原文建议在双栈场景使用 IPv6 对应的较小值；若界面与规则设计按 IP 版本拆分，可分别核对匹配范围。这里的数字依赖所用 MTU，不是任何链路都适用的常量。典型现象是 ICMP 和 UDP 能通，某些 TCP/TLS 会话却卡住；这时应把 MTU、路径 MTU 和 MSS 纳入排查，不能仅凭 ping 成功判定全部业务正常。

7. 配置客户端

客户端 [Interface] 段填写自己的地址与私钥，[Peer] 段填写服务端公钥和公网 Endpoint。客户端 AllowedIPs 列出应走隧道的目的地；服务端 peer 的 Allowed IPs 列出该客户端使用的隧道身份地址。两端字面相似，方向和用途不同。

下面是明确限制为内网访问的改写示例。尖括号内容必须替换为本次在相应设备上生成的真实密钥；这些字段故意不可直接使用，不是现成凭据。原文附录中的公开私钥一律不可复用。

[Interface]
PrivateKey = <CLIENT_PRIVATE_KEY>
Address = 10.10.10.2/32
DNS = 10.10.10.1

[Peer]
PublicKey = <OPNSENSE_PUBLIC_KEY>
AllowedIPs = 10.10.10.1/32, 192.168.1.0/24
Endpoint = opnsense.example.com:51820

客户端路由包含 DNS 服务器地址，否则设了隧道 DNS 却可能无法到达。Endpoint 要换成实际可公开解析的域名或公网地址。若只需单台业务服务器，AllowedIPs 还可缩窄为它的 /32；即使路由包含整个 LAN，防火墙仍只允许上一节明确放行的服务。

需要双栈时，原文用客户端 fd00:1234:abcd:ef09:10:2/128、服务端 fd00:1234:abcd:ef09:10:1/64 演示；应重新规划自己的唯一 ULA 或 GUA 网段，并添加实际目的网段与 DNS 地址。若明确选择全隧道，客户端 AllowedIPs 改为 0.0.0.0/0, ::/0，同时完成两种 IP 协议的出口与 DNS 检查；只处理 IPv4 不代表 IPv6 已受到相同控制。

为说明字段对应关系，服务端的等价逻辑配置如下；OPNsense 应通过 GUI 管理，不要把它粘贴覆盖系统自动生成文件：

[Interface]
Address = 10.10.10.1/24
ListenPort = 51820
PrivateKey = <OPNSENSE_PRIVATE_KEY>

[Peer]
PublicKey = <CLIENT_PUBLIC_KEY>
AllowedIPs = 10.10.10.2/32

原文给出了 wg genkey | tee private.key | wg pubkey > public.key。若在具备 WireGuard 工具的 Unix 类客户端手工生成，应先在受保护的专用目录设置文件权限并避免覆盖已有密钥。下面增加 umask、禁止覆盖，以及分步生成，是安全改写，本文未执行：

umask 077
set -C
wg genkey > private.key
wg pubkey < private.key > public.key

首条生成失败就应停止，不继续处理不存在或旧的私钥文件。私钥只留在所属设备，不进入聊天记录、仓库、公开截图或普通日志；复制的是 public.key。客户端应用的内建生成流程通常更直观。需要维持 NAT 或防火墙状态时，可按客户端条件启用 keepalive；它用于维持状态，不是修复错误公钥或路由的手段。

8. 先看握手，再查数据、路由和 DNS

在 VPN → WireGuard → Status 查看实例、peer、最后握手时间与收发字节，实例还显示底层 wgX 设备状态。首先主动发起一项被允许的访问，使判断有明确时间窗口；闲置 peer 没有刚刚更新的握手，不一定代表故障。

WireGuard 自身的日志有限，但 OPNsense 配置过程会记录错误或事件，先看 VPN → WireGuard → Log File。官方还指出可在控制台用 ifconfig 观察运行状态；本文没有执行任何设备命令。排障记录应隐藏私钥、用户身份与不需要公开的网络信息。

9. 恢复配置时保持一致性

官方备份文档支持部分恢复和完整恢复，但配置组件相互依赖，完整恢复更容易维持一致性；部分恢复可能出现意外行为。恢复到不同硬件或虚拟机时，控制台设置默认不从备份导入，以免失去控制台访问；不要无理由关闭 Exclude console settings from import。若硬件接口名不同，系统不会直接自动重启，而会要求修正接口分配。

恢复后重新核对接口映射、WireGuard 启用状态、peer 绑定、规则、DNS 与同一项业务访问。检查备份可读取不等于已验证恢复成功；本文只核对文档，没有实施回退演练。

审阅与许可说明

本稿仅完成静态审阅：已识别并移除可直接复制的公开示例私钥，以受限业务规则替换原文宽泛的默认演示，增加权限保护与回退说明；保留了原文全隧道和双栈设置的含义。未作握手、吞吐、DNS、IPv6 或规则执行测试。没有发现其他问题不等于配置已经没有漏洞。

原文与合并章节由 OPNsense / Deciso B.V. 发布，文档适用 BSD 2-Clause。以下保留文档版权、条件和免责声明。配图是未完纪原创示意图，未使用项目商标图形或伪造界面截图。

Deciso B.V. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE OPNSENSE DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.