Risolvi l'errore di connessione "Beh, che imbarazzo" di Collabora Online

Il messaggio di Collabora Online "Che imbarazzo, non riusciamo a connetterci al tuo documento" è un sintomo, non una diagnosi. Viene visualizzato dopo il caricamento della shell dell'editor, ma la sessione del documento non riesce a completarsi. Nelle implementazioni attuali, il modo più rapido per risolvere il problema è identificare quale connessione nel percorso WOPI non funziona, anziché modificare impostazioni di Collabora a caso.

Questa guida utilizza come punti di riferimento la documentazione di amministrazione di Nextcloud 35 e le linee guida dell'SDK 25.04 di Collabora Online. La stessa logica di risoluzione dei problemi si applica a molte integrazioni ownCloud e WOPI personalizzate, ma i nomi esatti delle impostazioni possono variare a seconda della piattaforma e della versione.

Quali sono le cause solitamente di questo errore di connessione collaborativa?

Una sessione di navigazione funzionante dipende da diversi passaggi distinti. Il browser dell'utente deve raggiungere sia il server di archiviazione che Collabora; il server di archiviazione deve raggiungere Collabora; Collabora deve raggiungere il server di archiviazione; i protocolli e i certificati devono essere compatibili; e il proxy inverso deve inoltrare correttamente le route HTTP e WebSocket di Collabora. La pagina ufficiale di risoluzione dei problemi di Nextcloud elenca esplicitamente questi requisiti di raggiungibilità bidirezionale.

Ciò significa che non esiste un'unica soluzione universalmente corretta. Scegli il percorso di riparazione in base al primo test fallito:

1. Verificare gli endpoint di rilevamento e funzionalità di Collabora

Inizia con l'URL pubblico di Collabora che la tua integrazione utilizza effettivamente. Apri questi endpoint in un browser e dal server di archiviazione:

https://office.example.com/hosting/discovery
https://office.example.com/hosting/capabilities

La documentazione di Nextcloud per la risoluzione dei problemi raccomanda entrambi i test. L'endpoint di rilevamento dovrebbe restituire dati XML, mentre il test delle funzionalità dovrebbe restituire dati relativi alle funzionalità di Collabora. Un timeout, un avviso relativo al certificato, un errore 404, una pagina di errore con il marchio del proxy o un ciclo di reindirizzamento indicano che è necessario risolvere i problemi di rete o del proxy inverso prima di modificare le impostazioni WOPI.

Innanzitutto, verifica gli URL pubblici di individuazione e funzionalità di Collabora; entrambi devono essere raggiungibili tramite lo stesso nome host utilizzato dall'integrazione.

Per indicazioni autorevoli sugli endpoint, consultare la sezione Risoluzione dei problemi di Nextcloud Office e il manuale dell'SDK di Collabora Online 25.04 .

2. Testa tutte e quattro le direzioni di rete, non solo il browser.

Un errore comune è presumere che, poiché office.example.comsi apre in un browser desktop, Collabora possa anche recuperare i file dal server di archiviazione. Questo non è garantito. Eseguite dei test direttamente sugli host o sui container:

# From the Nextcloud/storage server
curl -fsS https://office.example.com/hosting/discovery >/dev/null && echo OK

# From the Collabora host/container
curl -fsS https://cloud.example.com/status.php

# Then inspect Collabora logs
docker logs --tail 100 collabora

Se il nome host pubblico viene risolto in modo diverso all'interno di Docker, Kubernetes o in una rete privata, è necessario decidere se correggere il DNS interno, aggiungere una mappatura host appropriata o instradare il traffico attraverso l'endpoint pubblico. Il DNS interno è generalmente più pulito su larga scala; una voce nel file hosts è veloce per una piccola installazione statica, ma diventa più difficile da gestire.

Esegui test di raggiungibilità direttamente dai server, quindi utilizza il registro di Collabora per distinguere un errore di rete da un errore di attendibilità WOPI.

3. Correggi il proxy inverso se mancano le route WebSockets o Collabora.

Collabora non è una normale applicazione web statica. Il suo reverse proxy necessita di percorsi per le risorse del browser, il rilevamento/le funzionalità, il traffico dei documenti e i WebSocket. Nel manuale dell'SDK di Collabora, l'esempio Nginx inoltra /browser, /hosting/discovery, /hosting/capabilities, il /cool/.../wspercorso WebSocket e /coolil /looltraffico correlato.

Per il percorso WebSocket, il proxy deve preservare l'host e passare l'aggiornamento HTTP. Un modello Nginx semplificato è il seguente:

location ~ ^/cool/(.*)/ws$ {
    proxy_pass http://127.0.0.1:9980;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 36000s;
}

Non copiate ciecamente questo schema se la terminazione TLS è diversa. Collabora documenta modelli separati per la terminazione TLS end-to-end e SSL. Se la terminazione TLS avviene su Nginx e la connessione backend è HTTP, le impostazioni SSL interne di Collabora devono corrispondere a tale configurazione. Utilizzare HTTPS ovunque è più semplice da gestire, mentre la terminazione TLS sul proxy riduce la gestione dei certificati all'interno dei container, ma introduce un ulteriore livello di configurazione.

Un proxy inverso corretto deve inoltrare le route HTTP di Collabora e preservare l'aggiornamento WebSocket per la sessione del documento.

4. Verificare la coerenza del protocollo, del certificato e del nome host.

