Ubuntu WireGuard 客户端：安装、配置与日常管理
本文详细介绍如何在 Ubuntu 系统上安装 WireGuard 客户端，并通过 wg-quick 和 systemctl 管理 VPN 连接。
一、WireGuard 简介
WireGuard 是一款现代 VPN 协议，以内核模块方式运行，具有代码量小、性能高、配置简单、加密算法先进等特点。它使用公钥加密技术进行身份认证，与传统 VPN 相比，配置和维护都更加简便。
在 Ubuntu 上，WireGuard 由两部分组成：
- 内核模块：实际处理加密和解密的核心组件
- 用户态工具：
wg和wg-quick命令行工具，用于配置和管理
注意：Ubuntu 20.04 及以上版本内核已内置 WireGuard 模块，只需安装用户态工具即可。
二、安装 WireGuard
2.1 安装命令
# 更新软件包索引
sudo apt update
# 安装 WireGuard 用户态工具
sudo apt install wireguard -y2.2 验证安装
# 查看版本
wg --version
# 检查内核模块是否可用
modprobe wireguard
lsmod | grep wireguard如果 lsmod | grep wireguard 有输出，说明内核模块已成功加载。
三、生成客户端密钥对
每个 WireGuard 节点都需要自己的密钥对。
# 进入 WireGuard 配置目录
sudo mkdir -p /etc/wireguard
cd /etc/wireguard
# 设置安全权限：仅 root 可访问
sudo umask 077
# 生成私钥
sudo wg genkey | sudo tee client_private.key
# 根据私钥生成公钥
sudo cat client_private.key | wg pubkey | sudo tee client_public.key
# 查看生成的密钥
echo "私钥: $(sudo cat client_private.key)"
echo "公钥: $(sudo cat client_public.key)"输出示例：
私钥: kL5gF9hE2jM8nP3qR6sT1uV4wX7yZ0bC3dE5fG6hJ7k=
公钥: J9sK2lM4nP6qR8tU1wX3yZ5bC7dE9fG0hJ2kL4mN6oP=重要：
client_public.key（公钥）的内容需要提供给服务端管理员，用于在服务端配置中添加你的设备。client_private.key（私钥）必须妥善保管，绝不能泄露。
3.1 与服务端交换密钥
| 你提供给服务端 | 服务端提供给你 |
|---|---|
| 客户端公钥 | 服务端公钥 |
| — | 分配的客户端 VPN IP |
完成密钥交换后，服务端会在其配置文件中添加：
[Peer]
PublicKey = <你的客户端公钥>
AllowedIPs = 10.8.0.2/32 # 为你分配的 IP四、创建客户端配置文件
在 /etc/wireguard/ 目录下创建配置文件。接口名称通常使用 wg0，也可以自定义（如 home、office）。
sudo nano /etc/wireguard/wg0.conf4.1 基础配置模板
[Interface]
# 客户端自己的私钥（从 client_private.key 获取）
PrivateKey = kL5gF9hE2jM8nP3qR6sT1uV4wX7yZ0bC3dE5fG6hJ7k=
# 客户端在 VPN 中的 IP（由服务端分配）
Address = 10.8.0.2/24
# DNS 服务器（可选，防止 DNS 泄露）
DNS = 119.29.29.29, 223.5.5.5
# MTU（可选，网络不稳定时可设为 1420）
MTU = 1420
[Peer]
# 服务端的公钥（从服务端管理员获取）
PublicKey = J9sK2lM4nP6qR8tU1wX3yZ5bC7dE9fG0hJ2kL4mN6oP=
# 服务端的公网地址和端口
Endpoint = <服务器IP>:51820
# 路由策略：哪些流量走 VPN
# 选项1: 0.0.0.0/0 - 所有流量走 VPN（全局模式）
# 选项2: 10.8.0.0/24 - 仅 VPN 内网流量走 VPN（分流模式）
AllowedIPs = 10.8.0.0/24
# 保持连接活跃（NAT 穿透必须）
PersistentKeepalive = 254.2 配置参数详解
| 段 | 参数 | 必填 | 说明 |
|---|---|---|---|
[Interface] | PrivateKey | ✅ | 客户端的私钥，必须保密 |
Address | ✅ | VPN 内网 IP，格式 IP/掩码，由服务端分配 | |
DNS | ❌ | 防止 DNS 泄露，推荐填写 | |
MTU | ❌ | 最大传输单元，不稳定时可设为 1420 | |
[Peer] | PublicKey | ✅ | 服务端的公钥 |
Endpoint | ✅ | 服务端公网地址，格式 IP:端口 | |
AllowedIPs | ✅ | 路由规则，哪些目标 IP 走 VPN | |
PersistentKeepalive | ❌ | 心跳间隔，NAT 后必须，推荐 25 秒 |
4.3 设置文件权限
sudo chmod 600 /etc/wireguard/wg0.conf五、使用 wg-quick 管理连接
5.1 wg-quick 是什么？
wg-quick 是 WireGuard 官方提供的自动化配置脚本，它读取配置文件并自动完成以下操作：
- 创建 WireGuard 虚拟网卡
- 配置 IP 地址
- 添加路由表
- 设置 DNS
- 执行自定义脚本
5.2 基本命令
| 命令 | 功能 |
|---|---|
sudo wg-quick up wg0 | 启动 wg0 接口 |
sudo wg-quick down wg0 | 关闭 wg0 接口 |
sudo wg-quick up /path/to/config.conf | 使用指定配置文件启动 |
5.3 启动 VPN 连接
sudo wg-quick up wg0执行过程输出示例：
[#] ip link add wg0 type wireguard
[#] wg setconf wg0 /dev/fd/63
[#] ip -4 address add 10.8.0.2/24 dev wg0
[#] ip link set mtu 1420 up dev wg0
[#] ip -4 route add 10.8.0.0/24 dev wg05.4 查看连接状态
sudo wg show正常输出示例：
interface: wg0
public key: Ns9XK8pLm2Qr5Tv7Wx9Yz1Bc3De5Fg7Hj9Kl1Mn3Pq5=
private key: (hidden)
listening port: 45678
peer: J9sK2lM4nP6qR8tU1wX3yZ5bC7dE9fG0hJ2kL4mN6oP=
endpoint: <服务器IP>:51820
allowed ips: 10.8.0.0/24
latest handshake: 32 seconds ago ← 有具体时间说明连接正常
transfer: 1.24 MiB received, 368.42 KiB sent
persistent keepalive: every 25 seconds关键判断标准：
latest handshake显示具体时间 → 连接正常latest handshake显示(none)→ 握手失败，需排查
5.5 测试连通性
# ping 服务端的 VPN 内网 IP
ping -c 4 10.8.0.15.6 关闭 VPN 连接
sudo wg-quick down wg0六、使用 systemctl 管理服务
6.1 服务模板机制
WireGuard 的 systemd 服务采用模板设计：wg-quick@.service。接口名作为参数传递，因此可以管理多个独立接口。
- 启动
wg0接口 →wg-quick@wg0.service - 启动
home接口 →wg-quick@home.service
6.2 systemctl 命令大全
| 操作 | 命令 | 说明 |
|---|---|---|
| 启动 | sudo systemctl start wg-quick@wg0 | 立即启动 VPN |
| 停止 | sudo systemctl stop wg-quick@wg0 | 立即停止 VPN |
| 重启 | sudo systemctl restart wg-quick@wg0 | 完全重建接口（会断连） |
| 重载 | sudo systemctl reload wg-quick@wg0 | 仅更新 Peer 配置（不断连） |
| 查看状态 | systemctl status wg-quick@wg0 | 显示服务状态和日志 |
| 开机自启 | sudo systemctl enable wg-quick@wg0 | 系统启动时自动连接 |
| 禁用自启 | sudo systemctl disable wg-quick@wg0 | 取消开机自启 |
6.3 设置开机自动连接
# 启用开机自启
sudo systemctl enable wg-quick@wg0
# 立即启动（或重启系统后自动启动）
sudo systemctl start wg-quick@wg06.4 查看服务状态
systemctl status wg-quick@wg0正常输出示例：
● wg-quick@wg0.service - WireGuard via wg-quick(8) for wg0
Loaded: loaded (/lib/systemd/system/wg-quick@.service; enabled)
Active: active (exited) since Sat 2026-06-13 15:30:00 CST; 2h ago
Process: 12345 ExecStart=/usr/bin/wg-quick up wg0 (code=exited, status=0/SUCCESS)
Main PID: 12345 (code=exited, status=0/SUCCESS)6.5 查看服务日志
# 查看最近 50 条日志
sudo journalctl -u wg-quick@wg0 -n 50
# 实时跟踪日志（Ctrl+C 退出）
sudo journalctl -u wg-quick@wg0 -f6.6 reload vs restart：重要区别
| 场景 | 推荐操作 | 连接是否中断 |
|---|---|---|
修改了 [Peer] 部分 | reload | ❌ 不中断 |
修改了 [Interface] 部分 | restart | ✅ 会中断 |
修改了 AllowedIPs | reload | ❌ 不中断 |
修改了 Address 或 DNS | restart | ✅ 会中断 |
使用 reload 添加新客户端：
sudo nano /etc/wireguard/wg0.conf # 添加新的 [Peer]
sudo systemctl reload wg-quick@wg0 # 无中断重载6.7 服务的完整生命周期
# 常见管理流程
sudo systemctl enable wg-quick@wg0 # 设置开机自启
sudo systemctl start wg-quick@wg0 # 立即启动
systemctl is-enabled wg-quick@wg0 # 检查是否自启
systemctl status wg-quick@wg0 # 查看状态
sudo systemctl stop wg-quick@wg0 # 停止
sudo systemctl disable wg-quick@wg0 # 取消自启
# 彻底移除服务
sudo systemctl stop wg-quick@wg0
sudo systemctl disable wg-quick@wg0
sudo rm -f /etc/systemd/system/wg-quick@wg0.service # 通常不需要
sudo systemctl daemon-reload七、配置 DNS（Ubuntu 特殊处理）
7.1 问题背景
wg-quick 的 DNS 配置项默认调用 resolvconf 命令，但 Ubuntu 默认使用 systemd-resolved，因此需要额外配置。
7.2 正确配置方法
在 [Interface] 段使用 PostUp 调用 resolvectl：
[Interface]
Address = 10.8.0.2/24
PrivateKey = <私钥>
PostUp = resolvectl dns %i 10.8.0.1; resolvectl domain %i ~home
PostDown = resolvectl revert %i
[Peer]
PublicKey = <服务端公钥>
AllowedIPs = 10.8.0.0/24
Endpoint = 服务器IP:51820
PersistentKeepalive = 25参数说明：
%i：自动替换为接口名（如wg0）resolvectl dns：设置 DNS 服务器resolvectl domain：指定域名搜索范围resolvectl revert：关闭接口时恢复默认设置
7.3 验证 DNS 配置
# 查看 wg0 接口的 DNS 状态
resolvectl status wg0正常输出：
Link 6 (wg0)
Current Scopes: DNS
DNS Servers: 10.8.0.1
DNS Domain: ~home八、高级配置：wg-quick 专有选项
在 [Interface] 段，wg-quick 支持以下扩展选项：
| 选项 | 类型 | 说明 |
|---|---|---|
PreUp | 脚本 | 接口创建前执行的命令 |
PostUp | 脚本 | 接口创建后执行的命令 |
PreDown | 脚本 | 接口关闭前执行的命令 |
PostDown | 脚本 | 接口关闭后执行的命令 |
Table | auto/off/数字 | 路由表控制：auto(默认)、off(禁用)、或指定表 ID |
SaveConfig | true/false | 关闭时是否保存配置到文件 |
8.1 使用 Table=off 禁用自动路由
如果希望手动控制路由，可以关闭自动路由：
[Interface]
Table = off
...8.2 使用 SaveConfig 自动保存
[Interface]
SaveConfig = true
...关闭接口时，客户端动态变化的 endpoint 等信息会自动保存回配置文件。
九、常见问题排查
9.1 握手失败（latest handshake 为 none）
症状：sudo wg show 显示 latest handshake: (none)
可能原因：
- 服务端未添加你的客户端公钥
- 客户端
[Peer].PublicKey填写错误（应填服务端公钥） - 防火墙未放行 UDP 51820 端口
- Endpoint 地址或端口错误
解决方案：
# 测试 UDP 连通性
nc -vuz <服务端IP> 51820
# 检查配置文件
sudo cat /etc/wireguard/wg0.conf
# 查看详细日志
sudo journalctl -u wg-quick@wg0 -n 509.2 配置文件权限错误
症状：启动时提示 Warning: /etc/wireguard/wg0.conf' is world accessible
解决方案：
sudo chmod 600 /etc/wireguard/wg0.conf9.3 服务启动失败：wg0 already exists
症状：Job for wg-quick@wg0.service failed
原因：接口已存在，可能之前未正常关闭
解决方案：
sudo wg-quick down wg0
sudo systemctl start wg-quick@wg09.4 MTU 问题导致连接异常
症状：能握手成功但无法正常传输数据
解决方案：在 [Interface] 中降低 MTU
MTU = 12809.5 查看详细错误日志
# 查看 systemd 服务日志
sudo journalctl -u wg-quick@wg0 -n 100 --no-pager
# 直接运行 wg-quick 查看实时输出
sudo wg-quick up wg0十、完整操作速查表
日常使用
| 操作 | 命令 |
|---|---|
| 连接 VPN | sudo wg-quick up wg0 |
| 断开 VPN | sudo wg-quick down wg0 |
| 查看状态 | sudo wg show |
| 测试连通 | ping 10.8.0.1 |
| 设置开机自启 | sudo systemctl enable wg-quick@wg0 |
| 禁用开机自启 | sudo systemctl disable wg-quick@wg0 |
故障排查
| 操作 | 命令 |
|---|---|
| 查看服务状态 | systemctl status wg-quick@wg0 |
| 查看日志 | sudo journalctl -u wg-quick@wg0 -n 50 |
| 测试 UDP 连通性 | nc -vuz <服务端IP> 51820 |
| 重启服务 | sudo systemctl restart wg-quick@wg0 |
| 重载配置 | sudo systemctl reload wg-quick@wg0 |