Installazione dell'app CasaOS fallita: registri, DNS e porte

Un fallimento nell'installazione di un'app CasaOS di solito si presenta come un semplice errore nell'interfaccia utente: lo store delle app non si carica, il pulsante di installazione fallisce o il contenitore appare ma non si apre mai. La causa reale è solitamente più profonda dell'interfaccia CasaOS. CasaOS è progettato per un'installazione con un clic e il deployment di app Docker, quindi un'installazione fallita può derivare dal livello di servizio CasaOS, dal download dell'immagine Docker, dalla risoluzione DNS, dall'ora di sistema, dall'architettura CPU o da conflitti di porta host.

Il modo più sicuro per risolvere i problemi non è reinstallare CasaOS subito. Inizia leggendo l'errore reale, poi testa un livello alla volta: log, rete e DNS, sincronizzazione dell'ora, architettura CPU, porte e compatibilità Docker.

Sintesi rapida: Il messaggio di errore di CasaOS è solo il primo sintomo

Un messaggio generico “installazione fallita” indica che CasaOS non ha potuto completare il deployment, ma non specifica quale livello ha fallito. Il catalogo app potrebbe non essersi caricato, Docker potrebbe non aver scaricato l'immagine, l'immagine potrebbe non corrispondere all'architettura CPU, una porta host potrebbe essere già occupata o il contenitore potrebbe essersi avviato e poi bloccato.

L'installazione dell'app CasaOS dipende sia dal livello di servizio CasaOS sia dall'ambiente Docker sottostante. Il download delle immagini Docker può essere influenzato anche dall'accesso al registro, dalle impostazioni del proxy, da connessioni a bassa larghezza di banda e dai timeout di download dei layer.

Usa questo ordine:

# 1. Leggi i log del servizio CasaOS
journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

# 2. Controlla i contenitori Docker
docker ps -a

# 3. Leggi i log del contenitore fallito
docker logs --tail 100 <nome_o_id_container>

# 4. Testa l'accesso a DNS e registro
getent hosts github.com
getent hosts registry-1.docker.io

# 5. Controlla l'ora di sistema
timedatectl

# 6. Controlla l'architettura CPU
uname -m

# 7. Controlla le porte in ascolto
sudo ss -tulpn | grep LISTEN

Inizia con i log prima di modificare le impostazioni

I log sono il modo più rapido per distinguere un problema di CasaOS da un problema di Docker, rete, immagine o app. Il sistema Linux journalctl il comando stampa le voci dal journal di systemd, e il suo -u l'opzione filtra i log per una specifica unità di servizio.

Per CasaOS, inizia con i log a livello di servizio:

journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

Quindi controlla Docker. Il Docker docker logs il comando recupera i log da un contenitore, e il --follow l'opzione può trasmettere nuovi output mentre il contenitore è in esecuzione.

docker ps -a
docker logs --tail 100 <nome_o_id_container>
docker logs -f <nome_o_id_container>

Quello che stai cercando:

Indizio nel log	Probabile direzione
host inesistente / errore di ricerca DNS	Risoluzione DNS o di rete
connessione scaduta	Rete, proxy, firewall, accesso al registro o larghezza di banda bassa
certificato / errore TLS / x509	Ora di sistema, certificati CA o intercettazione HTTPS
errore di formato exec	Architettura CPU errata per l'immagine
la porta è già allocata / bind: indirizzo già in uso	Conflitto di porta host
versione minima API supportata	Incompatibilità tra client Docker e API del demone
Il contenitore si chiude immediatamente	Configurazione app, permessi volume, variabile d'ambiente mancante o problema dell'immagine

La regola è semplice: non correggere cinque cose contemporaneamente. Copia la prima riga di errore chiara, poi testa il livello a cui si riferisce.

Controlla DNS e accesso di rete

Se lo store delle app non si carica o l'installazione fallisce durante il download di un'immagine, controlla DNS e accesso di rete in uscita prima di modificare le impostazioni di CasaOS. Docker scarica immagini da registri come Docker Hub. Se il tuo host CasaOS non riesce a risolvere i domini del registro, il download delle immagini potrebbe fallire prima ancora che il contenitore venga creato.

