Solucionar el error "No se puede conectar a Kopano Core" de la aplicación web de Kopano

La forma más rápida de solucionar el error "No se puede conectar con Kopano Core" en una aplicación web de Kopano es determinar cuál de las tres capas está fallando: Kopano Core , el punto final de la aplicación web con Core o la capa PHP-MAPI que la aplicación web utiliza para comunicarse con Core. Reiniciar todo puede parecer que soluciona el problema, pero oculta la causa y puede dificultar el diagnóstico de fallos recurrentes.

La documentación oficial de la aplicación web de Kopano indica que la aplicación web depende de php-mapiy su DEFAULT_SERVERconfiguración controla dónde se conecta la aplicación web a Kopano Core. Las opciones documentadas incluyen el socket Unix local, HTTP en el puerto 236 y HTTPS en el puerto 237. Consulte la documentación de configuración de la aplicación web de Kopano y el Manual del administrador de Kopano Core .

Nota importante sobre la versión: Los manuales de administración públicos de Kopano disponibles al momento de redactar este documento son anteriores a muchas distribuciones Linux actuales. Por lo tanto, los nombres de los paquetes, las versiones de PHP, los envoltorios de servicio y las ubicaciones de los registros pueden variar en su instalación. El modelo de conexión y las opciones de configuración que se describen a continuación se basan en la documentación publicada por Kopano, pero debe confirmar las rutas locales y las versiones de los paquetes antes de modificar un servidor de producción.

¿Qué solución deberías probar primero?

Empiece por el síntoma que mejor se adapte a su sistema, en lugar de aplicar todos los cambios a la vez.

1. ¿Está Kopano Core realmente en funcionamiento?

Verifique el proceso del servidor antes de editar la configuración de WebApp. En una distribución basada en systemd, utilice:

sudo systemctl status kopano-server

Si la unidad está averiada o inactiva, revise su registro reciente antes de reiniciarla:

sudo journalctl -u kopano-server -n 100 --no-pager

Busque errores de conexión a la base de datos, fallos de análisis de configuración, problemas de permisos, archivos faltantes o errores de inicio. La documentación principal de Kopano indica que los cambios de configuración generalmente requieren reiniciar el componente afectado, por ejemplo, con systemctl restart kopano-<component>. También documenta /etc/kopano/server.cfgcomo el archivo de configuración habitual para kopano-server. Consulte Configurar componentes de KC .

Elija esta opción cuando: el servicio esté claramente caído, falle tras el inicio o otras herramientas de Kopano tampoco puedan comunicarse con Core. Solucionar primero el problema de WebApp solo trataría un síntoma secundario.

Compromiso: reiniciar el sistema es el intento de recuperación más rápido, pero si el proceso vuelve a fallar inmediatamente, necesitará el registro de errores. En sistemas de producción, capture los detalles del fallo antes de reiniciar para no perder la evidencia más clara.

2. ¿WebApp apunta al punto final correcto de Kopano Core?

En WebApp, la configuración clave se encuentra DEFAULT_SERVERen config.php. El manual oficial de WebApp de Kopano documenta estos ejemplos:

define("DEFAULT_SERVER", "default:");
define("DEFAULT_SERVER", "file:///var/run/kopano/server.sock");
define("DEFAULT_SERVER", "http://localhost:236/kopano");
define("DEFAULT_SERVER", "https://localhost:237/kopano");

La configuración predeterminada documentada se asigna al socket local file:///var/run/kopano/server.sock. Esta suele ser la opción más sencilla cuando WebApp y Core se ejecutan en la misma máquina. Si se ejecutan en máquinas separadas, un socket Unix local no funcionará; en su lugar, se necesita un punto final HTTP o HTTPS accesible. La documentación de optimización del rendimiento de Kopano describe cómo un host de WebApp se conecta a un servidor Kopano independiente a través del puerto 236, o del puerto 237 para SSL. Consulte la sección sobre optimización del rendimiento y configuración de servidores divididos de Kopano .

Socket Unix local: generalmente es la opción con menor sobrecarga en un solo host y evita exponer un servicio TCP simplemente para el acceso local de la aplicación web. El inconveniente es que el socket debe existir y el proceso del servidor web debe poder usarlo.

HTTP en el puerto 236: facilita las pruebas entre hosts y es adecuado para redes internas de confianza cuando la arquitectura de seguridad lo permite. La desventaja es que el tráfico no se cifra en la capa de transporte de Kopano.

