Napraw błąd aplikacji internetowej Kopano „Nie można połączyć się z rdzeniem Kopano”

Najszybszym sposobem naprawienia błędu Kopano WebApp „Cannot Connect to Kopano Core” jest ustalenie, która z trzech warstw jest faktycznie uszkodzona: samo Kopano Core , punkt końcowy WebApp-to-Core , czy warstwa PHP-MAPI , której WebApp używa do komunikacji z Core. Ponowne uruchomienie wszystkich elementów może czasami wydawać się rozwiązaniem problemu, ale ukrywa przyczynę i może utrudniać diagnozę powtarzających się awarii.

Oficjalna dokumentacja aplikacji internetowej Kopano stwierdza, że ​​aplikacja internetowa jest zależna od php-mapi, a jej DEFAULT_SERVERustawienie kontroluje, gdzie aplikacja internetowa łączy się z rdzeniem Kopano. Udokumentowane opcje obejmują lokalne gniazdo Unix, HTTP na porcie 236 i HTTPS na porcie 237. Zapoznaj się z dokumentacją konfiguracji aplikacji internetowej Kopano oraz podręcznikiem administratora rdzenia Kopano .

Ważna uwaga dotycząca wersji: Publiczne podręczniki administratora Kopano dostępne w momencie pisania tego tekstu są starsze niż wiele obecnych dystrybucji Linuksa. W związku z tym nazwy pakietów, wersje PHP, wrappery usług i lokalizacje logów mogą się różnić w zależności od instalacji. Model połączenia i opcje konfiguracji opisane poniżej opierają się na opublikowanej dokumentacji Kopano, ale przed zmianą serwera produkcyjnego należy sprawdzić ścieżki lokalne i wersje pakietów.

Które rozwiązanie należy wypróbować w pierwszej kolejności?

Zacznij od objawu, który najlepiej pasuje do Twojego systemu, zamiast wprowadzać wszystkie zmiany naraz.

1. Czy Kopano Core faktycznie działa?

Sprawdź proces serwera przed edycją konfiguracji WebApp. W dystrybucji opartej na SystemD użyj:

sudo systemctl status kopano-server

Jeśli jednostka uległa awarii lub jest nieaktywna, przed ponownym uruchomieniem należy sprawdzić jej ostatni dziennik:

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

Poszukaj błędów połączenia z bazą danych, błędów analizy konfiguracji, problemów z uprawnieniami, brakujących plików lub błędów uruchamiania. Dokumentacja Kopano Core wskazuje, że zmiany konfiguracji zazwyczaj wymagają ponownego uruchomienia danego komponentu, na przykład za pomocą systemctl restart kopano-<component>. Dokumentuje również /etc/kopano/server.cfgstandardowy plik konfiguracyjny dla kopano-server. Zobacz Konfigurowanie komponentów KC .

Wybierz tę opcję, gdy: usługa jest ewidentnie niedostępna, ulega awarii po uruchomieniu lub inne narzędzia Kopano również nie mogą komunikować się z Core. Naprawa WebApp w pierwszej kolejności rozwiąże jedynie problem niższego poziomu.

Wada: restart to najszybsza próba odzyskania danych, ale jeśli proces natychmiast ponownie się nie powiedzie, potrzebne będą dane wyjściowe dziennika. W systemach produkcyjnych należy zarejestrować szczegóły awarii przed restartem, aby nie stracić najbardziej wyraźnych dowodów.

2. Czy WebApp wskazuje na właściwy punkt końcowy Kopano Core?

W przypadku aplikacji WebApp kluczowe ustawienie znajduje się DEFAULT_SERVERw config.php. Oficjalny podręcznik Kopano dotyczący aplikacji WebApp zawiera następujące przykłady:

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

