免责声明：这是一个独立的资源网站。 与 Voron 项目或其开发团队无关联。

Klipper Backup and Restore Guide for Voron — Never Lose Your Config

Klipper 固件 指南

Your Voron's configuration is the sum of hundreds of hours of tuning — pressure advance values dialed in filament by filament, input shaper resonance curves measured and saved, bed mesh profiles that compensate for every subtle warp in your build plate, and macros that automate your exact workflow. Losing that config to a corrupted SD card, a failed firmware update, or a misconfigured moonraker database is devastating. This guide covers every backup and restore strategy for a Klipper-based Voron, from quick manual saves to fully automated disaster recovery pipelines. 最后更新：2025 年 5 月。

需要备份的内容

A Voron running Klipper has several distinct layers of configuration. Backing up just printer.cfg is not enough for a full recovery. Here is everything that matters:

方法 1：Moonraker 备份插件（推荐）

moonraker-backup 插件是最省心的解决方案。它按您设定的计划创建整个配置目录的压缩存档，并可通过 SCP 或 rsync 推送到远程存储。 

# In moonraker.conf — enable the backup module
[backup]
enable: True
# Archive the entire ~/printer_data/config directory daily at 3am
# via a cron job on the host:
# 0 3 * * * /home/pi/moonraker/scripts/backup.sh

To install the moonraker backup plugin manually: 

cd ~/moonraker
git pull
./scripts/install-moonraker-backup.sh
# Edit /etc/cron.d/moonraker-backup to set schedule
# Backups land in ~/printer_data/backups/ by default

For off-site backups, add an rsync target in your cron job: 

#!/bin/bash
# ~/printer_data/scripts/backup-to-nas.sh
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
mkdir -p ~/printer_data/backups
cd ~/printer_data
tar czf "backups/config-$TIMESTAMP.tar.gz" config/
rsync -avz --remove-source-files backups/ user@nas:/volume1/voron-backups/

方法 2：基于 Git 的备份

Git-based versioning gives you the full power of change history — you can see exactly what you changed between prints, revert a bad tuning change, and maintain branches for different configurations. This is the preferred method for advanced users who want change tracking. 

cd ~/printer_data/config
git init
git add .
git commit -m "Initial config baseline"

# Add a remote (GitHub private repo, or your own Git server)
git remote add origin git@github.com:yourusername/voron-config.git
git branch -M main
git push -u origin main

# Create a backup script with automatic commits
cat > ~/printer_data/scripts/git-backup.sh << 'EOF'
#!/bin/bash
cd ~/printer_data/config
git add -A
git commit -m "Auto-backup $(date +%Y-%m-%d_%H:%M:%S)"
git push origin main
EOF

chmod +x ~/printer_data/scripts/git-backup.sh
# Add to cron: */30 * * * * ~/printer_data/scripts/git-backup.sh

With git-based backup, tracking configuration changes is trivial: 

# See what changed in the last backup
git diff HEAD~1 HEAD

# Show changes for a specific file over time
git log --oneline -p -- printer.cfg

# Revert a bad change
git revert HEAD

方法 3：通过 SCP/RSync/Samba 手动备份

For users who prefer a simple, no-dependency approach, manual backup is the most straightforward. Connect to your Raspberry Pi from your desktop and copy files directly. 

# From your desktop — copy entire config directory
scp -r pi@voron.local:~/printer_data/config/ ~/voron-backups/config-$(date +%Y%m%d)

# Using rsync (more efficient for repeated backups)
rsync -avz pi@voron.local:~/printer_data/config/ ~/voron-backups/

# Restore from backup
rsync -avz ~/voron-backups/config/ pi@voron.local:~/printer_data/config/
sudo service klipper restart

If you have Samba set up on the Pi, you can also map the config directory as a network drive on Windows or macOS and copy files through the file explorer. This is the least technical option but works well for quick manual saves before config changes.

方法 4：KIAUH 备份功能

KIAUH（Klipper 安装与更新助手）内置了覆盖整个 Klipper 生态系统的备份与恢复功能。如果您使用 KIAUH 安装了 Klipper，可以运行： 

cd ~/kiauh
./kiauh.sh
# Select 4) Advanced -> 9) Backup configuration
# KIAUH creates a timestamped archive of:
#   ~/printer_data/config/
#   ~/klipper/
#   ~/moonraker/
#   ~/klipper-screen/
# Restore via: 4) Advanced -> 10) Restore configuration

The KIAUH backup is comprehensive but manual — you need to run it intentionally. Combine it with one of the automated methods above for complete coverage.

最佳实践

针对您的 Voron 的稳健备份策略包含两个层级：

至少将一份备份存储在设备外部。Pi 上的 SD 卡故障会同时导致您的实时配置和任何本地备份丢失。NAS、第二台 Pi 或私有 GitHub 仓库均可视为外部存储。

灾难恢复场景

MCU 固件损坏

If your BTT Octopus, SKR Turbo, or Fysetc Spider stops responding (Klipper reports mcu 'mcu': Unable to connect), the firmware may be corrupted. Recover by reflashing via DFU mode: 

# Put the board into DFU mode
# BTT Octopus v1.1: hold BOOT button, press RESET, release BOOT
# Check if detected:
lsusb | grep DFU

# Flash the firmware binary directly
cd ~/klipper
make flash FLASH_DEVICE=0483:df11

# If you saved firmware.bin, you can also copy it to an SD card,
# insert it into the board, and power cycle. The board will
# automatically flash from the SD card.

