WireGuard 部署与迁移

蓝色 8 阅读 内网穿透

WireGuard 部署与迁移笔记

从零部署 → 日常运行 → 整站搬家到新服务器,一条主线走完。

wg-easy 15 · Docker host 模式 · 原生 VPS · 7 客户端

一、环境基线与文件分工

先对齐现状,后面所有操作都以此为准。

项本环境取值
部署方式wg-easy 15,Docker network_mode: host
服务端原生 VPS(公网 IP 直接落在网卡上,前面没有 NAT)
管理台:51821/tcp,INSECURE=true 免密
WireGuard 端口51820/udp
隧道网段10.9.0.0/24,IPv6 fdcc:ad94:bacf:61a4::/112
持久化目录宿主机 /opt/wg-easy → 容器 /etc/wireguard
客户端7 台(ars2 / iphome12 / ubutu24 / zhanglu / FNOS / win11 / mini2新)

目录里都有什么

文件 / 目录性质迁移怎么办
wg0.json客户端数据库(v15 的真相来源)必须原样保留
server/服务端密钥对必须原样保留
clients/各客户端配置模板原样保留
wg0.conf派生文件,由上面三者 + 环境变量渲染出来可沿用,只需改网卡名
记住这条分界

数据库和密钥是源,wg0.conf 是产物。文件头那句 Do not edit this file directly 不是客套——wg-easy 重启时会用它自己算出来的结果覆盖你的手改。所以:加设备、改密码一律走 Web 界面;只有迁移换网卡名这一种情况才手改。

二、首次部署(host 模式)

STEP 1

装载内核模块、开转发

# 立即生效
modprobe wireguard
sysctl -w net.ipv4.ip_forward=1
sysctl -w net.ipv6.conf.all.forwarding=1

# 持久化
cat >> /etc/sysctl.d/99-wg.conf <<'EOF'
net.ipv4.ip_forward=1
net.ipv6.conf.all.forwarding=1
EOF
sysctl --system

host 模式下容器直接用宿主机内核,没有 sysctls: 这一项可写,写了 compose 会报错。所以必须在宿主机上开,这也是和桥接模式最大的区别。

STEP 2

写 docker-compose.yml

services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    restart: unless-stopped
    network_mode: host          # 容器共享宿主机网络栈
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    environment:
      - WG_HOST=<VPS_IP 或域名>    # 写客户端 conf 里的 Endpoint
      - WG_PORT=51820
      - INSECURE=true
      - TZ=Asia/Shanghai
      - PASSWORD_HASH='$$argon2id$$v=19$$...'
    volumes:
      - /opt/wg-easy:/etc/wireguard
    # host 模式下 ports: 无效,不要写
compose 里的钱符号要双写

PASSWORD_HASH 含大量 $,YAML 里必须写成 $$,否则 compose 会当变量替换掉,导致哈希损坏、容器启动即退出。生成哈希:docker run --rm ghcr.io/wg-easy/wg-easy:15 wg genpw 再用镜像内的 wg hash 处理。

host 模式 vs 桥接模式

对比host(本环境选用)桥接 + ports
端口映射不需要,直接占用宿主机端口必须写 51820:51820/udp
sysctls不可用,须在宿主机开可在 compose 里声明
iptables 规则PostUp 直接作用于宿主机须额外 -i/-o docker0 放行
端口冲突与宿主机服务抢端口隔离,可改映射端口
排错直观度wg show 宿主机直接可用要 docker exec 进去看

选 host 的理由:隧道工具本身就该贴着宿主机网络栈跑,少一层 NAT 少一类问题,排错时命令都在宿主机上直接敲。

STEP 3

起容器并确认复用而非重建

docker compose up -d
docker compose logs --tail 40 | grep -iE 'existing|created|generat|error'

日志出现 Using existing configuration 一类字样 = 复用了老数据;如果显示重新生成并让你重新设密码,说明挂载路径和原来不一致,立刻停掉查路径,别让它把数据库覆盖了。

