Risolvere l'errore "Impossibile connettersi a Kopano Core" nella WebApp di Kopano.

Il modo più rapido per risolvere un errore "Impossibile connettersi a Kopano Core" in Kopano WebApp è determinare quale dei tre livelli è effettivamente guasto: Kopano Core stesso , l' endpoint WebApp-Core o il livello PHP-MAPI che WebApp utilizza per comunicare con Core. Riavviare tutto può a volte sembrare risolvere il problema, ma nasconde la causa e può rendere più difficile la diagnosi di guasti ricorrenti.

La documentazione ufficiale di Kopano WebApp afferma che WebApp dipende da php-mapie che la sua DEFAULT_SERVERimpostazione controlla dove WebApp si connette a Kopano Core. Le opzioni documentate includono il socket Unix locale, HTTP sulla porta 236 e HTTPS sulla porta 237. Consultare la documentazione di configurazione di Kopano WebApp e il Manuale di amministrazione di Kopano Core .

Nota importante sulla versione: i manuali di amministrazione pubblici di Kopano disponibili al momento della stesura di questo documento sono precedenti a molte distribuzioni Linux attualmente in uso. I nomi dei pacchetti, le versioni di PHP, i wrapper dei servizi e le posizioni dei file di log potrebbero quindi differire nella vostra installazione. Il modello di connessione e le opzioni di configurazione descritte di seguito si basano sulla documentazione ufficiale di Kopano, ma è consigliabile verificare i percorsi locali e le versioni dei pacchetti prima di apportare modifiche a un server di produzione.

Quale soluzione dovresti provare per prima?

Iniziate dal sintomo che meglio corrisponde al vostro sistema, invece di applicare tutte le modifiche contemporaneamente.

1. Kopano Core è effettivamente in esecuzione?

Prima di modificare la configurazione di WebApp, verifica il processo del server. Su una distribuzione basata su systemd, utilizza:

sudo systemctl status kopano-server

Se l'unità è guasta o inattiva, controllare il registro degli eventi recenti prima di riavviarla:

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

Cerca errori di connessione al database, errori di analisi della configurazione, problemi di autorizzazione, file mancanti o errori di avvio. La documentazione di Kopano Core indica che le modifiche alla configurazione generalmente richiedono il riavvio del componente interessato, ad esempio con systemctl restart kopano-<component>. Documenta inoltre /etc/kopano/server.cfgcome il file di configurazione usuale per kopano-server. Vedi Configurare i componenti KC .

Scegli questo percorso quando: il servizio è chiaramente non disponibile, si blocca dopo l'avvio o anche altri strumenti Kopano non riescono a comunicare con Core. Risolvere prima il problema con WebApp tratterebbe solo un sintomo secondario.

Compromesso: il riavvio è il tentativo di ripristino più rapido, ma se il processo fallisce di nuovo immediatamente, è necessario l'output del registro. Nei sistemi di produzione, è consigliabile acquisire i dettagli dell'errore prima del riavvio per non perdere le prove più evidenti.

2. L'applicazione Web punta all'endpoint corretto di Kopano Core?

In WebApp, l'impostazione chiave si trova DEFAULT_SERVERin config.php. Il manuale ufficiale di Kopano per WebApp documenta questi esempi:

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 configurazione predefinita documentata si basa sul socket locale file:///var/run/kopano/server.sock. Questa è solitamente la scelta più semplice quando WebApp e Core vengono eseguiti sulla stessa macchina. Se vengono eseguiti su macchine separate, un socket Unix locale non può funzionare; è necessario invece un endpoint HTTP o HTTPS raggiungibile. La documentazione di Kopano sull'ottimizzazione delle prestazioni descrive un host WebApp che si connette a un server Kopano separato tramite la porta 236, o la porta 237 per SSL. Vedere Ottimizzazione delle prestazioni di Kopano e configurazione di server separati .

Socket Unix locale: generalmente l'opzione con il minor overhead su un singolo host, evita di esporre un servizio TCP semplicemente per l'accesso locale all'applicazione Web. Il costo è che il socket deve esistere e il processo del server Web deve essere in grado di utilizzarlo.

HTTP sulla porta 236: più facile da testare su host diversi e adatto a reti interne affidabili, a condizione che l'architettura di sicurezza lo consenta. Il compromesso è che il traffico non viene crittografato a livello di trasporto di Kopano.