Moonraker 数据库损坏

Moonraker automatically creates a backup file (moonraker.aside) before applying database migrations. If the database becomes corrupted after a failed update: 

sudo service moonraker stop
cp ~/.moonraker_database/moonraker.aside ~/.moonraker_database/moonraker.sqlite
sudo service moonraker start

If the aside file is also corrupted or missing, you can restore from your last full config backup. The database will be rebuilt with saved variables from your save_variables.cfg include file.

SD 卡故障

Raspberry Pi SD 卡是大多数 Voron 构建中的单点故障。如果它完全损坏：

  1. 将全新的Raspberry Pi OS镜像刷写到新SD卡上
  2. 通过KIAUH安装Klipper、Moonraker和Fluidd/Mainsail
  3. Restore ~/printer_data/config/ from your off-device backup
  4. 根据恢复的配置重新编译并刷写每个MCU的固件
  5. 重启Klipper并验证所有轴归零和加热功能正常

MCU 更换——配置迁移

将 BTT Octopus 更换为不同的主板（例如，Octopus v1.1 到 v1.2，或 Octopus 到 Spider）意味着每个引脚名称都会改变。迁移过程： 

# 1. Get the pinout diagram for the new board from the manufacturer
# 2. Map old pin names to new pin names in a spreadsheet
# Example migration: BTT Octopus v1.1 -> Fysetc Spider v2.2
# Octopus: PC0 (stepper X step) -> Spider: PF12 (stepper X step)
# 3. Update printer.cfg with new pin mappings
# 4. Update [mcu] serial path (serial/by-id changes per board)
# 5. Recompile Klipper firmware for the new MCU
# 6. Flash, restart, and test each axis individually

# Find the new serial path
ls -l /dev/serial/by-id/
# Example: usb-Klipper_stm32f446xx_12345-if00

Always keep a copy of your original MCU's Klipper firmware binary alongside your config — if you need to swap back to the original board temporarily, you can reflash without recompiling.

完整备份脚本示例

这是一个全面的备份脚本，涵盖所有内容——配置目录、moonraker 数据库和固件二进制文件——并将它们推送到远程服务器： 

#!/bin/bash
# ~/printer_data/scripts/full-backup.sh
# Full Voron Klipper backup — config, database, firmware

BACKUP_DIR=~/printer_data/backups
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
BACKUP_FILE="$BACKUP_DIR/voron-full-$TIMESTAMP.tar.gz"
REMOTE_USER="backup"
REMOTE_HOST="192.168.1.100"
REMOTE_PATH="/volume1/voron-backups/"

mkdir -p "$BACKUP_DIR"

# 1. Archive config directory
# 2. Copy moonraker database (stop service first to ensure consistency)
sudo service moonraker stop
cp ~/.moonraker_database/moonraker.sqlite "$BACKUP_DIR/moonraker-$TIMESTAMP.sqlite"
sudo service moonraker start

# 3. Include firmware binaries if they exist
if [ -d ~/klipper/out ]; then
    cp ~/klipper/out/klipper.bin "$BACKUP_DIR/firmware-main-$TIMESTAMP.bin"
fi

# 4. Create compressed archive
tar czf "$BACKUP_FILE" -C ~/printer_data config/     -C "$BACKUP_DIR" "moonraker-$TIMESTAMP.sqlite"     --ignore-failed-read

# 5. Push to remote storage
rsync -avz "$BACKUP_FILE" "$REMOTE_USER@REMOTE_HOST:$REMOTE_PATH"

# 6. Clean up local copies older than 30 days
find "$BACKUP_DIR" -name "voron-full-*.tar.gz" -mtime +30 -delete

echo "Backup complete: $BACKUP_FILE"
echo "Pushed to $REMOTE_HOST:$REMOTE_PATH"

Make the script executable and schedule it in cron: 

chmod +x ~/printer_data/scripts/full-backup.sh
# Add to crontab: 0 3 * * * ~/printer_data/scripts/full-backup.sh

使用 Git 进行配置版本管理

For serious config management, git-based versioning is the gold standard. Beyond simple backup, it gives you the ability to:

The git diff command is invaluable for debugging — if a print fails after a config change, run git diff HEAD~1 HEAD to see exactly what you changed.

恢复检查清单

当灾难发生时，请遵循此清单以恢复运行：

  1. Restore ~/printer_data/config/ from backup
  2. 从备份或副本文件中恢复moonraker数据库
  3. Verify [mcu] serial paths match the connected hardware
  4. 如果SD卡或主板被更换，重新刷写每个MCU的固件
  5. Restart Klipper: sudo service klipper restart
  6. Restart Moonraker: sudo service moonraker restart
  7. 测试每个轴是否正确归零
  8. 测试热床加热和挤出机加热
  9. 运行热床网格校准
  10. 打印校准立方体以验证配置完整性

备份纪律是将令人沮丧的重建与五分钟恢复区分开来的关键。从上述四种方法中选择一种——为简单起见选择 moonraker 插件，为高级用户选择 git——并立即设置好。未来凌晨 2 点面对死掉的 SD 卡的您会感谢自己的。

需要为备份就绪的构建准备零件？

我们直接从中国工厂采购高质量的 Voron 组件——正品 Raspberry Pi 5、工业级 SD 卡、BTT Octopus 主板、LDO 步进电机和 Mean Well PSU。每个组件在发货前都经过工作台测试，确保您的 Voron 在可靠的硬件上运行。相比美国/欧盟分销商节省 30-50%。

Shop Tested Components →