WireGuard 组件

WireGuard® 是一种极其简单但快速且现代的 VPN，采用了最先进的加密技术。 此组件使用 自定义 实现，并非由原作者开发，目前 仅 适用于 ESP32、ESP8266 和 BK72xx 微控制器。

请注意 “WireGuard” 和 “WireGuard” 标志是 Jason A. Donenfeld 的注册商标。 请参阅 “WireGuard” 商标使用政策 获取更多信息。

WARNING

要成功使用此组件，您的远程主机上也必须安装 WireGuard® （已安装并准备好接受连接）。 如果您还没有安装，请阅读 远程对等端设置 部分。

WARNING

此组件需要系统时钟同步。

请参阅 时间 设置时间源， 如果 Home Assistant 位于远程对等端，不要使用 homeassistant 时间平台， 因为时间同步是建立 VPN 链接的前提条件。

SNTP 是一个有效的时间平台选择。

可以通过在配置中添加以下内容来创建到 单个 远程对等端的 VPN 隧道：

# 示例配置条目
wireguard:
  address: x.y.z.w
  private_key: AaBbCcDd...=
  peer_endpoint: wg.server.example
  peer_public_key: EeFfGgHh...=

  # 可选子网掩码（这是默认值，如果省略，
  # 则不会有出站流量通过隧道）
  netmask: 255.255.255.255

  # 可选端点端口（如果省略则使用 WireGuard 默认值）
  peer_port: 51820

  # 可选预共享密钥（如未使用则省略）
  peer_preshared_key: XxYyZzWw...=

  # 可选 IP/掩码列表（如果省略则允许任何主机）
  peer_allowed_ips:
    - x.y.z.0/24
    - l.m.n.o/32  # 单个主机可以省略 /32
    - [...]

  # 可选保活（默认禁用）
  peer_persistent_keepalive: 25s

建议至少对私钥和预共享密钥使用 密钥：

wireguard:
  private_key: !secret wg_privkey
  peer_preshared_key: !secret wg_shrdkey

配置变量

• address (必需, IPv4 地址): 设备的本地 VPN 地址。

  如果您打算通过 VPN 链接上传固件，您可能需要 将此值复制到 Wifi 的 use_address 参数。

• netmask (可选, IPv4 地址): 配置地址的子网掩码。 默认为 255.255.255.255。

  如果预期出站连接通过 VPN 链路传输（例如使用 Mqtt 连接到 远程 MQTT 代理），请参阅 静态路由和出站连接 部分。

• private_key (必需, 字符串): 设备的私钥。

• peer_endpoint (*必需, 字符串): 远程对等端的主机名。

• peer_port (可选, UDP 端口): 远程对等端监听的端口。 WireGuard® 默认值为 51820。

• peer_public_key (必需, 字符串): 远程对等端的公钥。

• peer_preshared_key (可选, 字符串): 本地设备与远程对等端之间 选择的预共享密钥。

• peer_persistent_keepalive (可选, 时间): 发送 保活 数据包 通过隧道的时间间隔。 默认情况下此功能禁用（0s）。

  如果设备与远程对等端之间存在 NAT 或防火墙， 请将此值设置为类似 25s。

• peer_allowed_ips (可选, IPv4 网络列表): 允许通过隧道的 CIDR 表示法网络列表（IP/掩码）。如果省略此参数， 则允许任何主机（0.0.0.0/0）。

  设备自身的 address/32 始终默认添加到此列表。

  如果预期出站连接通过 VPN 链路传输（例如使用 Mqtt 连接到 远程 MQTT 代理），请参阅 静态路由和出站连接 部分。

• reboot_timeout (可选, 时间): 当远程对等端不可达时， 等待重启设备的时间。可以通过设置为 0s 来禁用。 默认为 15min。

• require_connection_to_proceed (可选, 布尔值): 设置为 true 以 在继续引导设备之前等待远程对等端上线。 默认为 false。

  这可用于延迟使用 VPN 隧道的组件的初始化， 直到 VPN 准备就绪。例如，如果您使用 Mqtt 连接远程代理，您可能会在 MQTT 设置后立即遇到启动冻结， 因为它等待代理可达，但连接无法建立直到 VPN 链路也 处于活动状态。要避免这种死锁，请将此参数设置为 true， 以便在远程对等端上线之前不初始化 MQTT。

• update_interval (可选, 时间): 检查 连接状态和最新握手值的频率。默认为 10s。

• id (可选, ID): 手动指定用于代码生成的 ID。

静态路由和出站连接

目前在 ESP 设备上无法为网络接口配置静态路由， 因此 peer_allowed_ips 列表仅用于允许（或丢弃）通过 VPN 隧道的 数据包，而不是为远程主机定义静态路由。

路由由配置的 netmask 隐式添加， 只有 目标地址在 address/netmask 定义的同一网络内的数据包 才会被路由到隧道。

这意味着用户需要调整 netmask 参数以”覆盖”允许 IP 列表中的 所有 网络，才能成功建立到远程主机的 出站 连接。 入站连接不受 netmask 影响。