三、wg0.conf 逐段注释

这是本环境实际在用的配置文件(密钥已脱敏),每一段为什么这么写标在旁边。

# 服务端接口段
[Interface]
PrivateKey = REDACTED              # 服务端身份,绝不能换;换了 7 台客户端全废
Address = 10.9.0.1/24, fdcc:ad94:bacf:61a4::cafe:1/112
                                    # 隧道内自身地址;/24 决定能发多少客户端
ListenPort = 51820                  # 对外 UDP 端口,客户端 Endpoint 要对齐
MTU = 1420                          # 1500 - 60(IP+UDP+WG) - 20(外层) 的安全值
Table = auto                        # 路由表交给 wg 自己挑,避免和策略路由打架

PreUp =                             # 留空:启动时无需前置动作
PostUp = iptables -t nat -A POSTROUTING -s 10.9.0.0/24 -o ens17 -j MASQUERADE; \
         iptables -A INPUT -p udp -m udp --dport 51820 -j ACCEPT; \
         iptables -A FORWARD -i wg0 -j ACCEPT; \
         iptables -A FORWARD -o wg0 -j ACCEPT;
#   └─ ① 源 NAT:让客户端借服务器公网 IP 上网(唯一含机器相关项的规则)
#   └─ ② 放行 UDP 入站;③④ 允许隧道流量转发

PreDown =
PostDown = # 与 PostUp 严格镜像,把加的规则逐条 -D 删掉

# 每个客户端一个 [Peer],共 7 个
[Peer]
PublicKey = REDACTED               # 客户端公钥
PresharedKey = REDACTED            # 预共享密钥,叠加一层对称加密(抗量子)
AllowedIPs = 10.9.0.3/32, fdcc:ad94:bacf:61a4::cafe:3/128
                                    # 服务端视角:这个 peer 只允许用这个地址
AllowedIPs 在两端的含义不同,最容易搞混

服务端写 /32,是「这个 peer 只能自称这个地址」,起校验作用;客户端写 0.0.0.0/0 是「全量走隧道」(全局代理),写 192.168.1.0/24 则是「只有这段走隧道」(分流回内网)。改之前先想清楚是哪一端。

四、迁移动线总览

换服务器时,七样东西各有各的命运,先分类再动手,就不会漏。

要素换机后动作
wg0.json 数据库直接可用整目录拷贝
server/ 密钥对直接可用整目录拷贝
clients/直接可用整目录拷贝
客户端 IP 分配直接可用不动,10.9.0.2~.8 全部保留
wg0.conf一处不兼容只改 -o 网卡名
VPS 公网 IP变了客户端 conf 的 Endpoint 一行
客户端本地 conf密钥全不用改顶多改 Endpoint 那一行
一次成功的迁移,客户端侧只需改一行

因为服务端私钥、预共享密钥、AllowedIPs 全部延续,7 台设备不用重新导入、不用重新配对。如果迁移后你必须让所有客户端重新下载配置,说明服务端密钥被重建了——那是有问题的迁移,不是正常的。

五、迁移六步 SOP

STEP 1

旧服务器:停写 + 打包

cd /opt
docker compose -f wg-easy/docker-compose.yml down
tar czf wg-easy-migrate-$(date +%F).tar.gz wg-easy/
sha256sum wg-easy-migrate-*.tar.gz > wg-easy.sha256

一定要 down 再打包。容器在运行中时数据库可能处于写入中间态,热的 tar 包恢复后偶尔会缺客户端。

STEP 2

传到新服务器并校验

scp wg-easy-migrate-*.tar.gz wg-easy.sha256 root@<新IP>:/opt/
# 新服务器侧
cd /opt && sha256sum -c wg-easy.sha256
tar xzf wg-easy-migrate-*.tar.gz
ls -la /opt/wg-easy
STEP 3

