Cómo restaurar Home Assistant después de una actualización fallida del contenedor

Eva Wong es la redactora técnica y manitas residente en ZimaSpace. Es una geek de toda la vida apasionada por los laboratorios domésticos y el software de código abierto, y se especializa en traducir conceptos técnicos complejos en guías prácticas y fáciles de seguir. Eva cree que alojar servicios propios debería ser divertido, no intimidante. A través de sus tutoriales, ayuda a la comunidad a desmitificar la configuración del hardware, desde montar su primer NAS hasta dominar los contenedores Docker.

Por lo general, un fallo al actualizar un contenedor de Home Assistant debe tratarse como un problema de sustitución del entorno de ejecución, no como una razón para crear una instalación nueva. Si el directorio /config montado desde el host está intacto, la ruta de recuperación más segura es conservar ese estado, verificar la asignación del volumen, iniciar una imagen conocida como funcional y probar la instalación existente antes de restaurar una copia de seguridad anterior.

El paso peligroso es permitir que un contenedor nuevo se inicie con una ruta del host incorrecta o vacía. Entonces, Home Assistant puede mostrar el proceso de configuración inicial como si la configuración hubiera desaparecido, mientras el estado original sigue existiendo en otra ubicación del disco. Primero, congela los cambios, identifica el directorio de configuración autorizado y no elimines el contenedor ni el directorio antiguos hasta que la instancia recuperada supere las pruebas.

Detén las nuevas escrituras y encuentra la ruta real de /config

Detén el contenedor que falla e inspecciona la definición de ejecución que lo creó. Confirma qué directorio del host o volumen con nombre está asignado a /config y luego inspecciona esa ubicación para encontrar tus archivos YAML, .storage, componentes personalizados, secretos y base de datos.

Un caso de recuperación de la comunidad tras una actualización de Docker reveló que una instancia de Home Assistant «completamente nueva» se debía en realidad a que el contenedor apuntaba a una carpeta de configuración incorrecta. Los datos persistentes no se habían borrado; simplemente, el nuevo entorno de ejecución no los estaba montando correctamente.

Copia o crea una instantánea del directorio de configuración actual antes de cambiar permisos, rutas o archivos de la base de datos. Incluso un estado parcialmente dañado es una prueba valiosa y puede contener automatizaciones o credenciales más recientes que la última copia de seguridad.

Recrear el entorno de ejecución sin recrear la instalación

Usa el mismo modo de red, la zona horaria, las asignaciones de dispositivos, el acceso a la radio USB, los privilegios o capacidades y el montaje del host en /config que usaba el contenedor funcional antes de la actualización. La imagen se puede reemplazar; esos parámetros de ejecución y los datos persistentes determinan si el servicio vuelve como la misma instancia de Home Assistant.

La persistencia del contenedor depende del montaje del host, no del sistema de archivos del contenedor. Un ejemplo de Home Assistant Container monta un volumen persistente del host directamente en /config, de modo que recrear el entorno de ejecución no vuelve a crear la configuración del hogar. Si esa asignación cambia durante una actualización, el contenedor de reemplazo puede parecer nuevo aunque el estado original siga existiendo en otro lugar.

No copies el sistema de archivos del contenedor antiguo en la nueva imagen. Vuelve a crear la implementación a partir de una definición documentada de Compose o de ejecución y vuelve a conectar explícitamente el estado persistente.

Revierte la imagen antes de restaurar un estado anterior

Si el montaje de configuración es correcto, pero la nueva versión de Home Assistant no se inicia o interrumpe una integración crítica, prueba la imagen anterior que se sabe que funcionaba con el mismo /config preservado. Así podrás distinguir entre «el nuevo entorno de ejecución es incompatible con el estado actual» y «el estado está dañado».

El flujo de trabajo actual de Home Assistant Container separa explícitamente la imagen del estado persistente: primero haz una copia de seguridad, descarga la imagen de destino, vuelve a crear el contenedor y usa una etiqueta específica de una imagen anterior cuando sea necesario revertir la versión. Ese es el límite de recuperación que debes preservar: reemplazar el entorno de ejecución sin alterar la ruta de configuración autorizada.

Al revertir, recuerda que algunas actualizaciones migran las estructuras de datos. Usa una copia de seguridad anterior a la migración si la versión antigua no puede leer de forma segura un estado que la nueva ya actualizó. No alternes versiones repetidamente usando la única copia de los datos persistentes.

Restaura una copia de seguridad solo cuando el estado actual no sea fiable

Usa una copia de seguridad cuando falte la configuración persistente, esté dañada, se haya sobrescrito parcialmente o ya no sea compatible con la versión que puedes ejecutar de forma segura. Cuando sea posible, restaura en un destino aislado o limpio para poder comparar el estado recuperado con la copia dañada.

Guarda fuera del host averiado la contraseña de cifrado o el kit de emergencia necesarios para abrir la copia de seguridad. Una copia de seguridad que solo existe en el mismo disco o que no se puede descifrar no ofrece una vía de recuperación.

El ejemplo de ZimaSpace sobre separar la recuperación de Home Assistant del propio host de almacenamiento refuerza la misma regla: el estado de la aplicación necesita una ruta de restauración independiente, no solo un disco activo duplicado.

Valida el contenedor recuperado antes de eliminar nada

  • Confirma que estén presentes los usuarios, paneles, integraciones, automatizaciones, ayudantes y áreas esperados.
  • Verifica una ruta de dispositivo local y otra de radio si se utilizan Zigbee, Z-Wave o Bluetooth.
  • Comprueba si Recorder informa de errores en la base de datos o en la migración.
  • Reinicia el contenedor recuperado y confirma que vuelve a aparecer el mismo estado.
  • Conserva la etiqueta de la imagen antigua, una copia de la configuración y la última copia de seguridad que se sabe que funciona hasta que se complete correctamente este segundo arranque.

Si la imagen antigua con la configuración original funciona, la actualización fallida se debió principalmente a un problema del entorno de ejecución o de la versión. Si ninguna imagen funciona con el mismo estado, pasa a reparar la configuración o a restaurar una copia de seguridad. Si un contenedor limpio solo funciona con un /config vacío, no des por «resuelto» el problema con la configuración inicial hasta entender qué impide la recuperación en el estado persistente.

Preguntas frecuentes

¿Debo eliminar el contenedor de Home Assistant que falló antes de solucionar el problema?

No. Detén el contenedor primero y conserva su definición de ejecución y la ruta de configuración montada. Puedes crear un contenedor de reemplazo sin eliminar el que falló, lo que mantiene disponible la información para revertir el cambio mientras compruebas el nuevo entorno de ejecución.

¿Por qué Home Assistant muestra la configuración inicial después de una actualización?

La razón más común específica de los contenedores es que el entorno de ejecución de reemplazo no está viendo la ruta original /config. Verifica el montaje del host antes de asumir que se borró la configuración o de restaurar una copia de seguridad antigua sobre un estado más reciente.

Soporte y consejos

Más para leer

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.