让我们用一些例子来说明：

address	netmask	allowed ips	可用的出站连接
172.16.0.100	省略 或 255.255.255.255	省略 或任何其他值	无，未创建任何路由
172.16.0.100	255.255.255.0	省略	到 172.16.0.0/24 网络
172.16.0.100	255.255.255.0	- 172.16.0.0/24<br />- 192.168.0.0/24 - 任何其他	仅到 172.16.0.0/24，因为 192.168.0.0/24 和任何其他网络将超出 172.16.0.0/24 范围
172.16.0.100	255.255.255.0	- 192.168.0.0/24	无，因为 192.168.0.0/24 不属于 172.16.0.0/24
10.44.0.100	255.0.0.0	省略	到 10.0.0.0/8 网络
10.44.0.100	255.0.0.0	- 10.44.0.0/16<br />- 10.10.0.0/16	仅到允许列表中的网络，因为子网掩码会路由整个 10.0.0.0/8，但 wireguard 只允许这两个子网
任何	0.0.0.0	省略	任何
任何	0.0.0.0	- 172.16.0.0/24<br />- 10.44.0.0/16 - 10.10.0.0/16	到允许 IP 列表中的任何网络，因为子网掩码会路由任何流量，但 wireguard 只允许其自己的列表

NOTE

将 netmask 设置为 0.0.0.0 的效果是任何流量都通过 VPN 链路路由。 这就像将 wireguard 接口设置为系统默认值一样。

传感器

以下是此组件可用的传感器。

状态二值传感器

此二值传感器跟踪远程对等端的连接状态（在线/离线）。

# 示例配置条目
binary_sensor:
  - platform: wireguard
    status:
      name: 'WireGuard 状态'

可以在上述配置中添加 二值传感器 的所有选项。

启用二值传感器

此二值传感器跟踪 WireGuard® 是否 已启用。

# 示例配置条目
binary_sensor:
  - platform: wireguard
    enabled:
      name: 'WireGuard 已启用'

可以在上述配置中添加 二值传感器 的所有选项。

最新握手传感器

此传感器报告最新完成握手的 时间戳。

# 示例配置条目
sensor:
  - platform: wireguard
    latest_handshake:
      name: 'WireGuard 最新握手'

可以在上述配置中添加 传感器 的所有选项。

地址文本传感器

此传感器将配置的 地址 暴露给前端。

# 示例配置条目
text_sensor:
  - platform: wireguard
    address:
      name: 'WireGuard 地址'

可以在上述配置中添加 文本传感器 的所有选项。

动作

以下动作可用。

wireguard.disable 动作

此动作会断开活动的 VPN 链路（如有）并禁用该组件。

on_...:
  then:
    - wireguard.disable:

Lambda 等效代码为 id(wireguard_id).disable()。

NOTE

要在设备启动时禁用 WireGuard®，您可以在 on_boot 步骤中执行此动作。

wireguard.enable 动作

此动作启用组件并开始连接远程对等端。

on_...:
  then:
    - wireguard.enable:

Lambda 等效代码为 id(wireguard_id).enable()。

条件

以下条件可用。

wireguard.enabled 条件

此条件检查 WireGuard® 当前是否已启用。

on_...:
  - if:
      condition: wireguard.enabled
      then:
        - ...
      else:
        - ...

Lambda 等效代码为 id(wireguard_id).is_enabled()。

wireguard.peer_online 条件

此条件检查远程对等端是否 在线。

on_...:
  - if:
      condition: wireguard.peer_online
      then:
        - ...
      else:
        - ...

Lambda 等效代码为 id(wireguard_id).is_peer_up()。

远程对等端设置

在服务器、家庭服务器或一般主机上安装和配置 WireGuard® 有许多不同的方法。这取决于 使用的平台和操作系统。

您可以先阅读 官方文档 了解它是什么以及如何在常见操作系统上 系统级 安装。 如果您打算通过 Home Assistant 安装，请阅读 Home Assistant Community Add-on: WireGuard 主题。请注意，安全设置 VPN 需要一些网络经验， 您需要打开路由器端口并可能使用自定义命令来重定向流量。

一切配置完成后，您应该能够将设备 添加到 Home Assistant。请参阅下一节。

连接到远程 Home Assistant

ESP 设备应该能够通过 VPN 链路与远程 Home Assistant 交互， 就像在本地网络一样，但初始的 自动发现 可能无法工作，您需要 手动 添加设备。

以下是步骤：

1. 转到 Home Assistant “集成”页面
2. 点击”添加集成”按钮（右下角）
3. 从列表中选择”ESPHome”
4. 输入配置的 IP 地址 作为主机名

设备现在应该链接到您的远程 Home Assistant。

NOTE

如果您在链接 ESP 设备时遇到问题，尝试将 Wifi 的 use_address 参数设置为 此处配置的 地址 值。

另见

• 时间组件
• SNTP 时间源
• 自动化
• WireGuard® 官方网站
• Home Assistant Community Add-on: WireGuard （也可在 GitHub 上找到）