Udokumentowana wartość domyślna mapuje na gniazdo lokalne file:///var/run/kopano/server.sock. Jest to zazwyczaj najprostszy wybór, gdy aplikacja WebApp i Core działają na tej samej maszynie. Jeśli działają na oddzielnych maszynach, lokalne gniazdo Unix nie będzie działać; zamiast tego potrzebny jest osiągalny punkt końcowy HTTP lub HTTPS. Dokumentacja Kopano dotycząca dostrajania wydajności opisuje hosta aplikacji WebApp łączącego się z oddzielnym serwerem Kopano przez port 236 lub port 237 w przypadku protokołu SSL. Zobacz Dostrajanie wydajności Kopano i konfiguracja podzielonego serwera .

Lokalne gniazdo Unix: zazwyczaj opcja o najniższym narzucie na jednym hoście, która pozwala uniknąć udostępniania usługi TCP tylko w celu uzyskania dostępu do lokalnej aplikacji internetowej. Kosztem jest to, że gniazdo musi istnieć, a proces serwera WWW musi móc z niego korzystać.

HTTP na porcie 236: łatwiejszy do przetestowania na wielu hostach i odpowiedni dla zaufanych sieci wewnętrznych, o ile pozwala na to architektura bezpieczeństwa. Wadą jest to, że ruch nie jest szyfrowany na poziomie warstwy transportowej Kopano.

HTTPS na porcie 237: odpowiedni, gdy potrzebujesz szyfrowanego transferu między aplikacją WebApp a Core. Wprowadza wymagania dotyczące konfiguracji i walidacji certyfikatów. Specjalna dokumentacja konfiguracyjna Kopano pokazuje aplikację WebApp korzystającą z protokołu HTTPS DEFAULT_SERVER, a w niektórych scenariuszach również z certyfikatów klienckich. Zobacz specjalne konfiguracje rdzenia Kopano .

3. Jeśli używasz gniazda Unix, czy ono istnieje i czy serwer WWW może się do niego dostać?

W przypadku wdrożenia na tym samym hoście należy sprawdzić samo gniazdo:

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

Jeśli pliku brakuje, nie twórz zwykłego pliku o tej nazwie. Gniazdo jest tworzone przez działający serwer Kopano. Brakujące gniazdo zazwyczaj wskazuje na uruchomienie Core, zmienioną ścieżkę gniazda lub niezgodność konfiguracji.

Jeśli gniazdo istnieje, sprawdź jego właściciela i tryb. Użytkownik serwera WWW musi mieć dostęp do gniazda poprzez ścieżkę do katalogu. W zależności od dystrybucji, konto serwera WWW może być kontem użytkownika www-data, apachelub innego użytkownika specyficznego dla usługi. Unikaj rozwiązywania błędów uprawnień za pomocą trybów ogólnych, takich jak chmod 777;, które zwiększają widoczność i mogą zostać nadpisane przy następnym utworzeniu gniazda przez usługę.

Lepszym rozwiązaniem jest dopasowanie WebApp do lokalizacji gniazda wygenerowanej przez Kopano, a następnie użycie uprawnień grupy lub usługi przypisanych do dystrybucji. Jeśli serwer został dostosowany, przed zmianą właściciela należy porównać konfigurację rdzenia z punktem końcowym WebApp.

4. Co zrobić, jeśli Core jest sprawny, ale WebApp nadal wyświetla komunikat, że nie może nawiązać połączenia?

Następnie sprawdź PHP-MAPI. Kopano wyraźnie stwierdza, że ​​WebApp zależy od php-mapi. Sprawdzenie konfiguracji WebApp może również sprawdzić dostępność PHP i PHP-MAPI. Zobacz dokumentację WebApp Config.php .

Szybkie sprawdzenie CLI wygląda następująco:

php -m | grep -i mapi

Test ten ma jednak istotne ograniczenie: interfejs wiersza poleceń PHP może nie używać tej samej konfiguracji co Apache PHP, PHP-FPM lub inna integracja z serwerem WWW. Pozytywny wynik CLI dowodzi jedynie, że środowisko CLI widzi dany moduł.

