Klipper Moonraker and Fluidd/Mainsail Setup for Voron

Klipper 固件设置

Klipper is the firmware that powers most Voron printers, but the user interface you actually interact with is a separate layer: Moonraker provides the API backend, and a web frontend (Fluidd or Mainsail) gives you the graphical interface. Setting these up correctly is essential for a smooth Voron experience. This guide covers everything from initial installation through remote access, plugins, and troubleshooting. 最后更新：2025年5月。

无论您是从零开始构建新的 Voron，还是将现有打印机从 OctoPrint 升级到 Klipper 生态系统，本指南都会逐步引导您完成每个步骤。我们使用 KIAUH（Klipper 安装和更新助手）作为推荐的安装方法，涵盖 moonraker.conf 中的关键配置选项，比较 Fluidd 与 Mainsail，并向您展示如何添加用于耗材管理、打印失败检测等的插件。

Moonraker 概述 — 功能说明

Moonraker 是一个基于 Python 的 API 服务器，充当 Klipper 固件和 Web 前端之间的桥梁。它在您的 Raspberry Pi（或 CB1，或任何 Linux 主机）上作为 systemd 服务运行，并提供 JSON-RPC API，Fluidd 和 Mainsail 等 Web 界面使用该 API 与 Klipper 通信。

Moonraker 所做的远不止中继命令：

Klipper 通信： Talks to Klipper via its UNIX socket, translating between Klipper's internal commands and the web frontend's API requests.
文件管理： Manages G-code files on the Raspberry Pi's filesystem, handles uploads, directory organization, and file operations. Can be configured to manage multiple printer configurations and firmware files.
更新管理器： Provides automatic or manual updates for Klipper, Moonraker, the web frontend, and system packages through a unified interface. This is one of Moonraker's killer features — one-click updates for your entire printer software stack.
授权与安全： Manages trusted clients, API keys, CORS domains, and authentication for web access. Essential for remote access security.
数据库与历史记录： Maintains a SQLite database of print history, job queue, and system statistics. The history tab in Fluidd/Mainsail uses this data.
WebSocket 与文件流： Provides real-time WebSocket connections for live status updates, and streams G-code files to Klipper during printing.
插件系统： Supports third-party plugins that extend functionality (more on this below).

Fluidd 与 Mainsail — 如何选择前端界面

Fluidd 和 Mainsail 都是基于 Vue.js 构建的现代 Web 界面，在您的浏览器中运行并与 Moonraker 通信。它们看起来相似并共享许多功能，但存在关键差异：

功能	Fluidd	Mainsail
开发状态	积极维护，团队规模略小	积极维护，贡献者基础更广
文件大小	更轻量（约15MB）	略重（约25MB）
仪表盘 V2	在 v1.x 版本中增加支持	原生支持，更多小部件
自定义	良好——可配置布局	优秀——拖放式仪表盘，自定义主题
移动端体验	良好的响应式设计	优秀——支持 PWA，移动端优化控制
内置摄像头	单摄像头，基础控制	多摄像头，支持延时摄影
默认主题	浅色、简约	默认深色主题，高度可定制

我们的推荐： Start with Mainsail. It has more features, a more polished mobile experience, and the drag-and-drop dashboard makes it easy to set up exactly the layout you want. However, if you're running on a Pi Zero or very memory-constrained hardware, Fluidd's lighter footprint may be the better choice. Both are excellent — you can't go wrong with either. You can even install both and switch between them while configuring, then remove the one you don't use.

通过 KIAUH 安装（推荐）

KIAUH（Klipper 安装和更新助手）是在 Raspberry Pi 和类似单板计算机上安装和管理 Klipper、Moonraker 和 Web 界面的标准工具。它是一个 bash 脚本，可自动执行整个设置过程。

前置条件

运行 Raspberry Pi OS Lite（推荐 64 位）或任何基于 Debian 的发行版的 Raspberry Pi 3B+、4B、5 或 CB1
已为您的 Voron 安装并配置 Klipper（请参阅我们的 Klipper 设置指南）
Python 3.8+（预装在 Pi OS 上）
Git (sudo apt install git -y)
Pi 上的互联网连接

KIAUH 安装步骤

下载 KIAUH：

cd ~
git clone https://github.com/dw-0/kiauh.git
cd kiauh
chmod +x kiauh.sh
./kiauh.sh