Usa test di risoluzione nomi invece di usare solo ping:

getent hosts github.com
getent hosts registry-1.docker.io
getent hosts hub.docker.com

Il getent Il comando interroga database configurati tramite il Name Service Switch, incluso il database hosts usato per le ricerche di hostname. Se questi comandi non restituiscono nulla, CasaOS potrebbe non riuscire a raggiungere GitHub, Docker Hub o un catalogo app personalizzato anche se la dashboard locale si apre ancora.

Poi controlla la configurazione del resolver:

cat /etc/resolv.conf

Su Linux, /etc/resolv.conf è il file di configurazione del resolver usato per il DNS, e il nameserver Le voci definiscono quali server DNS il resolver deve interrogare. Se il DNS è rotto, passare temporaneamente a resolver pubblici stabili può confermare se questo è il problema:

sudo nano /etc/resolv.conf

Esempio di test temporaneo:

nameserver 1.1.1.1
nameserver 8.8.8.8

Non fermarti a “internet funziona sul mio laptop.” CasaOS gira sul server, quindi è il percorso DNS del server che conta.

Controlla l'ora di sistema prima di incolpare lo store delle app

Un orario di sistema errato può compromettere HTTPS e la validazione dei certificati in modi che sembrano errori dello store o del registro app. Prima di modificare la configurazione di Docker o CasaOS, verifica che l'orologio del server sia corretto e che la sincronizzazione dell'ora sia attiva.

timedatectl

Nell'output, cerca righe come:

Orologio di sistema sincronizzato: sì
Servizio NTP: attivo

Se la sincronizzazione è disattivata, abilitala:

sudo timedatectl set-ntp true

Dopo averla abilitata, attendi un momento e riesegui timedatectl prima di riprovare l'installazione dell'app CasaOS.

Conferma che l'architettura della tua CPU corrisponda all'immagine dell'app

CasaOS può funzionare su diverse piattaforme hardware, inclusi dispositivi x86-64 e ARM. Questo non significa che ogni app Docker in ogni catalogo supporti ogni architettura. Un Raspberry Pi, Orange Pi, scheda ARM mini o box Android riutilizzato potrebbe non riuscire a eseguire un'immagine costruita solo per linux/amd64.

Controlla l'architettura del tuo host:

uname -m

uname -m risultato	Significato usuale
x86_64	AMD64 / x86-64
aarch64	ARM64
armv7l	ARM a 32 bit
i386 / i686	x86 a 32 bit

Il codice del contenitore deve essere compatibile con l'architettura dell'host perché i contenitori condividono il kernel dell'host. Senza emulazione, non è possibile eseguire un linux/amd64 contenitore su un arm64 host. Le immagini multi-piattaforma risolvono questo fornendo varianti come linux/amd64 e linux/arm64 sotto un'immagine.

Se i log mostrano errore di formato exec, controlla la pagina dell'immagine o il manifesto del registro per il supporto ARM. Se l'immagine non supporta la tua piattaforma, cambiare le impostazioni di CasaOS non risolverà il problema. Hai bisogno di un'immagine multi-arch, un tag diverso o un'app diversa.

Controlla conflitti di porta prima di reinstallare

Alcune installazioni di app CasaOS si completano, ma l'app non si apre comunque. In molti casi, il container è partito ma la porta host era già occupata o mappata in modo errato.

Controlla le porte in ascolto attive:

sudo ss -tulpn | grep LISTEN

Poi confronta il risultato con le impostazioni delle porte dell'app. Docker Compose definisce porte come mappature tra la macchina host e i container, e queste mappature permettono l'accesso esterno ai servizi in esecuzione all'interno dei container.

Una mappatura tipica è questa:

porte:
  - "8080:80"

Parte	Significato
8080	Porta host: quella che il tuo browser visita
80	Porta container: quella su cui l'app ascolta all'interno del container

Se un altro servizio usa già la porta host 80, non cambiare prima la porta del container. Cambia la porta host con un valore non utilizzato:

porte:
  - "8080:80"

Questo è particolarmente importante per app come proxy inversi, blocchi pubblicità, dashboard e server web, perché spesso usano di default porte 80, 443, 8080, o 3000.

Una lista di controllo pratica per i fallimenti delle app CasaOS

