Solucionar el problema del modo de mantenimiento de Nextcloud atascado en OCC

Finalizas una actualización de Nextcloud, pero todos siguen viendo la página de mantenimiento. O bien, la actualización se interrumpió y el sitio no volvió a estar en línea. El comando OCC para desactivar el modo de mantenimiento es breve, pero ejecutarlo antes de comprobar el estado de la actualización puede revelar una instalación incompleta. Empieza por confirmar qué instancia de Nextcloud estás administrando y si aún se requiere una actualización de la base de datos.

Ejemplo ilustrativo: Imaginemos una pequeña oficina que utiliza Nextcloud en Ubuntu. Una actualización programada se interrumpió tras la implementación de nuevos archivos de código, y la página web sigue indicando que el servidor está en modo de mantenimiento. Este ejemplo es hipotético; se trata de un hilo de discusión para aplicar las comprobaciones que se describen a continuación, no de un informe de un incidente o prueba real.

Qué significa el modo de mantenimiento

El modo de mantenimiento de Nextcloud bloquea el acceso normal de los usuarios mientras un administrador realiza tareas como una actualización o una copia de seguridad. Este estado afecta a todo el servidor, por lo que los usuarios pueden ver un aviso de mantenimiento incluso cuando el servidor web esté en funcionamiento. El manual de administración actual de Nextcloud documenta el comando OCC para activar o desactivar este modo e indica que es posible que los usuarios deban actualizar su navegador después de desactivarlo.

En el caso de la oficina ilustrativa, la página de mantenimiento por sí sola no le indica al administrador si la actualización ha finalizado. Deben consultar Nextcloud antes de cambiar el modo.

Paso 1: Confirme el tipo de instalación y la ruta OCC.

Los ejemplos de comandos aquí son para una instalación convencional de Nextcloud basada en archivos en Ubuntu, con el código en /var/www/nextcloudy la cuenta del servidor web llamada www-data. Nextcloud documenta que occse encuentra en el directorio de instalación y debe ejecutarse como el usuario HTTP; en Debian y Ubuntu ese usuario normalmente es www-data.

Para esta configuración estándar, introduzca el directorio de instalación:

cd /var/www/nextcloud

Si tus archivos de Nextcloud se encuentran en otra ubicación, utiliza esa ruta. Snap, Docker, los dispositivos y el alojamiento gestionado utilizan diferentes envoltorios de comandos o estructuras de sistema de archivos. No ejecutes el comando host en una instalación de contenedor ni asumas que la ruta de archivo se aplica a esas implementaciones. Sigue las instrucciones de actualización correspondientes a tu método de instalación, tal como se describe en la guía oficial de actualización de Nextcloud .

En el ejemplo de la oficina, el administrador revisa las notas de implementación y confirma que se trata de una instalación de archivo antes de ejecutar OCC.

Paso 2: Compruebe el estado de Nextcloud antes de desactivar el mantenimiento.

Ejecute OCC como la cuenta del servidor web para que los archivos y la configuración conserven la propiedad esperada:

sudo -E -u www-data php occ status

Observe los campos maintenancey needsDbUpgrade. Las versiones actuales también admiten un código de salida de estado:

sudo -E -u www-data php occ status -e
echo $?

Los códigos de salida documentados son útiles cuando un script verifica la salida: 0indica funcionamiento normal, 1significa que el modo de mantenimiento está habilitado y 2significa que occ upgradees necesario. También se debe revisar la salida de estado simple; no utilice el código de salida únicamente para decidir si se debe reabrir el sitio.

Para el hipotético servidor de oficina, si needsDbUpgradees verdadero o status -edevuelve 2, el siguiente paso correcto es completar la actualización, no simplemente desactivar el modo de mantenimiento.

Paso 3: Finalice primero la actualización incompleta.

Si se implementó intencionalmente una actualización de código de Nextcloud y OCC informa que es necesaria una actualización de la base de datos, realice o verifique una copia de seguridad reciente de la base de datos, la configuración y los datos antes de continuar. Luego, ejecute el comando documentado desde el directorio de instalación:

sudo -E -u www-data php occ upgrade

Lea la salida del comando y espere a que finalice. No lo interrumpa, ya que la página web permanece sin cambios mientras se ejecutan las migraciones. El actualizador integrado puede dejar el modo de mantenimiento activado cuando occ upgradefalla el reemplazo del código. Si el actualizador no finalizó el reemplazo del código, siga su registro y reanude el proceso de actualización correspondiente a su instalación en lugar de ir directamente a . Las instrucciones del actualizador integradomaintenance:mode --off de Nextcloud explican las fases de actualización e identifican el registro del actualizador como un recurso de diagnóstico.