确认新机器的真实网卡名

ip route | grep default
# default via 203.0.113.1 dev eth0 proto static
#                                  ^^^^ 记下这个
ip -br link
这一步是迁移失败的头号原因

旧配置里写的是 ens17,那是绑定虚拟机插槽编号的命名(systemd 可预测命名)。换机器几乎必然变成别的名字(eth0 / ens3 / enp1s0 都常见)。不改的后果:wg 起来、握手成功、客户端能连上,但上不了网——因为 MASQUERADE 规则挂在一个不存在的网卡上,静默失败。

STEP 4

替换网卡名(两处必须同时改)

cd /opt/wg-easy
cp wg0.conf wg0.conf.bak
sed -i 's/-o ens17/-o eth0/g' wg0.conf

grep -c 'ens17' wg0.conf   # 必须返回 0
grep -c -- '-o eth0' wg0.conf   # 必须返回 2(PostUp + PostDown)

漏改 PostDown 不会立刻出错,但下次停容器时那条旧规则删不掉,反复启停会把 MASQUERADE 叠成好几条,排查时非常迷惑。

STEP 5

核对网段不撞 + 私钥对得上

# 网段冲突检查(有输出才需要处理)
ip addr show | grep -E '10\.9\.|fdcc:'
docker network ls -q | xargs -r docker network inspect 2>/dev/null | grep -E '10\.9\.|fdcc:'

# 私钥一致性:两行输出必须完全相同
grep PrivateKey wg0.conf | awk '{print $3}'
cat /opt/wg-easy/server/private-key

私钥对不上时,wg-easy 会以数据库为准重写 wg0.conf,你 STEP 4 的手改就白做了。所以顺序必须是:先确认私钥一致,再改网卡名;或者改完再复核一次文件没被覆盖。

STEP 6

起容器

cd /opt/wg-easy && docker compose up -d
docker compose logs --tail 40

日志里没有 Permission denied、RTNETLINK、Operation not supported 就算起来。看到 WireGuard is up 一类字样最稳。

六、迁移后验收

四道关卡,逐条过,全绿才算迁完。

#检查命令通过标准
1接口起来了wg show有 interface: wg0,listening port 51820
2NAT 规则挂上iptables -t nat -L POSTROUTING -n -v | grep 10.9有规则且 pkts 会涨
3转发放行iptables -L FORWARD -n -v | grep wg0INPUT/FORWARD 各两条
4客户端在握手wg show 看 latest handshake几十秒内刷新,transfer 双向有量

客户端侧要做的唯一动作

如果公网 IP 变了,本地 conf 改一行即可,不用重新下载整份:

Endpoint = <旧IP>:51820    →    Endpoint = <新IP>:51820

各平台改法:

  • Windows / macOS 客户端:界面里编辑隧道,改 Endpoint 后保存
  • Linux wg-quick:vim /etc/wireguard/wg0.conf 改完 wg-quick down wg0 && wg-quick up wg0
  • 飞牛 / 软路由:Web 界面里改对端地址后重新连接
想让以后换服务器零改动

把 WG_HOST 填成域名而不是 IP,配 DDNS 跟随时公网 IP。这样以后再搬家,客户端一行都不用动。这是本次迁移最值得补的一笔技术债。

七、回滚预案

迁移当天旧服务器不要停机、不要删数据,等新机稳定运行一天以上、7 台设备都切过来再说。出问题时原路退回:

# 新服务器
docker compose -f /opt/wg-easy/docker-compose.yml down

# 旧服务器:恢复打包时的状态
cd /opt && rm -rf wg-easy && tar xzf wg-easy-migrate-<日期>.tar.gz
cd wg-easy && docker compose up -d

# 客户端:Endpoint 改回旧 IP

能这么干脆地回滚,靠的是两件事:服务端私钥没变(所以客户端密钥不用动),旧数据没被覆盖(所以状态完全一致)。

