# 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) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://klipper.3dwork.io/klipper/mejoras/backup-klipper.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.