Usa questa lista di controllo prima di reinstallare CasaOS o eliminare i container.

Controlla	Comando	Segnale positivo	Segnale negativo
Log del servizio CasaOS	journalctl -xeu casaos-app-management --no-pager	Flusso di installazione chiaro o errore specifico	Fallimento ripetuto del servizio o errore API Docker
Log live di CasaOS	journalctl -u casaos -f	Azioni UI appaiono nei log	Azione dell'app fallisce silenziosamente o si blocca in loop
Elenco container Docker	docker ps -a	Container creato e stato visibile	Container mancante o che si riavvia ripetutamente
Log del container	docker logs --tail 100 <contenitore>	App avviata normalmente	Errore di uscita, permessi, configurazione o architettura
Ricerca DNS	getent hosts registry-1.docker.io	Indirizzi IP restituiti	Nessun risultato o errore di ricerca
Download immagine	docker pull <image>:<tag>	Download immagine	Timeout, TLS, autenticazione o nessun manifesto corrispondente
Ora di sistema	timedatectl	Orologio sincronizzato, NTP attivo	Deriva temporale o NTP inattivo
Architettura	uname -m	La piattaforma dell'immagine corrisponde	Host ARM con immagine solo amd64
Porte	sudo ss -tulpn | grep LISTEN	Porta host inutilizzata	Porta già occupata

Modelli comuni di errore e cosa significano di solito

Lo Store delle app non si carica

Se lo Store delle app non si carica, inizia con il DNS e l'accesso alla rete. CasaOS dipende da cataloghi esterni e fonti di immagini durante i normali flussi di lavoro delle app, quindi il server deve essere in grado di risolvere e raggiungere queste fonti.

Controlla:

getent hosts github.com
getent hosts registry-1.docker.io
timedatectl
journalctl -u casaos -f

Se il DNS fallisce, correggi il resolver del server. Se il DNS funziona ma il download Docker fallisce, verifica l'accesso al registro e le condizioni di proxy o firewall.

Installazione dell'app fallita durante il download dell'immagine

Se l'installazione fallisce durante il download dell'immagine, copia l'errore esatto di Docker. Prova manualmente:

docker pull <image>:<tag>

Se il pull manuale fallisce con errori DNS o timeout, il problema non è l'interfaccia CasaOS. Se fallisce con un errore di architettura o nessun manifesto corrispondente, controlla la piattaforma dell'immagine.

L'app si installa ma non si apre

Se l'app risulta installata ma il browser non riesce ad aprirla, controlla prima le porte. Una porta host errata o in conflitto può far sembrare rotto un contenitore funzionante.

Controlla:

docker ps
sudo ss -tulpn | grep LISTEN

Poi verifica se l'app è associata alla porta host che stai visitando.

L'app si avvia e si ferma immediatamente

Se il contenitore esiste ma si chiude, leggi i log del contenitore:

docker logs --tail 100 <contenitore>

Cerca variabili d'ambiente mancanti, percorsi volume non validi, errori di database, errori di permessi o errore di formato exec.

I log mostrano errori di versione API Docker

Se i log menzionano incompatibilità della versione API Docker, non indovinare. Esegui prima:

docker version

I problemi di versione dell'API Docker devono essere trattati come casi avanzati di risoluzione problemi. Considera un override dell'API solo se i log mostrano chiaramente una incompatibilità. Non aggiungere un override systemd solo perché un'app è fallita una volta.

Problemi di Docker e permessi nelle app CasaOS

Alcune app falliscono perché il contenitore è stato creato ma non ha l'accesso previsto a un volume, dispositivo o percorso di rete. Questo è comune quando gli utenti installano template personalizzati, spostano dati dell'app, montano dischi esterni o modificano manualmente le cartelle host.

Controlla i percorsi mappati dell'app e i log:

docker inspect <nome_o_id_contenitore>
docker logs --tail 100 <nome_o_id_container>

Cerca:

• cartella host mancante;
• permesso negato;
• filesystem di sola lettura;
• impossibile inizializzare il database;
• file di configurazione non trovato;
• percorso del dispositivo mancante;
• l'utente del contenitore non può scrivere sul volume montato.

