wesher：实践指南

作者：袖梨 2026-09-11

真正理解wesher，要从它处理的任务开始：wireguard 覆盖网状网络管理器。把它放到日常自动化流程中，最容易暴露的是输入边界、依赖和失败处理如果不清楚就很难稳定复用，不能只看演示是否顺利。我建议用一项范围明确的真实任务完成最小试跑，重点记录配置时间、输出质量、异常信息和维护痕迹，再与现有方案比较。编辑判断上，愿意先做小范围验证并复查原始文档的团队可以优先研究它；其他团队不必为了热门标签勉强接入。

威舍尔

wesher 使用线卫创建和管理跨一组节点的加密网状覆盖网络。

其主要用例是为公共云网络添加低维护安全性或连接不同的云提供商。

⚠ WARNING：由于网格成员资格是由网格范围的预共享密钥控制的，这有效地降低了一些 Wireguard 带来的安全优势。有关更多详细信息，请参阅下面的安全注意事项。

快速入门

开始之前：
1. make sure the wireguard kernel module is available on all nodes. It is bundled with linux newer than 5.6 and can otherwise be installed following the instructions here.
2. 所有节点之间必须可访问以下端口（请参阅配置选项来更改这些端口）：
  - 51820 UDP
  - 7946章

下载适合您的架构的最新版本：

$ wget -O wesher https://github.com/costela/wesher/releases/latest/download/wesher-$(go env GOARCH)
$ chmod a+x wesher

在第一个节点上：
```
# ./wesher
```
这将在前台启动 wesher 守护进程，并且在终端上运行时，当前将输出生成的集群密钥，如下所示：
```
new cluster key generated: XXXXX
```
注意：为了避免意外在日志中泄漏，创建的密钥_仅_在终端上运行时才会显示。当通过其他方式启动时（e.g.：桌面会话管理器或初始化系统），可以使用 grep ClusterKey /var/lib/wesher/state.json 检索密钥。
最后，在任何其他节点上：
```
# wesher --cluster-key XXXXX --join x.x.x.x
```
其中 XXXXX 是上述步骤打印的 base64 编码的 256 位密钥，x.x.x.x 是已加入网格集群的任何节点的主机名或 IP。

权限

请注意，wireguard - 以及 wesher - 需要 root 访问权限才能正常工作。

还可以通过以下方式为 wesher 二进制文件提供足够的功能来管理 wireguard 接口：

# setcap cap_net_admin=eip wesher

这将允许以非特权用户身份运行，但某些功能（例如自动将对等条目添加到 /etc/hosts；请参阅下面的配置选项）将不起作用。

（可选）系统集成

dist 文件夹下提供了最小的 systemd 单元文件，可以将其复制到 /etc/systemd/system：

# wget -O /etc/systemd/system/wesher.service https://raw.githubusercontent.com/costela/wesher/master/dist/wesher.service
# systemctl daemon-reload
# systemctl enable wesher

提供的单元文件假定 wesher 安装到 /usr/local/sbin。

请注意，如上所述，初始簇键不会显示在日志中。它可以通过手动运行 wesher 一次来初始化，也可以通过 /etc/default/wesher 作为 WESHER_CLUSTER_KEY 环境变量进行预播种（请参阅下面的配置选项）。

从源安装

有几种从源安装 wesher 的方法：

首选：

$ git clone https://github.com/costela/wesher.git
$ cd wesher
$ make

该方法可以构建与已发布的二进制文件逐位相同的二进制文件，假设使用相同的 go 版本来构建其各自的 git 标签。

或者：

$ GO111MODULE=on go get github.com/costela/wesher

注意：此方法不会为 --version 提供有意义的输出。

特点

wesher工具构建集群并管理每个节点上wireguard的配置以创建点对点所有节点之间连接，从而形成全网状。这种方法可能无法扩展到数百个节点（基准已接受），但具有足够的性能来加入跨多个云提供商的多个节点，或者只是为了保护单个公共云中的节点间通信。

自动密钥管理

Wireguard 私钥在每个节点启动时创建，然后广播各自的公钥跨集群。

控制平面集群通信通过预共享的 AES-256 密钥进行保护。该键可以自动在集群中第一个节点启动期间创建，或者可以提供（请参阅配置）。然后，必须通过带外安全通道（e.g.ssh、cloud-init 等）将集群密钥发送到其他节点。设置后，集群密钥将保存在本地并在下次启动时重复使用。

自动 IP 地址管理

每个节点的覆盖 IP 地址是从专用网络中自动选择的（默认情况下为 10.0.0.0/8；MUST 与用于集群通信的底层网络不同），并根据对等点的主机名进行一致的哈希处理。

使用一致散列意味着给定节点将始终接收相同的覆盖 IP 地址（请参阅限制下面介绍这种方法）。

注意：节点的主机名也被底层集群管理使用（使用成员列表）用于识别节点，因此在集群中必须是唯一的。

自动/etc/hosts管理

为了简化节点内通信，wesher 还为网格中的每个对等点添加条目到 /etc/hosts。这使得能够使用节点的主机名来确保通过安全覆盖网络进行通信（假设 files 是 /etc/nsswitch.conf 中 hosts 的第一个条目）。

请参阅下面的配置了解如何禁用此行为。

无缝重启

如果集群中的节点重新启动，它将尝试使用相同的集群密钥重新加入最后已知的节点。这意味着重新启动不需要手动干预。

配置选项

所有选项都可以作为命令行标志或环境变量传递：

选项	环境	描述	默认
`--cluster-key KEY`	WESHER_CLUSTER_KEY	集群成员身份的共享密钥；必须是 32 字节 base64 编码；如果没有提供将会生成	autogenerated/loaded
`--join HOST,...`	WESHER_JOIN	现有集群成员的主机名或 IP 地址的逗号分隔列表；如果未提供，将尝试恢复任何已知状态或以其他方式等待更多成员
`--init`	WESHER_INIT	是否显式（重新）初始化集群；之前运行的任何已知状态都将被忘记	`false`
`--bind-addr ADDR`	WESHER_BIND_ADDR	IP 集群成员身份绑定地址（不能与 --bind-iface 一起使用）	自动检测到的
`--bind-iface IFACE`	WESHER_BIND_IFACE	集群成员身份绑定的接口（不能与 --bind-addr 一起使用）
`--cluster-port PORT`	WESHER_CLUSTER_PORT	用于成员八卦流量的端口（TCP 和 UDP）；跨集群必须相同	`7946`
`--wireguard-port PORT`	WESHER_WIREGUARD_PORT	用于wireguard流量的端口（UDP）；跨集群必须相同	`51820`
`--overlay-net ADDR/MASK`	WESHER_OVERLAY_NET	为覆盖网状网络分配地址的网络（CIDR 格式）；较小的网络会增加 IP 冲突的机会	`10.0.0.0/8`
`--interface DEV`	WESHER_INTERFACE	要创建和管理的wireguard接口的名称	`wgoverlay`
`--no-etc-hosts`	WESHER_NO_ETC_HOSTS	是否跳过为网格中每个节点写入主机条目	`false`
`--log-level LEVEL`	WESHER_LOG_LEVEL	设置详细程度（debug/info/warn/error 之一）	`warn`