Behebung des Kopano-WebApp-Fehlers „Verbindung zu Kopano Core nicht möglich“

Der schnellste Weg, den Fehler „Verbindung zu Kopano Core nicht möglich“ einer Kopano-Webanwendung zu beheben, besteht darin, die fehlerhafte der drei Ebenen zu ermitteln: Kopano Core selbst , der Webanwendungs-zu-Core-Endpunkt oder die PHP-MAPI-Schicht , die die Webanwendung zur Kommunikation mit Core verwendet. Ein Neustart aller Komponenten kann das Problem zwar gelegentlich beheben, verschleiert aber die Ursache und erschwert die Diagnose wiederkehrender Fehler.

Die offizielle WebApp-Dokumentation von Kopano gibt an, dass WebApp von Kopano Core abhängt php-mapiund dessen DEFAULT_SERVEREinstellung die Verbindungsart von WebApp zu Kopano Core steuert. Zu den dokumentierten Optionen gehören der lokale Unix-Socket, HTTP auf Port 236 und HTTPS auf Port 237. Weitere Informationen finden Sie in der Kopano WebApp-Konfigurationsdokumentation und im Kopano Core-Administratorhandbuch .

Wichtiger Versionshinweis: Die zum Zeitpunkt der Erstellung dieses Dokuments verfügbaren öffentlichen Administratorhandbücher von Kopano sind älter als viele aktuelle Linux-Distributionen. Paketnamen, PHP-Versionen, Service-Wrapper und Speicherorte der Protokolldateien können daher in Ihrer Installation abweichen. Das unten beschriebene Verbindungsmodell und die Konfigurationsoptionen basieren auf der veröffentlichten Dokumentation von Kopano. Sie sollten jedoch die lokalen Pfade und Paketversionen überprüfen, bevor Sie Änderungen an einem Produktivserver vornehmen.

Welche Lösung sollten Sie zuerst ausprobieren?

Beginnen Sie mit dem Symptom, das am besten zu Ihrem System passt, anstatt alle Änderungen gleichzeitig vorzunehmen.

1. Läuft Kopano Core tatsächlich?

Prüfen Sie den Serverprozess, bevor Sie die WebApp-Konfiguration bearbeiten. Verwenden Sie bei einer systemd-basierten Distribution Folgendes:

sudo systemctl status kopano-server

Wenn das Gerät ausgefallen oder inaktiv ist, überprüfen Sie dessen aktuelles Protokoll, bevor Sie es neu starten:

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

Suchen Sie nach Datenbankverbindungsfehlern, Konfigurationsfehlern, Berechtigungsproblemen, fehlenden Dateien oder Startfehlern. Die Kopano-Core-Dokumentation weist darauf hin, dass Konfigurationsänderungen in der Regel einen Neustart der betroffenen Komponente erfordern, beispielsweise mit `npm start` . Dort wird auch `.config.json` als übliche Konfigurationsdatei für Kopano systemctl restart kopano-<component>beschrieben . Siehe „KC-Komponenten konfigurieren“ ./etc/kopano/server.cfgkopano-server

Wählen Sie diesen Weg, wenn der Dienst eindeutig ausgefallen ist, nach dem Start abstürzt oder auch andere Kopano-Tools nicht mit dem Kern kommunizieren können. Die Behebung des Problems mit der Webanwendung würde lediglich ein Symptom eines Folgeproblems lösen.

Abwägung: Ein Neustart ist der schnellste Wiederherstellungsversuch, doch wenn der Prozess sofort wieder fehlschlägt, benötigen Sie die Protokollausgabe. Erfassen Sie auf Produktivsystemen die Fehlerdetails vor dem Neustart, um die wichtigsten Beweise nicht zu verlieren.

2. Verweist WebApp auf den korrekten Kopano Core-Endpunkt?

In WebApp befindet sich die Schlüsseleinstellung DEFAULT_SERVERin config.php. Das offizielle WebApp-Handbuch von Kopano dokumentiert folgende Beispiele:

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");

