Para pasar de Uptime Kuma 1.23 a la versión 2 en Docker, para el contenedor, archiva el directorio data y cambia la imagen a louislam/uptime-kuma:2.5.9; latest no sirve, porque sigue apuntando a la 1.23.17. El primer arranque de la 2 convierte el historial de latidos en tablas agregadas y después borra los latidos brutos, así que no lo interrumpas y guarda la copia: es la única vuelta atrás fiable. Esta guía repite esa actualización el 18 de octubre de 2026 sobre una instalación con monitores, notificaciones e historial, y documenta lo que se rompió. La misma guía está disponible en inglés.

Puntos clave

  • louislam/uptime-kuma:latest y :1 siguen sirviendo la 1.23.17 (Node.js 18, Debian 10). Para la versión 2 hay que pedir :2 o, mejor, una versión fija como 2.5.9.
  • La migración agrega cada día de cada monitor en stat_daily, stat_hourly y stat_minutely. En mi prueba pasó de 604.866 latidos a 11.014 y la disponibilidad a 30 días siguió en 99,90 %.
  • Si la paras a medias, la 2.5.6 no vuelve a arrancar: Failed to prepare your database: Aggregate table migration is already in progress. Se arregla restaurando la copia o con npm run reset-migrate-aggregate-table-state.
  • Pasar a MariaDB al actualizar no migra nada: con UPTIME_KUMA_DB_TYPE=mariadb la 2.5.6 arrancó vacía y pidió crear el usuario administrador.
  • La 1.23.17 arranca sin quejarse sobre una base ya migrada, pero calcula mal: mostró un 97,07 % a 30 días en lugar del 99,90 %. Vuelve atrás restaurando el archivo, no cambiando la etiqueta.

Qué cambia en Uptime Kuma 2 y por qué latest no te actualiza

Uptime Kuma 2 es la siguiente versión mayor tras la rama 1.23. La 2.0.0 salió el 20 de octubre de 2025 y, a 2 de noviembre de 2026, la última estable es la 2.5.9, del 31 de octubre. La 1.23.17 se publicó el mismo día que la 2.0.0 y es la última de la rama 1. El cambio de fondo es la base de datos: la 2 deja de calcular la disponibilidad recorriendo la tabla de latidos y la guarda agregada por minuto, hora y día.

La 2.5.9 corrige un envenenamiento de la caché del RSS[1] de las páginas de estado que no exige cuenta y afecta desde la 2.1.0. Es la versión a la que conviene ir. La 2.5.8 ya había cerrado una ejecución remota de código[2] al alcance de los administradores. La migración desde la 1.23 la probé con la 2.5.6, del 9 de octubre. El 2 de noviembre pasé a la 2.5.9 una instalación 2.5.8 con dos monitores, una notificación y una página de estado, y siguió todo en su sitio.

La etiqueta latest no te mueve a la 2. La página de etiquetas de la wiki oficial lo dice así: "latest tag is deprecated, which is always pointing to v1." Lo comprobé leyendo package.json dentro de cada imagen:

for t in latest 1.23.17 2.5.6; do
  docker run --rm --entrypoint node louislam/uptime-kuma:$t \
    -e "console.log(require('/app/package.json').version)"
done

La salida fue 1.23.17, 1.23.17 y 2.5.6. Si actualizas tus contenedores con Watchtower y tu Compose dice latest, nunca recibirás la 2. Si aún no tienes Uptime Kuma, empieza por la guía para instalar Uptime Kuma; esta parte de una instalación como aquella.

La guía de migración de la wiki enumera los cambios incompatibles. Los que afectan a una instalación en Docker son estos:

Cambio Qué notas
Badges con :duration limitado /api/badge/1/uptime/1440 devuelve 403; el máximo es 720 horas o 365 días
Copia de seguridad en JSON eliminada Solo queda copiar el directorio data
Caché DNS de los monitores HTTP eliminada La wiki propone el nscd que trae la imagen
Reintentos por defecto de 1 a 0 Solo en monitores nuevos; los existentes conservan su valor
Plantillas de correo con LiquidJS Variables sensibles a mayúsculas
Imágenes Alpine y Debian Buster en el host Sin soporte; en Buster la wiki desaconseja actualizar