Przydatne kontrole następcze obejmują:

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

Następnie porównaj to z konfiguracją PHP używaną przez serwer WWW lub pulę FPM. Jeśli pakiet jest nieobecny lub wersje są niezgodne, zainstaluj pasujący zestaw pakietów Kopano Core/PHP-MAPI z repozytorium przeznaczonego dla Twojej dystrybucji i wydania Kopano. Nie mieszaj niepowiązanych kompilacji PHP-MAPI tylko po to, aby rozszerzenie pojawiło się w php -m.

Wybierz tę trasę, gdy: aplikacja kopano-server jest sprawna, punkt końcowy jest poprawny i osiągalny, ale podczas sprawdzania połączenia lub konfiguracji po stronie PHP występuje błąd aplikacji WebApp.

Kompromis: ponowna instalacja lub aktualizacja pakietu może być właściwym rozwiązaniem w przypadku niezgodności plików binarnych, ale zmienia więcej elementów systemu niż naprawa pojedynczego punktu końcowego. Najpierw sprawdź wersje pakietów i odpowiednio zaplanuj aktualizacje produkcyjne.

Czy powinieneś zrestartować serwer Apache, PHP-FPM czy Kopano?

Uruchom ponownie komponent, którego konfiguracja lub moduł faktycznie uległy zmianie.

• Jeśli dokonałeś zmiany /etc/kopano/server.cfg, uruchom ponownie kopano-server.
• Jeśli zainstalowałeś lub włączyłeś rozszerzenie PHP, uruchom ponownie warstwę obsługi PHP używaną przez aplikację internetową, np. Apache lub odpowiednią usługę PHP-FPM.
• Jeśli zmieniłeś tylko plik konfiguracyjny PHP aplikacji internetowej, pełny restart rdzenia Kopano zwykle nie jest konieczny, chyba że zmienił się również sam punkt końcowy rdzenia.

Dokładne polecenie usługi sieciowej różni się w zależności od dystrybucji i pakietu PHP. Przykładami mogą być systemctl restart apache2, systemctl restart httpd, lub wersjonowana jednostka PHP-FPM. Użyj nazwy usługi dostępnej na hoście, zamiast kopiować polecenie bezmyślnie.

A co ze zdalnymi serwerami Core i zaporami sieciowymi?

Jeśli WebApp i Kopano Core są rozdzielone, najpierw zweryfikuj routing i skonfigurowany program nasłuchujący, zanim obwinisz WebApp. Dokumentacja Kopano opisuje dostęp HTTP na porcie 236 i dostęp SSL na porcie 237. Zdalne wdrożenie dodaje zatem kilka trybów awarii, których nie ma lokalne wdrożenie w gnieździe Unix: reguły zapory, powiązanie programu nasłuchującego, DNS, certyfikaty TLS, odwrotne serwery proxy i pośrednie zasady sieciowe.

W przypadku punktu końcowego HTTP można przynajmniej sprawdzić, czy z hosta aplikacji internetowej można nawiązać kontakt z programem nasłuchującym TCP:

nc -vz core.example.net 236

W przypadku protokołu HTTPS należy osobno zweryfikować punkt końcowy TLS za pomocą narzędzia odpowiedniego do polityki certyfikacji. Udane połączenie TCP nie dowodzi, że uwierzytelnianie aplikacji webowej lub operacje MAPI zakończą się powodzeniem, ale nieudane połączenie dowodzi, że PHP-MAPI nie może nawiązać połączenia ze skonfigurowaną usługą za pośrednictwem tego adresu i portu.

Jeśli używasz odwrotnego proxy, pamiętaj, że dokumentacja Kopano wymaga, aby ścieżka proxy i mapowanie zaplecza były spójne z adresem URL używanym przez aplikację internetową. Oficjalny podręcznik Core zawiera również uwagi dotyczące protokołu HTTP/1.1 w kontekście proxy ruchu Kopano. Zobacz konfigurację komponentów Kopano Core .

