WireGuard 部署与迁移
WireGuard 部署与迁移笔记
从零部署 → 日常运行 → 整站搬家到新服务器,一条主线走完。
一、环境基线与文件分工
先对齐现状,后面所有操作都以此为准。
| 项 | 本环境取值 |
|---|---|
| 部署方式 | 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 模式)
装载内核模块、开转发
# 立即生效
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 --systemhost 模式下容器直接用宿主机内核,没有 sysctls: 这一项可写,写了 compose 会报错。所以必须在宿主机上开,这也是和桥接模式最大的区别。
写 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: 无效,不要写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 少一类问题,排错时命令都在宿主机上直接敲。
起容器并确认复用而非重建
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 只允许用这个地址服务端写 /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
旧服务器:停写 + 打包
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 包恢复后偶尔会缺客户端。
传到新服务器并校验
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确认新机器的真实网卡名
ip route | grep default
# default via 203.0.113.1 dev eth0 proto static
# ^^^^ 记下这个
ip -br link旧配置里写的是 ens17,那是绑定虚拟机插槽编号的命名(systemd 可预测命名)。换机器几乎必然变成别的名字(eth0 / ens3 / enp1s0 都常见)。不改的后果:wg 起来、握手成功、客户端能连上,但上不了网——因为 MASQUERADE 规则挂在一个不存在的网卡上,静默失败。
替换网卡名(两处必须同时改)
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 叠成好几条,排查时非常迷惑。
核对网段不撞 + 私钥对得上
# 网段冲突检查(有输出才需要处理)
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 的手改就白做了。所以顺序必须是:先确认私钥一致,再改网卡名;或者改完再复核一次文件没被覆盖。
起容器
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 |
| 2 | NAT 规则挂上 | iptables -t nat -L POSTROUTING -n -v | grep 10.9 | 有规则且 pkts 会涨 |
| 3 | 转发放行 | iptables -L FORWARD -n -v | grep wg0 | INPUT/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,只改文件不重启不生效。
查: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,服务端与客户端同时改。
因: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 输出为准。