WireGuard部署与迁移

蓝色 0 阅读 内网穿透效率工具

WireGuard 部署与运维手册

两个脚本把系统层全部包掉:部署跑一次 bootstrap.sh,之后任何时候跑 ./wg-tidy.sh 看健康度。

本文只讲本环境:wg-easy 15 · Docker host 模式 · 原生 VPS。

wg-easy 15 · host 模式 · 原生 VPS · 51820/udp · 脚本化部署

最短路径:三条命令

  1. 准备:把 docker-compose.yml、bootstrap.sh、wg-tidy.sh 放进 /opt/wg-easy/
  2. 初始化:chmod +x bootstrap.sh && ./bootstrap.sh —— 模块、转发、防火墙、NAT、开机兜底一次配完
  3. 起服务: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 靠它定位基本不动
restartDocker 重启后自动拉起不动
network_mode: host直接用宿主机网络,省掉 DNAT 那一跳不动;host 下不能写 ports: / sysctls:
cap_add: NET_ADMIN给容器改 iptables 的权限不动;模块由宿主加载,加不加都一样
volumes 第一条配置落盘,左侧须与 INSTALL_DIR 一致换安装目录时改左边
volumes 第二条挂入宿主机内核模块目录(只读),容器里的 wg 命令才能用不动
WG_HOST客户端连进来的地址必改:公网 IP 或域名;用域名则换 IP 免重导
WG_PORTWireGuard 监听端口改了要同步改安全组放行、wg-tidy.sh 里的 WG_PORT
WG_DEFAULT_ADDRESS客户端地址模板,.1 留给服务端,x 自动分配换网段时改。x 是占位符,不要动
WG_ALLOWED_IPS走隧道的流量范围全隧道用 0.0.0.0/0;只走内网就填内网网段
WG_PERSISTENT_KEEPALIVENAT 保活间隔(秒)手机等移动设备尤其需要,一般不动
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 连不上时,按这个顺序查

  1. 先跑体检:./wg-tidy.sh。组 5 若显示“有 peer 但全部没握手”,基本是客户端 Endpoint 还指着旧 IP,或 51820/udp 没放行。
  2. 看流量有没有真的走 NAT:docker exec wg-easy wg show。握手在刷新、但 transfer 双向不涨,说明包没进 NAT,回头查组 3 的命中包数。
  3. 管理台打不开:先看安全组里 51821/tcp 的来源是不是你当前的出口 IP(家宽会变);若用 --admin-ip 收紧了 ufw,那边同样要跟着改。
  4. 能连上但域名全超时: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.dbSQLite 表结构随版本变,字段含义不固定,容易读错一律以 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,脚本会把缺的逐个报出来。

端口监听与文本处理。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 里两个 forwardbuiltin 内核不出现在 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 实际输出为准。