Die dokumentierte Standardeinstellung ist die Verwendung des lokalen Sockets file:///var/run/kopano/server.sock. Dies ist in der Regel die einfachste Wahl, wenn WebApp und Core auf demselben Rechner laufen. Laufen sie auf getrennten Rechnern, funktioniert ein lokaler Unix-Socket nicht; Sie benötigen stattdessen einen erreichbaren HTTP- oder HTTPS-Endpunkt. Die Dokumentation zur Leistungsoptimierung von Kopano beschreibt, wie ein WebApp-Host über Port 236 (bzw. Port 237 für SSL) eine Verbindung zu einem separaten Kopano-Server herstellt. Siehe Kopano-Leistungsoptimierung und Split-Server-Konfiguration .

Lokaler Unix-Socket: Im Allgemeinen die ressourcenschonendste Option auf einem einzelnen Host, da kein TCP-Dienst nur für den lokalen Zugriff auf die Webanwendung bereitgestellt werden muss. Der Nachteil besteht darin, dass der Socket existieren und vom Webserverprozess genutzt werden können muss.

HTTP auf Port 236: einfacher auf verschiedenen Hosts zu testen und geeignet für vertrauenswürdige interne Netzwerke, sofern Ihre Sicherheitsarchitektur dies zulässt. Der Nachteil ist, dass der Datenverkehr auf der Kopano-Transportschicht nicht verschlüsselt wird.

HTTPS auf Port 237: Diese Option ist geeignet, wenn eine verschlüsselte Übertragung zwischen Webanwendung und Core erforderlich ist. Dies erfordert die Einrichtung und Validierung von Zertifikaten. Die spezielle Konfigurationsdokumentation von Kopano zeigt, wie die Webanwendung HTTPS DEFAULT_SERVERund in einigen Fällen Clientzertifikate verwendet. Siehe die speziellen Core-Konfigurationen von Kopano .

3. Falls Sie einen Unix-Socket verwenden, existiert dieser und kann der Webserver ihn erreichen?

Bei einer Bereitstellung auf demselben Host überprüfen Sie den Socket selbst:

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

Falls die Datei fehlt, erstellen Sie keine reguläre Datei mit diesem Namen. Der Socket wird vom laufenden Kopano-Server erstellt. Ein fehlender Socket deutet daher in der Regel auf einen Fehler beim Core-Start, einen geänderten Socket-Pfad oder eine Konfigurationsabweichung hin.

Existiert der Socket, prüfen Sie dessen Eigentümer und Zugriffsrechte. Der Webserver-Benutzer muss über seinen Verzeichnispfad auf den Socket zugreifen können. Je nach Distribution kann das Webserver-Konto beispielsweise „webserver.conf“ www-data, apache„webserver.conf“ oder ein anderer dienstspezifischer Benutzer sein. Vermeiden Sie die Behebung von Berechtigungsfehlern mit allgemeinen Zugriffsrechten wie chmod 777„webserver.conf“, da dies das Risiko erhöht und beim nächsten Neuaufbau des Sockets durch den Dienst überschrieben werden kann.

Ein besserer Ansatz besteht darin, die Web-App an den von Kopano generierten Socket-Speicherort anzupassen und anschließend die von der Distribution vorgesehenen Gruppen- oder Dienstberechtigungen zu verwenden. Falls Ihr Server angepasst wurde, vergleichen Sie die Core-Konfiguration mit dem Web-App-Endpunkt, bevor Sie die Besitzverhältnisse ändern.

4. Was ist, wenn der Kern fehlerfrei funktioniert, die Webanwendung aber weiterhin meldet, dass keine Verbindung hergestellt werden kann?

Prüfen Sie als Nächstes PHP-MAPI. Kopano gibt explizit an, dass WebApp davon abhängt php-mapi. Die WebApp-Konfigurationsprüfung kann auch die Verfügbarkeit von PHP und PHP-MAPI testen. Siehe Dokumentation zu WebApp Config.php .

Ein kurzer CLI-Check ist:

php -m | grep -i mapi

Dieser Test hat jedoch eine wichtige Einschränkung: Die PHP-Befehlszeilenschnittstelle verwendet möglicherweise nicht dieselbe Konfiguration wie Apache PHP, PHP-FPM oder eine andere Webserver-Integration. Ein positives Ergebnis der Befehlszeilenschnittstelle beweist lediglich, dass die Umgebung das Modul erkennt.