八、迁移高频故障

握手正常,但客户端上不了网

查:iptables -t nat -L POSTROUTING -n -v | grep 10.9

因:PostUp 的 -o 网卡名不对,MASQUERADE 挂空。这是换机后第一高发故障。

修:STEP 3/4 改网卡名,然后必须重载让规则重新执行——docker compose restart wg-easy,只改文件不重启不生效。

容器起来了,但 wg0 接口不存在

查:docker compose logs | grep -iE 'NET_ADMIN|perm|module';lsmod | grep wireguard

因:cap_add 缺 NET_ADMIN,或宿主机没加载 wireguard 模块。

修:补 NET_ADMIN + SYS_MODULE;宿主机 modprobe wireguard。

客户端全部连不上,日志显示重新生成了配置

查:ls -la /opt/wg-easy/wg0.json;docker inspect wg-easy | grep -A3 Mounts

因:挂载路径与旧机不一致,容器没读到数据库,当成全新实例初始化了。

修:立刻 down,把路径改回一致,用备份的 wg0.json 覆盖掉新生成的那份再起。

容器反复重启 / 启动即退出

查:docker compose logs --tail 50 看第一行报错

因(按概率排):① PASSWORD_HASH 里的 $ 没写成 $$,哈希被截断;② host 模式写了 ports: 或 sysctls: 导致 compose 拒绝启动;③ 51820/51821 被宿主机其他进程占了。

修:ss -lunp | grep 51820、ss -ltnp | grep 51821 找占用者;删掉非法字段。

部分客户端能连、部分不能

查:wg show 里逐个 peer 看有没有 latest handshake

因:连不上的那几台本地 Endpoint 还是旧 IP(他们没改,或改漏了)。

修:客户端侧改 Endpoint。服务端不用动——peer 是逐台独立握手的,一部分成功就证明服务端配置正确。

能连但网速很慢 / 大文件卡死

因:MTU。外层再套一层(PPPoE、云服务器overlay、运营商 NAT444)时 1420 仍偏大,大包被静默丢弃。

修:逐步下调测试 1380 → 1360,服务端与客户端同时改。

改了 wg0.conf 但没生效

因:wg-easy 只在启动时渲染这个文件,运行中不会热加载;而且下次启动还会覆盖你的手改。

修:改完 docker compose restart wg-easy。改网卡名这类必要手改,重启后再 grep 一次确认没被覆盖。

一条容易误判的日志

如果你顺手用 SSH 排错,看到 Client: password auth failed / Outbound: Sending DISCONNECT (11)——那是 SSH 客户端密码认证失败后自己断开,跟 WireGuard 毫无关系,别往隧道方向排查。查 sshd_config 的 PasswordAuthentication 和 PermitRootLogin 即可。

九、待办与加固

  • 把 WG_HOST 从 IP 换成域名并配 DDNS —— 下次迁移客户端零改动
  • 管理台 51821 在安全组里限制为仅自己 IP 可访问(当前 INSECURE=true 是免密的,等于公网裸奔)
  • 或改用 PASSWORD_HASH 并设强密码,关掉 INSECURE
  • 写定时备份:0 3 * * * tar czf /backup/wg-$(date +\%F).tar.gz -C /opt wg-easy,保留最近 7 份
  • 安全组只放行 51820/udp 全网开放,其余端口按需收紧
  • 每季度用 wg show 记录各 peer 流量,异常增长排查是否被滥用
  • 本文档的密钥占位处,本地副本可填真值,但不要上传 GitHub 或云盘同步目录

环境基线:wg-easy 15 · Docker host 模式 · 原生 VPS · 隧道 10.9.0.0/24 · 7 客户端。文中所有密钥与公网 IP 均已脱敏,标记为 REDACTED / <占位>。

标注「按通用行为推断」的部分未在目标环境逐条实测,实际以 docker compose logs 输出为准。