选择安装选项： KIAUH launches a menu-based interface. Type "1" for "Install" to enter the installation menu.
选择要安装的组件： Use the spacebar to select:
- [x] Klipper (already installed — skip if present)
- [x] Moonraker
- [x] Mainsail（或 Fluidd — 或两者都选）
Press Enter to confirm.
配置 Moonraker： KIAUH will ask for:
- 实例名称： Leave as "printer" or set a custom name if running multiple instances.
- Klipper Unix 套接字路径： Default is /tmp/klippy_uds. Leave as default unless you have a custom Klipper config.
- 配置目录： Default is ~/printer_data/config. Accept the default.
- 日志目录： Default is ~/printer_data/logs. Accept the default.
安装 nginx： KIAUH will install and configure nginx as a reverse proxy for the web interface. This is handled automatically — you don't need to configure nginx manually unless you want custom domains or SSL.
完成安装： KIAUH will download and install all components, configure systemd services, and start them. After completion, your web interface should be accessible at http://<your-pi-ip>/ or http://<your-pi-ip>:80.

手动安装（不使用 KIAUH）

If you prefer to install manually (useful for custom setups or troubleshooting), the basic steps are:

Clone the Moonraker repository: git clone https://github.com/Arksine/moonraker.git ~/moonraker
Run the install script: cd ~/moonraker && ./scripts/install-moonraker.sh
Clone your chosen frontend: git clone https://github.com/mainsail-crew/mainsail.git ~/mainsail or git clone https://github.com/fluidd-core/fluidd.git ~/fluidd
配置 nginx 以从其构建目录提供前端服务。每个前端的仓库中都提供了示例 nginx 配置。
Copy and customize moonraker.conf from the Moonraker repository's docs/example-moonraker.conf.

手动安装让您拥有更多控制权，但更容易出错。除非您有特定原因，否则请使用 KIAUH。

Moonraker 关键配置

Moonraker's configuration file lives at ~/printer_data/config/moonraker.conf (or ~/klipper_config/moonraker.conf on older setups). Here are the most important sections:

[authorization] — 安全设置

[authorization]
# Enable API key authentication
api_key_file: ~/printer_data/config/api_key.txt
# List of CORS domains allowed to access Moonraker
cors_domains:
    http://*.local
    http://192.168.*
# Trusted IPs that bypass authentication
trusted_clients:
    127.0.0.1
    192.168.1.0/24
# Force HTTPS for all external connections (requires SSL certificate)
force_logout: false

trusted_clients is important for local network access. Add your local subnet (e.g., 192.168.1.0/24) so devices on your LAN can access the web interface without entering a password every time. cors_domains must include any domains from which you'll access Moonraker — if you're using a reverse proxy or custom domain, add it here.

[file_manager] — 文件系统访问

[file_manager]
# Enable file upload and management
enable_object_processing: True
# Path to the config directory
config_path: ~/printer_data/config
# Path to the G-code directory
log_path: ~/printer_data/logs
# Additional file paths that can be accessed
enable_multi_mcu_firmware: True
firmware_path: ~/printer_data/firmware_binaries

The enable_multi_mcu_firmware option lets you store Klipper firmware binaries for multiple MCU configurations (e.g., mainboard + toolhead board + accelerometer). Moonraker can upload the correct binary to each MCU during firmware update. The firmware_path directory is where KIAUH stores compiled firmware binaries.

[update_manager] — 自动更新

[update_manager]
# Enable automatic updates
enable_auto: False            ; Set True to auto-update (not recommended for production)
channel: dev                  ; Options: dev, beta, stable
# Refresh interval in hours
refresh_interval: 24

[update_manager klipper]
type: git_repo
path: ~/klipper
origin: https://github.com/Klipper3d/klipper.git
manage_python: True
requirements: ~/klipper/scripts/klippy-requirements.txt
install_script: ~/klipper/scripts/install-ubuntu-22.04.sh
is_system_service: True

[update_manager moonraker]
type: git_repo
path: ~/moonraker
origin: https://github.com/Arksine/moonraker.git
manage_python: True
requirements: ~/moonraker/requirements.txt
install_script: ~/moonraker/scripts/install-moonraker.sh
is_system_service: True

[update_manager mainsail]
type: web
channel: stable
repo: mowad/mainsail
path: ~/mainsail

The update manager checks each configured component for updates and presents them in the web UI. You can update with one click in Fluidd/Mainsail's "Machine" tab. We recommend keeping enable_auto: False — review update notes before applying, as occasionally updates introduce breaking changes.

实用 Moonraker 插件

Obico（拉丝检测）

Obico 是一个 AI 驱动的打印失败检测系统，使用摄像头画面识别常见的打印失败：拉丝、层移、结块和完全打印脱离。检测到失败时，它可以暂停打印、向您的手机发送通知，并可选择取消打印。