HTTPS sulla porta 237: appropriato quando è necessario un trasporto crittografato tra WebApp e Core. Introduce requisiti di configurazione e convalida dei certificati. La documentazione di configurazione specifica di Kopano mostra WebApp che utilizza HTTPS DEFAULT_SERVERe, in alcuni scenari, certificati client. Consultare le configurazioni speciali di Kopano per Core .

3. Se si utilizza un socket Unix, questo esiste ed è raggiungibile dal server web?

Per una distribuzione sullo stesso host, verificare il socket stesso:

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

Se il file non è presente, non creare un file normale con quel nome. Il socket viene creato dal server Kopano in esecuzione. Pertanto, la mancanza di un socket di solito indica un problema all'avvio di Core, un percorso del socket modificato o un'incongruenza nella configurazione.

Se il socket esiste, verificarne la proprietà e i permessi. L'utente del server web deve essere in grado di accedere al socket tramite il suo percorso di directory. A seconda della distribuzione, l'account del server web potrebbe essere www-data, apache, o un altro utente specifico del servizio. Evita di risolvere gli errori di autorizzazione con permessi generici come chmod 777; ciò aumenta l'esposizione e potrebbe essere sovrascritto la prossima volta che il servizio ricrea il socket.

Un approccio migliore consiste nell'allineare WebApp con la posizione del socket generata da Kopano e quindi utilizzare le autorizzazioni di gruppo o di servizio previste dalla distribuzione. Se il server è stato personalizzato, confrontare la configurazione di Core con l'endpoint di WebApp prima di modificarne la proprietà.

4. Cosa succede se Core è integro ma WebApp continua a segnalare un errore di connessione?

Successivamente, controlla PHP-MAPI. Kopano afferma esplicitamente che WebApp dipende da PHP-MAPI php-mapi. Il controllo della configurazione di WebApp può anche verificare la disponibilità di PHP e PHP-MAPI. Consulta la documentazione di WebApp Config.php .

Ecco un rapido controllo da riga di comando:

php -m | grep -i mapi

Tuttavia, questo test presenta un'importante limitazione: l'interfaccia a riga di comando PHP potrebbe non utilizzare la stessa configurazione di Apache PHP, PHP-FPM o di un'altra integrazione con un server web. Un risultato positivo nella CLI dimostra solo che l'ambiente CLI rileva il modulo.

Tra i controlli di follow-up utili si annoverano:

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

Quindi confrontalo con la configurazione PHP utilizzata dal tuo server web o pool FPM. Se il pacchetto è mancante o le versioni sono incompatibili, installa il set di pacchetti Kopano Core/PHP-MAPI corrispondente dal repository destinato alla tua distribuzione e versione di Kopano. Non mescolare build PHP-MAPI non correlate solo per far apparire l'estensione in php -m.

Scegli questo percorso quando: kopano-server è integro, l'endpoint è corretto e raggiungibile, ma l'applicazione Web fallisce durante i controlli di connessione o configurazione lato PHP.

Compromesso: la reinstallazione o l'aggiornamento del pacchetto potrebbe essere la soluzione giusta in caso di incompatibilità dei file binari, ma comporta modifiche a una parte maggiore del sistema rispetto alla correzione di un singolo endpoint. Verificare prima le versioni dei pacchetti e pianificare gli aggiornamenti in produzione di conseguenza.

È necessario riavviare Apache, PHP-FPM o Kopano Server?

Riavvia il componente la cui configurazione o il cui modulo sono stati effettivamente modificati.

• Se hai apportato modifiche /etc/kopano/server.cfg, riavvia kopano-server.
• Se hai installato o abilitato un'estensione PHP, riavvia il livello di servizio PHP utilizzato da WebApp, come Apache o il relativo servizio PHP-FPM.
• Se hai modificato solo il file di configurazione PHP dell'applicazione Web, di solito non è necessario riavviare completamente Kopano Core, a meno che non sia cambiato anche l'endpoint di Core stesso.

Il comando esatto per il servizio web varia a seconda della distribuzione e del pacchetto PHP. Ad esempio, potrebbe essere systemctl restart apache2, systemctl restart httpdo un'unità PHP-FPM con versione. Utilizza il nome del servizio presente sul tuo host anziché copiare un comando ciecamente.

Che dire dei server Core e dei firewall remoti?

