WireGuard 常用 CLI 命令与工具详解

目标：系统梳理 WireGuard 两把命令行工具 wg 与 wg-quick 的常用子命令，逐条给出命令示例与真实回显，帮助快速完成密钥管理、接口配置与运行状态检查，已在 WireGuard Tools v1.0.20210914 实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
WireGuard 用户态工具：wireguard-tools 1.0.20210914-1ubuntu2
核心工具版本路径：/usr/bin/wg、/usr/bin/wg-quick
示例接口：wg0；隧道网段 10.99.0.0/24；服务器 10.99.0.1/24

$ wg --version
wireguard-tools v1.0.20210914 - https://git.zx2c4.com/wireguard-tools/

二、工具概览

工具	内置来源	职责	典型用途
`wg`	wireguard-tools	纯内核接口配置/查询（不含链路管理）	生成密钥、增删对端、查询状态/握手/流量
`wg-quick`	wireguard-tools	高层封装脚本（含建网卡/配IP/路由/脚本钩子）	一键 `up`/`down` 接口

💡 说明：wg 只管「WireGuard 设备的加密参数」，wg-quick 在此之上补做了「建 Tunnel 网卡、配地址、加路由、执行 PreUp/PostUp 等」工作。二者结合使用（大多数场景用 wg-quick 启停，用 wg 查状态/改对端）。

wg 全部子命令（wg --help 实测回显）：

$ wg --help
Usage: wg <cmd> [<args>]

Available subcommands:
  show: Shows the current configuration and device information
  showconf: Shows the current configuration of a given WireGuard interface, for use with `setconf'
  set: Change the current configuration, add peers, remove peers, or change peers
  setconf: Applies a configuration file to a WireGuard interface
  addconf: Appends a configuration file to a WireGuard interface
  syncconf: Synchronizes a configuration file to a WireGuard interface
  genkey: Generates a new private key and writes it to stdout
  genpsk: Generates a new preshared key and writes it to stdout
  pubkey: Reads a private key from stdin and writes a public key to stdout
You may pass `--help' to any of these subcommands to view usage.

wg-quick 子命令（wg-quick --help 实测回显）：

$ wg-quick --help
Usage: wg-quick [ up | down | save | strip ] [ CONFIG_FILE | INTERFACE ]

  CONFIG_FILE is a configuration file, whose filename is the interface name
  followed by `.conf'. Otherwise, INTERFACE is an interface name, with
  configuration found at /etc/wireguard/INTERFACE.conf. It is to be readable
  by wg(8)'s `setconf' sub-command, with the exception of the following additions
  to the [Interface] section, which are handled by wg-quick:

  - Address: may be specified one or more times and contains one or more
    IP addresses (with an optional CIDR mask) to be set for the interface.
  - DNS: an optional DNS server to use while the device is up.
  - MTU: an optional MTU for the interface; if unspecified, auto-calculated.
  - Table: an optional routing table to which routes will be added; if
    unspecified or `auto', the default table is used. If `off', no routes
    are added.
  - PreUp, PostUp, PreDown, PostDown: script snippets which will be executed
    by bash(1) at the corresponding phases of the link, most commonly used
    to configure DNS. The string `%i' is expanded to INTERFACE.
  - SaveConfig: if set to `true', the configuration is saved from the current
    state of the interface upon shutdown.

See wg-quick(8) for more info and examples.

三、前置条件

已安装 wireguard-tools（含 wg、wg-quick）；
需要 root 权限（创建网卡/改网络参数）执行 wg set、wg-quick 等写操作；查询类命令（wg show）一般无需 root；
建立接合前核对两端公钥与（如用）预共享密钥。

四、工具详解

💡 说明：以下命令均已在「服务器 wg0 ↔ 客户端 10.99.0.2」的真实点对点环境跑出所列回显，命令输入即实测命令、输出即实测输出。

4.1 `wg genkey` / `wg pubkey`：生成并推导密钥对

生成一个随机私钥（Curve25519），并由此私钥推导对应公钥。私钥只能由 wg genkey 产生，公钥由私有键盘算（用 wg pubkey）。

wg genkey                      # 生成私钥
wg pubkey < private.key        # 由私钥推导公钥

实测回显（密钥为随机生成，示例仅为格式参考）：

$ wg genkey
wIFYPX+L64T+1h7ccSBL1V8VcZslPduYXCNZBo51K0s=

$ echo "wIFYPX+L64T+1h7ccSBL1V8VcZslPduYXCNZBo51K0s=" | wg pubkey
OS1y7sVcfkYx0MlxpVAS9QbS/6geUGUxcHFXmtaKYgY=

常用做法（一次生成私钥并落盘 + 推导公钥）：

umask 077
wg genkey | tee server_private.key | wg pubkey > server_public.key

💡 说明：wg genkey 输出私钥，本端私钥自留、只把公钥给对方；wg pubkey 从 stdin 读私钥、往 stdout 写公钥（不会修改原文件）。

4.2 `wg genpsk`：生成预共享密钥

生成一段额外的对称预共享密钥（PresharedKey），在 [Peer] 中两端保持一致，用于增强抗重放与未来抗量子能力。