HTTPS en el puerto 237: apropiado cuando se necesita transporte cifrado entre WebApp y Core. Introduce requisitos de configuración y validación de certificados. La documentación de configuración especial de Kopano muestra WebApp usando HTTPS DEFAULT_SERVERy, en algunos casos, certificados de cliente. Consulte las configuraciones especiales de Kopano Core .

3. Si utiliza un socket Unix, ¿existe y puede el servidor web acceder a él?

Para una implementación en el mismo host, verifique el socket en sí:

ls -l /var/run/kopano/server.sock
file /var/run/kopano/server.sock
ss -xl | grep kopano

Si el archivo no existe, no cree un archivo normal con ese nombre. El socket lo crea el servidor Kopano en ejecución. Por lo tanto, la ausencia de un socket suele deberse al inicio de Core, a un cambio en la ruta del socket o a una discrepancia en la configuración.

Si el socket existe, inspeccione su propietario y modo. El usuario del servidor web debe poder acceder al socket a través de su ruta de directorio. Según su distribución, la cuenta del servidor web puede ser www-data, apache, u otro usuario específico del servicio. Evite solucionar errores de permisos con modos amplios como chmod 777; esto aumenta la vulnerabilidad y puede sobrescribirse la próxima vez que el servicio recree el socket.

Una mejor opción es alinear la aplicación web con la ubicación del socket generada por Kopano y luego usar los permisos de grupo o servicio previstos por la distribución. Si su servidor ha sido personalizado, compare la configuración de Core con el punto final de la aplicación web antes de cambiar la propiedad.

4. ¿Qué ocurre si Core funciona correctamente pero WebApp sigue indicando que no puede conectarse?

Compruebe PHP-MAPI a continuación. Kopano indica explícitamente que WebApp depende de él php-mapi. La comprobación de configuración de WebApp también puede verificar la disponibilidad de PHP y PHP-MAPI. Consulte la documentación de WebApp Config.php .

Una comprobación rápida mediante la interfaz de línea de comandos es:

php -m | grep -i mapi

Sin embargo, esta prueba tiene una limitación importante: la interfaz de línea de comandos de PHP puede no usar la misma configuración que Apache PHP, PHP-FPM u otra integración de servidor web. Un resultado positivo en la CLI solo demuestra que el entorno de la CLI detecta el módulo.

Entre las comprobaciones de seguimiento útiles se incluyen:

php --ini
php -i | grep -i mapi

Luego, compárelo con la configuración de PHP utilizada por su servidor web o grupo FPM. Si falta el paquete o las versiones son incompatibles, instale el conjunto de paquetes Kopano Core/PHP-MAPI correspondiente desde el repositorio destinado a su distribución y versión de Kopano. No mezcle compilaciones de PHP-MAPI no relacionadas simplemente para que la extensión aparezca en php -m.

Elija esta ruta cuando: kopano-server esté en buen estado, el punto final sea correcto y accesible, pero la aplicación web falle durante sus comprobaciones de conexión o configuración del lado PHP.

Compromiso: reinstalar o actualizar el paquete puede ser la solución adecuada cuando los binarios no coinciden, pero implica modificar más el sistema que solucionar un único problema. Confirme primero las versiones de los paquetes y programe las actualizaciones de producción según corresponda.

¿Debe reiniciar Apache, PHP-FPM o el servidor Kopano?

Reinicie el componente cuya configuración o módulo haya cambiado.

• Si has cambiado /etc/kopano/server.cfg, reinicia kopano-server.
• Si ha instalado o habilitado una extensión de PHP, reinicie la capa de servicio de PHP utilizada por WebApp, como Apache o el servicio PHP-FPM correspondiente.
• Si solo modificaste el archivo de configuración PHP de WebApp, normalmente no es necesario reiniciar completamente Kopano Core, a menos que también haya cambiado el punto final de Core.

El comando exacto del servicio web varía según la distribución y el paquete de PHP. Algunos ejemplos podrían ser systemctl restart apache2, systemctl restart httpd, o una unidad PHP-FPM con versiones. Utilice el nombre del servicio presente en su servidor en lugar de copiar un comando sin más.

¿Qué ocurre con los servidores Core remotos y los cortafuegos?