Se WebApp e Kopano Core sono separati, prima di attribuire la colpa a WebApp, verificare il routing e il listener configurato. La documentazione di Kopano descrive l'accesso HTTP sulla porta 236 e l'accesso SSL sulla porta 237. Un'implementazione remota introduce quindi diverse modalità di errore che un'implementazione locale con socket Unix non presenta: regole del firewall, binding del listener, DNS, certificati TLS, proxy inversi e policy di rete intermedie.

Per un endpoint HTTP, è possibile almeno verificare se un listener TCP è raggiungibile dall'host dell'applicazione Web:

nc -vz core.example.net 236

Per HTTPS, verifica separatamente l'endpoint TLS con uno strumento appropriato alla tua policy di certificazione. Una connessione TCP riuscita non garantisce che l'autenticazione dell'applicazione Web o le operazioni MAPI avranno successo, ma una connessione non riuscita dimostra che PHP-MAPI non riesce a raggiungere il servizio configurato su quell'indirizzo e quella porta.

Se si utilizza un proxy inverso, ricordarsi che la documentazione di Kopano richiede che il percorso del proxy e la mappatura del backend siano coerenti con l'URL utilizzato da WebApp. Il manuale ufficiale di Core riporta anche le considerazioni relative a HTTP/1.1 per il proxy del traffico Kopano. Consultare la sezione "Configurazione del componente Kopano Core" .

Un ordine diagnostico pratico che riduce al minimo i cambiamenti non necessari

1. Verifica kopano-serverlo stato. Se non funziona, ripara prima il Core.
2. Leggere i log di Core. Eventuali errori del database o della configurazione devono essere risolti prima che WebApp possa connettersi.
3. Verifica DEFAULT_SERVER. Conferma che corrisponda a un socket locale o al corretto endpoint HTTP/HTTPS remoto.
4. Verifica il socket o il listener di rete effettivo. Questo permette di distinguere i problemi di trasporto da quelli di PHP.
5. Verifica PHP-MAPI nell'ambiente di runtime web. Non affidarti esclusivamente all'ambiente PHP da riga di comando.
6. Riavvia solo i servizi interessati. Quindi, esegui nuovamente il test dell'applicazione Web e controlla i log se l'errore persiste.

Questo ordine è più sicuro rispetto a iniziare con la reinstallazione dei pacchetti perché preserva le prove e rende significativo ogni test. Inoltre, evita l'errore opposto: riavviare ripetutamente WebApp o Apache quando Kopano Core stesso non riesce ad avviarsi.

Quando modificare DEFAULT_SERVER è la soluzione sbagliata?

Non apportare modifiche DEFAULT_SERVERsolo perché la pagina di accesso mostra un errore di connessione. Se il valore attuale punta correttamente all'istanza Core desiderata, modificarlo potrebbe nascondere il problema originale o indirizzare gli utenti al backend sbagliato.

Ad esempio, la sostituzione default:con http://localhost:236/kopanonon è di per sé un aggiornamento. Modifica il protocollo di trasporto dal socket predefinito locale documentato a TCP. Questo può essere utile per il debug o per una topologia che richiede TCP, ma modifica anche la sicurezza e la superficie operativa. Per una configurazione sullo stesso host, correggere il socket mancante o inaccessibile è spesso una soluzione più pulita rispetto all'apertura di un altro listener.

Cosa fare se l'errore persiste?

A quel punto, raccogli le prove da entrambe le parti della connessione:

• il valore esatto DEFAULT_SERVER, senza credenziali o segreti;
• systemctl status kopano-servere le recenti voci del registro del server Kopano;
• le informazioni relative alla proprietà del socket o al listener remoto;
• la versione di PHP e l'estensione MAPI caricata nell'ambiente di runtime del server web;
• Il registro degli errori dell'applicazione Web/PHP relativo a un tentativo di accesso non riuscito.

La documentazione di Kopano per le applicazioni web afferma che la registrazione degli errori PHP è abilitata tramite le impostazioni PHP config.phpe sconsiglia di visualizzare gli errori direttamente, poiché ciò potrebbe corrompere le risposte JSON. Pertanto, i log lato server rappresentano una fonte diagnostica più affidabile. Consultare le impostazioni di registrazione ufficiali dell'applicazione web prima di aumentare il livello di dettaglio.

Una volta identificato se l'errore riguarda l'avvio di Core, il trasporto, i permessi, PHP-MAPI o la rete remota, applica la soluzione più semplice che agisca su quel livello specifico. Questo approccio è più affidabile rispetto a trattare "Impossibile connettersi a Kopano Core" come un singolo errore con un'unica soluzione universale.