3、安装与部署：在树莓派/主机上安装Klipper、配置Python环境、使用KIAUH或手动安装的完整流程
Klipper 的部署方式与传统 Marlin 固件有本质区别：它并非将全部运动控制逻辑烧录进 MCU，而是采用“上位机（Linux 主机）+ 下位机（MCU 微控制器）”的分布式架构。上位机负责 G代码解析、运动规划、温度控制等复杂计算，下位机仅执行实时性要求最高的步进脉冲生成与传感器采样。因此，安装 Klipper 实际上包含两条主线：一是在树莓派或 x86 主机上搭建完整的 Linux 运行环境与 Python 依赖；二是为 3D 打印机主控板编译并烧录对应的 Klipper 固件。本章将围绕这两条主线，详细讲解从裸机到可运行 Klipper 的完整部署流程，涵盖 KIAUH 脚本自动化安装与手动安装两种路径，并深入剖析 Python 虚拟环境、udev 规则、串口权限等关键细节。
3.1 部署前的系统准备与核心原理
Klipper 的安装并非简单的“复制文件”，而是需要理解其运行时的进程模型与通信机制。Klipper 上位机由三个核心进程组成：klipper.py（主控进程，负责 G代码解析、运动学计算、温度控制）、moonraker.py（API 服务进程，提供 HTTP/WebSocket 接口，供前端界面调用）、以及可选的 web 前端（Mainsail 或 Fluidd，通过 Moonraker 与 Klipper 交互）。这三个进程均运行在 Linux 用户态，通过 Python 解释器执行，因此 Python 环境的正确性直接决定系统稳定性。
在硬件层面，上位机与下位机之间通过串口（通常是 USB 虚拟串口）通信，通信协议为 Klipper 自定义的二进制协议。下位机 MCU 运行的是经过裁剪的实时固件，仅负责步进脉冲生成、温度 ADC 采样、限位开关读取等硬实时任务。这种架构的优势在于：运动规划在性能强大的上位机完成，MCU 只需执行简单的脉冲序列，因此 Klipper 可以实现更高的步进频率（如 1/64 微步下 200mm/s 以上的打印速度）。
部署前需要确认以下基础条件：
- 硬件平台：树莓派 3B/4B/5（推荐 4B 及以上）、x86 主机（Debian/Ubuntu）、或性能足够的 ARM 开发板（如 RK3328）。最低要求为 1GB RAM、4GB 存储，但推荐 2GB+ RAM 与 16GB 存储以保证 Moonraker 数据库与日志空间。
- 操作系统：树莓派官方 64 位 Raspberry Pi OS（Bookworm 或 Bullseye）、Ubuntu Server 22.04+、Debian 11+。注意：32 位系统虽然可以运行，但 Python 包兼容性与内存管理不如 64 位。
- Python 版本：Klipper 要求 Python 3.7 以上，推荐 3.9+。系统自带的 Python 版本可通过
python3 --version检查。 - 网络环境：安装过程中需要从 GitHub 拉取 Klipper、Moonraker、KIAUH 等仓库，建议提前配置好代理或确保网络通畅。
3.2 使用 KIAUH 自动化安装（推荐路径）
KIAUH（Klipper Installation And Update Helper）是社区维护的自动化部署脚本，它封装了 Klipper、Moonraker、Mainsail/Fluidd、以及常用工具（如 KlipperScreen、OctoPrint 兼容层）的安装与更新流程。使用 KIAUH 可以显著降低手动安装的出错概率，尤其适合初学者或需要频繁重装的环境。
3.2.1 KIAUH 安装步骤
- 系统更新与基础依赖：
sudo apt update && sudo apt upgrade -y
sudo apt install git curl python3 python3-venv python3-pip -y- 克隆 KIAUH 仓库并运行：
cd ~
git clone https://github.com/dw-0/kiauh.git
cd kiauh
./kiauh.sh- 交互式菜单操作：KIAUH 启动后显示主菜单，输入
1进入安装菜单，然后依次选择：
1- Klipper（安装主程序）2- Moonraker（安装 API 服务）3- Mainsail 或 Fluidd（选择前端界面）
KIAUH 会自动创建 ~/klipper、~/moonraker 目录，并在 ~/klipper-env 和 ~/moonraker-env 中创建独立的 Python 虚拟环境。安装完成后，KIAUH 会提示配置系统服务（systemd），使 Klipper 与 Moonraker 开机自启。
3.2.2 验证安装结果
安装完成后，执行以下命令检查服务状态：
sudo systemctl status klipper
sudo systemctl status moonraker如果服务处于 active (running) 状态，说明安装成功。此时访问 http://<树莓派IP>:4408（Mainsail 默认端口）或 :4409（Fluidd），即可看到前端界面。但此时打印机尚未配置，需要继续编译并烧录下位机固件。
4），可同时更新 Klipper、Moonraker 与前端，并自动重启服务。
3.3 手动安装流程（深入理解架构）
手动安装虽然繁琐，但能帮助开发者深入理解 Klipper 的目录结构与运行机制，对于后续二次开发或排障至关重要。以下为手动安装的完整流程：
3.3.1 创建 Python 虚拟环境
cd ~
git clone https://github.com/Klipper3d/klipper.git
cd klipper
python3 -m venv ~/klipper-env
~/klipper-env/bin/pip install -r requirements.txt注意：requirements.txt 中包含了 greenlet、pyserial、cffi 等关键依赖。安装完成后，可通过 ~/klipper-env/bin/python -c "import serial; print(serial.__version__)" 验证 pyserial 是否可用。
3.3.2 安装 Moonraker
cd ~
git clone https://github.com/Arksine/moonraker.git
cd moonraker
python3 -m venv ~/moonraker-env
~/moonraker-env/bin/pip install -r requirements.txt3.3.3 配置 systemd 服务
手动创建服务文件，使 Klipper 与 Moonraker 开机自启：
sudo nano /etc/systemd/system/klipper.service内容如下：
[Unit]
Description=Klipper 3D Printer Firmware
After=network.target
[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/klipper
ExecStart=/home/pi/klipper-env/bin/python /home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target同样创建 moonraker.service，ExecStart 指向 ~/moonraker-env/bin/python ~/moonraker/moonraker/moonraker.py。然后执行 sudo systemctl daemon-reload 并启用服务。
3.3.4 配置串口权限
将用户加入 dialout 组，避免每次烧录或连接打印机时都需要 sudo：
sudo usermod -a -G dialout $USER
sudo reboot3.4 编译与烧录下位机固件
无论使用 KIAUH 还是手动安装，编译下位机固件都是必经步骤。Klipper 固件编译基于 make menuconfig 配置，需要根据主控板的 MCU 型号、通信接口、时钟频率进行设置。
3.4.1 配置编译选项
cd ~/klipper
make menuconfig在菜单中需要正确设置以下关键项：
| 配置项 | 常见值 | 说明 |
|---|---|---|
| Micro-controller Architecture | STMicroelectronics STM32 / Raspberry Pi RP2040 / Atmel AVR | 根据主控板主芯片选择 |
| Processor model | STM32F103 / STM32F407 / RP2040 等 | 精确到具体型号 |
| Bootloader offset | 8KiB bootloader（常见）或 No bootloader | 需参考主控板出厂 bootloader |
| Clock Reference | 8 MHz crystal / 12 MHz crystal / Internal clock | 错误设置将导致串口通信失败 |
| Communication interface | USB (PA11/PA12) / UART (PA9/PA10) | 决定固件通过 USB 还是串口通信 |
3.4.2 编译与烧录
make -j4
# 烧录命令因 MCU 而异，常见方式：
# STM32 通过 DFU 模式：
sudo dfu-util -a 0 -D out/klipper.bin
# 或通过 SD 卡拷贝 bin 文件
# RP2040 通过 USB 启动模式：
sudo make flash FLASH_DEVICE=/dev/serial/by-id/usb-RaspberryPi_Pico*ls /dev/serial/by-id/ 是否能看到设备。若看不到，可能是时钟配置错误或 bootloader 偏移不正确。此时需要重新进入 DFU 模式（通常按住主控板上的 BOOT 按钮再上电），重新烧录。
3.5 案例拆解：从零部署一台 Voron 0.2 打印机
以下为实际部署案例，展示从裸机到完成 Klipper 连接的完整过程。
硬件环境：树莓派 4B（4GB RAM）、Voron 0.2 套件（主控板为 BTT SKR Mini E3 V3.0，MCU 为 STM32G0B1）、Mainsail 前端。
初始状态：树莓派已烧录 Raspberry Pi OS 64 位（Bookworm），主控板未烧录任何固件。
操作过程：
- SSH 登录树莓派，执行
sudo apt update && sudo apt upgrade -y，耗时约 10 分钟。 - 克隆 KIAUH 并运行，选择安装 Klipper + Moonraker + Mainsail。KIAUH 自动完成虚拟环境创建与依赖安装，耗时约 5 分钟。
- 进入
~/klipper目录，执行make menuconfig，选择 STM32G0B1、8KiB bootloader、8 MHz crystal、USB 通信。保存退出。 - 执行
make -j4编译，生成out/klipper.bin。 - 将主控板通过 USB 连接树莓派，按住 BOOT 按钮上电，执行
sudo dfu-util -a 0 -D out/klipper.bin烧录。烧录完成后重新上电。 - 执行
ls /dev/serial/by-id/，确认出现usb-Klipper_stm32g0b1xxxx设备。 - 编辑
~/printer.cfg，设置[mcu]段的serial参数为上述设备路径。 - 执行
sudo systemctl restart klipper，在 Mainsail 界面看到温度读数正常，说明通信成功。
结果对比：整个部署过程约 30 分钟（含编译时间），相比手动安装节省约 20 分钟，且避免了因 Python 依赖冲突导致的反复排障。
复盘经验：SKR Mini E3 V3.0 的 STM32G0B1 在 menuconfig 中需要选择 STM32G0B1 而非 STM32G0B0，两者引脚兼容但 bootloader 地址不同。此外，该主控板使用 8 MHz 晶振，若误选 12 MHz 将导致串口无法识别。
3.6 常见误区与总结复盘
在 Klipper 部署过程中，以下问题出现频率最高：
| 误区 | 后果 | 正确做法 |
|---|---|---|
| 使用系统 Python 直接 pip install | 依赖冲突、系统包损坏 | 始终使用 venv 虚拟环境 |
| 忽略 udev 规则配置 | 每次重启后串口设备名变化 | 使用 /dev/serial/by-id/ 固定路径 |
| menuconfig 中时钟频率选错 | 固件无法启动或串口无响应 | 查阅主控板原理图或官方文档确认晶振频率 |
| 烧录后未重启服务 | Klipper 仍连接旧固件 | 烧录后执行 sudo systemctl restart klipper |
| 使用 32 位系统 | 部分 Python 包编译失败 | 强制使用 64 位系统镜像 |
~/klipper/logs/klippy.log）中出现 Unable to open serial port，优先检查：① 设备路径是否存在；② 用户是否在 dialout 组；③ 固件是否烧录成功；④ 时钟配置是否正确。日志中会明确提示 MCU 的 ID 信息，可用于交叉验证。
总结而言，Klipper 的部署核心在于“上位机环境隔离”与“下位机固件匹配”两个关键点。KIAUH 工具将前者自动化，而后者需要开发者对硬件有充分了解。建议初学者先使用 KIAUH 完成首次部署，再通过手动安装加深理解。无论哪种方式，务必在修改配置前备份 printer.cfg，并养成查看 klippy.log 的习惯——这是 Klipper 排障最重要的入口。