SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场wireguard

wireguard

部署与运维

查看项目

更新于 10-16 09:39

技能介绍

用途

WireGuard 是一个 VPN 工具，用于在对等端之间建立加密隧道。本条目围绕其密钥生成、对等端配置、服务端与客户端搭建、路由、NAT/伪装、故障排查以及 wg-quick 管理展开。

身份与安装

  • 内核模块：wireguard（内核 5.6+ 内置；通过 DKMS 回移植到 5.4）
  • 配置文件：/etc/wireguard/wg0.conf（接口名与文件名一致：wg0）
  • 管理方式：wg-quick up wg0 / wg-quick down wg0 / wg（状态与统计）
  • 单元：wg-quick@wg0.service（用于持久运行的 systemd 单元）
  • 安装：apt install wireguard / dnf install wireguard-tools（现代发行版通常已预包含内核模块）

密钥生成

# Generate server keys
wg genkey | tee server_private.key | wg pubkey > server_public.key

# Generate client keys
wg genkey | tee client_private.key | wg pubkey > client_public.key

# Optional: pre-shared key (adds post-quantum resistance layer)
wg genpsk > preshared.key

chmod 600 server_private.key client_private.key preshared.key

私钥绝不离开生成它的主机。公钥可自由共享。预共享密钥（PSK）是恰好两个对等端之间共享的对称密钥——每对等端一个 PSK，存储在双方的配置中。

密钥操作

目标 命令
启动接口 sudo wg-quick up wg0
关闭接口 sudo wg-quick down wg0
开机启用 sudo systemctl enable wg-quick@wg0
立即启动并开机启用 sudo systemctl enable --now wg-quick@wg0
显示所有接口状态 sudo wg show
显示特定接口 sudo wg show wg0
显示当前运行配置 sudo wg showconf wg0
检查握手时间戳 sudo wg show wg0 latest-handshakes
显示传输统计 sudo wg show wg0 transfer
运行时添加对等端 sudo wg set wg0 peer <pubkey> allowed-ips 10.0.0.3/32
将运行时更改保存到文件 sudo wg-quick save wg0
不关闭/启动接口重载配置 sudo wg syncconf wg0 <(wg-quick strip wg0)

预期端口

  • 51820/udp — 默认；通过 [Interface] 中的 ListenPort 设置
  • WireGuard 仅支持 UDP，不支持 TCP。
  • 验证监听：ss -ulnp | grep wireguard
  • 防火墙放行：ufw allow 51820/udp 或 firewall-cmd --add-port=51820/udp --permanent

健康检查

  1. sudo wg show — 列出所有接口和对等端；确认接口已启动
  2. sudo wg show wg0 latest-handshakes — epoch 时间戳；任何大于 0 的值表示对等端已连接；超过约 3 分钟前的值表示连接空闲或中断
  3. 跨隧道 ping（例如从服务器 ping 第一个客户端的隧道 IP ping 10.0.0.2）
  4. journalctl -u wg-quick@wg0 -n 50 — 启动错误、PostUp 脚本失败
  5. sudo wg show wg0 transfer — 发送/接收字节数；RX 为零表示没有流量返回

常见故障

症状 可能原因 修复
wg show 显示对等端但无握手 服务器防火墙阻止 UDP 51820，或粘贴的公钥错误 在服务器上开放 UDP 端口；验证密钥完全匹配
握手发生但无流量 服务器上 ip_forward 已禁用；缺少 PostUp NAT 规则 sysctl -w net.ipv4.ip_forward=1；验证 PostUp iptables 规则
握手反复超时 客户端端点错误（IP 或端口错误） 确认服务器的公网 IP 和 ListenPort；检查 Endpoint 行
DNS 泄漏到隧道外 客户端 [Interface] 中未设置 DNS 服务器，或 DNS 无法通过隧道访问 在客户端配置中设置 DNS = <server-tunnel-ip>；在服务器上运行 DNS 服务器
移动客户端空闲后断开 路由器上的 NAT 表使 UDP 映射过期 在客户端的 [Peer]（服务器条目）中添加 PersistentKeepalive = 25
分流路由错误流量 AllowedIPs 过宽或在对等端之间重叠 AllowedIPs 是路由表——每个 IP 范围只能出现在一个对等端中
启动时 wg-quick: Permission denied wg0.conf 权限不是 600 chmod 600 /etc/wireguard/wg0.conf
RTNETLINK answers: Operation not supported WireGuard 内核模块未加载 modprobe wireguard；在较旧内核上安装 wireguard-dkms

痛点

  • AllowedIPs 是路由表：每个对等端的 AllowedIPs 决定哪些目标 IP 通过该对等端的隧道路由。0.0.0.0/0, ::/0 = 所有流量（全 VPN）。特定子网 = 分流隧道。常见错误：两个对等端之间 AllowedIPs 重叠——WireGuard 会接受配置但路由变得未定义。

  • 无自动发现：每个对等端必须显式添加到其他每个对等端的配置中。没有中央认证服务器或证书颁发机构。添加新客户端意味着编辑服务器配置并重新加载。

  • 仅 UDP：WireGuard 严格使用 UDP。如果网络阻止所有 UDP（限制严格的酒店/企业防火墙），WireGuard 将无法工作。与 OpenVPN 不同，没有 TCP 回退。

  • 握手超时 = 连接断开：wg show 将 latest handshake 显示为 Unix 时间戳。如果超过 3 分钟前，隧道很可能已中断。PersistentKeepalive = 25 每 25 秒发送一次保活以维持 NAT 映射并更快检测死连接。

  • 服务器需要 ip_forward：为使服务器在对等端之间（或到互联网）路由流量，必须启用 net.ipv4.ip_forward = 1。在 /etc/sysctl.d/99-wireguard.conf 中持久设置 net.ipv4.ip_forward = 1；用 sysctl -p 激活。

  • 文件权限：/etc/wireguard/wg0.conf 必须为 600 模式（仅所有者可读）。如果权限过于开放，wg-quick 会警告并可能拒绝启动。该文件以明文包含私钥。

  • 运行时更改与文件更改：wg set 立即修改运行中的接口，但不会持久化到 wg0.conf。使用 wg-quick save wg0 将运行时状态写回文件，或使用 wg syncconf wg0 <(wg-quick strip wg0) 在不关闭接口的情况下应用文件更改。

参考资料

参见 references/：

  • wg0.conf.annotated — 完整注释的服务器和客户端配置示例
  • setup-patterns.md — 常见部署场景的分步指南
  • docs.md — 官方文档和社区资源