WireGuard 连不上怎么排查：握手、AllowedIPs 与路由

查看接口、地址和端口

WireGuard 通过网络接口承载隧道内 IP 流量，并使用 UDP 传输加密数据。先列出当前能观察到的 WireGuard 接口，再把接口名称与地址列表、实际监听端口对应起来，不预设接口名或端口。

下面的地址命令会列出当前网络命名空间中的各接口；只把目标 WireGuard 接口的条目用于本次判断。命令不存在、权限被拒绝和列表为空是不同情况，应先核对已安装的工具、授权及运行环境，不能都归为隧道故障。

sudo 不会自动切换到业务所在的网络命名空间。官方文档说明，WireGuard 接口可以迁移到其他命名空间，而用于收发加密 UDP 的 socket 留在接口最初创建的命名空间；容器场景要分别确认隧道接口与外层网络的观察位置。

本文的工具语义以 wireguard-tools v1.0.20250521 和 iproute2 v6.12.0 为可复查基线。实际发行版的软件包、网络管理器和命名空间安排仍需按本机情况核对，接口存在本身也不能证明目标业务已经连通。

sudo wg show interfaces
ip -brief address show
sudo wg show all listen-port

查询时保留公钥，保护私钥

接口私钥和 peer 预共享密钥不能进入截图、公开工单或诊断日志。公钥用于识别 peer，可在需要时交换；它与端点、地址范围组合后仍可能暴露网络拓扑。

wg 手册明确说明，dump 输出包含接口私钥和 peer 的预共享密钥；showconf 会输出配置文件格式的当前配置。wg-quick strip 去掉的是 wg-quick 扩展选项，不是秘密字段，不能把它当作配置脱敏工具。

WG_HIDE_KEYS 仅控制普通格式的 show 如何显示密钥，不保护 dump、显式密钥查询或配置导出。本教程只使用指定的非密钥查询字段，不要求读取完整配置或生成新的密钥。

检查配置文件和备份的访问权限即可，无须把完整内容复制到终端记录。官方快速入门在生成密钥前设置限制性文件权限；现有密钥的位置、权限和轮换应按当前配置处理，不要为诊断重新生成。

检查 peer 和双向 AllowedIPs

查询结果按接口和 peer 公钥区分记录。先确认目标 peer 身份，再把本端配置的 AllowedIPs 与实际业务的隧道内地址范围核对，避免拿另一个 peer 的规则解释当前流量。

官方 Cryptokey Routing 概念说明：发送时按隧道内目标 IP 选择 peer；接收时，解密并认证后的隧道内源 IP 必须属于该 peer 获准的范围。这两种方向需要分别核对，不能只检查本端要访问的目标地址。

AllowedIPs 不是端口开放清单，也不单独证明系统已经建立正确路由。应同时确认对端用于返回流量的地址范围，以及本端和对端实际地址、路由与访问控制；覆盖整个地址族的范围还会扩大路由和入站源地址匹配边界，需要与业务目的逐项对应。

sudo wg show all allowed-ips

查看握手与收发计数

把 endpoints、latest-handshakes、transfer 和 persistent-keepalive 的结果按接口与 peer 公钥对应起来。实际端点可能在收到该 peer 正确认证的数据后更新，因此配置文件中的初始端点与当前观察值不一定相同。

此版本的脚本式输出中，latest-handshakes 给出握手时间戳，transfer 的两项计数依次是接收字节与发送字节。计数是累计状态，不是即时速率；握手记录也不证明隧道内每个目标服务、DNS 或返回路径都可用。

WireGuard 空闲时保持安静。在正常业务操作前后对照握手和计数，观察是否变化；握手时间较旧或计数暂未增长，并不能单独说明故障。

PersistentKeepalive 用于需要维持 NAT 或状态防火墙映射的场景，默认关闭，并非所有 peer 都需要。它不能替代 UDP 路径、端口访问控制和系统路由检查；应先确认实际需求，不把开启 keepalive 当作通用修复。