Quando l'errore indica un problema di volume o permessi, correggi prima il percorso o i permessi. Reinstallare l'app senza modificare il percorso errato di solito ricrea lo stesso errore.

Errori che rendono più difficile la risoluzione dei problemi di CasaOS

Errore 1: Reinstallare l'app prima di leggere i log

Reinstallare può nascondere l'errore originale e creare contenitori duplicati, volumi orfani o ripetuti download di immagini. Leggi prima i log del servizio CasaOS e i log dei contenitori Docker.

Errore 2: Sistemare il DNS senza testare la risoluzione dei nomi

Cambiare il DNS casualmente può rendere più difficile la risoluzione dei problemi. Testa prima la risoluzione con getent hosts. Se il server non riesce a risolvere i domini del registro o del catalogo, allora modifica la configurazione del resolver.

Errore 3: Ignorare la compatibilità tra immagini ARM e AMD64

CasaOS può funzionare su dispositivi ARM, ma non tutte le immagini delle app supportano ARM. Se il tuo host è aarch64 o armv7l e l'immagine è solo amd64, l'installazione potrebbe fallire o il container potrebbe uscire con errore di formato exec.

Errore 4: Cambiare le porte del container invece delle porte host

Se la documentazione dell'app dice che il container ascolta sulla porta 80, non cambiare la porta interna del container a meno che tu non sappia che l'app la supporta. Cambia invece la porta host. Questo mantiene intatto il comportamento interno del servizio dell'app evitando conflitti a livello host.

Come riprovare l'installazione in sicurezza

Dopo aver trovato la causa probabile, riprova in modo controllato:

1. Salva il messaggio di errore esatto.
2. Correggi un solo strato alla volta.
3. Riavvia il servizio correlato solo se necessario.
4. Riprova l'installazione dell'app.
5. Guarda i log mentre riprovi.
6. Controlla se il container esiste.
7. Controlla se la porta dell'app è in ascolto.
8. Apri l'app dall'IP host e dalla porta host corretti.

Un tentativo sicuro potrebbe essere così:

journalctl -u casaos -f

In un altro terminale:

docker ps -a
docker logs -f <nome_o_id_container>

Poi riprova l'app in CasaOS. Questo ti dà l'azione UI, il comportamento del servizio CasaOS e l'output del container Docker in un unico passaggio.

FAQ

Perché CasaOS dice che l'installazione dell'app è fallita?

Perché uno strato nella catena di installazione è fallito. La causa può essere i log del servizio CasaOS, il download dell'immagine Docker, DNS, ora di sistema, architettura CPU, conflitti di porte, permessi o compatibilità API Docker. Inizia dai log, poi testa lo strato indicato dal primo errore reale.

Come controllo i log di installazione di un'app CasaOS?

Inizia con:

journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

Poi controlla Docker:

docker ps -a
docker logs --tail 100 <nome_o_id_container>

Perché CasaOS non riesce a caricare l'App Store?

I controlli più comuni sono DNS, accesso di rete in uscita, ora di sistema e log del servizio CasaOS. Testa il DNS dal server stesso con getent hosts github.com e getent hosts registry-1.docker.io, poi controlla timedatectl e journalctl -u casaos -f.

Cosa significa errore di formato exec cosa significa in CasaOS?

Di solito significa che l'immagine Docker non corrisponde all'architettura della tua CPU. Per esempio, un host ARM potrebbe cercare di eseguire un'immagine solo amd64. Controlla uname -m e conferma se l'immagine supporta la tua piattaforma.

Come faccio a sapere se un'app CasaOS è fallita a causa di un conflitto di porte?

Controlla quali porte sono già in ascolto:

sudo ss -tulpn | grep LISTEN

Quindi confrontalo con la porta host dell'app. Se un altro servizio usa già la stessa porta host, cambia la porta host dell'app con un valore non utilizzato mantenendo la porta del container come previsto dall'app.

Un errore nell'installazione di un'app CasaOS diventa molto più facile da risolvere se si considera il messaggio dell'interfaccia utente come un sintomo, non la causa principale. Leggi prima i log, poi verifica DNS, ora, architettura, porte e compatibilità Docker prima di reinstallare l'app o modificare le impostazioni di sistema.