Risolvere il problema di avvio del container Collabora CODE su architettura ARM64

Se un container di Collabora Online Development Edition (CODE) si chiude immediatamente su una macchina ARM64, prima di modificare le impostazioni di rete, i certificati o WOPI, è consigliabile verificare la compatibilità dell'architettura. Al 7 ottobre 2026, il collabora/coderepository ufficiale elenca linux/arm64le varianti native per le versioni correnti, inclusa la latestversione 26.04.4.2.1. Ciò significa che un host ARM64 moderno in genere non necessita dell'emulazione x86 per eseguire CODE. Il flusso di lavoro più utile per i principianti consiste nel verificare l'architettura dell'host, controllare il tag dell'immagine, rimuovere eventuali impostazioni forzate per AMD64, scaricare un'immagine compatibile con ARM64 e solo successivamente risolvere i problemi di configurazione a livello di applicazione.

Questa guida si concentra sull'errore di avvio in sé. Non presuppone che ogni problema ARM64 abbia la stessa causa. Se il container si avvia correttamente ma Nextcloud, ownCloud o un altro host WOPI non riescono a connettersi ad esso, si tratta di un livello di risoluzione dei problemi diverso.

Cosa devi sapere prima di cambiare qualsiasi cosa

ARM64 è un'architettura CPU ARM a 64 bit. Linux la identifica comunemente come aarch64, mentre Docker di solito etichetta lo stesso target come linux/arm64. AMD64 , chiamato anche x86-64, è un'architettura CPU diversa. Un'immagine container contiene binari compilati per una o più architetture; Docker può selezionare automaticamente la variante corretta solo quando il tag dell'immagine fornisce un manifesto compatibile.

Un'immagine multipiattaforma è un singolo tag immagine il cui manifesto del registro punta a build di immagini separate per architetture come AMD64 e ARM64. Docker documenta che, quando viene scaricata un'immagine multipiattaforma, seleziona automaticamente la variante corrispondente per l'host. Per il comportamento sottostante, consultare la documentazione di Docker sulle immagini multipiattaforma .

Per quanto riguarda Collabora CODE nello specifico, consulta l' elenco ufficiale dei tag collabora/code su Docker Hub anziché affidarti a un vecchio tutorial. Quando questo articolo è stato verificato il 7 ottobre 2026, latestincludeva e un tag dedicato era anch'esso elencato. Le versioni precedenti potrebbero differire, quindi il tag che effettivamente implementi è più importante di un'affermazione generica come "Collabora supporta ARM".26.04.4.2.1linux/arm64latest-arm64

Preparare una sessione di risoluzione dei problemi sicura

• Conserva una copia del tuo docker-compose.ymlcomando corrente o di distribuzione.
• Annota il tag immagine Collabora esatto che stai utilizzando.
• Non eliminare i dati dell'applicazione o la configurazione del reverse proxy solo per diagnosticare un'incompatibilità architetturale.
• Se si tratta di un'implementazione in produzione, testare prima un tag sostitutivo durante una finestra di manutenzione o su un host di staging.

L'obiettivo è semplice: Docker dovrebbe scaricare un'immagine ARM64, il container dovrebbe rimanere in esecuzione invece di terminare immediatamente e i suoi log dovrebbero procedere con il normale avvio di Collabora anziché fallire con un errore di architettura.

Passaggio 1: Confermare l'host e l'architettura Docker

Esegui questi controlli sulla macchina che effettivamente esegue il container di Collabora:

uname -m
docker info --format '{{.Architecture}}'
docker version

Su un host Linux nativo a 64 bit ARM, uname -min genere restituisce aarch64, mentre Docker dovrebbe segnalare arm64. In questo contesto, questi nomi si riferiscono alla stessa famiglia di architetture.

Se Docker segnala AMD64 anche se la macchina fisica è ARM64, verifica se stai utilizzando un contesto Docker remoto, una macchina virtuale o Docker Desktop con un backend diverso. Risolvi questa ambiguità prima di continuare. Altrimenti, potresti ispezionare un sistema durante la distribuzione su un altro.

Quale errore indica un'incompatibilità architetturale?

I segnali tipici includono exec format errorun messaggio del registro che indica la presenza di un problema no matching manifest for linux/arm64, oppure un servizio Compose configurato esplicitamente con tale servizio platform: linux/amd64. Questi messaggi forniscono prove più solide di un'incompatibilità di piattaforma rispetto al generico output "container exited".

Passaggio 2: Ispeziona l'esatto tag dell'immagine Collabora prima di trascinarla

Non dare per scontato che ogni tag storico abbia lo stesso supporto della piattaforma di oggi latest. Controlla i metadati del registro per il tag nella tua implementazione:

docker buildx imagetools inspect collabora/code:latest

La documentazione di Docker relativa al comando `buildx imagetools inspect` spiega come questo comando visualizza le piattaforme contenute in un'immagine del registro. È possibile utilizzare anche docker manifest inspect; Docker documenta questo comando nel suo riferimento all'ispezione del manifest .

Se linux/arm64appare, puoi usare il tag multi-piattaforma e lasciare che Docker selezioni l'immagine corretta. Per un test di risoluzione dei problemi esplicito, il repository ufficiale elenca anche latest-arm64. Per le implementazioni di produzione a lungo termine, un tag con versione esatta che hai testato è solitamente più facile da riprodurre rispetto a latest, perché latestsi sposta man mano che vengono pubblicate nuove versioni.

Se il tag che hai aggiunto non include ARM64, hai tre opzioni:

Passaggio 3: rimuovere un override AMD64 accidentale e scaricare in modo pulito