La documentazione di configurazione di Nextcloud per Office indica che il server Collabora Online dovrebbe utilizzare lo stesso protocollo dell'installazione di Nextcloud, con HTTPS consigliato. In pratica, le configurazioni miste HTTP/HTTPS pubbliche possono causare il blocco dei contenuti, reindirizzamenti errati o errori di convalida dei certificati backend.

Verificate insieme questi elementi:

• L'URL di Collabora salvato nella tua piattaforma di archiviazione è esattamente l'URL pubblico a cui gli utenti accedono.
• Il certificato presentato da tale nome host è valido per il nome host ed è considerato attendibile dal server di archiviazione.
• Collabora è in grado di convalidare il certificato HTTPS del server di archiviazione.
• Il tuo proxy inverso inoltra correttamente l'host e lo schema originali.
• Non è previsto alcun reindirizzamento dal nome host di Collabora configurato a un altro nome host non previsto da WOPI.

Un certificato autofirmato può essere accettabile in un ambiente di laboratorio se ogni componente è esplicitamente configurato per considerarlo attendibile, ma questa comodità va a scapito della portabilità e spesso causa il fallimento di aggiornamenti o ricostruzioni di container in un secondo momento. Per la produzione, una catena di certificati pubblicamente attendibile o considerata attendibile dall'organizzazione è la scelta più sicura.

5. Correggere le liste di elementi consentiti WOPI anziché disabilitarle.

Se il rilevamento funziona e i log di Collabora mostrano messaggi come " Unauthorized WOPI hostnessun host WOPI accettabile corrispondente alla destinazione", il problema si è spostato dalla connettività di base alla configurazione della fiducia. La documentazione ufficiale di Nextcloud per la risoluzione dei problemi indica specificamente agli amministratori di consultare i log del container per questo caso.

Per quanto riguarda lo storage, Nextcloud consiglia di limitare le richieste WOPI agli indirizzi IP dei server Collabora utilizzando l' impostazione "Consenti elenco per richieste WOPI" . Lato Collabora, gli host di storage WOPI consentiti devono corrispondere agli URL di storage effettivamente ricevuti da Collabora. Per più domini di storage, l'SDK di Collabora documenta i gruppi di alias WOPI.

Mantieni l'URL del server Collabora e l'elenco di elementi consentiti WOPI allineati con la distribuzione reale; utilizza voci attendibili ristrette anziché disattivare la convalida.

Consulta la configurazione di Nextcloud Office per l'URL del server corrente e le indicazioni sulla lista di autorizzazione WOPI. Se utilizzi ownCloud Infinite Scale, il suo servizio di collaborazione utilizza COLLABORATION_APP_ADDRl'URL dell'app Office e COLLABORATION_WOPI_SRCla sorgente WOPI raggiungibile esternamente; consulta la documentazione del servizio di collaborazione di ownCloud .

Quando è consigliabile utilizzare CODE integrato anziché un server Collabora separato?

Per un'installazione Nextcloud di piccole dimensioni, il server CODE integrato riduce il numero di componenti gestiti esternamente. Il compromesso è che dipende comunque dalla capacità dell'istanza Nextcloud di raggiungere se stessa tramite il nome host utilizzato nel browser. La documentazione di Nextcloud per la risoluzione dei problemi lo specifica chiaramente e suggerisce di risolvere correttamente tale nome host quando il server CODE integrato non riesce a connettersi.

Un server Collabora separato è generalmente più adatto quando è necessario un dimensionamento indipendente, un servizio centralizzato per più istanze di storage o un'architettura di produzione con confini delle risorse più definiti. Aggiunge la configurazione di DNS, proxy, certificati, firewall e trust WOPI, quindi il carico operativo è maggiore.

Cosa non fare

• Non disabilitare la convalida WOPI come prima soluzione. Ciò potrebbe nascondere l'effettiva mancata corrispondenza del nome host e indebolire un livello di sicurezza.
• Non esporre direttamente la porta 9980 solo perché il proxy non funziona. Ripara il proxy, a meno che l'esposizione diretta non sia una scelta di sicurezza intenzionale.
• Non dare per scontato che una risposta 200 dalla homepage di Collabora dimostri che la modifica dei documenti funziona. Rilevamento, funzionalità, accesso ai file WOPI e WebSockets sono percorsi separati.
• Non modificare più livelli contemporaneamente. Esegui un test dopo ogni modifica per capire se la vera causa del problema risiedeva in DNS, TLS, proxy o nella relazione di fiducia WOPI.

Lista di controllo per la verifica finale

Dopo aver apportato una modifica, verificare il sistema nel seguente ordine:

1. Apri /hosting/discoverye /hosting/capabilitiesda un browser.
2. Recupera gli stessi endpoint dal server di archiviazione.
3. Dal server Collabora, recuperare l'URL dello stato del server di archiviazione.
4. Apri un documento monitorando contemporaneamente i log di Collabora e quelli di archiviazione.
5. Verificare che il browser stabilisca la connessione WebSocket di Collabora senza disconnessioni ripetute.
6. Se è richiesta la modifica collaborativa, verificare che un secondo utente possa aprire e modificare un documento di prova.

Se tutti e sei i controlli hanno esito positivo, il messaggio generico "Beh, che imbarazzo!" non dovrebbe più mascherare un errore di connessione. Se il messaggio persiste, acquisisci le righe esatte del log di Collabora e l'errore di rete del browser per un tentativo di apertura del documento; queste due informazioni sono più utili del messaggio generico dell'interfaccia utente.