wg genpsk

实测回显：

$ wg genpsk
3IyCcW7R3hN28LGn5gT7u0KkFfm1WWF91WxOKyqeA24=

4.3 `wg show`：查询接口状态、握手与流量

不带参数列出所有 WireGuard 接口；带接口名只显示指定接口。这是排障最常用的命令。

wg show                 # 所有接口
wg show wg0             # 指定接口
wg show interfaces      # 只列出接口名

实测回显（服务器侧）：

$ wg show wg0
interface: wg0
  public key: omjFjOq26vb24495db2kUGSVx1bZHoAnkLbmsTPwmyg=
  private key: (hidden)
  listening port: 51820

peer: AYpcaJY8ZqMEYeTGQz7I+LuXpt98k5q56gr70N4sAw8=
  preshared key: (hidden)
  endpoint: 172.24.0.3:36983
  allowed ips: 10.99.0.2/32
  latest handshake: 6 seconds ago
  transfer: 564 B received, 476 B sent

$ wg show interfaces
wg0

💡 说明：重点看 endpoint（对端来源）、latest handshake（最后握手）、transfer（已收发字节）。peer: <公钥> 没有 endpoint/latest handshake 时表示对端尚未成功连上本端。

wg show 支持仅取出某一项（wg show wg0 allowed-ips / peers / endpoints 等）：

$ wg show wg0 peers
AYpcaJY8ZqMEYeTGQz7I+LuXpt98k5q56gr70N4sAw8=

$ wg show wg0 all endpoints
wg0     AYpcaJY8ZqMEYeTGQz7I+LuXpt98k5q56gr70N4sAw8=    172.24.0.3:36983

4.4 `wg showconf` / `wg setconf` / `wg addconf` / `wg syncconf`：配置文件与运行态互转

wg showconf wg0：把接口当前运行态输出为 setconf 可读的配置文本；
wg setconf wg0 <file>：用文件整体覆盖接口配置；
wg addconf wg0 <file>：在现有接口配置后追加（不删除已有对端）；
wg syncconf wg0 <file>：把接口配置同步为文件内容（保留已有但文件未列的 Peer，视为「增量同步」）。

wg showconf wg0 实测回显：

$ wg showconf wg0
[Interface]
ListenPort = 51820
PrivateKey = uP1UGKv4jhEXcVBOqHSEx9PxOze4QOjM6WaFs7iGIFE=

[Peer]
PublicKey = AYpcaJY8ZqMEYeTGQz7I+LuXpt98k5q56gr70N4sAw8=
PresharedKey = SjzKE6w7Wr6pyCHsxF2ghJV5VekzHifb67Mh6ZFj/50=
AllowedIPs = 10.99.0.2/32
Endpoint = 172.24.0.3:36983

手动应用配置文件：

wg setconf wg0 /etc/wireguard/wg0.conf
# 或只追加一段（如新增一个对端）
wg addconf wg0 /tmp/extra_peer.conf

⚠️ 注意：setconf 会先把接口配置清空再写入整个文件（等价整体替换）；addconf 追加；syncconf 保留而非清空。三者对「已有对端是否保留」行为不同，按需选用。

4.5 `wg set`：运行时增删改对端/本端

在不清空接口的前提下，按需增/删/改某个对端或本端参数。常用动作：

# 新增/更新一个对端（allowed-ips 多条用逗号）
wg set wg0 peer AYpcaJY8ZqMEYeTGQz7I+LuXpt98k5q56gr70N4sAw8= \
  allowed-ips 10.99.0.2/32 \
  preshared-key <PSK> \
  endpoint <服务器IP>:51820

# 删除一个对端
wg set wg0 peer <对端公钥> remove

# 修改本端监听端口
wg set wg0 listen-port 51821

实测回显（先加对端、再删除，均无额外输出，只以 wg show 复核）：

$ wg set wg0 peer AYpcaJY8ZqMEYeTGQz7I+LuXpt98k5q56gr70N4sAw8= allowed-ips 10.99.0.2/32
$ wg show wg0 peers
AYpcaJY8ZqMEYeTGQz7I+LuXpt98k5q56gr70N4sAw8=

$ wg set wg0 peer AYpcaJY8ZqMEYeTGQz7I+LuXpt98k5q56gr70N4sAw8= remove
$ wg show wg0 peers
$

💡 说明：wg set 适合临时增删对端，不必碰磁盘上的 wg0.conf；若希望改动持久化，同时更新 /etc/wireguard/wg0.conf 或开启 SaveConfig。

4.6 `wg-quick up` / `wg-quick down`：一键启停接口

wg-quick 读取 /etc/wireguard/<接口名>.conf，自动完成「建网卡 → 配 Address → addconf → 加路由 → 挂 Miss 钩子」等链路工作。接口名即配置文件主名：

wg-quick up wg0
wg-quick down wg0

wg-quick up wg0 实测回显：