Un errore comune non è l'immagine Collabora stessa, ma un file di distribuzione che impone la piattaforma sbagliata. Docker Compose definisce platformil sistema operativo di destinazione e l'architettura utilizzati per selezionare la variante dell'immagine. La documentazione del servizio Docker Compose mostra valori come linux/arm64/v8.

Su un host ARM64, questa impostazione è sospetta:

services:
  collabora:
    image: collabora/code:latest
    platform: linux/amd64

Se non hai bisogno dell'emulazione, rimuovi quella riga e lascia che Docker scelga la variante nativa dell'host. In alternativa, specifica platform: linux/arm64quando desideri che l'architettura sia esplicita.

Quindi rimuovi solo il container non riuscito e scarica nuovamente l'immagine. Non eliminare i dati persistenti a meno che tu non abbia un motivo specifico per farlo:

docker compose down
docker image rm collabora/code:latest 2>/dev/null || true
docker pull --platform linux/arm64 collabora/code:latest
docker compose up -d

Se si utilizza il tag di architettura dedicato per un'esecuzione diagnostica, sostituire collabora/code:latest-arm64. Una volta confermato che la distribuzione funziona, valutare la possibilità di bloccare una versione esatta, ad esempio un tag 26.04.x ​​testato, anziché lasciare un sistema di produzione su un tag in continuo cambiamento.

Passaggio 4: Verificare che CODE si avvii prima di procedere alla risoluzione dei problemi di integrazione.

Dopo aver ricreato il container, verifica lo stato e i log:

docker compose ps
docker compose logs --tail=100 collabora

Per una distribuzione a singolo container, i comandi equivalenti sono docker ps -ae docker logs --tail=100 <container-name>.

Il primo criterio di successo è che il container rimanga attivo e non si blocchi più con un errore relativo al manifesto o al formato dell'eseguibile. Solo dopo aver verificato ciò, si può procedere alla verifica della raggiungibilità della porta 9980, delle impostazioni del reverse proxy, del TLS, degli host WOPI consentiti o dell'integrazione dell'applicazione. La documentazione ufficiale di Collabora per CODE Docker è la fonte più indicata per verificare i parametri di distribuzione correnti.

Errori comuni da principiante da evitare

Installare QEMU prima di controllare l'immagine ufficiale

L'emulazione può essere utile quando il software esiste solo per un'altra architettura CPU, ma le attuali immagini Collabora CODE includono varianti ARM64. Aggiungere prima l'emulazione può nascondere il problema reale e introdurre un ulteriore elemento da gestire. È preferibile utilizzare l'architettura nativa ARM64 quando la versione di CODE richiesta la supporta.

Presupponendo che "ultimo" e un vecchio tag appuntato siano equivalenti

La disponibilità della piattaforma è associata a uno specifico tag immagine e al relativo manifesto. Un tag corrente può supportare ARM64, mentre una versione precedente no. Verifica il riferimento esatto nel tuo file Compose.

Imposizione della piattaforma: linux/amd64 perché una vecchia guida la utilizzava

Ciò può indurre un host ARM64 a utilizzare la variante x86-64 anche in presenza di un'immagine nativa ARM64. Rimuovere l'override a meno che non si disponga di un motivo specifico e comprovato per l'emulazione.

Modifica delle impostazioni WOPI, SSL o proxy prima che il processo possa essere eseguito

Si verifica un exec format errorproblema prima che Collabora possa elaborare in modo significativo la maggior parte delle configurazioni a livello di applicazione. Correggi prima la selezione dell'architettura. La risoluzione dei problemi di rete e WOPI verrà dopo.

Eliminazione dei volumi durante la diagnosi

In genere, le incongruenze architetturali non richiedono la distruzione dei dati persistenti. È consigliabile limitare l'ambito della correzione per semplificare il ripristino.

E se l'immagine ARM64 esistesse ancora?

Se il manifesto include chiaramente linux/arm64e Docker scarica quella variante, l'architettura non è più la spiegazione principale. A quel punto, cattura:

• docker compose psOdocker ps -a
• le ultime 100-200 righe del log
• il tag CODE esatto
• le tue versioni di Docker Engine e Compose
• le parti non segrete della definizione del servizio Compose

Successivamente, analizza le autorizzazioni, i percorsi montati, i profili di sicurezza, la pressione della memoria, i conflitti di porte, i certificati o la configurazione WOPI in base al messaggio di log effettivo. Evita di cambiare ripetutamente architettura una volta verificato che l'immagine in esecuzione sia ARM64.

Un percorso decisionale pratico

1. Se il sistema host non è ARM64, interrompi l'utilizzo di una soluzione specifica per ARM64 e diagnostica la piattaforma reale.
2. Se l'host è ARM64 ma il tag CODE scelto non ha un manifesto ARM64, passare a un tag nativo supportato oppure scegliere deliberatamente una strategia di hosting diversa.
3. Se il tag supporta ARM64 ma Compose impone AMD64, rimuovere o correggere l' platformimpostazione.
4. Se l'immagine ARM64 corretta è ancora presente, trattatela come un normale problema di avvio di Collabora e consultate i log anziché continuare ad attribuire la colpa all'architettura della CPU.

In conclusione

Su un moderno sistema ARM64, la soluzione preferibile di solito non è l'emulazione. Come verificato il 7 ottobre 2026, i tag Collabora CODE ufficiali attuali includono immagini native ARM64. Confermare aarch64/ arm64sull'host, esaminare il manifesto dell'immagine esatto, eliminare i riferimenti AMD64 obsoleti o forzati, scaricare nuovamente l'immagine compatibile con ARM64 e verificare che il container rimanga in esecuzione. Questa sequenza rende la risoluzione dei problemi accessibile anche ai principianti ed evita che modifiche non correlate a SSL, proxy o WOPI mascherino un'incompatibilità di base della piattaforma.