WireGuard部署与迁移
WireGuard 部署与运维手册
两个脚本把系统层全部包掉:部署跑一次 bootstrap.sh,之后任何时候跑 ./wg-tidy.sh 看健康度。
本文只讲本环境:wg-easy 15 · Docker host 模式 · 原生 VPS。
wg-easy 15 · host 模式 · 原生 VPS · 51820/udp · 脚本化部署
最短路径:三条命令
- 准备:把
docker-compose.yml、bootstrap.sh、wg-tidy.sh放进/opt/wg-easy/ - 初始化:
chmod +x bootstrap.sh && ./bootstrap.sh—— 模块、转发、防火墙、NAT、开机兜底一次配完 - 起服务:
cd /opt/wg-easy && docker compose up -d && sleep 8 && ./wg-tidy.sh—— 看到FAIL 0即完成
顺序不能反:bootstrap.sh 必须在
docker compose up之前跑,因为它要把防火墙规则先落好,否则 Docker 插进来的链会把它盖掉。
./wg-tidy.sh的./不能省 —— Linux 默认不把当前目录放进PATH,省掉就是command not found。想随处直接敲wg-tidy.sh,建个软链:ln -s /opt/wg-easy/wg-tidy.sh /usr/local/bin/
目录
- 一、文件分工与三个产物
- 1.1 bootstrap.sh
- 1.2 wg-tidy.sh
- 二、部署:bootstrap.sh
- 2.1 放好三个文件
- 2.2 按自己机器改脚本配置区
- 2.3 跑初始化
- 三、docker-compose.yml 逐项说明
- 3.1 写入 docker-compose.yml
- 3.2 逐项对照:含义与改法
- 3.3 存盘、验语法、起服务
- 四、上线验收与客户端接入
- 4.1 跑 wg-tidy.sh,看到 FAIL 0
- 4.2 在管理台建第一个客户端
- 4.3 Linux / macOS 命令行安装
- 4.4 真实验证:看计数,不看状态
- 五、日常运维
- 5.1 常用操作速查
- 5.2 连不上时,按这个顺序查
- 5.3 改完配置必须重启容器
- 六、迁移到新服务器
- 6.1 旧机:停容器后打包
- 6.2 新机:解包、改 compose、跑 bootstrap.sh
- 6.3 起服务,先放一台客户端验证
- 6.4 逐台更新 Endpoint
- 七、回滚预案
- 八、脚本已兜住的十四类问题
- 九、wg-tidy.sh 逐关说明
- 9.1 依赖自检与分组判据
- 9.2 USE_SECURITY_GROUP:防火墙归谁管
- 9.3 --clean 为什么不按行号删
- 9.4 源与产物:哪些文件能改
- 9.5 信数字,不要信文字
- 十、加固清单
一、文件分工与三个产物
整个部署只有三个文件要维护,职责完全不重叠。它们都放在 /opt/wg-easy/,也就是 docker-compose.yml 旁边。
| 文件 | 谁负责 | 什么时候动它 |
|---|---|---|
docker-compose.yml | 容器怎么跑 | 换公网 IP、换网段、升级镜像 |
bootstrap.sh | 宿主机系统层:内核参数、防火墙、NAT、开机兜底 | 新机器跑一次;换网卡名/网段后重跑(幂等) |
wg-tidy.sh | 只读体检 + 可选清理:问内核"规则在不在",不解析文字 | 任何时候,尤其连不上时、升级后、改配置后 |
运行时还会在同目录生成两样东西:wg-easy.db(SQLite,存客户端与服务端私钥)和 wg0.conf(容器渲染出的配置)。这两个不用手工维护,但备份和迁移时是主角。
1.1 bootstrap.sh
新机器一次性初始化 · 幂等,重复跑不会叠加规则 · 每步自校验,失败即中止并指出改哪
| 步骤 | 做什么 | 自检与失败提示 |
|---|---|---|
| 1/6 内核模块 | modprobe wireguard,已加载就跳过 | 判定顺序 /sys/module/wireguard → lsmod → modinfo;都没有才尝试装 wireguard-tools + headers,仍失败提示"OpenVZ/LXC 需宿主机开 TUN 或换 KVM" |
| 2/6 IP 转发 | 写 /etc/sysctl.d/99-wg-easy.conf | 回读 /proc/sys/net/ipv4/ip_forward;只比较有效行,注释差异不算改动 |
| 3/6 网段冲突 | 扫本机地址是否落在 10.9. / fdcc:,排除 wg*、docker*、lo 自身接口 | 冲突时列出接口名让你确认,不自作主张改 |
| 4/6 防火墙 | 默认 USE_SECURITY_GROUP=1:不动 ufw 默认策略,只幂等补 51820/udp、51821/tcp;--admin-ip 才收紧 SSH 与管理台来源;--use-ufw 才交给 ufw 管端口 | 动策略要再传 --apply-policy,且改前打印"现值 / 期望"与本机对外监听端口 |
| 5/6 NAT + FORWARD | 后端跟随系统(iptables -V 判 nft / legacy),同一族命令写 MASQUERADE(-o 自动填主网卡)与两条 FORWARD | 全部 -C 先查再 -A/-I,重复跑不产生重复规则;另一后端也有本网段 NAT 时只提示不删 |
| 6/6 落盘与开机兜底 | rules.v4 先比对内容再写;wg-nat.service 同样比对,变了才 daemon-reload | 落盘后回读校验含本网段与 -i wg0;规则没变时整个第 6 步都是 SKIP |
跑完打印两行汇总——预检:PASS n WARN n FAIL n 与 执行:NEW n UPD n SKIP n FAIL n——再给你下一步该敲的命令。再跑一次应该看到 NEW 0 / UPD 0,否则说明有东西和脚本预期不一致。
1.2 wg-tidy.sh
只读体检 · 不改系统 ·
--clean才动规则,且删空会自动补回 ·--fix只打印
它把"该有的状态"逐条问内核,按组打印;每条 WARN / FAIL 都给四行——实测 / 应为 / 修法 / 后果,编号可回查,不需要你理解 iptables 也能修。
| 命令 | 做什么 | 会不会改系统 |
|---|---|---|
./wg-tidy.sh | 只体检,打印全部检查组 | 不会 |
./wg-tidy.sh --fix | 末尾按编号列出修复命令 | 不会,只打印 |
./wg-tidy.sh --clean | 把重复的 FORWARD wg0 规则收敛到各 2 条 | 会删规则 |
./wg-tidy.sh --report FILE | 同时把去色日志写到文件 | 不会 |
./wg-tidy.sh --quiet | 只打印 WARN / FAIL 与汇总 | 不会 |
./wg-tidy.sh --no-color | 关颜色,用于存文件、贴日志、老终端 | 不会 |
退出码 0 = 没有 FAIL(有 WARN 也算 0),1 = 有 FAIL,2 = 参数错,可以直接挂 cron 当健康探针。
注意|一个容易多此一举的地方:netfilter-persistent
这台机器不需要装它。规则持久化已经由
wg-nat.service(开机幂等补规则)加/etc/iptables/rules.v4(落盘)两层负责,两者bootstrap.sh都配好了。它和
wg-nat.service干的是同一件事,装上只是多一层重复。更麻烦的是:它可能用另一套后端重写rules.v4——nft 与 legacy 两张表互不相通,装上之后你在命令行查到的和实际生效的就不是同一套,排查时会以为规则丢了。同理,
iptables -t nat -L看到空的也不代表没配:先iptables -V确认自己查的是哪一族。
二、部署:bootstrap.sh
2.1 放好三个文件
mkdir -p /opt/wg-easy && cd /opt/wg-easy
# 上传 docker-compose.yml、bootstrap.sh、wg-tidy.sh
chmod +x bootstrap.sh wg-tidy.sh
2.2 按自己机器改脚本配置区
两个脚本开头都有配置区,默认值对应本文环境,不符就改:
# bootstrap.sh 与 wg-tidy.sh 都要改,两处保持一致
WG_SUBNET="10.9.0.0/24" # 隧道网段,须与 wg0.conf 一致
WG_PORT=51820 # WireGuard UDP 端口
UI_PORT=51821 # 管理台 TCP 端口
# 只有 bootstrap.sh 有这一行
INSTALL_DIR="/opt/wg-easy" # compose 与数据目录
# 两个脚本都有,默认已经是 1
USE_SECURITY_GROUP=1 # 1=端口放行交给云安全组,脚本不碰 ufw 默认策略(推荐)
# 0=由 ufw 管,还要再传 --use-ufw
wg-tidy.sh 的 INSTALL_DIR 不用填 —— 它自动取脚本所在目录(readlink -f "$0"),整个 /opt/wg-easy 挪到别的路径也不用改配置。
注意|两个脚本的网段与端口必须一致
wg-tidy.sh是拿这几个值去比对实际状态的。bootstrap.sh 里改了网段、wg-tidy.sh 没改,它会把正常的规则报成缺失。改一处就同步改另一处。
2.3 跑初始化
./bootstrap.sh
正常结束长这样(节选):
预检通过:PASS 12 / WARN 0 / FAIL 0
────────────────────────────────────────────
执行
2/6 IP 转发
[SKIP] /etc/sysctl.d/99-wg-easy.conf 内容已是期望值
验证:ip_forward=1 ipv6_forwarding=1
5/6 NAT 与 FORWARD(后端 nft)
[NEW ] 写入 MASQUERADE 10.9.0.0/24 → ens17
验证:NAT 回读在位
────────────────────────────────────────────
汇总
预检:PASS 12 WARN 0 FAIL 0
执行:NEW 3 UPD 1 SKIP 12 FAIL 0
三件事照抄就行:每条 [NEW] / [UPD] 后面跟的"验证"必须出现,没出现就是那一步没真的生效;预检有 FAIL 时脚本直接停下,不会带着半成品往下走;修好那一项重跑一遍,已配好的项自动变 SKIP。
脚本在中途某步失败会直接中止,不会带着半成品状态往下走;修好那一项后重新跑一遍即可,已配好的项会跳过。
三、docker-compose.yml 逐项说明
3.1 写入 docker-compose.yml
cd /opt/wg-easy
nano docker-compose.yml
文件内容如下,每个字段上方都有注释:
services:
wg-easy:
# 镜像:锁死大版本 15,不用 latest,避免升级时被静默换掉
image: ghcr.io/wg-easy/wg-easy:15
# 容器名:固定为 wg-easy,`docker exec wg-easy wg show` 靠它定位
container_name: wg-easy
# 重启策略:宿主或 Docker 重启后自动拉起;手动 stop 则不再拉起
restart: unless-stopped
# 网络模式:host 直用宿主机网络,省掉 DNAT 一跳
# 注意:host 模式下不能再写 ports: 与 sysctls:,写了启动直接报错
network_mode: host
# 能力:允许容器操作 iptables(host 下非必需,保留不影响)
cap_add:
- NET_ADMIN
volumes:
# 配置落盘:左侧目录必须与 bootstrap.sh 的 INSTALL_DIR 保持一致
- /opt/wg-easy:/etc/wireguard
# 挂入宿主内核模块目录(只读),容器里的 wg 命令才可用
- /lib/modules:/lib/modules:ro
environment:
# 【必改】连接地址:公网 IP 或域名;用域名则换 IP 免重导
- WG_HOST=填你的公网IP或域名
# WireGuard 监听端口:改动后同步安全组放行与 wg-tidy.sh 的 WG_PORT
- WG_PORT=51820
# 客户端地址模板:.1 留给服务端,x 是自动分配占位符,不要改
- WG_DEFAULT_ADDRESS=10.9.0.x
# 走隧道的流量范围:全隧道填 0.0.0.0/0;只走内网填内网网段
- WG_ALLOWED_IPS=0.0.0.0/0
# NAT 保活间隔(秒):移动网络尤其需要,一般不动
- WG_PERSISTENT_KEEPALIVE=25
# 下发的 DNS:不写可能导致客户端解析不了域名
- WG_DEFAULT_DNS=1.1.1.1
# MTU:偏大时大包会静默丢失(能 ping、网页卡死),1360 较稳
- WG_MTU=1360
# 管理台端口:改动后同步安全组放行
- UI_PORT=51821
# 【必改】初始化库:首装 true;迁移必须 false,否则客户端被清空
- INIT_ENABLED=true
# 【必改】管理台登录密码:不设会放开无密码访问
- PASSWORD=改掉它
# 日志时区:想看本地时间改成 Asia/Shanghai
- TZ=UTC
这段里只有 WG_HOST、PASSWORD、INIT_ENABLED 三处需要动,下表逐项说明;其余保持原样。
3.2 逐项对照:含义与改法
| 项 | 作用 | 什么时候动它 |
|---|---|---|
image | 锁死大版本 15,不用 latest | 升级镜像时改版本号 |
container_name | 固定容器名,docker exec 靠它定位 | 基本不动 |
restart | Docker 重启后自动拉起 | 不动 |
network_mode: host | 直接用宿主机网络,省掉 DNAT 那一跳 | 不动;host 下不能写 ports: / sysctls: |
cap_add: NET_ADMIN | 给容器改 iptables 的权限 | 不动;模块由宿主加载,加不加都一样 |
volumes 第一条 | 配置落盘,左侧须与 INSTALL_DIR 一致 | 换安装目录时改左边 |
volumes 第二条 | 挂入宿主机内核模块目录(只读),容器里的 wg 命令才能用 | 不动 |
WG_HOST | 客户端连进来的地址 | 必改:公网 IP 或域名;用域名则换 IP 免重导 |
WG_PORT | WireGuard 监听端口 | 改了要同步改安全组放行、wg-tidy.sh 里的 WG_PORT |
WG_DEFAULT_ADDRESS | 客户端地址模板,.1 留给服务端,x 自动分配 | 换网段时改。x 是占位符,不要动 |
WG_ALLOWED_IPS | 走隧道的流量范围 | 全隧道用 0.0.0.0/0;只走内网就填内网网段 |
WG_PERSISTENT_KEEPALIVE | NAT 保活间隔(秒) | 手机等移动设备尤其需要,一般不动 |
WG_DEFAULT_DNS | 客户端下发的 DNS | 不写的话客户端可能解析不了域名 |
UI_PORT | 管理台端口 | 改了要同步改安全组放行 |
INIT_ENABLED | 是否初始化数据库 | 必改:首装 true;迁移必须 false,否则客户端被清空 |
PASSWORD | 管理台登录密码 | 必改:不设等于无密码访问 |
TZ | 日志时间口径 | 想看本地时间就改 Asia/Shanghai |
3.3 存盘、验语法、起服务
docker compose config # 只验语法并回显生效配置,不报错再往下
docker compose up -d # 环境变量是启动时读的,改完文件必须重启才生效
起完之后直接进入第四章「上线验收」,跑 wg-tidy.sh。
四、上线验收与客户端接入
4.1 跑 wg-tidy.sh,看到 FAIL 0
./wg-tidy.sh
期望结尾(节选):
结论:可用,2 项加固建议(无阻断项)
...
合计:PASS 40 WARN 2 FAIL 0 SKIP 3
可加固(按安全优先排序)
1) [16] NAT 生效后端
2) [19] ufw 叠加
开头先说结论,再看明细。计数分四类,SKIP 单列,不进风险统计——它的意思是"环境不具备,这项没判",不等于通过:
| 计数 | 含义 | 要不要管 |
|---|---|---|
PASS | 现状符合预期 | 不管 |
WARN | 能用,但有风险 | 记下来,方便时处理 |
FAIL | 已断,或重启必坏 | 必须处理,会出现在"最该先处理"列表 |
SKIP | 环境不具备,本项未判 | 先补环境,再复跑 |
有 FAIL 就加 --fix,它按编号把修复命令逐条列出来:
./wg-tidy.sh --fix
4.2 在管理台建第一个客户端
浏览器打开 http://<公网IP>:51821,登录后点新建。取配置有两条路,随便挑:直接扫二维码,或 Download 下载 .conf 再导入。
① Windows
装官方 WireGuard for Windows → 导入隧道 → 从文件导入 .conf → 点激活,状态变绿即通。
② macOS
App Store 装官方 WireGuard(走网络扩展,不用碰内核)→ 导入隧道 → 从文件导入 .conf。首次要在「系统设置 → 通用」里允许它添加 VPN 配置,跳过这一步会一直连不上。
③ Linux
装 wireguard-tools,把 .conf 落到 /etc/wireguard/,开机自连交给 systemd 单元。具体命令见 4.3 小节。
④ Android
官方版,扫描和导入都支持。+ → 从二维码扫描 或 + → 从文件导入隧道(选 .conf)。提示"配置未加密"是正常的,确认即可。电池优化里设成"无限制",否则锁屏会被掐断。
⑤ iOS
+ → 从二维码创建 直接扫;或从微信 / QQ / 邮件收到 .conf 后用 WireGuard 打开,允许添加 VPN 配置。
4.3 Linux / macOS 命令行安装
两台都是同一套 wireguard-tools,wg-quick 用法完全一致,区别只有配置文件路径:Linux 是 /etc/wireguard/,macOS 是 /usr/local/etc/wireguard/(brew install wireguard-tools 之后就有了)。
# ① 落位:权限必须 600,wg-quick 会因为组别权限太宽而拒绝加载
sudo install -m 600 -o root -g root ~/Downloads/xxx.conf /etc/wireguard/wg0.conf
# ② 起隧道(传的是隧道名,不带 .conf 后缀)
sudo wg-quick up wg0
# ③ 开机自连:单元名 wg-quick@<隧道名>,必须与文件名一致
sudo systemctl enable --now wg-quick@wg0
enable --now 一条同时完成「现在连」和「开机自连」,up 与 enable 不用分两步。macOS 没有 systemd,用 brew services 或登录项代替第 ③ 步。
四件容易踩的事
- 落盘用
install -m 600而不是cp——cp不携带权限,下载的.conf多是 644,组别权限太宽wg-quick会拒绝加载。 - 多台客户端别都叫
wg0—— 一台一个名字(wg-laptop、wg-home),文件名就是隧道名,重名互相覆盖。 - 状态
active (exited)且无常驻进程是正常的 —— 单元是oneshot+RemainAfterExit,隧道跑在内核里,不需要守护进程。 - 改过
Address/DNS/PostUp必须restart才生效;只增删 peer 可以wg syncconf wg0 <(wg-quick strip wg0),不断现有连接。
排障看 journalctl -u wg-quick@wg0 -b,比 wg-quick up 的终端输出完整。不想装成系统服务就手动 sudo wg-quick up/down wg0,两条路别同时用 —— 手工起的那条不在 systemd 登记里,systemctl stop 管不到。
4.4 真实验证:看计数,不看状态
# 服务器端:看这个 peer 的 transfer 双向都在涨
docker exec wg-easy wg show
# 客户端:DNS 与外网分别验
nslookup google.com 223.5.5.5
curl.exe -I https://www.google.com
latest handshake 在几十秒内刷新、transfer 收发都有量,才算真的通。只看"已连接"是不够的——握手走 UDP 入站,即使 NAT 挂了它也能成功。
五、日常运维
5.1 常用操作速查
| 要做的事 | 怎么做 | 注意 |
|---|---|---|
| 改管理台密码 | 管理台 Settings 里改 | 改完用新标签页验证一次再关 |
| 加 / 删客户端 | 管理台点新建 / 删除 | 不要手改 wg0.conf,会被覆盖 |
| 改网段 / 加第二个网段 | 管理台改,同时改两个脚本配置区的 WG_SUBNET,再重跑 bootstrap.sh | 地址池别和内网、Docker 网段重叠 |
| 升级镜像 | docker compose pull && docker compose up -d | 升完跑一次 ./wg-tidy.sh;INIT_ENABLED 保持 false |
| 备份 | tar czf /backup/wg-$(date +\%F).tar.gz -C /opt wg-easy | 停容器再备;含私钥,别往云盘/仓库同步目录放 |
| 看日志 | docker compose logs --tail 50 -f | 启动阶段最有用,能看出是否复用了老库 |
| 定期体检 | ./wg-tidy.sh | 升级后、改配置后、感觉变慢时各跑一次 |
| 收敛重复规则 | ./wg-tidy.sh --clean | 手工补过规则、规则叠加后想收敛时跑一次 |
5.2 连不上时,按这个顺序查
- 先跑体检:
./wg-tidy.sh。组 5 若显示“有 peer 但全部没握手”,基本是客户端Endpoint还指着旧 IP,或51820/udp没放行。 - 看流量有没有真的走 NAT:
docker exec wg-easy wg show。握手在刷新、但transfer双向不涨,说明包没进 NAT,回头查组 3 的命中包数。 - 管理台打不开:先看安全组里
51821/tcp的来源是不是你当前的出口 IP(家宽会变);若用--admin-ip收紧了 ufw,那边同样要跟着改。 - 能连上但域名全超时:
WG_DEFAULT_DNS指向了隧道内部地址。改成公网可用 DNS,重启容器再生效。
四条都过不了,再回第九章逐组核对判据;不要先去手改 wg0.conf。
5.3 改完配置必须重启容器
wg-easy 只在启动时渲染 wg0.conf 并执行里面的 PostUp,运行中既不热加载也不监视文件。所以手改了任何东西都要 docker compose restart wg-easy,改完再 grep 一次确认没被覆盖回去。
六、迁移到新服务器
因为系统层已经脚本化,迁移比首次部署还简单:搬数据库 + compose 改两处 + 新机跑一次 bootstrap.sh。实际要动的就下面这几样:
| 文件 | 换机后 | 动作 |
|---|---|---|
wg-easy.db | 直接可用 | 客户端与服务端私钥全在这个 SQLite 库里;停容器后再拷贝 |
docker-compose.yml | 改两处 | WG_HOST 换新地址;INIT_ENABLED 保持 false |
wg0.conf | 不必带 | 容器启动时按库和环境变量重新渲染,手工带过去反而会被覆盖 |
bootstrap.sh / wg-tidy.sh | 直接复用 | 和 compose 一起放回 /opt/wg-easy/ |
| 系统层(转发/NAT/防火墙) | 脚本重做 | 新机跑 ./bootstrap.sh,网卡名自动探测 |
客户端的 .conf 不用重发:私钥仍在库里,只改 Endpoint 一行即可(用了域名则连这行都不用改)。
6.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 出来的包偶尔会缺客户端。这里直接打包整个 /opt/wg-easy,不必逐个挑文件,库、compose、脚本一次带全。
6.2 新机:解包、改 compose、跑 bootstrap.sh
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
cd /opt/wg-easy
# 把 bootstrap.sh、wg-tidy.sh 也放进来(数据包里可能已有)
# 改 compose 两处:
# WG_HOST=<新IP 或域名>
# INIT_ENABLED=false ← 迁移必须 false
sudo ./bootstrap.sh --dry-run # 先看它打算改什么,不改系统
sudo ./bootstrap.sh
注意|网卡名不用再手改了
bootstrap.sh第 5 步用ip route get 1.1.1.1探测当前主网卡并写进 MASQUERADE,旧机的ens17换成新机的eth0/ens3是自动完成的。剩下要确认wg0.conf里PostUp那条——它由容器渲染,起容器后wg-tidy.sh组 8 会比对-o与主网卡,不一致直接点名。
关键|迁移后必须跑组 8,它专治"搬到新机就上不了网"
三种断法都在这组里现形:
PostUp里还是旧网卡名(能握手、上不了网)、conf的 peer 数与运行态不一致(少了客户端)、WG_HOST还指着旧 IP(客户端连不上)。还有一处更隐蔽的:新机常是 nft、容器内仍是 legacy。这时
bootstrap.sh写的规则落在宿主那族,容器启动又往自己那族写一遍,rules.v4只带走了其中一套。登录后第一件事跑./wg-tidy.sh看组 3——若报"本族 0 包、另一族有包",就说明两套后端在并存,先按它给的修法统一,再谈放客户端。
注意|后端怎么统一:宿主跟着容器走
容器内用哪族由镜像决定(wg-easy 15 就是 legacy),宿主可能是 nft。两族规则互不相通,症状很典型:规则都在、命令行看着对,但包一个都不命中。
先比对两边:
sudo iptables -V docker exec wg-easy iptables -V不同族就把宿主切到容器那族:
sudo update-alternatives --set iptables /usr/sbin/iptables-legacy sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy sudo systemctl restart docker # 必须:旧容器的端口规则还在旧族,不重建就不通 sudo ./bootstrap.sh # 按新族重写 NAT 与 rules.v4 ./wg-tidy.sh # 组 3 应显示"本族有包"两个容易漏的点:
iptables-save/iptables-restore在 Ubuntu 不由 alternatives 管,切完用sudo iptables-save | head -2验一下,输出里带# Warning: iptables-legacy tables present就说明它还在读另一族;另外之后删规则一律带显式前缀(iptables-legacy或iptables-nft),裸iptables会随 alternatives 变脸——用它删"nft 那条",实际删掉的是 legacy 自己。
6.3 起服务,先放一台客户端验证
docker compose up -d
docker compose logs --tail 40 # 应显示复用已有配置,不是重新初始化
./wg-tidy.sh # 重点看组 3 与组 8,FAIL 0 再往下走
先只改一台客户端的 Endpoint 试通,再推其余设备。全部一起放的话,出问题时很难分辨是服务端没改对、还是某一台自己没改。
6.4 逐台更新 Endpoint
Endpoint = <旧IP>:51820 → Endpoint = <新IP>:51820
PC 端在客户端界面改完保存;手机端重新导入一次该文件。**密钥、AllowedIPs、DNS 一律不动。**若 WG_HOST 填的是域名,这一步整个省掉。
注意|怎么判断迁移是干净的
客户端只需改一行 Endpoint 就是正确迁移。如果迁移后你必须让所有设备重新下载整份配置,说明服务端密钥被重建了 —— 那意味着老库没被读起来,回去查
INIT_ENABLED和挂载路径。
七、回滚预案
迁移当天旧机不要停机、不要删数据。等新机稳定跑满一天、设备都切过来,再考虑回收。要退回时原路返回:
# 新机:停掉
docker compose -f /opt/wg-easy/docker-compose.yml down
# 旧机:先确认备份包完整,再恢复;rm -rf 会删掉现有目录
cd /opt && sha256sum -c wg-easy.sha256 && rm -rf wg-easy && tar xzf wg-easy-migrate-<日期>.tar.gz
cd wg-easy && ./bootstrap.sh && docker compose up -d
docker compose logs --tail 20 && ./wg-tidy.sh
# 客户端:Endpoint 改回旧 IP
能这么干脆地退回来,靠两件事:服务端私钥没变(就在 wg-easy.db 里,随库一起拷回)、旧数据没被覆盖(状态完全一致)。
八、脚本已兜住的十四类问题
下面这些不需要你判断、也不需要你检查 —— bootstrap.sh 已经把它们配成正确状态,wg-tidy.sh 负责在它们偏离时报出来。列出来只是让你知道脚本在替你看着什么。
| 风险 | 不处理会怎样 | 谁兜住 |
|---|---|---|
| FORWARD 链 policy 为 DROP | 包被解密后即被内核丢弃,握手成功、有流量计数、但什么都打不开 | bootstrap.sh 第 4 步设 ACCEPT;wg-tidy.sh 组 3 验(查 policy + -C 问内核) |
缺 FORWARD -i/-o wg0 ACCEPT | 同上,且更隐蔽(policy 是 ACCEPT 也会丢) | bootstrap.sh 第 5 步;wg-tidy.sh 组 3 |
| 反复手工补同一条 FORWARD 规则 | 规则叠到 8 条。功能上无害(包匹配第一条就走),但排障时规则表一片混乱,你会以为链路有问题 | ./wg-tidy.sh --clean 收敛到各 2 条,删空自动补回 |
| NAT 规则挂在错误网卡名上 | 换机后静默失败,握手照常成功 | bootstrap.sh 自动探测主网卡;wg-tidy.sh 组 3 与组 8 都比对 -o 与主网卡 |
| 规则写在没生效的那套后端 | 命令行看到规则在、包里却一个都不命中;换机时备份又只带走一套 | wg-tidy.sh 组 3 同时读 nft 与 legacy 的命中数,指出"哪一族在真正承载流量",并提示统一 |
把 wg0.conf 当源文件手改 | 容器下次启动被覆盖,改动静默丢失,你会以为改了其实没改 | 9.4 节点名它是渲染产物;要改就改 compose 环境变量 |
想核对 peer 数/私钥去解析 wg-easy.db | SQLite 表结构随版本变,字段含义不固定,容易读错 | 一律以 wg show 为准;库里只做 integrity_check,不解析字段 |
ip_forward 没开或被别的组件改回 0 | 转发整条断掉,重启后时好时坏 | bootstrap.sh 第 2 步回读 /proc 校验;wg-tidy.sh 组 2 |
| 规则重启后丢失 | 每次重启都要人工补一遍 | wg-nat.service 幂等补规则 + rules.v4 落盘;wg-tidy.sh 组 6 验(list-unit-files 精确匹配,不用 is-enabled) |
rules.v4 里没有本网段 | 重启后规则补不回来,表现为"连得上但上不了网" | bootstrap.sh 用当前后端的 save > /etc/iptables/rules.v4;wg-tidy.sh 组 6 报出来 |
| 管理台 51821 对全网开放 | 被扫描器认出指纹后撞密码 | 默认走安全组限来源;要收紧 SSH 与管理台就传 --admin-ip,wg-tidy.sh 组 3 按 USE_SECURITY_GROUP 分支提示 |
客户端 DNS 指向 10.9.0.1 | 连上了但所有域名解析超时 | compose 里 WG_DEFAULT_DNS 写死可用 DNS |
| MTU 偏大导致大包静默丢失 | 能 ping、能握手,网页和下载卡死 | compose 里 WG_MTU=1360 |
| 脚本跑到一半失败留下半成品 | 系统处于说不清的中间态 | 每步自校验,失败即中止并指出改哪一项;预检有 FAIL 时根本不进执行阶段 |
九、wg-tidy.sh 逐组说明
8 组顺序跑完,不因某一项失败而中途退出 —— 诊断脚本必须把全部项跑完,你才看得到全貌,所以开头刻意没开 set -e。
9.1 依赖自检与分组判据
iptables / iptables-legacy
规则查询与落盘。用哪一族跟着系统走:iptables -V 里带 nf_tables 就是 nft,带 legacy 就是 legacy,脚本把 iptables / iptables-save 自动换到同族前缀。
但宿主与容器可能不是同一族(容器常是 legacy、宿主是 nft)。只看一族得出的"全部通过"没有意义,所以组 3 会同时读两族的命中数,告诉你哪一族在真正承载流量。
ARM 精简镜像常见缺口
很多 arm64 模板只装 nftables。补法:apt install -y iptables wireguard-tools,脚本会把缺的逐个报出来。
ss / awk / readlink
端口监听与文本处理。readlink -f 在 busybox 上缺失时自动退回 dirname "$0",不影响使用。
判据总原则
全程不解析 iptables -L 的文字列位:在不在问 -C,计数读 -S 原文。这是它不误报的根本原因,也是 9.2 那次踩坑换来的。
| 组 | 查什么(判据) | 判定含义 |
|---|---|---|
| 1 系统与依赖 | uid;发行版与架构;必需命令是否齐;iptables -V 判后端;docker daemon;compose 能否解析 | 缺命令是 FAIL(后面几组都做不下去)。后端是什么不算错,只决定查哪一族 |
| 2 内核与转发 | /sys/module/wireguard → lsmod → modinfo 三级判;回读 /proc 里两个 forward | builtin 内核不出现在 lsmod 属正常。forward 不是 1 才 FAIL |
| 3 防火墙与 NAT | -C 问规则在不在;-S 取条数、-o 取出口;两族各取命中包数;ufw status | 组里最硬的是命中包数与"哪一族在承载"。规则在、本族 0 包 = 写进了没生效的那套后端 |
| 4 容器与数据 | compose 解析端口/密码/INIT;库文件大小属主;integrity_check;wg0.conf 是否存在 | PASSWORD 为空不是问题:v15 密码存库,首次在管理台注册。库只验完整性与属主,不解析字段 |
| 5 接口与客户端 | wg show 取监听端口、peer 数、握手、allowed_ips 去重 | 全部不握手 = Endpoint 指错或 51820 不通;部分不握手多为备用设备。wg 没装则整组跳过 |
| 6 持久化 | list-unit-files 精确匹配;rules.v4 grep 网段与 -i wg0;unit 里写的网卡名 | 缺落盘或缺兜底 = 重启后可能丢规则 |
| 7 时间与资源 | 时间同步状态;磁盘占用;容器近若干行日志的关键字 | 日志只看关键字,不做语义判断,别把它当结论 |
| 8 迁移一致性 | conf 里 -o vs 主网卡;conf 的 peer 数 vs 运行态;WG_HOST 是否指向本机;conf 与库的时间 | 换机后最常断的三处就在这里:网卡名、peer 数、WG_HOST |
9.2 USE_SECURITY_GROUP:防火墙归谁管
注意|默认就按安全组判断
脚本分不清"你没防火墙"和"你的防火墙在云控制台",所以默认按安全组处理:
USE_SECURITY_GROUP=1,不碰 ufw 默认策略,只提示你去控制台确认下方三条入站规则。这也是 bootstrap.sh 的默认行为——它不会替你改ufw default deny incoming。想让 ufw 接管端口,就把配置区改
0并给bootstrap.sh传--use-ufw;真要改默认策略还得再传--apply-policy,改之前它会打印现值、期望和本机对外监听端口。这一步别省:策略一改,没写进清单的端口立刻失联(8008 那种面板端口最容易中招)。万一两套都在跑,选一个关掉,别留着:
sudo ufw disable(前提是安全组三条齐,之后只改一处),或反过来把配置区改0交给 ufw。并存的代价不是安全,而是改端口要改两处,漏一处就是一次失联。改完先
curl -s ifconfig.me核对一遍 —— 家宽 IP 会变,掉线时连不上管理台,先查是不是 IP 换了。为什么推荐安全组而不是 ufw:安全组改错在控制台一点就回滚;ufw 把自己关在外面只能找服务商开 VNC 救。两者功能重叠,没必要都开;真都开了,改端口时两处都要改,脚本会额外提示这一点。
# 安全组应当只有这三条入站
51820/udp 来源 0.0.0.0/0 # VPN 必须全网开放
51821/tcp 来源 <你的公网IP>/32 # 管理台,只给你自己
22/tcp 来源 <你的公网IP>/32 # SSH 同理
9.3 --clean 为什么不按行号删
按行号删有个经典坑:删掉第 3 行后,原来的第 4 行就变成第 3 行,循环一跑就删错。所以 --clean 按规则内容删(iptables -D FORWARD -i wg0 -j ACCEPT),并用 count_fwd() 每轮重新数,删到各剩 2 条就停(PostUp 一条 + 兜底服务一条)。
还带三重保险:删除失败立刻 break 不死循环;计数器上限 20 轮;任何方向被删到 0 条立刻自动补回并报 FAIL —— 绝不留下断网的窗口。所以跑两次、跑十次结果都一样。
它也管 NAT。容器的 wg-quick up 用 -A 追加一条 MASQUERADE,wg-nat.service 开机又补一条,所以容器每重启一次 NAT 就多一条。--clean 会把它们收敛到 1 条,删空同样自动补回。
9.4 源与产物:哪些文件能改
注意|能改 / 只能间接改 / 不能改
docker-compose.yml、bootstrap.sh、wg-tidy.sh是能改的(改完记得把两个脚本的网段端口配置区保持一致);wg-easy.db是唯一数据源,客户端和私钥都在库里,只能经管理台间接改;wg0.conf是渲染产物,每次启动都会覆盖,文件头那句Do not edit this file directly是字面意思。迁移改网卡名是唯一需要手改
wg0.conf的场景,且必须在容器起来之前改。也别去猜库结构:
wg-easy.db是 SQLite,表结构随版本变 —— 想核对 peer 数或私钥,直接看wg show。
9.5 信数字,不要信文字
关键|整章最该记住的一句
整章最该记住的一句话:组 3 的 NAT 命中包数,比"规则在不在"可靠得多。规则在但命中 0,说明流量根本没到;命中在涨,说明链路就是通的 —— 这时候任何脚本报 FAIL,都该先怀疑脚本而不是配置。
同理,手机/电脑实测能上网,本身就是最强的验收结论,优先级高于任何脚本输出。
十、加固清单
- 管理台
51821只放行自己的 IP(bootstrap.sh 已自动做;换网络环境后要更新安全组或 ufw 里那一条) - 管理台必须设置密码 —— 不设等于无密码,51821 暴露的是登录页,而库里存着全部客户端私钥,这是唯一还能被人直接摸进去的口子
- 云安全组只放行
51820/udp全网开放,其余端口按需收紧 - 写定时备份:
0 3 * * * tar czf /backup/wg-$(date +\%F).tar.gz -C /opt wg-easy,保留最近 7 份 - 备份含私钥,不要放云盘同步目录或 Git 仓库
- 每季度看一次各 peer 的
transfer(wg show wg0 transfer,或./wg-tidy.sh第 4 关会逐个列出),异常增长排查是否被滥用 - 把
./wg-tidy.sh挂 cron 每周跑一次,退出码非 0 就收邮件 —— 它只读不改,挂上去没有副作用 - 升级前先备份、升级后跑
./wg-tidy.sh;INIT_ENABLED长期保持false
环境基线:wg-easy 15 · Docker host 模式 · 原生 VPS · 隧道 10.9.0.0/24 · 管理台密码登录。文中 IP 与密钥均为占位。
配套文件:docker-compose.yml(第三章)、bootstrap.sh(系统层初始化,幂等)、wg-tidy.sh(只读体检,--clean 收敛重复规则、--fix 打印修复命令)。三个文件都放 /opt/wg-easy/;bootstrap.sh 与 wg-tidy.sh 的网段、端口配置区必须保持一致,INSTALL_DIR 只有 bootstrap.sh 需要填。
兼容性:wg-tidy.sh 只用 POSIX shell 语法 + coreutils,无 bash 4+ 特性、无 GNU 扩展,已在 Debian 11/12/13 · amd64/arm64 上核对;iptables 后端为 nft 或 legacy 均可。readlink -f 缺失的 busybox 环境会自动退回 dirname "$0"。
判据口径:查规则在不在一律用 iptables -C(返回码即答案),计数读 iptables -S 原文,不解析 iptables -L -v 的文字列位 —— Docker 会往 FORWARD 插 DOCKER-USER 等跳转链,列位会漂。
口径:命令与路径对应本文环境实际取值;换机替换网段、端口、目录三处即可。wg-easy 各小版本日志措辞略有差异,以 docker compose logs 实际输出为准。