WireGuard

Abstract

WireGuard 是一个轻量、现代的 VPN 协议，适合把个人设备、云服务器和家庭内网组成一个稳定的私有网络。

wireguard

核心概念

WireGuard 本身只做一件事：在两台机器之间建立加密隧道。每台机器都是一个 peer，通过公私钥识别身份，通过 AllowedIPs 决定哪些流量走隧道。

典型个人场景

从外网访问家里的 NAS、开发机、Home Assistant。
把云服务器、笔记本、手机、家用服务器放进同一个私有网段。
替代复杂的 OpenVPN / IPsec 配置，用更少的参数完成稳定组网。

常用端口是 UDP 51820。如果 peer 在 NAT 后面，通常需要配置 PersistentKeepalive = 25，让连接状态保持活跃。

环境准备

基础条件

至少准备一台有公网入口的机器，通常是云服务器：

项目	建议
公网入口	云服务器公网 IP，或家庭宽带公网 IP + DDNS
系统	Ubuntu 22.04 / 24.04
端口	UDP `51820` 用于 WireGuard
域名	可选，但推荐绑定到公网入口
Docker	使用 `wg-easy`、`subspace` 等 Web UI 时需要

防火墙配置

如果是云服务器，需要同时检查两层防火墙：

云厂商安全组：放行 UDP 51820。
Ubuntu 本机防火墙：放行 UDP 51820。

sudo ufw allow 51820/udp
sudo ufw status

地址规划

个人使用可以直接规划一个独立 VPN 网段：

节点	VPN 地址	说明
Server	`10.8.0.1/24`	WireGuard 服务端
Laptop	`10.8.0.2/32`	笔记本
Phone	`10.8.0.3/32`	手机
Home Server	`10.8.0.10/32`	家庭服务器 / NAS

地址冲突

这个网段不要和家里、公司、云服务器内网已有网段冲突。

部署架构

最常见的个人架构是 hub-spoke：公网服务器作为中心节点，其他设备都连到这个中心节点。

flowchart LR
    phone[Phone<br/>10.8.0.3] --> wg[WireGuard Server<br/>10.8.0.1]
    laptop[Laptop<br/>10.8.0.2] --> wg
    home[Home Server / NAS<br/>10.8.0.10] --> wg
    wg --> internet[Internet]

常见流量模式：

模式	`AllowedIPs`	适合场景
Split Tunnel	`10.8.0.0/24`	只访问 VPN 内部节点，个人组网首选
Full Tunnel	`0.0.0.0/0, ::/0`	所有流量都走 VPN，适合公共 Wi-Fi 下代理全流量
Site-to-Site	`10.8.0.0/24, 192.168.1.0/24`	访问家庭局域网或办公室局域网

默认选择

默认选择是 Split Tunnel：稳定、简单、不会影响日常上网。

安装方式

方式	适合场景	个人建议
`wg-easy`	快速部署、经常新增手机/电脑客户端	日常首选
原生 WireGuard	想理解底层配置、节点数量少、需要完全可控	必须掌握
`subspace`	了解早期 WireGuard GUI，或已有历史部署	新项目不优先

wg-easy

wg-easy 是 WireGuard + Web UI 的一体化部署方式。它适合个人服务器，因为创建客户端、下载配置、扫码导入都可以在浏览器完成。

wg-easy

安装方法：Basic Installation

推荐使用 Docker Compose 一键安装，方便管理。

自定义配置

挂载路径可以改为任意位置，方便备份和管理。
环境变量可以自定义，例如 INSECURE 可以设置为 true 以允许不安全的连接。

官方 docker-compose.yml自定义 docker-compose.yml

volumes:
  etc_wireguard:

services:
  wg-easy:
    #environment:
    #  Optional:
    #  - PORT=51821
    #  - HOST=0.0.0.0
    #  - INSECURE=false

    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    networks:
      wg:
        ipv4_address: 10.42.42.42
        ipv6_address: fdcc:ad94:bacf:61a3::2a
    volumes:
      - etc_wireguard:/etc/wireguard
      - /lib/modules:/lib/modules:ro
    ports:
      - "51820:51820/udp"
      - "51821:51821/tcp"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
      # - NET_RAW # ⚠️ Uncomment if using Podman
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv6.conf.all.disable_ipv6=0
      - net.ipv6.conf.all.forwarding=1
      - net.ipv6.conf.default.forwarding=1

networks:
  wg:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 10.42.42.0/24
        - subnet: fdcc:ad94:bacf:61a3::/64

