Respaldar volúmenes de Docker de impresión 3D

Coge el archivo de copia de seguridad que genera la propia aplicación y replícalo fuera del host, y después haz una instantánea de los volúmenes con nombre con las escrituras pausadas si además quieres recuperar el estado exacto de la máquina. Copiar el directorio de un volumen en caliente, con el stack en marcha, es el único método que parece una copia de seguridad y en silencio no lo es, porque una base de datos SQLite copiada a mitad de una escritura puede restaurarse en un archivo que abre bien y le faltan las últimas transacciones.

En un PrintStash sobre Docker hay cinco volúmenes con nombre en el stack por defecto, y solo dos importan para recuperarse. Saber cuáles son esos dos es casi todo el trabajo.

Qué hay en cada volumen

El archivo de Compose por defecto monta estos en el contenedor de la API:

Volumen	Montado en	Contiene	¿Respaldarlo?
printstash_db	/data/db	La base de datos SQLite y la clave de secretos generada	Sí, este es el importante
printstash_data	/data/files	Los bytes de modelos, G-code y documentos que PrintStash posee	Sí
printstash_thumbs	/data/thumbs	Las miniaturas generadas	Opcional, se regeneran
printstash_staging	/data/staging	Espacio temporal para importaciones en curso	No
printstash_backups	/data/backups	Los archivos de copia que escribe la aplicación	Cópialos fuera, no dependas de ellos aquí

Otros dos aparecen solo con un perfil activado: printstash_postgres cuando ejecutas el perfil de Postgres en lugar de SQLite, y printstash_seaweedfs cuando usas el servicio compatible con S3 que viene incluido. Si usas cualquiera de los dos, ese volumen sustituye o complementa al de arriba, y se aplica la misma regla: respalda lo que de verdad guarda tus bytes.

El detalle que conviene fijar está dentro de printstash_db. Junto a la base de datos vive .printstash-secrets-key, generada en el primer arranque cuando VAULT_SECRETS_KEY no está definida. Es lo que descifra las claves de API de impresora guardadas, los códigos de acceso de Bambu y el secreto de cliente de OIDC. Restaura una base de datos sin ella y la bóveda vuelve con esos campos ilegibles.

Tu archivo .env no está en ningún volumen. Vive en el host, al lado del archivo de compose, y contiene VAULT_JWT_SECRET, las credenciales de almacenamiento y posiblemente VAULT_SECRETS_KEY. Respáldalo por separado, en un sitio que no sea un repositorio público.

Primero el archivo, después la instantánea

PrintStash crea una copia de seguridad completa a demanda a través de su API, y el archivo contiene la base de datos, los blobs que PrintStash posee, los documentos, las miniaturas y un manifiesto. Desde la v0.11.3, la parte de SQLite es una instantánea transaccionalmente consistente que incluye los datos del WAL ya confirmados, y el conjunto de blobs se toma de esa misma instantánea.

Esa es la diferencia importante frente a un cp -r sobre el directorio del volumen. El archivo está coordinado con la base de datos; una copia de sistema de archivos de una base de datos SQLite en marcha no lo está, y el fallo aparece en el momento de restaurar, no en el de respaldar.

Así que la rutina que sobrevive a un mal día:

1. Pausa a quien escribe. Los hooks de posprocesado del slicer, las importaciones programadas, cualquier cosa con una clave de API.

2. Lanza una copia de seguridad completa por la API. Necesita un superusuario; PrintStash no lleva su propio planificador, así que lo que la hace periódica es un cron o un temporizador de systemd.

3. Saca el archivo del host. La replicación a un bucket compatible con S3 viene integrada, y automatizar copias de seguridad en S3 cubre los ajustes del bucket y la llamada de programación.

4. Si quieres recuperar el stack entero y no solo la biblioteca, haz también una instantánea de printstash_db y printstash_data, con la API parada:

   docker compose stop api
   docker run --rm -v printstash_db:/src:ro -v "$PWD":/out alpine \
     tar czf /out/printstash_db.tgz -C /src .
   docker run --rm -v printstash_data:/src:ro -v "$PWD":/out alpine \
     tar czf /out/printstash_data.tgz -C /src .
   docker compose start api

5. Restaura una en un stack de pruebas y abre un modelo que reconozcas. Hasta que eso haya pasado, lo que tienes es un archivo, no un procedimiento de recuperación.

Lo que una instantánea de volumen no te devuelve

