Índice
-
Introducción
-
¿Por qué las actualizaciones pueden causar errores en Dolibarr?
-
Preparación para una actualización: mejores prácticas
-
Categorías de errores de actualización comunes
-
Caso práctico 1: Desajuste del esquema de la base de datos
-
Caso práctico 2: Incompatibilidad de versiones de PHP
-
Caso práctico 3: Falta el archivo install.lock
-
Caso práctico 4: Problemas de compatibilidad de módulos
-
Caso práctico 5: Errores de permisos de archivos
-
Caso práctico 6: Interfaz de usuario vacía o rota después de la actualización
-
Caso práctico 7: Errores en los archivos de idioma
-
Caso práctico 8: Trabajos cron y tareas programadas que fallan
-
Análisis de registros: dónde buscar y qué observar
-
Herramientas y scripts para ayudar en la resolución de problemas
-
Cómo revertir de forma segura una actualización fallida
-
Lecciones aprendidas y estrategias preventivas
-
Recursos de apoyo comunitario y profesional
-
Conclusión
1. Introducción
Dolibarr ERP/CRM se adopta ampliamente gracias a su flexibilidad y diseño modular. Sin embargo, como cualquier sistema complejo, las actualizaciones, especialmente las importantes, pueden generar problemas inesperados. Comprender, diagnosticar y resolver estos errores rápidamente es crucial para la continuidad del negocio. Este artículo explora escenarios reales de errores de actualización, sus causas raíz y soluciones estructuradas.
2. ¿Por qué las actualizaciones pueden causar errores en Dolibarr?
Cada nueva versión introduce cambios en:
-
Esquemas de bases de datos
-
Funciones y compatibilidad de PHP
-
API internas y estructuras de clases
-
Plantillas de IU y lógica de renderizado
-
Interfaces y configuraciones del módulo
Si estos cambios no van acompañados de una preparación y pruebas adecuadas, los errores serán casi inevitables.
3. Preparación para una actualización: mejores prácticas
Antes de actualizar:
-
Información su base de datos y sistema de archivos.
-
Pruebe la actualización en un entorno de ensayo.
-
Revise tu versión de PHP compatibilidad.
-
Verificar a terceros compatibilidad del módulo.
-
Confirmar la presencia de
install.lock. -
Personalizaciones de documentos para reimplementación.
Un enfoque basado en listas de verificación reduce drásticamente el riesgo.
4. Categorías de errores comunes de actualización
-
Errores de base de datos: desajuste de esquema, columnas faltantes
-
Errores fatales de PHP:clase/función no encontrada
-
Problemas de representación de la interfaz de usuario: diseños rotos, plantillas faltantes
-
Errores de idioma: traducciones faltantes
-
Problemas de acceso:errores de permisos después de cambios de archivo
-
Fallos del módulo: el código personalizado falla después de un cambio de núcleo
Cada categoría puede manifestarse con síntomas vagos como pantallas en blanco, errores 500 o fallas en la interfaz de usuario.
5. Caso práctico 1: Desajuste del esquema de la base de datos
Síntoma:
“Columna desconocida 'ref_ext' en 'lista de campos'” al ver facturas.
Causa principal:
Se omitió o falló la ejecución de un paso de migración de base de datos.
Resolución:
-
Comprobar
/install/directorio para el asistente de actualización. -
Consulte el documento
llx_constTabla para seguimiento de versiones. -
Vuelva a ejecutar la actualización desde
/install/ -
Comparar manualmente
llx_factureestructura utilizando el/install/mysql/archivos
6. Caso práctico 2: Incompatibilidad de versiones de PHP
Síntoma:
Pantalla blanca o error "Función obsoleta".
Causa principal:
La versión de Dolibarr requiere una versión de PHP más nueva o más antigua que la actual.
Resolución:
-
Consulte la matriz de compatibilidad PHP oficial de Dolibarr
-
Actualice PHP si es demasiado antiguo o cambie a una versión inferior si es demasiado nueva
-
Asegúrese de que las extensiones PHP sean necesarias (
pdo,gd,intl) están instalados
7. Caso práctico 3: Falta el archivo install.lock
Síntoma:
Dolibarr muestra el asistente de instalación en lugar del inicio de sesión.
Causa principal:
El install.lock El archivo fue eliminado o no se volvió a crear.
Resolución:
-
Crea un archivo vacío llamado
install.locken el directorio raíz -
Establecer permisos correctos (644)
-
Bloquear
/install/directorio con.htaccesscomo medida secundaria
8. Caso práctico 4: Problemas de compatibilidad de módulos
Síntoma:
Los módulos personalizados ya no cargan ni generan excepciones.
Causa principal:
Cambios en los ganchos principales, estructuras de clases o firmas de API.
Resolución:
-
Comprueba la compatibilidad del módulo con tu versión de Dolibarr
-
Actualice el módulo si existe una versión más nueva
-
Deshabilitar módulos incompatibles temporalmente
-
Examinar los registros de errores para identificar funciones obsoletas
9. Caso práctico 5: Errores de permisos de archivos
Síntoma:
Errores de “Permiso denegado” durante la carga de archivos o la generación de PDF.
Causa principal:
Los permisos del sistema de archivos se restablecieron o están mal configurados después de la actualización.
Resolución:
-
Establecer
htdocsydocumentscarpetas en las que el usuario web puede escribir -
Usar
chmod -R 755ychown -R www-data:www-data -
Confirmar
conf.phpes legible
10. Caso práctico 6: Interfaz de usuario en blanco o rota después de la actualización
Síntoma:
Se carga la pantalla de inicio de sesión, pero después de iniciar sesión la interfaz está en blanco.
Causa principal:
Incompatibilidad de tema o plantilla.
Resolución:
-
Cambiar a un tema predeterminado (Eldy) desde la base de datos directamente
-
Borrar caché de
documents/temp/ -
Deshabilitar CSS o JavaScript personalizados
11. Caso práctico 7: Errores en archivos de idioma
Síntoma:
Etiquetas faltantes o sin traducir a pesar de la configuración del idioma.
Causa principal:
Archivos de idioma obsoletos o faltantes para nuevas funciones.
Resolución:
-
Ejecute el restablecimiento de caché de idioma a través de
admin/tools.php?action=clear_langcache -
Descargue el último paquete de idioma del portal de traducción de Dolibarr
-
Actualizar archivos manualmente en
/langs/
12. Caso práctico 8: Trabajos cron y tareas programadas que fallan
Síntoma:
Las facturas, informes o tareas no se ejecutan según lo programado.
Causa principal:
Las URL de Cron cambiaron o cron_run_jobs.php El camino cambió.
Resolución:
-
Actualizar el trabajo cron para reflejar la nueva ruta de la versión de Dolibarr
-
Comprueba eso
cron_run_jobs.phpes ejecutable -
Comprobar registros en
documents/admin/cronjobs.log
13. Análisis de registros: dónde buscar y qué observar
Ubicaciones clave:
-
htdocs/conf/conf.php→ configuración de base de datos y depuración -
htdocs/logs/(si está habilitado) -
Registros de errores de Apache/Nginx
-
documents/admin/system.log -
Consola del navegador para errores de JS
Activar $dolibarr_main_prod = 0; in conf.php para salida de error detallada (sólo para depuración).
14. Herramientas y scripts para ayudar en la resolución de problemas
-
dolibarr_dev_toolsRepositorio GitHub -
Herramientas de administración: Comprobador de integridad de la base de datos
-
Herramientas de diferenciación de SQL (por ejemplo, MySQL Workbench)
-
Comparación de archivos:
diff, Meld, Más allá de toda comparación
15. Cómo revertir de forma segura una actualización fallida
-
Restaurar desde la copia de seguridad de la base de datos anterior a la actualización
-
Revertir el sistema de archivos desde el directorio comprimido de Dolibarr
-
Deshabilitar todos los módulos no esenciales
-
Utilice el control de versiones para los archivos de configuración y de módulo
Pruebe siempre la estrategia de reversión en fase de pruebas antes de aplicarla a producción.
16. Lecciones aprendidas y estrategias preventivas
-
Nunca actualice directamente en producción sin probar
-
Automatizar las copias de seguridad y los procesos de restauración
-
Mantener la documentación de los módulos instalados y sus versiones
-
Lea los registros de cambios de Dolibarr y los hilos del foro antes de actualizar
-
Suscríbete a las actualizaciones de versiones de Dolibarr para recibir alertas tempranas
17. Recursos de apoyo comunitario y profesional
-
Problemas de Dolibarr en GitHub: https://github.com/Dolibarr/dolibarr/issues
-
Foros de Dolibarr: https://www.dolibarr.org/forum/
-
Canales IRC/Matrix
-
Integradores profesionales de Dolibarr y socios de soporte
18. Conclusión
Las actualizaciones de Dolibarr pueden ser complejas, especialmente en entornos altamente personalizados. Sin embargo, con una planificación adecuada, el conocimiento de los problemas más comunes y una solución de problemas estructurada, la mayoría de los errores se pueden resolver de forma rápida y segura. Esta guía le proporciona información práctica basada en casos concretos y pasos prácticos para garantizar que su próxima actualización sea fluida y sin complicaciones.