services:
  wg-easy:
    environment:
      - PORT=51821
      - HOST=0.0.0.0
      - INSECURE=true

    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    networks:
      wg:
        ipv4_address: 10.42.42.42
        ipv6_address: fdcc:ad94:bacf:61a3::2a
    volumes:
      - /root/wg-easy/wireguard:/etc/wireguard
      - /lib/modules:/lib/modules:ro
    ports:
      - "51820:51820/udp"
      - "51821:51821/tcp"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
      # - NET_RAW # ⚠️ Uncomment if using Podman
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv6.conf.all.disable_ipv6=0
      - net.ipv6.conf.all.forwarding=1
      - net.ipv6.conf.default.forwarding=1

networks:
  wg:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 10.42.42.0/24
        - subnet: fdcc:ad94:bacf:61a3::/64

其中的 10.42.42.42 和 10.42.42.0/24 网段一般不需要修改

一般不需要改。

这里的 10.42.42.0/24 是 Docker 为 wg-easy 容器创建的 bridge 网络，10.42.42.42 是 wg-easy 容器在这个 Docker 网络里的固定地址。它们主要用于容器内部通信，不是 WireGuard 客户端拿到的 VPN 地址段。

真正给 WireGuard 客户端使用的网段通常在 wg-easy 的 Web UI 或环境变量里配置，例如 10.8.0.0/24。客户端连接后拿到的是这类 VPN 地址，而不是 10.42.42.42。

只有在下面情况才建议修改：

你的服务器、家庭局域网、公司内网或其他 Docker 网络已经用了 10.42.42.0/24。
同一台机器上还有其他容器网络，和这个网段冲突。

如果要改，需要同时改两处，并保持 ipv4_address 落在 subnet 里面：

networks:
  wg:
    ipv4_address: 10.43.43.42

networks:
  wg:
    ipam:
      config:
        - subnet: 10.43.43.0/24

简单判断：如果服务器上执行 ip route 没看到已有的 10.42.42.0/24，通常就可以保持官方默认值。

WireGuard

原生方式适合少量固定节点，或者需要清楚掌控每一条路由规则的场景。

服务端

安装：

sudo apt update
sudo apt install -y wireguard

生成密钥：

wg genkey | sudo tee /etc/wireguard/server_private.key | wg pubkey | sudo tee /etc/wireguard/server_public.key
sudo chmod 600 /etc/wireguard/server_private.key

开启转发：

echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-wireguard.conf
sudo sysctl --system

创建 /etc/wireguard/wg0.conf：

[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = <server-private-key>

[Peer]
PublicKey = <client-public-key>
AllowedIPs = 10.8.0.2/32

启动：

sudo systemctl enable --now wg-quick@wg0
sudo wg show

客户端

安装并生成密钥：

sudo apt update
sudo apt install -y wireguard
wg genkey | sudo tee /etc/wireguard/client_private.key | wg pubkey | sudo tee /etc/wireguard/client_public.key
sudo chmod 600 /etc/wireguard/client_private.key

创建 /etc/wireguard/wg0.conf：

[Interface]
Address = 10.8.0.2/32
PrivateKey = <client-private-key>

[Peer]
PublicKey = <server-public-key>
Endpoint = <server-public-ip-or-domain>:51820
AllowedIPs = 10.8.0.0/24
PersistentKeepalive = 25

启动：

sudo systemctl enable --now wg-quick@wg0
sudo wg show

新增客户端

每新增一个客户端，都需要在服务端追加一个 [Peer]：

[Peer]
PublicKey = <new-client-public-key>
AllowedIPs = 10.8.0.3/32

修改后重启服务：

sudo systemctl restart wg-quick@wg0

subspace

subspace 是较早期的 WireGuard Web GUI，提供设备管理、配置生成、二维码导入等能力。

subspace

subspace 的定位

适合了解 WireGuard Web UI 的早期实现。
如果已经在用，可以继续维护，但需要确认当前 fork、镜像和依赖的更新状态。
新部署个人 VPN 时，优先选择 wg-easy。

排查

现象	检查点
没有握手	公网 IP / 域名、UDP `51820`、安全组、本机防火墙、系统时间
有握手但访问不了	`AllowedIPs`、目标服务监听地址、目标机器防火墙
NAT 后连接不稳定	客户端配置 `PersistentKeepalive = 25`
连接后不能上网	是否误配 `AllowedIPs = 0.0.0.0/0`，以及服务端 NAT/DNS 是否完整
Web UI 打不开	容器状态、`51821/tcp`、反向代理、安全组

总结

日常个人组网优先 wg-easy，先把网络跑通。
一定要理解原生配置里的 Address、PublicKey、AllowedIPs、Endpoint。
管理后台不要长期裸露公网。
客户端命名保持清晰，例如 phone-iphone-15、laptop-macbook、server-nas。
迁移或重装前先备份 WireGuard 配置和客户端私钥。