Sinnvolle Folgeprüfungen umfassen:

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

Vergleichen Sie dies anschließend mit der PHP-Konfiguration Ihres Webservers oder FPM-Pools. Falls das Paket fehlt oder die Versionen inkompatibel sind, installieren Sie das passende Kopano Core/PHP-MAPI-Paketset aus dem für Ihre Distribution und Kopano-Version vorgesehenen Repository. Verwenden Sie keine unterschiedlichen PHP-MAPI-Builds, nur damit die Erweiterung angezeigt wird php -m.

Wählen Sie diese Route, wenn: kopano-server die Anwendung fehlerfrei läuft, der Endpunkt korrekt und erreichbar ist, WebApp jedoch bei den Verbindungs- oder Konfigurationsprüfungen auf PHP-Seite fehlschlägt.

Abwägung: Eine Neuinstallation oder Aktualisierung des Pakets kann bei inkompatiblen Binärdateien die richtige Lösung sein, verändert aber mehr Systemkomponenten als die Behebung eines einzelnen Problems. Prüfen Sie daher zuerst die Paketversionen und planen Sie Aktualisierungen in der Produktionsumgebung entsprechend.

Sollten Sie Apache, PHP-FPM oder den Kopano-Server neu starten?

Starten Sie die Komponente neu, deren Konfiguration oder Modul sich tatsächlich geändert hat.

• Wenn Sie Änderungen vorgenommen haben /etc/kopano/server.cfg, starten Sie neu kopano-server.
• Wenn Sie eine PHP-Erweiterung installiert oder aktiviert haben, starten Sie die von WebApp verwendete PHP-Serverschicht neu, z. B. Apache oder den entsprechenden PHP-FPM-Dienst.
• Wenn Sie nur die PHP-Konfigurationsdatei der WebApp geändert haben, ist ein vollständiger Neustart von Kopano Core in der Regel nicht erforderlich, es sei denn, der Core-Endpunkt selbst hat sich ebenfalls geändert.

Der genaue Befehl für den Webdienst variiert je nach Distribution und PHP-Paket. Beispiele hierfür sind `<service>` systemctl restart apache2, systemctl restart httpd`<service>` oder eine versionierte PHP-FPM-Unit. Verwenden Sie den Dienstnamen, der auf Ihrem Host vorhanden ist, anstatt einen Befehl einfach zu kopieren.

Wie sieht es mit entfernten Core-Servern und Firewalls aus?

Wenn WebApp und Kopano Core getrennt sind, überprüfen Sie zunächst das Routing und den konfigurierten Listener, bevor Sie WebApp als Fehler vermuten. Die Kopano-Dokumentation beschreibt den HTTP-Zugriff über Port 236 und den SSL-Zugriff über Port 237. Eine Remote-Bereitstellung birgt daher zusätzliche Fehlerquellen, die bei einer lokalen Unix-Socket-Bereitstellung nicht auftreten: Firewall-Regeln, Listener-Bindung, DNS, TLS-Zertifikate, Reverse-Proxys und zwischengeschaltete Netzwerkrichtlinien.

Bei einem HTTP-Endpunkt können Sie zumindest prüfen, ob ein TCP-Listener vom WebApp-Host aus erreichbar ist:

nc -vz core.example.net 236

Überprüfen Sie bei HTTPS den TLS-Endpunkt separat mit einem Tool, das Ihrer Zertifikatsrichtlinie entspricht. Eine erfolgreiche TCP-Verbindung beweist nicht, dass die WebApp-Authentifizierung oder MAPI-Operationen erfolgreich sein werden. Eine fehlgeschlagene Verbindung beweist jedoch, dass PHP-MAPI den konfigurierten Dienst über diese Adresse und diesen Port nicht erreichen kann.

Wenn Sie einen Reverse-Proxy verwenden, beachten Sie bitte, dass die Kopano-Dokumentation voraussetzt, dass der Proxy-Pfad und das Backend-Mapping mit der URL der Webanwendung übereinstimmen. Das offizielle Core-Handbuch weist außerdem auf die HTTP/1.1-Bestimmungen für das Proxying des Kopano-Datenverkehrs hin. Siehe Kopano Core-Komponentenkonfiguration .

