> For the complete documentation index, see [llms.txt](https://klipper.3dwork.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://klipper.3dwork.io/klipper/mejoras/backup-klipper.md). # Backup Klipper La mayoría de los usuarios no piensan en el backup hasta que algo sale mal: la SD se corrompe, una actualización rompe algo, o se borra sin querer el `printer.cfg` tras semanas de calibración. En ese momento, tener (o no tener) un backup marca la diferencia entre recuperarse en minutos o empezar desde cero. Esta guía cubre dos estrategias complementarias: | Tipo | Qué cubre | Cuándo usarlo | | ------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------ | | **Imagen completa de SD** | Todo el sistema operativo + Klipper + configuraciones | Antes de actualizaciones importantes, cuando el sistema funciona perfectamente | | **Backup de configuración en GitHub** | Solo los ficheros `.cfg` y scripts | Antes de cualquier cambio de configuración, de forma automatizada | **Recomendación**: usa ambos métodos. La imagen SD te salva si el hardware falla. El backup en GitHub te salva en el día a día cuando tocas algo que no deberías. *** ## ¿Qué ficheros son críticos? Antes de hablar de herramientas, es importante saber qué necesitas guardar realmente: | Fichero / Directorio | Importancia | Descripción | | -------------------------------------- | -------------- | ---------------------------------------------------------- | | `~/printer_data/config/printer.cfg` | **Crítico** | Configuración principal de la impresora | | `~/printer_data/config/moonraker.conf` | **Crítico** | Configuración de la API Moonraker | | `~/printer_data/config/*.cfg` | **Crítico** | Todos los includes, macros, configuraciones adicionales | | `~/printer_data/config/variables.cfg` | **Importante** | Variables persistentes de macros (z-offset guardado, etc.) | | `~/klipper/` | Opcional | El código fuente de Klipper — recuperable con `git pull` | | `~/moonraker/` | Opcional | Código de Moonraker — recuperable | | `~/printer_data/database/` | Opcional | Historial de impresiones, spoolman, estadísticas | {% hint style="warning" %} El directorio `~/printer_data/gcodes/` (archivos de impresión) y los timelapse **no se incluyen** en el backup de configuración. Si los necesitas, inclúyelos manualmente o usa una solución de backup diferente. {% endhint %} *** ## Cuándo hacer backup * **Siempre antes de actualizar** Klipper, Moonraker o cualquier componente del sistema * **Antes de tocar el `printer.cfg`** si vas a hacer cambios importantes * **Tras finalizar una calibración** que te costó tiempo (Input Shaper, Pressure Advance, z-offset) * **Cuando la impresora funciona perfectamente** — ese es el momento ideal, no cuando ya hay problemas *** ## Método 1 — Imagen completa de la SD Una imagen de la SD es una copia bit a bit de todo el sistema: sistema operativo, Klipper, Moonraker, interfaces web, configuraciones y todo lo demás. Si restauras esta imagen en una SD nueva, recuperas exactamente el estado que tenías. {% hint style="info" %} Aunque está enfocado a hosts con SD (Raspberry Pi), la lógica aplica a cualquier host Linux con almacenamiento extraíble. {% endhint %} ### Crear imagen — Windows (Win32DiskImager) * Apaga el host correctamente antes de extraer la SD: ```bash sudo shutdown now ``` O desde la interfaz web de Mainsail/Fluidd → botón de apagado del host. * Extrae la SD e insértala en el PC con Windows * Descarga e instala [**Win32DiskImager**](https://win32diskimager.com/) * Selecciona el **Device** correcto (tu SD) y elige la ruta de destino con extensión `.img`
* Pulsa **Read** y espera a que finalice
### Crear imagen — macOS (Disk Utility) * Inserta la SD en el Mac * Abre **Disk Utility** (Cmd+Space → "Disk Utility") * En el menú **File → New Image → Image from...** selecciona tu SD
* Elige destino y nombre, asegúrate de no marcar encriptación, y pulsa **Save** ### Crear imagen — desde la propia Raspberry Pi Puedes crear la imagen directamente desde el host sin extraer la SD. Necesitas un pendrive USB con espacio suficiente. Conecta el pendrive y comprueba dónde se montó: ```bash # Lanza antes de y después de insertar el pendrive para ver qué apareció nuevo df -h ``` Anota el punto de montaje (ejemplo: `/media/pi/MYBACKUP`). Instala el script de backup: ```bash cd ~ git clone https://github.com/lzkelley/bkup_rpimage.git ``` Lanza el backup: ```bash sudo sh ~/bkup_rpimage/bkup_rpimage.sh start -c /media/pi/MYBACKUP/klipper_backup.img ``` {% hint style="success" %} **Comprimir la imagen con PiShrink** Las imágenes de SD suelen ocupar más de lo necesario. PiShrink las comprime significativamente y facilita restaurarlas en SDs más pequeñas: ```bash wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh sudo chmod +x pishrink.sh sudo mv pishrink.sh /usr/local/bin # Comprimir la imagen recién creada sudo pishrink.sh -z /media/pi/MYBACKUP/klipper_backup.img ``` La opción `-z` crea un archivo `.gz` comprimido. Para restaurarlo, los programas de flasheo lo admiten directamente. {% endhint %} **Automatizar con cron:** ```bash sudo crontab -e ``` Añade una de estas líneas según tu preferencia: ```bash # Backup incremental (sobreescribe siempre el mismo fichero) — cada noche a las 2:00 0 2 * * * sudo sh /home/pi/bkup_rpimage/bkup_rpimage.sh start -c /media/pi/MYBACKUP/klipper_backup.img # Backup con fecha en el nombre — un fichero diferente cada día 0 2 * * * sudo sh /home/pi/bkup_rpimage/bkup_rpimage.sh start -c /media/pi/MYBACKUP/klipper_$(date +%Y-%m-%d).img ``` ### Restaurar la imagen SD {% tabs %} {% tab title="Raspberry Pi Imager (Win/macOS)" %} La opción más sencilla. Descárgalo desde [raspberrypi.com/software](https://www.raspberrypi.com/software/). * Selecciona **Use Custom** como sistema operativo ![](/files/Zbpfy2P3AVkkcojdx0zm) * Selecciona tu imagen `.img` y la SD nueva como destino ![](/files/o4VA0utUTox0vVsUCddH) * Pulsa **Write** y espera ![](/files/FBybmkPhOjOdpT3lUIP3) {% endtab %} {% tab title="balenaEtcher (Win/macOS/Linux)" %} Descarga [**balenaEtcher**](https://www.balena.io/etcher/). * Selecciona **Flash from file** y elige tu imagen * Selecciona la SD nueva como destino
* Pulsa **Flash** y acepta los avisos de seguridad que aparezcan {% endtab %} {% tab title="Win32DiskImager (Windows)" %} * Abre [**Win32DiskImager**](https://win32diskimager.com/) con la nueva SD ya insertada * Selecciona la imagen previamente creada y la SD como destino * Pulsa **Write** (en lugar de Read)
{% endtab %} {% endtabs %} *** ## Método 2 — Backup de configuración en GitHub Este método guarda solo los ficheros de configuración (`.cfg`, scripts, etc.) en un repositorio GitHub privado con historial de versiones. Es el complemento perfecto al método anterior: más rápido, siempre accesible online y con control de cambios. Ventajas respecto a la imagen de SD: * Se lanza con una macro desde Mainsail/Fluidd en segundos * Puedes ver qué cambió entre versiones y revertir a un punto concreto * Accesible desde cualquier ordenador sin extraer la SD * No necesitas hardware adicional ### Paso 1 — Crear el repositorio en GitHub Si no tienes cuenta en GitHub, créala en [github.com/signup](https://github.com/signup) (cuenta gratuita). * Haz login y crea un nuevo repositorio pulsando **New** ![](/files/-MlOxWk2t2xzzSyEegU4) * Dale un nombre descriptivo (ej: `voron24_klipper_config`) y elige si quieres que sea **Private** (recomendado — tus configs pueden contener datos de red)
* Anota la URL del repositorio — la necesitarás más adelante:
### Paso 2 — Crear el token de acceso El script de backup necesita un token para autenticarse con GitHub desde el host. * Ve a [**GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)**](https://github.com/settings/tokens) * Pulsa **Generate new token (classic)**
* Dale un nombre descriptivo (ej: `klipper-backup-voron`) * Expiration: puedes usar **No expiration** o una fecha larga — si el token expira, el backup dejará de funcionar silenciosamente * Permisos necesarios: marca **`repo`** (acceso completo al repositorio)
* Pulsa **Generate token** y **copia el token inmediatamente** — solo se muestra una vez. Guárdalo en un lugar seguro.
### Paso 3 — Instalar la extensión G-Code Shell Command El backup se lanza mediante una macro de Klipper que ejecuta un script shell. Para eso necesitas la extensión `gcode_shell_command`. **Instalación desde KIAUH (recomendada):** ``` Menú principal → 4) Advanced → 9) Shell Command Extension ``` ![](/files/e107WthvHiJlyYyBWXWc) **Instalación manual:** ```bash # Descarga el plugin desde el repositorio de KIAUH wget -O ~/klipper/klippy/extras/gcode_shell_command.py https://raw.githubusercontent.com/dw-0/kiauh/master/kiauh/resources/gcode_shell_command.py # Reinicia Klipper para que cargue la extensión sudo systemctl restart klipper ``` ### Paso 4 — Descargar y configurar el script de backup ```bash cd ~/printer_data/config # Descarga el script wget -O 3dwork-autocommit.sh https://raw.githubusercontent.com/3dwork-io/3dwork-klipper/master/scripts/3dwork-autocommit.sh ``` Edita el script para adaptarlo a tu instalación: ```bash nano ~/printer_data/config/3dwork-autocommit.sh ``` Ajusta estas variables al principio del fichero: ```bash ### Directorio de configuración de Klipper (obligatorio) config_folder=~/printer_data/config ### Directorio de Klipper (opcional, descomenta si quieres incluirlo) klipper_folder=~/klipper ### Directorio de Moonraker (opcional) moonraker_folder=~/moonraker ### Interfaz web — descomenta solo la que uses mainsail_folder=~/mainsail #fluidd_folder=~/fluidd ### Rama del repositorio (normalmente main o master — verifica en tu repo) branch=main ``` Guarda con `Ctrl+X` → `Y` → `Enter` y dale permisos de ejecución: ```bash chmod +x ~/printer_data/config/3dwork-autocommit.sh ``` {% hint style="warning" %} Si editas el script desde Mainsail o Fluidd (editor web), los permisos de ejecución se pierden. Tendrás que volver a ejecutar `chmod +x` desde SSH. {% endhint %} ### Paso 5 — Configurar el repositorio git local ```bash # Instala git si no está disponible sudo apt-get install git -y # Ve al directorio de configuración cd ~/printer_data/config # Inicializa el repositorio local git init # Configura tu identidad (git lo requiere para los commits) git config --global user.email "tu@email.com" git config --global user.name "Tu Nombre" # Añade el repositorio remoto de GitHub # Sustituye TU_TOKEN y la URL por los tuyos git remote add origin https://TU_TOKEN@github.com/tu-usuario/tu-repo.git # Verifica que se añadió correctamente git remote -v ```
Haz el primer commit y push: ```bash git branch -M main # Asegura que la rama se llama main git add . # Añade todos los ficheros al commit git commit -m "Primer backup" git push -u origin main # Sube al repositorio remoto # Prueba el script para verificar que funciona sh ~/printer_data/config/3dwork-autocommit.sh ```
### Paso 6 — Crear la macro de Klipper Añade esto a tu `printer.cfg` o a un fichero de macros: ```ini [gcode_shell_command backup_cfg_github] command: sh /home/pi/printer_data/config/3dwork-autocommit.sh timeout: 30. verbose: True [gcode_macro BACKUP_CFG_GITHUB] description: Sube los ficheros de configuración a GitHub gcode: RUN_SHELL_COMMAND CMD=backup_cfg_github ``` {% hint style="warning" %} Ajusta la ruta en `command:` al path real de tu script. Si tu usuario no es `pi` (es el caso en sistemas más nuevos), el path será diferente — usa `echo $HOME` en SSH para comprobarlo. El `timeout` de 30 segundos puede quedarse corto si el repositorio tiene muchos ficheros o la conexión es lenta. Sube a 60 si experimentas timeouts. {% endhint %} Ahora puedes lanzar el backup desde la sección de Macros de Mainsail o Fluidd: ![](/files/La05vihTBhmqwFyyCo3B) En la consola verás el progreso: ![Ejemplo de consola durante el backup](/files/MzcHI5DPkUou9xcElGQB) Y en GitHub tendrás el historial completo de cambios:
### Automatizar el backup al final de cada impresión La mejor estrategia es lanzar el backup automáticamente cuando termina una impresión. Añade la llamada a tu macro `PRINT_END` (o donde finalices tus impresiones): ```ini [gcode_macro PRINT_END] gcode: # ... tu código de fin de impresión ... M84 # Desactiva motores BACKUP_CFG_GITHUB # Backup automático al terminar ``` Así cada vez que acaba una impresión tienes una copia actualizada en GitHub sin tener que recordarlo. *** ## Método 3 — KGB (Klipper Git Backup) [**KGB**](https://github.com/Low-Frequency/Klipper-Git-Backup) es una alternativa al script anterior creada por la comunidad, con un asistente de configuración propio y arranque automático con el sistema. {% hint style="warning" %} Si ya tienes configurado el método anterior (script 3dwork-autocommit), no necesitas KGB. Elige uno de los dos. {% endhint %} **Instalación:** ```bash sudo apt-get install git -y cd ~ && git clone https://github.com/Low-Frequency/Klipper-Git-Backup.git chmod +x ~/Klipper-Git-Backup/*.sh ./Klipper-Git-Backup/kgb.sh ``` El asistente te guiará por la configuración:
Como mínimo configura la opción **1) Configure** con tu usuario de GitHub, email, URL del repositorio y directorio de configuración. {% hint style="warning" %} **Clave SSH requerida por KGB** Durante la configuración, KGB genera una clave SSH pública que debes añadir a tu cuenta de GitHub: GitHub → **Settings → SSH and GPG keys → New SSH key** Pega la clave pública que te mostró KGB. {% endhint %} KGB se ejecuta automáticamente al arrancar el host y hace push a GitHub cuando hay conexión disponible. *** ## Restaurar la configuración desde GitHub Este es el paso más importante — el que necesitarás cuando algo salga mal. ### Restauración rápida (sobreescribir con lo que hay en GitHub) ```bash cd ~/printer_data/config git fetch --all # Sobreescribe todo el directorio config con el contenido de GitHub # CUIDADO: esto borra los cambios locales no subidos git reset --hard origin/main ``` {% hint style="danger" %} `git reset --hard` borra **todo** lo que tengas en el directorio config que no esté en GitHub. Antes de ejecutarlo, asegúrate de que tienes el estado correcto en el repositorio remoto. {% endhint %} ### Restauración en instalación nueva Si la SD murió y estás empezando desde cero con MainsailOS: ```bash # 1. Instala las dependencias básicas sudo apt-get install git -y # 2. Clona directamente tu repositorio en el directorio de config # (si el directorio ya existe, hazlo en uno temporal y luego mueve los ficheros) cd ~ git clone https://github.com/tu-usuario/tu-repo.git printer_data/config # 3. Reinicia Klipper para que cargue la configuración sudo systemctl restart klipper sudo systemctl restart moonraker ``` ### Recuperar una versión anterior de un fichero concreto Una de las ventajas del control de versiones es poder recuperar un fichero concreto de un momento específico sin afectar al resto: ```bash cd ~/printer_data/config # Ver el historial de commits git log --oneline # Recuperar printer.cfg de un commit específico (sustituye HASH por el id del commit) git checkout HASH -- printer.cfg # O recuperar el fichero tal como estaba hace 3 commits git checkout HEAD~3 -- printer.cfg ``` Esto es especialmente útil cuando haces un cambio en la configuración y rompes algo — puedes recuperar exactamente cómo estaba antes sin restaurar todo. *** ## Checklist de backup Antes de hacer cualquier cambio importante en tu impresora, verifica: * [ ] ¿Tienes una imagen SD reciente del sistema funcionando? * [ ] ¿Está el repositorio GitHub actualizado con el estado actual? * [ ] ¿Está el `variables.cfg` (z-offset, PA, etc.) incluido en el backup? * [ ] ¿Sabes dónde está guardado el token de GitHub (por si expira)? * [ ] ¿Probaste alguna vez restaurar desde el backup? (hazlo antes de necesitarlo de verdad)