故障排查

先找到对应症状，查看它在面板中的显示方式，然后按步骤处理。大多数问题都从节点页面开始排查：节点横幅、协议配置、事件、日志和诊断标签页，以及运行状况页面。

节点上的命令以 root 身份运行。Agent 服务为 mistgate-node；日志在 journal 中：

journalctl -u mistgate-node -n 100 --no-pager

节点一直处于离线状态#

显示方式

• 等待安装：已添加节点，但还没有 Agent 连接。横幅（「正在等待 Agent」）会显示安装命令的有效期限，或说明命令已过期。通过 SSH 安装节点时，参见下文「SSH 安装失败」。
• 主机闪断（灰色）：连接中断不到 10 分钟。短暂中断通常由服务商造成，此时还不会产生告警。
• 无法连接：连接中断 10 分钟或更久。会打开「节点无法连接」告警，并写入「已停止响应」事件。

处理方法

1. 打开服务商控制面板，检查服务器是否正在运行。

2. 如果服务器正在运行，请通过 SSH 登录并重启 Agent（横幅上有可复制的命令）：

   Shell

   systemctl restart mistgate-node && journalctl -u mistgate-node -n 50 --no-pager

3. 检查节点是否能够连接面板：Agent 始终主动向外连接到安装命令中的地址（--panel host:port，默认端口为 443）。节点上的出站防火墙或面板服务器上的入站防火墙都可能阻止连接。

4. 面板端的 Agent 接入端点需要 TLS：公共监听器必须使用 --acme-domain 或 --tls-cert 运行，或者面板需要单独的 --agent-listen。参见配置。

5. 如果日志显示 Agent 尚未注册，或节点已退役，Agent 会退出，systemd 不会重启它。请从节点的设置标签页生成新安装命令并重新注册。退役节点无法再次注册；请将服务器作为新节点添加。

6. 对于距离较远或响应较慢的节点，请在节点的设置中调高Agent 连接断开等待时间和Agent 拨号超时。

待处理节点的安装命令过期后，必须生成新安装命令；旧命令无法再次使用。

注册失败#

mistgate-node enroll 会输出 enroll: 和失败原因。

install 需要 root 权限和已注册的状态目录：先运行 enroll；如果更改过 --state-dir，两条命令使用相同的设置。

如果管理后台中的创建安装命令失败并显示「未配置面板地址」，说明面板不知道 Agent 应连接哪个地址：使用 --public-url 运行 setup，或使用 --agent-addr 运行 serve（参见 CLI）。

SSH 安装失败#

节点 → 添加节点 → 通过 SSH 自动安装会从面板服务器发起连接，因此节点的 SSH 端口必须能从面板服务器访问，节点也必须能够反向连接面板。任务失败时，向导会说明原因，并提供重试安装（再次输入 SSH 密码；会从中断处继续）和打开安装管理器，后者会显示具体原因。

最常见的原因：

• 服务商防火墙或安全组没有允许面板服务器通过 SSH 端口连接（「面板未能及时连接此 SSH 地址和端口」）。面板无法更改服务商的规则。
• 服务器无法连接面板 Agent 地址，或面板没有公共地址；两种情况都会显示「未配置面板的公网地址，节点无法回连」。检查 --public-url 或 --agent-addr，以及节点到面板的出站 TCP 连接（通常为 443）。
• 面板还没有可信节点发布包（「安装已停止」）：查看更新页面上的发布包一行。

所有失败消息及处理方法见通过 SSH 安装节点中的「安装失败时」。

协议配置无法启动#

显示方式

• 节点的协议配置标签页中，该项会显示启动失败和原因；节点横幅会显示「『<profile>』启动失败」。
• 客户端视角检测会显示「✕ 未启动」，并写入「『<profile>』启动失败」事件。

端口重新空闲后，重启协议配置（或应用节点诊断的重启协议配置修复）。

如果端口位于其他协议配置的端口跳跃范围内，或 TCP 443 被 Caddy 等 Web 服务器占用，节点诊断也会报告此问题。在将协议配置部署到节点之前，添加协议配置对话框会检查端口和证书，并提供空闲端口。

客户端已连接，但没有流量#

显示方式

• 检测结果为部分失败（隧道已建立，但一个测试页面失败），或显示「隧道正常，但节点通往互联网的出口不通」或「测试网站返回错误」。
• 告警原因会说明问题；用户可能会说「已连接，但什么都打不开」。

检查项目

1. 节点自身的 DNS 解析器：节点诊断中的服务器 DNS 解析。测试域名由节点解析；如果解析失败，请应用修复 DNS 解析器。
2. 节点设置中的此节点的 DNS 服务器：用户流量使用的解析器。默认值是服务器自身的 DNS 解析器。
3. WARP：如果只有经 WARP 出口的协议配置失败，参见「节点上没有可用的 WARP」。
4. AmneziaWG：如果主机防火墙丢弃转发流量（常见于同一服务器上安装 Docker 时），节点诊断的AmneziaWG 后端会发出警告。
5. 节点诊断中的非 Mistgate 防火墙规则和其他 VPN 的残留：外部 nat 或重定向规则可能会吞掉流量。
6. 节点诊断中的IPv6：无法建立出站连接的 IPv6 地址会导致有 IPv6 记录的网站卡住。

如果检测结果正常但只有一个人无法连接，请检查此用户的状态（已停用、已过期、超出配额）和用户页面中的设备。参见用户和分组。

服务商封锁 UDP#