Praktyczna diagnostyka minimalizująca niepotrzebne zmiany

1. Sprawdź kopano-serverstatus. Jeśli błąd jest nieaktualny, najpierw napraw Core.
2. Przeczytaj dzienniki Core. Aby aplikacja WebApp mogła się połączyć, należy rozwiązać problemy z bazą danych lub konfiguracją.
3. Sprawdź DEFAULT_SERVER. Upewnij się, że pasuje do gniazda lokalnego lub prawidłowego zdalnego punktu końcowego HTTP/HTTPS.
4. Przetestuj rzeczywiste gniazdo lub odbiornik sieciowy. To pozwoli oddzielić błędy transportu od problemów z PHP.
5. Zweryfikuj PHP-MAPI w środowisku uruchomieniowym web. Nie polegaj wyłącznie na środowisku PHP CLI.
6. Uruchom ponownie tylko te usługi, których dotyczy problem. Następnie przetestuj ponownie aplikację internetową i przejrzyj logi, jeśli błąd nadal występuje.

Taka kolejność jest bezpieczniejsza niż rozpoczynanie od ponownej instalacji pakietów, ponieważ zachowuje dowody i sprawia, że ​​każdy test jest wiarygodny. Pozwala to również uniknąć odwrotnego błędu: wielokrotnego restartowania aplikacji webowej lub Apache, gdy samo jądro Kopano nie może się uruchomić.

Kiedy zmiana DEFAULT_SERVER jest złym rozwiązaniem?

Nie zmieniaj wartości DEFAULT_SERVERtylko dlatego, że strona logowania wyświetla błąd połączenia. Jeśli bieżąca wartość prawidłowo wskazuje na docelową instancję rdzenia, jej zmiana może ukryć pierwotny problem lub skierować użytkowników do niewłaściwego zaplecza.

Na przykład zastąpienie default:nie http://localhost:236/kopanojest z założenia aktualizacją. Zmienia ono transport z udokumentowanego lokalnego gniazda domyślnego na TCP. Może to być przydatne do debugowania lub w topologii wymagającej TCP, ale zmienia również bezpieczeństwo i powierzchnię operacyjną. W przypadku konfiguracji z tym samym hostem, naprawienie brakującego lub niedostępnego gniazda jest często bardziej przejrzyste niż otwarcie kolejnego nasłuchującego.

Co zrobić, jeśli błąd nadal występuje?

W tym momencie należy zebrać dowody z obu stron związku:

• dokładna DEFAULT_SERVERwartość, z usuniętymi danymi uwierzytelniającymi lub tajemnicami;
• systemctl status kopano-serveri ostatnie wpisy w dzienniku serwera Kopano;
• informacje o właścicielu gniazda lub zdalnym odbiorniku;
• wersja PHP i załadowane rozszerzenie MAPI w środowisku wykonawczym serwera WWW;
• Dziennik błędów WebApp/PHP dotyczący nieudanej próby logowania.

Dokumentacja aplikacji internetowej Kopano informuje, że rejestrowanie błędów PHP jest włączane poprzez ustawienia PHP config.phpi ostrzega przed bezpośrednim wyświetlaniem błędów, ponieważ może to spowodować uszkodzenie odpowiedzi JSON. Z tego powodu logi po stronie serwera są lepszym źródłem diagnostyki. Przed zwiększeniem szczegółowości zapoznaj się z oficjalnymi ustawieniami rejestrowania aplikacji internetowej .

Po ustaleniu, czy awaria dotyczy uruchamiania rdzenia, transportu, uprawnień, PHP-MAPI czy sieci zdalnej, zastosuj najmniejszą poprawkę, która rozwiązuje ten problem. To rozwiązanie jest skuteczniejsze niż traktowanie komunikatu „Nie można połączyć się z rdzeniem Kopano” jako pojedynczego błędu z jednym uniwersalnym rozwiązaniem.