如何在 Printer Tools 中修复 Moonraker WebSocket 连接错误

你需要准备

• 运行 Moonraker 的打印机当前使用的准确本地 IP 地址或主机名
• 确认 Klippy 显示为 Ready，而不是 Error 或 Shutdown
• 手机或电脑与打印机主机可以互相访问的同一网络
• 如果你的配置使用 HTTPS 或反向代理，需要包含协议和端口的完整地址
• 你的安装所需的任何 Moonraker API key、Bearer token 或 Basic Auth 凭据

诊断 Moonraker WebSocket 错误

1. 1

   确认 Klippy 是否真的就绪

   在浏览器中打开同一主机，或者如果已安装 Mainsail 或 Fluidd，也可以在那里打开。如果 Klippy 在那里同样显示 Error 或 Shutdown，问题出在 Klipper 或你的 printer.cfg，而不是 Printer Tools，重新连接应用也无济于事，除非 Klippy 本身恢复正常。

2. 2

   重新检查主机地址

   路由器重启后通常会分配一个新的本地 IP 地址。确认运行 Moonraker 的机器当前的地址，如果发生变化，请在 Printer Tools 中更新。在路由器中为该设备保留一个静态地址可以避免这种情况再次发生。

3. 3

   为自定义配置输入完整地址

   如果 Moonraker 位于 HTTPS、非默认端口或反向代理之后，请像在浏览器中输入那样输入完整地址。Printer Tools 会根据你提供的信息构建 WebSocket URL，因此不完整或错误的地址会在到达 Moonraker 之前就失败。

4. 4

   匹配你的安装所需的身份验证

   如果 Moonraker 强制要求 API key、Bearer token 或 Basic Auth，必须在 Printer Tools 中输入相同的凭据。凭据不匹配会导致 WebSocket 在打开后立即关闭，而不是阻止最初的连接尝试。

5. 5

   强制进行一次干净的重新连接

   移除并重新添加打印机，或者关闭再打开连接，以便从头重置该套接字，而不是等待自动重试。这也会清除上一次连接尝试遗留的任何待处理请求。

6. 6

   排查网络路径问题

   访客 Wi-Fi、客户端隔离、VLAN 防火墙规则或活跃的 VPN 配置文件，都可能阻止手机访问打印机主机，即使两台设备都显示有互联网访问。在断定问题出在 Moonraker 本身之前，先在同一网络段中进行测试。

Printer Tools 中的 Moonraker 状态

Klipper 仪表盘会实时反映 WebSocket 的状态，并在 Moonraker 恢复可访问后自动更新。

WebSocket 连接支持的功能

• 实时推送的打印状态、进度、温度和标准 Klipper 对象
• 无需重新打开应用即可每 5 秒自动重新连接一次
• 在正常后台使用期间保持连接存活的心跳机制
• 每次连接成功后立即执行的 Klippy 状态检查
• 在你的 Moonraker 配置需要时支持 API key、Bearer token 或 Basic Auth

这无法解决的问题

• Klippy 的错误或关闭状态必须在 Klipper 本身中解决，而不是通过 Printer Tools
• 如果打印机保存的 IP 未更新，Printer Tools 将无法连接到已更改地址的主机
• 手机与打印机主机之间的网络隔离会阻止 WebSocket 连接，与应用设置无关
• 即使应用显示已断开连接，正在进行的打印仍会在打印机上继续

常见的 WebSocket 错误

常见问题