Si WebApp y Kopano Core están separados, primero verifique el enrutamiento y el listener configurado antes de culpar a WebApp. La documentación de Kopano describe el acceso HTTP en el puerto 236 y el acceso SSL en el puerto 237. Por lo tanto, una implementación remota añade varios modos de fallo que una implementación local de socket Unix no tiene: reglas de firewall, enlace del listener, DNS, certificados TLS, proxies inversos y política de red intermedia.

Para un punto final HTTP, al menos puede comprobar si se puede acceder a un oyente TCP desde el host de la aplicación web:

nc -vz core.example.net 236

Para HTTPS, verifique el punto final TLS por separado con una herramienta adecuada a su política de certificados. Una conexión TCP exitosa no garantiza que la autenticación de la aplicación web o las operaciones MAPI se realicen correctamente, pero una conexión fallida sí demuestra que PHP-MAPI no puede acceder al servicio configurado a través de esa dirección y puerto.

Si utiliza un proxy inverso, recuerde que la documentación de Kopano exige que la ruta del proxy y la asignación del backend sean coherentes con la URL que utiliza la aplicación web. El manual oficial de Core también menciona consideraciones sobre HTTP/1.1 para el proxy del tráfico de Kopano. Consulte la configuración de componentes de Kopano Core .

Un orden diagnóstico práctico que minimiza los cambios innecesarios.

1. Comprueba kopano-serverel estado. Si ha fallado, repara primero el núcleo.
2. Lea los registros principales. Los fallos de la base de datos o de la configuración deben resolverse antes de que la aplicación web pueda conectarse.
3. Verificar DEFAULT_SERVER. Confirmar que coincide con un socket local o con el punto final HTTP/HTTPS remoto correcto.
4. Pruebe el socket o el oyente de red. Esto permite diferenciar los fallos de transporte de los problemas de PHP.
5. Verifique PHP-MAPI en el entorno de ejecución web. No se fíe únicamente del entorno PHP de la línea de comandos.
6. Reinicie únicamente los servicios afectados. A continuación, vuelva a probar la aplicación web y revise los registros si el error persiste.

Este orden es más seguro que comenzar reinstalando paquetes, ya que conserva la evidencia y hace que cada prueba sea significativa. Además, evita el error contrario: reiniciar repetidamente WebApp o Apache cuando Kopano Core no puede iniciarse.

¿Cuándo cambiar DEFAULT_SERVER es una solución incorrecta?

No realice cambios DEFAULT_SERVERsimplemente porque la página de inicio de sesión muestre un error de conexión. Si el valor actual apunta correctamente a la instancia de Core prevista, modificarlo puede ocultar el problema original o redirigir a los usuarios al servidor incorrecto.

Por ejemplo, reemplazar default:con http://localhost:236/kopanono implica necesariamente una mejora. Cambia el protocolo de transporte del socket local predeterminado documentado a TCP. Esto puede ser útil para la depuración o para una topología que requiera TCP, pero también modifica la seguridad y la superficie operativa. En una configuración del mismo host, solucionar el problema del socket faltante o inaccesible suele ser más sencillo que abrir un nuevo oyente.

¿Qué debe hacer si el error persiste?

En ese momento, recopile pruebas de ambos lados de la conexión:

• el DEFAULT_SERVERvalor exacto, sin credenciales ni secretos;
• systemctl status kopano-servery entradas recientes del registro del servidor Kopano;
• la información sobre la propiedad del socket o del oyente remoto;
• la versión de PHP y la extensión MAPI cargada en el entorno de ejecución del servidor web;
• El registro de errores de la aplicación web/PHP relacionado con un intento de inicio de sesión fallido.

La documentación de la aplicación web de Kopano indica que el registro de errores de PHP se habilita mediante la configuración de PHP config.phpy advierte sobre el peligro de mostrar los errores directamente, ya que esto puede corromper las respuestas JSON. Por lo tanto, los registros del servidor son la mejor fuente de diagnóstico. Consulte la configuración oficial de registro de la aplicación web antes de aumentar el nivel de detalle.

Una vez que identifique si el fallo se debe al inicio de Core, al transporte, a los permisos, a PHP-MAPI o a la red remota, aplique la solución más sencilla que aborde esa capa. Esto es más fiable que tratar el error "No se puede conectar a Kopano Core" como un único problema con una solución universal.