Los archivos que indexas en su sitio no están en nada de esto. Una carpeta del NAS añadida como biblioteca externa se lee donde vive, PrintStash nunca posee esos bytes, y quitar un modelo o el volumen nunca los borra. No están en el archivo de copia y tampoco están en printstash_data, así que tu política de instantáneas del NAS tiene que cubrirlos. Esa separación es deliberada y es la parte que la gente descubre en el peor momento.

Restaurar es una vuelta atrás, no una fusión. La restauración integrada valida y prepara la base de datos y los blobs antes de aplicar nada, pausa a quien esté escribiendo mientras trabaja, y deshace los cambios de almacenamiento si falla a medio camino. Lo que no hace es reconciliar una base de datos restaurada con los archivos añadidos después de la copia.

Un cambio de la v0.12.0 pertenece a cualquier conversación sobre distribución del almacenamiento: el mantenimiento de arranque y el horario ya no deducen la propiedad de los archivos borrando objetos no indexados, y las rutas de la bóveda local en el primer arranque tienen que ser ahora directorios escribibles, dedicados y vacíos. Si tu volumen /data/files es una carpeta compartida que contiene otras cosas, mueve ese contenido a External Libraries.

Preguntas que surgen

¿Puedo copiar sin más la carpeta de /var/lib/docker/volumes?

Puedes, y está bien para los volúmenes que guardan archivos normales, pero no para la base de datos mientras la API está en marcha. SQLite en modo WAL mantiene las transacciones recientes en un archivo auxiliar, así que una copia tomada a mitad de una escritura puede producir una base de datos que abre limpiamente y le falta el trabajo más reciente, que es el peor tipo de fallo porque nada se queja hasta que vas a buscar algo. Para primero el contenedor de la API, o usa el archivo de copia integrado, que se coordina con la base de datos en lugar de copiar a su alrededor.

¿Tengo que parar todo el stack para hacer una instantánea?

Parar el contenedor de la API es suficiente, y es el contenedor que escribe. El frontend no guarda estado. Si prefieres no parar nada, haz el archivo de copia integrado y acepta que cubre los datos propios de PrintStash en lugar de los bytes exactos en disco, que para casi cualquier recuperación es lo que querías de verdad.

¿Qué pasa si restauro la base de datos sin la clave de secretos?

La bóveda arranca, tus modelos y tu historial están intactos, y todos los campos cifrados fallan al descifrarse. En la práctica eso significa que hay que volver a introducir las claves de API de impresora guardadas, los códigos de acceso de Bambu LAN y el secreto de cliente de OIDC. Guarda .printstash-secrets-key de dentro de printstash_db, o define VAULT_SECRETS_KEY explícitamente en .env y respalda ese archivo, que es el arreglo más limpio porque convierte la clave en algo que gestionas tú y no en algo generado donde puede que no vayas a buscarlo.

¿Los archivos que están en printstash_backups ya están a salvo?

No, están en el mismo host y a menudo en el mismo disco que los datos que protegen. Eso cubre una actualización que sale mal o un borrado por error, que es el caso habitual, y no cubre nada de un disco averiado, una máquina perdida o un docker compose down -v que se lleva por delante los volúmenes con nombre. Replícalos a un bucket o a otra máquina, y descarga uno de vez en cuando para que exista una copia en algún sitio al que no lleguen ni la aplicación ni su host.

¿La copia de seguridad incluye mi carpeta de STL en el NAS?

No, por diseño. Una carpeta indexada como biblioteca externa sigue siendo tuya: PrintStash la lee en su sitio, escribe archivos nuevos en ella sin sobrescribir rutas existentes, y nunca borra los bytes de origen. Eso significa que el archivo de copia cubre los metadatos, las revisiones, los resultados y el historial de la biblioteca para esos modelos, mientras que de las mallas se encarga lo que respalde el NAS. Las dos mitades necesitan un plan, y solo una de ellas es trabajo de PrintStash. Copias de seguridad que sí se restauran cubre el modelo de recuperación completo.

Fuentes

• PrintStash docker-compose.yml para los volúmenes con nombre y sus puntos de montaje, backend/app/core/config.py para el directorio de copias y la ruta por defecto del archivo de clave de secretos, y backend/app/core/secrets.py para cómo se cifran los secretos guardados, en el repositorio. Consultado el 20 de agosto de 2026.
• La guía de copia de seguridad y restauración para el contenido del archivo y el comportamiento de la restauración, y las notas de la versión v0.12.0 para los cambios en el mantenimiento de arranque y en las rutas de la bóveda en el primer arranque.