$ wg-quick up wg0
[#] ip link add wg0 type wireguard
[#] wg setconf wg0 /dev/fd/63
[#] ip -4 address add 10.99.0.1/24 dev wg0
[#] ip link set mtu 1420 up dev wg0

wg-quick down wg0 实测回显：

$ wg-quick down wg0
[#] ip link delete dev wg0

💡 说明：wg-quick up 会打印其内部执行的各条底层命令（ip link add wg0 type wireguard、wg setconf wg0 /dev/fd/63 等），便于排查；down 通过 ip link delete 整体移除接口。若配置含 PostUp（如转发/伪装），也在此阶段执行。

4.7 `wg-quick strip` / `wg-quick save`

wg-quick strip wg0：剥离 wg-quick 扩展项，输出仅剩 wg 原生参数（供 wg setconf 直接使用）；
wg-quick save wg0：把当前运行态保存回 /etc/wireguard/wg0.conf（内部实则为 wg showconf wg0）。

wg-quick strip wg0 实测回显（仅保留原生参数）：

$ wg-quick strip wg0
[Interface]
ListenPort = 51820
PrivateKey = uP1UGKv4jhEXcVBOqHSEx9PxOze4QOjM6WaFs7iGIFE=

[Peer]
PublicKey = AYpcaJY8ZqMEYeTGQz7I+LuXpt98k5q56gr70N4sAw8=
PresharedKey = SjzKE6w7Wr6pyCHsxF2ghJV5VekzHifb67Mh6ZFj/50=
AllowedIPs = 10.99.0.2/32

wg-quick save wg0 实测回显（实际即调用 wg showconf）：

$ wg-quick save wg0
[#] wg showconf wg0

💡 说明：strip 常配合脚本把 wg-quick 配置交给纯 wg setconf 使用；save 适合把动态变更的对端/Endpoint 落盘持久化。

五、注意事项

私钥与预共享密钥切勿外泄；用 wg genkey/wg genpsk 生成后文件权限设 600（umask 077）。
同一份 PresharedKey 必须在两端一致，否则握手失败；Allowips 用逗号分隔多条。
wg setconf（整体覆盖）与 addconf/syncconf（增量）的行为不同，必改时先备份 /etc/wireguard/wg0.conf。
wg show 中 （hidden) 表示该值不显示明文；私钥本就应从不出现在任何回显中。
wg-quick 是 bash 脚本，依赖 ip、iptables；缺失时报 command not found，先安装 iproute2、iptables。

六、常见问题（FAQ）

Q1：wg show 一直不出现 latest handshake？ 多为对端没有成功连上。核对 Endpoint 是否可达、防火墙放行、以及两端 PublicKey/PresharedKey 是否正确。也可 wg show wg0 endpoints 观察对端是否已上报来源。

Q2：wg setconf wg0 file 覆盖后原有对端没了？ setconf 是整体替换——先清空再写文件。如需保留已存在对端，改用 addconf（追加）或 syncconf（按文件同步、保留文件外对端）。

Q3：wg-quick up wg0 报 Unable to access interface / Unknown device type？ 内核未启用 WireGuard（Linux < 5.6 且未装模块）。请先按《Ubuntu 22.04 安装 WireGuard 指南》确认内核支持并可创建 wireguard 类型接口。

Q4：改完 wg0.conf 没生效？ wg-quick 只在 up 时读取配置。改配置后执行 wg-quick down wg0 && wg-quick up wg0（或 systemd 时 systemctl restart wg-quick@wg0）。

Q5：wg showconf 里多出我从未写的 Endpoint？ 那是对端实际连入后被 wg 学习的运行态（来源地址），showconf 会把它带出；只要 SaveConfig 未开，不会写回磁盘配置。

Q6：如何快速拿到纯 wg 可用的配置？ wg-quick strip wg0 直接输出剥离扩展项后的原生参数，可重定向给 wg setconf wg0 /dev/stdin 等使用。

七、参考链接

wg 手册：man wg
wg-quick 手册：man wg-quick
WireGuard 官方快速上手：https://www.wireguard.com/quickstart/
wireguard-tools 源码：https://git.zx2c4.com/wireguard-tools/

WireGuard 常用 CLI 命令与工具详解

WireGuard 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、工具详解

4.1 wg genkey / wg pubkey：生成并推导密钥对

4.2 wg genpsk：生成预共享密钥

4.3 wg show：查询接口状态、握手与流量

4.4 wg showconf / wg setconf / wg addconf / wg syncconf：配置文件与运行态互转

4.5 wg set：运行时增删改对端/本端

4.6 wg-quick up / wg-quick down：一键启停接口

4.7 wg-quick strip / wg-quick save

五、注意事项

六、常见问题（FAQ）

七、参考链接

4.1 `wg genkey` / `wg pubkey`：生成并推导密钥对

4.2 `wg genpsk`：生成预共享密钥

4.3 `wg show`：查询接口状态、握手与流量

4.4 `wg showconf` / `wg setconf` / `wg addconf` / `wg syncconf`：配置文件与运行态互转

4.5 `wg set`：运行时增删改对端/本端

4.6 `wg-quick up` / `wg-quick down`：一键启停接口

4.7 `wg-quick strip` / `wg-quick save`