Installation: sign up at obico.io, install the Obico plugin via KIAUH (it's in the KIAUH plugin menu under "Extension 3"), or manually add the Moonraker plugin. Configure your webcam in Moonraker's [webcam] section. The free tier covers one printer with basic detection; the paid tier adds multiple cameras, faster AI processing, and unlimited printers. For Voron owners printing expensive ABS parts, this is cheap insurance against failed overnight prints.

G-Code Shell 命令

此插件允许您直接从 G-code 宏在 Raspberry Pi 上执行任意 shell 命令。用例：运行脚本将打印数据上传到电子表格、通过 ntfy.sh 触发通知、从宏重启 Pi，或运行自定义相机延时摄影脚本。

Installation: clone the repository to ~/moonraker-plugins and add the plugin to moonraker.conf. Example usage in a macro:

[gcode_shell_command notify_print_done]
command: curl -d "Voron print complete on printer1" ntfy.sh/voron_alerts
timeout: 2.
verbose: True

[gcode_macro PRINT_END]
gcode:
    # ... existing PRINT_END code ...
    RUN_SHELL_COMMAND CMD=notify_print_done

This sends a push notification to your phone via ntfy.sh whenever a print finishes. The possibilities are endless — be creative but cautious: shell commands run as the Pi user and have full system access.

Spoolman（耗材库存管理）

Spoolman 是一个轻量级 Web 服务，用于跟踪您的耗材卷：材料、颜色、品牌、剩余重量和使用历史。Moonraker Spoolman 插件将其集成到 Fluidd/Mainsail 中，在打印期间自动从活动耗材卷中扣除耗材使用量。

Installation: install Spoolman (Docker or Python), then add the plugin to Moonraker. In your PRINT_START macro, add SET_ACTIVE_SPOOL ID=<spool_id> to associate a print with a spool. The web interface shows remaining filament and estimated spool life. Essential if you have more than 3-4 spools and want to track what's left without weighing each one.

远程访问 — 从任何地方连接您的 Voron

从本地网络外部访问 Voron 的 Web 界面很方便，但需要谨慎的安全措施。以下是选项，按安全性从高到低排列：

Tailscale（推荐）

Tailscale creates a wireguard-based mesh VPN that connects all your devices (phone, laptop, desktop, Raspberry Pi) into a secure virtual network. Install Tailscale on your Raspberry Pi and on every device you want to access Moonraker from. Then access the web interface at http://<pi-tailscale-ip>/ from anywhere in the world, with full encryption and no open ports on your home router.

Installation on Pi: curl -fsSL https://tailscale.com/install.sh | sh, then sudo tailscale up. Authenticate via the URL displayed. That's it — Tailscale handles all the networking. On your phone, install the Tailscale app and connect. Moonraker will be accessible at the Pi's Tailscale IP address. Tailscale's free tier covers up to 3 users and 100 devices, which is enough for most Voron owners.

WireGuard（自托管 VPN）

如果您不想依赖第三方服务，可以设置自己的 WireGuard VPN 服务器（在 Raspberry Pi、VPS 或家庭服务器上），并配置您的设备通过它连接。这比 Tailscale 设置更复杂，但让您完全控制。许多 Voron 用户在其家庭路由器（pfSense、OPNsense 或 OpenWrt）上运行 WireGuard，并在外出时连接手机/笔记本电脑。

Moonraker 内置代理（Moonraker-trusted Proxy 模式）

Moonraker 包含一个轻量级 HTTP 代理，可以通过端口 7125 提供 Web 前端服务。结合动态 DNS 服务，这允许直接访问您的打印机。但是，如果您转发端口 7125，这会将 Moonraker 直接暴露在互联网上——不推荐。如果您使用此方法，请在前面放置一个带有 HTTPS 和强身份验证的 nginx 反向代理。

端口转发（不推荐）

从家庭路由器向 Raspberry Pi 转发端口（80、443 或 7125）会将您的打印机暴露在开放的互联网上。即使有 Moonraker 的 API 密钥认证，这也有风险：Moonraker、nginx 或 Web 前端中未修补的漏洞可能被利用。Voron 社区已经出现过打印机被未经授权用户访问的案例。请使用 VPN。

移动端应用

Mobileraker（iOS / Android）： The most popular native mobile app for Moonraker. Provides live camera feed, print status, temperature graphs, and the ability to start/stop prints. Supports multiple printers and push notifications for print completions or failures. Premium version ($2.99) adds widgets and Apple Watch support. Highly recommended.
iPhone 版 G-Code View： A lightweight iOS app that provides a simple interface for viewing G-code files, monitoring print progress, and checking temperatures. Less feature-rich than Mobileraker but free and fast. Good as a quick-status checker.
Mainsail Mobile (PWA)： Mainsail's built-in Progressive Web App support means you can "install" the web interface on your phone's home screen. It caches assets and provides a full-screen experience with touch controls. Works well on recent browsers. No app store download needed.

故障排除

WebUI 无法加载（空白页面/连接被拒绝）

nginx 未运行： Check with sudo systemctl status nginx. If stopped: sudo systemctl restart nginx. Check nginx error logs at /var/log/nginx/error.log.
端口或 IP 错误： The web interface serves on port 80 (HTTP) or 443 (HTTPS). Ensure you're connecting to http://<pi-ip>:80 or just http://<pi-ip>. Some setups use port 7125 for Moonraker direct access — try that if port 80 fails.
防火墙拦截： Check if ufw or iptables is blocking port 80: sudo ufw status. Allow port 80: sudo ufw allow 80.
浏览器缓存： Hard-reload (Ctrl+Shift+R) or clear browser cache. Fluidd/Mainsail caches assets aggressively — an old cached version may not connect to the updated Moonraker API.

Moonraker 无法连接 Klipper

Klipper 未运行： Check with sudo systemctl status klipper. Restart: sudo systemctl restart klipper.
Socket 路径不匹配： Verify that the klippy_uds_address in moonraker.conf matches the actual path. Default is /tmp/klippy_uds. Check that this file exists: ls -la /tmp/klippy_uds. If it doesn't exist, Klipper isn't running or has a different socket path configured.
Moonraker 未运行： sudo systemctl status moonraker. Logs at ~/printer_data/logs/moonraker.log. The log usually indicates exactly what's wrong — check the last 50 lines.
权限被拒绝： The Moonraker user may not have permission to read the Klipper socket. Ensure both services run as the same user (typically pi or klipper). Check ps aux | grep moonraker to see which user Moonraker is running as.

nginx 502 Bad Gateway

502 错误意味着 nginx 无法访问后端服务（Moonraker 或静态文件服务器）。原因：

Moonraker 未运行： Check Moonraker status as above.
nginx proxy_pass 配置错误： Your nginx config may be pointing to the wrong port. The default nginx config for Mainsail/Fluidd proxies API calls to http://localhost:7125. Verify this is correct in /etc/nginx/sites-available/mainsail or fluidd.
Web 前端文件未找到： Ensure the frontend build files exist at the path nginx expects. For Mainsail: ls ~/mainsail/dist should show the built files. If empty, run cd ~/mainsail && git pull to rebuild.

文件上传或配置编辑的权限问题

Moonraker 无法写入配置目录： Add the Moonraker user to the same group as the config directory: sudo usermod -a -G pi moonraker (or whatever group owns ~/printer_data). Then restart Moonraker.
Git 所有权问题： If you run git pull manually in the Klipper or Moonraker directories, the files may change ownership to root. Fix: sudo chown -R pi:pi ~/klipper ~/moonraker ~/mainsail (replace pi with your username).
/tmp 目录在重启后被清空： Some systems clear /tmp on reboot. If Klipper's socket is in /tmp, add a tmpfiles.d config: echo "d /tmp 1777 root root -" | sudo tee /etc/tmpfiles.d/tmp.conf. The socket is recreated when Klipper starts, so this is usually only an issue if Klipper fails to start after a reboot.

Moonraker + Fluidd/Mainsail 堆栈在 Voron 构建中已经成熟且经过充分测试。一旦正确设置，它非常稳定——许多用户报告数月无需接触配置即可正常运行。从 KIAUH 开始，添加 VPN 用于远程访问，安装一两个能解决实际问题的插件，您将拥有一个可与商业 3D 打印世界相媲美的专业级打印机控制系统。

需要为您的 Klipper 设置准备硬件？

我们备有 Raspberry Pi 4B/5、CB1 计算模块以及预装 Klipper + Moonraker + Mainsail 的预配置 microSD 卡——直接来自我们在中国的制造合作伙伴。此外还有：CAN 总线工具头板（SB2040、EBB36、EBB42）、USB 加速度计（用于 input shaper 的 ADXL345）以及兼容 Pi 的摄像头（OV5640、USB 1080p）用于 Obico 打印失败检测。所有硬件均经过 Voron 兼容性测试。中国直供价格，合并运输——将您的 Rock 5B、Pi 5 或 CB1 与主板和工具头订单捆绑以节省运费。

Shop Tested Components →