Hysteria2 和 AmneziaWG 使用 UDP；部分服务商会丢弃某些端口上的 UDP，或完全封锁 UDP。

显示方式

• 检测失败并显示「无握手：UDP 流量可能未到达」。
• 「协议配置 <profile> 未在端口 N 上响应，但此节点上的另一个协议配置可以响应；服务商封锁了 UDP 端口 N。」
• 「在线但无流量」告警原因显示「服务商似乎封锁了此 UDP 端口」，或者在端口 443 或多个端口上显示「服务商似乎封锁了所有入站 UDP」。
• 对于 AmneziaWG，节点协议配置标签页中的状态可以区分两种情况：「没有数据包到达端口：服务商或防火墙封锁了此 UDP 端口」，或「数据包能到达，但握手无法完成：节点与配置中的混淆参数不一致」。
• 节点的事件中出现 host_firewall_sync_failed：服务器自身的防火墙没有开放协议配置的 UDP 端口。

处理方法

1. 检查服务商控制面板中的防火墙或安全组：必须允许传入协议配置的 UDP 端口及端口跳跃范围。
2. 检查服务器自身的防火墙。启用 UFW 时，Agent 会自动为节点服务器的 UDP 端口和端口跳跃范围添加允许规则，但绝不会修改自己没有添加的规则：如果你设置了针对这些端口的 deny 或 reject 规则，该规则会保留，事件也会指出它。Agent 不会编辑 firewalld；请手动将 UDP 端口添加到其活动区域。
3. 将协议配置移到此节点上的另一个端口：在节点的协议配置标签页中选择更改端口。
4. 如果所有端口都被封锁，请联系服务商支持或迁移节点。

检测使用协议配置的主端口，不会检查端口跳跃范围，因此端口跳跃范围被封锁时不会显示此问题。

时钟偏差#

显示方式

• 节点诊断中的时钟：面板时钟偏差超过 2 秒或 NTP 未同步时显示「需要关注」，偏差超过 30 秒时显示「故障」。
• 节点事件：偏差超过 30 秒时显示「服务器时钟与面板相差 N 秒」。

时钟错误会导致证书、身份验证器验证码和 WireGuard 握手失效。

节点上的处理方法：

timedatectl set-ntp true
timedatectl

如果管理员的身份验证器验证码持续失败，请检查面板服务器和手机的时钟：验证码只在前后各一个 30 秒周期内有效。

缺少 AmneziaWG 内核模块#

显示方式

• 节点上的协议配置显示：「AmneziaWG 未能在节点上启动：请查看节点设置中的『AmneziaWG 后端』」。
• 节点诊断中的AmneziaWG 后端报告没有可用后端；内核头文件列出缺少的模块依赖。

处理方法

• 最简单的方法：将节点的AmneziaWG 后端设为自动（如果内核模块已加载则使用它，否则使用用户态），或设为用户态。用户态不需要模块，但需要 /dev/net/tun。

• 使用内核模块：选择内核模块。较新的 Agent 会在你确认后自行构建模块；模块就绪前，AmneziaWG 会继续在用户态运行。否则，可以在节点上手动运行；不带 --yes 时只会显示计划：

  Shell

  mistgate-node awg prepare-kernel
  mistgate-node awg prepare-kernel --yes

  此命令支持 Debian 和 Ubuntu（apt），不能在容器中运行，且需要关闭 Secure Boot 并使用 systemd。通过面板启动的任务会记录到 journal 单元 mistgate-awg-prepare。

• 如果诊断报告服务单元隐藏了 /dev/net/tun（单元版本过旧），请在运行状况 → 诊断中应用刷新服务单元。如果 Agent 太旧而无法提供修复，请使用当前二进制运行一次 mistgate-node install。

参见 AmneziaWG。

WARP 无法运行#

显示方式

• 节点 WARP 卡片显示异常、无后端或已暂停。
• 节点诊断中的WARP 出口报告问题；协议配置显示「节点上的 WARP 无法运行」。
• 「此节点的直连协议配置正常，但协议配置 <profile> 无法运行：其 WARP 出口不可用。」

经 WARP 出口的协议配置会在 WARP 连接断开时停止转发，不会改为直接发送流量。

处理方法

1. 在 WARP 卡片中选择重启 WARP，然后查看握手、探测结果和最近错误。从 Cloudflare 重新读取可刷新账户信息。
2. 如果状态为已暂停：选择恢复。
3. 如果显示「此主机无法使用 WARP」：其他工具正在使用 WARP 路由表、规则优先级或接口名称（例如旧的 wg-quick 配置）。移除该工具的配置。
4. 如果显示无后端：节点没有 WireGuard 内核模块，也没有 /dev/net/tun；如果诊断中的服务单元检查已过期，请在运行状况 → 诊断中应用刷新服务单元。如果 Agent 版本过旧而无法提供修复，请使用当前二进制运行一次 mistgate-node install。
5. 如果显示「经 WARP 出口的协议配置无法启动：节点没有 WARP 账户」：在节点上注册或导入账户，或将这些协议配置切换为直连。

节点没有 IPv6 也可以运行 WARP。参见 WARP。

更新已回滚#

显示方式

• 更新页面上的节点状态为已回滚；最近更新会说明原因。
• 滚动更新已暂停，「节点更新已停止」告警处于打开状态。
• 节点事件显示「更新已回滚」。

修复原因后，继续或取消滚动更新，然后通过新的滚动更新再次更新节点。参见更新。

无法访问管理后台#

mistgate serve 启动错误及其含义：