En el ejemplo, el administrador de la oficina solo ejecutaría el comando occ upgradesi el estado indica que la migración de la base de datos sigue pendiente y que el nuevo código esperado ya está implementado. Si el comando reporta un error, mantendrá el servidor inactivo e investigará dicho error primero.

Paso 4: Desactive el modo de mantenimiento con OCC.

Cuando la actualización se haya completado y el estado ya no indique que se requiere una actualización de la base de datos, desactive el modo de mantenimiento mediante el comando integrado de Nextcloud:

sudo -E -u www-data php occ maintenance:mode --off

Un comando exitoso informa que el modo de mantenimiento se ha desactivado. Esta es la forma admitida de cambiar el modo para una instalación estándar; además, mantiene el cambio de estado dentro de la propia interfaz de comandos de Nextcloud en lugar de depender de ediciones manuales en config.php.

El administrador de la oficina ahora ejecuta este comando solo después de que la migración se haya completado. Si no había ninguna actualización en curso y el estado mostraba que la instalación estaba lista, el mismo comando puede borrar una bandera de mantenimiento que quedó activada después del mantenimiento planificado.

Paso 5: Verificar el estado y la interfaz web.

Comprueba el estado de nuevo:

sudo -E -u www-data php occ status
sudo -E -u www-data php occ status -e

Para una instalación sin problemas, espere maintenance: false, needsDbUpgrade: false, y un código de salida normal de 0. Luego, abra el sitio desde una ventana nueva de navegación privada e inicie sesión con una cuenta de administrador. Pida a un usuario normal que actualice su navegador antes de asumir que su sesión sigue bloqueada.

En el escenario ilustrativo, el éxito significa que tanto el estado de OCC como la página web coinciden en que la instancia está nuevamente en línea. El ejemplo hipotético no implica que se haya ejecutado ningún comando ni que se haya reparado un servidor real.

Si la página de mantenimiento permanece

OCC afirma que el mantenimiento es falso.

Confirme que ejecutó OCC en la misma instalación que sirve la URL. Esto es importante en implementaciones con balanceo de carga, hosts Docker con varios contenedores o servidores con directorios Nextcloud antiguos y nuevos coexistiendo. Verifique la ruta raíz del documento o del contenedor y consulte la instancia asociada a la URL afectada. Si cada nodo web tiene su propia configuración, confirme que todos los nodos comparten la configuración y la base de datos previstas.

Si la instancia correcta indica que el mantenimiento está desactivado, compare la página del servidor de origen con la URL pública. Es posible que un proxy inverso o una caché estén devolviendo una respuesta obsoleta. Borre o ignore esa caché solo después de verificar qué capa devolvió la página de mantenimiento.

OCC no puede ejecutarse o devuelve un error de PHP.

Verifique que el comando utilice la versión de PHP CLI y las extensiones necesarias compatibles con la instalación web. Nextcloud indica que APCu está deshabilitado por defecto para PHP CLI y puede causar errores de OCC cuando APCu se configura como caché local. Su manual documenta cómo habilitarlo apc.enable_clien la configuración de PHP CLI o agregarlo --define apc.enable_cli=1al comando PHP cuando corresponda:

sudo -E -u www-data php --define apc.enable_cli=1 occ status

Utilice esta opción únicamente cuando el error indique un problema con la interfaz de línea de comandos de APCu; no es una solución general para todos los errores de PHP. Además, verifique que el comando se ejecute con el usuario web correcto y desde el directorio de instalación correcto.

Todavía es necesario actualizar la base de datos.

No fuerce la desactivación del indicador de mantenimiento para ocultar este estado. Vuelva a comprobar la salida del actualizador y los registros, verifique que esté instalada la versión correcta del código de Nextcloud y complete el procedimiento de actualización compatible con su tipo de instalación. Los documentos de referencia oficiales del sistema OCC y los comandos de mantenimientomaintenance:mode , statusy la actualización por línea de comandos.

Mantenga controlada la ventana de mantenimiento.

Deshabilitar el modo de mantenimiento permite que los usuarios vuelvan a acceder a la instancia, por lo que primero debe confirmar que la actualización de la base de datos y cualquier reemplazo de código necesario se hayan completado. Evite eliminar manualmente los archivos de actualización o editar la configuración de mantenimiento en el archivo de configuración como primera medida; hacerlo puede ocultar el problema sin completar la tarea que activó el modo.

Para la hipotética oficina, la decisión más segura es sencilla: verificar la instalación correcta, comprobar el estado, completar cualquier actualización necesaria y, a continuación, ejecutar maintenance:mode --offy verificar tanto OCC como el navegador. Si la actualización no se puede completar correctamente, deje activado el modo de mantenimiento y solucione el problema consultando el registro del actualizador o el procedimiento de recuperación específico de la instalación.