sudo wg show all endpoints
sudo wg show all latest-handshakes
sudo wg show all transfer
sudo wg show all persistent-keepalive

把系统路由与 AllowedIPs 对照起来

从目标业务的实际地址出发，检查相应地址族的路由表和策略规则，确认流量应从哪个接口、哪张表发出，并核对对端的返回路径。还要区分隧道内业务目标与承载加密 UDP 的外层端点，不能把两者的出接口要求混在一起。

wg-quick 会从 peer 的 AllowedIPs 推导并创建路由，遇到默认路由时还会使用 ip-rule 处理默认网关选择。只看 main 表可能漏掉实际生效的策略路径；IPv4 与 IPv6 也要分别检查。

Table 控制 wg-quick 创建路由的位置与方式，off 会关闭它的自动路由创建，但不表示系统不存在其他路由。由其他网络管理器配置的接口也不一定采用 wg-quick 的规则，应把查询结果与真正负责加载配置的工具对应起来。

这些命令只列出当前状态，不替业务做连通性测试。若路由或规则与预期不符，先确认配置来源及影响范围，不直接清空路由表、替换默认路由或放宽防火墙。

ip -4 route show table all
ip -6 route show table all
ip -4 rule show
ip -6 rule show

确认配置由哪个工具加载

找到接口实际使用的 wg-quick、网络管理器或其他管理工具，再查配置来源。wg-quick 接收接口名时先查 /etc/wireguard 中的配置，手册还允许发行版特定搜索路径；文件存在不代表已经加载。

Address、DNS、Table 与 hooks 等是 wg-quick 在 wg 配置格式之外处理的扩展项。此版本手册中的 DNS 处理调用 resolvconf，不能把这套流程直接套到所有网络管理器；wg 的配置加载也不等于同时配置好了接口地址、DNS 和系统路由。

wg-quick up 会设置接口、地址和路由，并可能执行 hooks；down 会拆除接口并可能保存配置；save 会写入配置。它们不是只读检查操作。PreUp、PostUp、PreDown 和 PostDown 是会由 shell 执行的片段，不是备注，加载来源不明的配置也就可能执行其中的命令。

启用 SaveConfig 后，wg-quick 关闭接口时会保存运行状态，关闭前修改的配置可能被覆盖。变更前保留原文件、运行状态和加载方式，恢复时才能对应原设置。

下面所有行都是注释，仅说明真实配置项，没有密钥、地址或可直接应用的网络配置。加载与恢复按当前管理工具处理，随后检查接口、peer 和路由。

# 配置项说明；不会加载配置或更改网络。
# Address：wg-quick 配置的接口地址。
# Table：wg-quick 自动创建路由的方式。
# SaveConfig：启用后，wg-quick 关闭时保存配置。
# PreUp / PostUp：启动前后执行的 shell 片段。
# PreDown / PostDown：关闭前后执行的 shell 片段。

按故障现象继续排查

当前看不到接口时，先核实工具、权限、网络命名空间和配置管理者；能看到接口时，再核对实际地址与 peer 身份。不要跳过这些前提，把同名接口、另一台主机或另一个容器的结果拼成一份结论。

有 peer 但业务访问时没有预期握手，检查双方公钥、当前端点与 UDP 路径。已有握手但业务失败，继续查双向 AllowedIPs、系统路由、返回路径、访问控制和目标服务。

若仅名称访问失败，应另查实际 DNS 配置与解析过程；若仅部分地址族或目标失败，则按相同接口、peer 与地址族重新对照记录。这些现象用于缩小排查范围，不代表已经确定了单一原因。

修改前保存脱敏诊断记录和配置备份，并确认 SSH 或控制台可访问。恢复后重新检查接口、peer、路由、管理访问和目标业务。

UFW 教程用于查看主机端口访问控制，SSH 教程用于检查管理入口；隧道本身和业务返回路径仍按本页步骤排查。