Cómo he probado la actualización

Monté Uptime Kuma 1.23.17 con Docker Compose 2.40.3 y Docker 29.5.2 en una máquina Linux arm64 de 18 núcleos, con los datos en un directorio ./data montado en /app/data. Creé 8 monitores: HTTP, palabra clave, TCP, ping, DNS, uno HTTP que falla a propósito y uno de tipo push. Añadí una notificación SMTP hacia un Mailpit, una página de estado y una ventana de mantenimiento.

Para tener historial que migrar, inserté en SQLite 60 días de latidos sintéticos de un minuto para 7 monitores, con una caída cada 997 minutos. Después dejé correr la instancia unos minutos con latidos reales. La tabla heartbeat quedó con 604.866 filas y kuma.db ocupaba 89,9 MB. Es un volumen comparable al ejemplo de la wiki (20 monitores y 90 días), aunque mis latidos son artificiales y la carga de la máquina era alta, así que no publico tiempos.

Paso 1: haz la copia de seguridad del directorio data con Uptime Kuma parado

La wiki insiste tres veces en la copia del directorio data, y es lo único que te deja volver a la 1.23. La 2 ya no tiene la exportación a JSON de los ajustes, así que la copia del directorio es el único método admitido. Fija la versión en un .env para que el cambio sea una sola línea:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:${KUMA_TAG}
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data

El .env contiene KUMA_TAG=1.23.17. Con eso, para el contenedor y archiva el directorio desde un contenedor auxiliar, porque los ficheros pertenecen a root:

docker compose stop uptime-kuma
docker run --rm -v "$PWD/data":/data:ro \
  -v "$PWD/backup":/backup alpine:3.22 \
  tar czf /backup/kuma-data-1.23.17.tar.gz -C /data .

Parar antes de copiar importa: SQLite en modo WAL guarda los cambios recientes en kuma.db-wal, y una copia en caliente puede quedar incoherente. Mi archivo ocupó 17,5 MB. Si usas un volumen con nombre en lugar de ./data, cambia la ruta del primer -v por el nombre del volumen. Si ya haces copias cifradas con restic, añade este fichero antes de seguir.

Paso 2: cambia la imagen a 2.5.9 y sigue el registro de la migración

Con la copia hecha, la actualización es una línea del .env y un up -d. Usa 2.5.9 en lugar de 2 si quieres decidir tú cuándo cambia la versión:

sed -i 's/^KUMA_TAG=.*/KUMA_TAG=2.5.9/' .env
docker compose up -d uptime-kuma
docker compose logs -f uptime-kuma

El registro empieza creando data/db-config.json con "type": "sqlite" y, a continuación, abre un servidor de migración en el puerto 3001. Mientras dura, la interfaz web solo muestra "Migration is in progress, it may take some time" y un enlace a /migrate-status con el progreso. En la consola verás una línea por cada día de cada monitor:

[DB] INFO: Migrating Aggregate Table
[DB] INFO: Getting list of unique monitors
[DB] INFO: [DON'T STOP] Migrating monitor 1s' (1 of 8 total)
  data - 2026-08-19 - total migration progress 0.00%
[DB] INFO: Clearing non-important heartbeats
[DB] INFO: Deleting non-important heartbeats for monitor 1
[DB] INFO: Aggregate Table Migration Completed

Mi migración escribió 428 líneas [DON'T STOP] y dejó 428 filas en stat_daily, 5.048 en stat_hourly y 9.779 en stat_minutely. Al terminar, la 2.5.6 arrancó la interfaz normal con los 8 monitores, la notificación, la página de estado y el mantenimiento. La disponibilidad a 30 días del monitor web-nginx era 99,90 % antes y después, y la de 24 horas, 99,93 %.

Qué borra la migración y cuánto ocupa la base de datos después

La migración borra los latidos que ya no necesita: tras agregar, clearHeartbeatData elimina de cada monitor los latidos no importantes de más de 24 horas y conserva las últimas 100 filas. En mi prueba la tabla heartbeat bajó de 604.866 filas a 11.014. Lo que queda son los cambios de estado (los latidos "importantes") y el último día completo; el detalle minuto a minuto anterior solo vive ya en las tablas agregadas.

El fichero no encoge solo. Tras migrar, kuma.db ocupaba 97 MB y kuma.db-wal otros 63,1 MB, porque SQLite no devuelve el espacio de las filas borradas hasta un VACUUM. La 2 lo lanza desde Settings > Monitor History > Shrink Database; yo lo ejecuté con el contenedor parado y el fichero bajó a 2,2 MB:

Tamaño de kuma.db en cada fase de la actualización MB
1.23.17 antes de actualizar
kuma.db: 89,9 MB
kuma.db-wal: 0 MB
2.5.6 tras la migración
kuma.db: 97,0 MB
kuma.db-wal: 63,1 MB
2.5.6 tras VACUUM
kuma.db: 2,2 MB
kuma.db-wal: 0 MB
Ver tabla de valores
Fasekuma.dbkuma.db-wal
1.23.17 antes de actualizar89,9 MB0 MB
2.5.6 tras la migración97,0 MB63,1 MB
2.5.6 tras VACUUM2,2 MB0 MB

Uptime Kuma 1.23.17 y 2.5.6 en Docker sobre Linux arm64, 8 monitores y 604.866 latidos (60 días sintéticos), 18 de octubre de 2026.

Si quieres conservar el detalle de cada latido de los últimos meses, quédate con el archivo del paso 1: es la única copia que lo tiene.

Error "Aggregate table migration is already in progress" al arrancar la 2

Este error aparece cuando la migración se cortó a medias, y la 2.5.6 se niega a arrancar hasta que lo arregles. Lo reproduje con docker kill al 47,54 % del progreso, que es lo que pasa si reinicias el host o si un orquestador mata el contenedor porque tarda. Al arrancar de nuevo, el registro dijo:

[DB] WARN: Aggregate table migration is already in progress,
  or it was interrupted
[DB] ERROR: Database migration failed
[SERVER] ERROR: Failed to prepare your database: Aggregate
  table migration is already in progress

El contenedor sale con código 1, y con restart: unless-stopped entra en bucle. La causa es el ajuste migrateAggregateTableState, que vale migrating desde que empieza la agregación hasta que termina. La wiki da una sola solución: restaurar la copia y repetir la actualización. El código de la 2.5.6 trae además un script que vacía las tres tablas stat_* y pone el estado en blanco:

docker compose stop uptime-kuma
docker run --rm -v "$PWD/data":/app/data \
  --entrypoint npm louislam/uptime-kuma:2.5.9 \
  run reset-migrate-aggregate-table-state
docker compose up -d uptime-kuma

Funcionó porque el borrado de latidos solo ocurre al final de la migración, así que tras un corte los datos brutos siguen ahí. La segunda pasada terminó con las mismas 428 filas diarias y 5.048 horarias que la migración sin cortes. Si el corte llegó durante "Clearing non-important heartbeats", restaura la copia.

¿Conviene pasar a MariaDB al actualizar a Uptime Kuma 2?

No, si lo que quieres es conservar tus monitores. La 2 admite MariaDB como base de datos, pero la wiki es tajante con el paso desde SQLite: "CANNOT be done directly and is not supported by official". Probé el atajo obvio, arrancar la 2.5.6 sobre el data de la 1.23 con las variables de MariaDB 11.8:

    environment:
      UPTIME_KUMA_DB_TYPE: "mariadb"
      UPTIME_KUMA_DB_HOSTNAME: "mariadb"
      UPTIME_KUMA_DB_PORT: "3306"
      UPTIME_KUMA_DB_NAME: "kuma"
      UPTIME_KUMA_DB_USERNAME: "kuma"
      UPTIME_KUMA_DB_PASSWORD: "tu_contrasena_de_mariadb"

El registro dijo UPTIME_KUMA_DB_TYPE is provided by env, try to override db-config.json, creó las tablas en MariaDB, informó No data to migrate y terminó en No user, need setup. La base kuma quedó con 0 monitores y 0 usuarios, y kuma.db siguió en el disco sin tocar. Además, db-config.json guarda la contraseña de MariaDB en texto plano dentro de data, así que trata ese directorio como un secreto.

Mi recomendación es actualizar sobre SQLite y quedarte ahí salvo que tengas un motivo concreto. Si quieres MariaDB, monta una instalación nueva de la 2 y vuelve a crear los monitores; la guía de MariaDB con Docker cubre el servidor. La imagen completa trae además un MariaDB embebido y Chromium para el monitor de tipo navegador; la -slim no trae ninguno de los dos. Docker Hub da para arm64 602,8 MB a la 2.5.6, 180 MB a la 2.5.6-slim y 152,9 MB a la 1.23.17.

Otros cambios que notarás después de actualizar

Tres cambios aparecieron en el laboratorio sin que la interfaz avisara. Ninguno impide arrancar, pero cada uno rompe algo que dependía de la 1.23:

  • Badges con más de 720 horas: /api/badge/1/uptime/1440 devolvía 99,90 % en la 1.23.17 y en la 2.5.6 responde 403 con {"status":"fail","msg":"The maximum number of hours is 720"}. Usa 60d. El valor es correcto, aunque la etiqueta del badge dice "Uptime (60h)".
  • Plantillas de correo: la 2.5.6 renderiza el asunto con LiquidJS. Mi asunto de la 1.23, [{{NAME}}] {{STATUS}}, siguió funcionando porque el código mantiene las variables en mayúsculas "for v1 compatibility, to be removed in v3". La variable que la wiki escribe como hostnameOrUrl salió vacía: en el código se llama hostnameOrURL.
  • Imágenes rootless: con 2.5.6-rootless sobre el data de la 1.23, el arranque falló con SQLITE_READONLY: attempt to write a readonly database, porque los ficheros eran de root y la imagen corre como el usuario node (UID 1000). Un chown -R 1000:1000 sobre data lo arregló, pero la wiki desaconseja esta imagen para el salto de la 1 a la 2.
  • Monitores TCP con TLS: la 2.5.8 retiró la opción TLS del monitor TCP Port, que no funcionaba bien, y los monitores que la usaban pasan a ser TCP normales. Si vigilabas así un certificado, cámbialo a un monitor HTTP.

En equipos lentos como una Raspberry Pi hay un ajuste nuevo de SQLite. La versión 2.3.0 añadió UPTIME_KUMA_SQLITE_SINGLE_CONNECTION para evitar bloqueos de la base de datos, y en la 2.5.6 el valor por defecto ya es una sola conexión: el registro lo confirma con Using single connection for SQLite. Solo lo tocarías para ponerlo a false y abrir hasta 20 conexiones.

Cómo volver a Uptime Kuma 1.23 si algo sale mal

La vuelta atrás fiable es restaurar el archivo del paso 1. Cambiar solo la etiqueta parece funcionar y no funciona. La 1.23.17 arrancó sobre la base migrada sin un solo error (Database patch not needed), pero la disponibilidad a 30 días de web-nginx bajó del 99,90 % al 97,07 %.

La 1.23 calcula sobre la tabla heartbeat, y tras la migración solo le quedan los cambios de estado, donde las caídas pesan de más. La restauración completa es esta:

docker compose stop uptime-kuma
docker run --rm -v "$PWD/data":/data \
  -v "$PWD/backup":/backup:ro alpine:3.22 sh -c \
  'rm -rf /data/* && tar xzf /backup/kuma-data-1.23.17.tar.gz -C /data'
sed -i 's/^KUMA_TAG=.*/KUMA_TAG=1.23.17/' .env
docker compose up -d uptime-kuma

Tras la restauración, la 1.23.17 volvió a ver los 604.866 latidos (más los nuevos) y el 99,90 % a 30 días. El rm borra también db-config.json, que es de la 2. Lo que hayas cambiado en la 2 entre la copia y la vuelta atrás se pierde. El laboratorio de copias de volúmenes Docker muestra el mismo patrón con volúmenes con nombre.

Preguntas frecuentes

¿Puedo usar la etiqueta 2 o next en lugar de una versión fija?

2 es la etiqueta que la wiki recomienda y el 2 de noviembre de 2026 apunta a la 2.5.9, igual que next. La diferencia es que next sigue a la última versión de Uptime Kuma, y la 3.0 ya está en beta. La incidencia 7944, cerrada el 8 de octubre de 2026, describe monitores que no se podían editar tras pasar de la 2.5.3 a la 3.0.0-beta.0. Fija 2.5.9 y sube de versión cuando tú decidas.

¿Cuánto tarda la migración del historial?

Depende del número de monitores y de días de historial, no del tamaño del fichero. La wiki cuenta 7 minutos para 20 monitores con 90 días y avisa de que en hardware lento puede llevar horas. Mi máquina estaba compartida y cargada, así que no doy un tiempo. Mira /migrate-status y no interrumpas el proceso.

¿Pierdo los monitores, las notificaciones o las páginas de estado?

No, si te quedas en SQLite. En mi prueba la 2.5.6 conservó los 8 monitores, la notificación SMTP, la página de estado y la ventana de mantenimiento, y el monitor push siguió con su token. Lo que pierdes es el detalle de cada latido de más de 24 horas, que pasa a vivir agregado.

Conclusión

Actualizar Uptime Kuma 1.23 a la 2 en Docker es cambiar la etiqueta, siempre que no sea latest. Lo que hay que preparar es el primer arranque, que reescribe el historial y borra los latidos brutos. Para el contenedor, archiva data, fija 2.5.9 y deja terminar la migración sin tocarla.

Si se corta, el script reset-migrate-aggregate-table-state o la copia te sacan del error. Quédate en SQLite salvo que vayas a empezar de cero, lanza Shrink Database al terminar y revisa badges y plantillas de correo. Para volver a la 1.23, restaura el archivo: la etiqueta sola te deja una 1.23 que arranca con números equivocados. Si dudas entre seguir con Uptime Kuma o pasarte a un monitor configurado como código, compara con Gatus en Docker.

Fuentes: [1] Wiki de Uptime Kuma, migración de la v1 a la v2[3], [2] Wiki de Uptime Kuma, etiquetas de Docker[4], [3] Uptime Kuma, versión 2.5.6 en GitHub[5], [4] Uptime Kuma, versión 2.0.0 en GitHub[6], [5] Uptime Kuma, versión 2.3.0 y UPTIME_KUMA_SQLITE_SINGLE_CONNECTION[7], [6] Uptime Kuma, incidencia 7944 sobre la 3.0.0-beta.0[8], [7] Etiquetas de louislam/uptime-kuma en Docker Hub[9], [8] Documentación de SQLite, VACUUM[10], [9] Documentación de LiquidJS[11].

Fuentes

  1. envenenamiento de la caché del RSS
  2. ejecución remota de código
  3. Wiki de Uptime Kuma, migración de la v1 a la v2
  4. Wiki de Uptime Kuma, etiquetas de Docker
  5. Uptime Kuma, versión 2.5.6 en GitHub
  6. Uptime Kuma, versión 2.0.0 en GitHub
  7. Uptime Kuma, versión 2.3.0 y UPTIME_KUMA_SQLITE_SINGLE_CONNECTION
  8. Uptime Kuma, incidencia 7944 sobre la 3.0.0-beta.0
  9. Etiquetas de louislam/uptime-kuma en Docker Hub
  10. Documentación de SQLite, VACUUM
  11. Documentación de LiquidJS