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/mask 列表（如果省略则允许任何主机）
  peer_allowed_ips:
    - x.y.z.0/24
    - l.m.n.o/32  # 单个主机可以省略 /32
    - [...]

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

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

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 (必选, string): 设备的私钥。

• peer_endpoint (必选, string): 远程对等方的主机名。

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

• peer_public_key (必选, string): 远程对等方的公钥。

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

• peer_persistent_keepalive (可选, Time): 发送 保活 数据包之前经过的时间量。 默认情况下此功能禁用（0s）。

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

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

  设备自身的 address/32 默认情况下总是添加到这个列表中。

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

• reboot_timeout (可选, Time): 远程对等方无法访问时 在重启设备之前等待的时间量。可以通过设置为 0s 禁用。 默认为 15min。

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

  这可以用于延迟使用 VPN 隧道的组件的初始化，直到 VPN 准备好。例如，如果你使用 Mqtt 到达远程代理，你可能会在 MQTT 设置之后立即遇到启动冻结， 因为它等待代理可访问， 但在 VPN 链接激活之前无法建立连接。为了绕过这种死锁，请将此参数设置为 true， 以便在远程对等方上线之前不初始化 MQTT。

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

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

静态路由和出站连接

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

路由通过已配置的 netmask 隐式添加， 仅 目标地址在 address/netmask 定义的网络内部的数据包 才会路由到隧道。

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

让我们通过一些例子来解释：

地址	子网掩码	允许的 IP	工作出站连接
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 - 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 - 10.10.0.0/16	仅到允许列表中的网络，因为子网掩码将路由整个 10.0.0.0/8，但 wireguard 只允许这两个子网
任意	0.0.0.0	省略	任意
任意	0.0.0.0	- 172.16.0.0/24 - 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 Status'

所有来自 二进制传感器 的选项都可以添加到上述配置中。

启用二进制传感器

此二进制传感器跟踪 WireGuard® 是否启用。

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

所有来自 二进制传感器 的选项都可以添加到上述配置中。

最新握手传感器

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

# 示例配置条目
sensor:
  - platform: wireguard
    latest_handshake:
      name: 'WireGuard Latest Handshake'

所有来自 传感器 的选项都可以添加到上述配置中。

地址文本传感器

此传感器向前端暴露已配置的 address。

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

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

动作

以下动作可用。

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 社区附加组件：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 社区附加组件：WireGuard （也在 GitHub 上）