Eine praktische diagnostische Reihenfolge, die unnötige Änderungen minimiert

1. kopano-serverStatus prüfen . Falls ein Fehler auftritt, zuerst den Kern beheben.
2. Lesen Sie die Core-Protokolle. Datenbank- oder Konfigurationsfehler müssen behoben werden, bevor die Webanwendung eine Verbindung herstellen kann.
3. Überprüfen Sie DEFAULT_SERVER, ob es sich um einen lokalen Socket oder den korrekten Remote-HTTP/HTTPS-Endpunkt handelt.
4. Testen Sie den eigentlichen Socket oder Netzwerk-Listener. Dadurch lassen sich Transportfehler von PHP-Problemen unterscheiden.
5. Überprüfen Sie PHP-MAPI in der Web-Laufzeitumgebung. Verlassen Sie sich nicht ausschließlich auf die PHP-Umgebung der Kommandozeile.
6. Starten Sie nur die betroffenen Dienste neu. Testen Sie anschließend die Webanwendung erneut und überprüfen Sie die Protokolle, falls der Fehler weiterhin besteht.

Diese Vorgehensweise ist sicherer als die Neuinstallation von Paketen, da sie Beweise sichert und jeden Test aussagekräftig macht. Außerdem vermeidet sie den gegenteiligen Fehler: das wiederholte Neustarten von WebApp oder Apache, wenn Kopano Core selbst nicht startet.

Wann ist die Änderung von DEFAULT_SERVER die falsche Lösung?

Ändern Sie die Werte nicht DEFAULT_SERVERallein deshalb, weil auf der Anmeldeseite ein Verbindungsfehler angezeigt wird. Wenn der aktuelle Wert korrekt auf die gewünschte Core-Instanz verweist, kann eine Änderung das ursprüngliche Problem verschleiern oder Benutzer zum falschen Backend weiterleiten.

Beispielsweise stellt der Austausch default:nicht http://localhost:236/kopanozwangsläufig ein Upgrade dar. Er ändert die Transportart vom dokumentierten lokalen Standard-Socket zu TCP. Dies kann zwar beim Debuggen oder in einer Topologie, die TCP erfordert, hilfreich sein, verändert aber auch die Sicherheit und die Betriebsumgebung. Bei einer Konfiguration auf demselben Host ist es oft sauberer, den fehlenden oder nicht erreichbaren Socket zu reparieren, als einen weiteren Listener zu öffnen.

Was sollten Sie tun, wenn der Fehler weiterhin besteht?

Sammeln Sie zu diesem Zeitpunkt Beweise von beiden Seiten der Verbindung:

• der genaue DEFAULT_SERVERWert, ohne Zugangsdaten oder Geheimnisse;
• systemctl status kopano-serverund aktuelle Journaleinträge des Kopano-Servers;
• die Socket-Besitzinformationen oder Informationen zum Remote-Listener;
• die PHP-Version und die geladene MAPI-Erweiterung in der Webserver-Laufzeitumgebung;
• Das WebApp/PHP-Fehlerprotokoll im Zusammenhang mit einem fehlgeschlagenen Anmeldeversuch.

Die WebApp-Dokumentation von Kopano besagt, dass die PHP-Fehlerprotokollierung über die PHP-Einstellungen aktiviert wird config.phpund warnt davor, Fehler direkt anzuzeigen, da dies JSON-Antworten beschädigen kann. Daher sind serverseitige Protokolle die bessere Diagnosequelle. Konsultieren Sie die offiziellen Protokollierungseinstellungen der WebApp, bevor Sie die Ausführlichkeit erhöhen.

Sobald Sie festgestellt haben, ob der Fehler beim Core-Start, beim Transport, bei Berechtigungen, bei PHP-MAPI oder im Remote-Netzwerk auftritt, wenden Sie die kleinstmögliche Korrektur an, die diese Ebene behebt. Dies ist zuverlässiger, als „Verbindung zu Kopano Core nicht möglich“ als einen einzigen Fehler mit einer universellen Lösung zu behandeln.