CasaOS-appinstallationen misslyckades: loggar, DNS och portar

Eva Wong är teknisk skribent och händig hemmabyggare på ZimaSpace. Som tekniknörd sedan barnsben med ett brinnande intresse för hemlabb och programvara med öppen källkodspecialiserar hon sig på att göra komplexa tekniska koncept begripliga genom praktiska, praktiska guider. Eva tycker att självhosting ska vara roligt, inte avskräckande. Genom sina handledningar hjälper hon communityn att göra hårdvaruinstallationer mindre mystiska, från att bygga sin första NAS till att bemästra Docker-containrar.

Ett misslyckat appinstallationsförsök i CasaOS visar sig oftast som ett enkelt fel i gränssnittet: appbutiken läses inte in, installationsknappen fungerar inte eller så visas containern men öppnas aldrig. Den verkliga orsaken ligger oftast djupare än CasaOS-gränssnittet. CasaOS är utformat för installation av appar med ett klick och driftsättning av Docker-appar, så en misslyckad installation kan bero på CasaOS-tjänstelagret, hämtning av Docker-avbildningar, DNS-namnuppslagning, systemtid, CPU-arkitektur eller konflikter med värdportar.

Det säkraste sättet att felsöka är att inte börja med att installera om CasaOS. Börja med att läsa det faktiska felet och testa sedan ett lager i taget: loggar, nätverk och DNS, tidssynkronisering, CPU-arkitektur, portar och Docker-kompatibilitet.

Kort sagt: Felmeddelandet från CasaOS är bara det första symptomet

Ett allmänt meddelande om att installationen misslyckades talar om att CasaOS inte kunde slutföra driftsättningen, men inte vilket lager som orsakade felet. Appkatalogen kanske inte har lästs in, Docker kanske inte har hämtat avbildningen, avbildningen kanske inte passar din CPU-arkitektur, en värdport kanske redan är upptagen eller så kanske containern har startat och sedan kraschat.

Installation av CasaOS-appar är beroende av både CasaOS-tjänstelagret och den underliggande Docker-miljön. Hämtning av Docker-avbildningar kan också påverkas av registeråtkomst, proxyinställningar, anslutningar med låg bandbredd och tidsgränser för hämtning av lager.

Följ den här ordningen:

# 1. Läs CasaOS-tjänsteloggarna
journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

# 2. Kontrollera Docker-containrar
docker ps -a

# 3. Läs loggarna för den misslyckade containern
docker logs --tail 100 <container_name_or_id>

# 4. Testa DNS och registeråtkomst
getent hosts github.com
getent hosts registry-1.docker.io

# 5. Kontrollera systemtiden
timedatectl

# 6. Kontrollera CPU-arkitekturen
uname -m

# 7. Kontrollera lyssnande portar
sudo ss -tulpn | grep LISTEN

Börja med loggarna innan du ändrar inställningar

Loggar är det snabbaste sättet att skilja ett CasaOS-problem från ett Docker-, nätverks-, avbildnings- eller appproblem. Linux-kommandot journalctl visar poster från systemd-journalen, och alternativet -u filtrerar loggar för en specifik tjänsteenhet.

För CasaOS kan du börja med loggar på tjänstenivå:

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

Kontrollera sedan Docker. Dockers kommando docker logs hämtar loggar från en container, och alternativet --follow kan strömma nya utdata medan containern körs.

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

Det här ska du leta efter:

Ledtråd i loggen Trolig orsak
no such host / DNS-uppslagsfel DNS eller nätverksnamnuppslagning
anslutningen tog för lång tid Nätverk, proxy, brandvägg, registeråtkomst eller låg bandbredd
certificate / TLS / x509-fel Systemtid, CA-certifikat eller HTTPS-avlyssning
fel på körbart format Fel CPU-arkitektur för avbildningen
port is already allocated / bind: address already in use Konflikt med värdport
lägsta API-version som stöds API-mismatch mellan Docker-klient och daemon
Containern avslutas omedelbart Appkonfiguration, volymbehörigheter, saknade miljövariabler eller problem med avbildningen

Regeln är enkel: försök inte åtgärda fem saker samtidigt. Kopiera den första tydliga felraden och testa sedan det lager som den pekar på.

Kontrollera DNS och nätverksåtkomst

Om App Store inte läses in eller installationen misslyckas medan en avbild laddas ned kontrollerar du DNS och utgående nätverksåtkomst innan du ändrar CasaOS-inställningarna. Docker hämtar avbilder från register som Docker Hub. Om din CasaOS-värd inte kan slå upp registernamn kan hämtningen av avbilder misslyckas innan containern ens har skapats.

Använd tester för namnuppslagning i stället för att bara använda ping:

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

Kommandot getent frågar databaser som konfigurerats via Name Service Switch, däribland värddatabasen som används för namnuppslagning. Om dessa kommandon inte returnerar något kanske CasaOS inte kan nå GitHub, Docker Hub eller en anpassad appkatalog, även om den lokala kontrollpanelen fortfarande öppnas.

Kontrollera sedan resolverkonfigurationen:

cat /etc/resolv.conf

I Linux är /etc/resolv.conf resolverns konfigurationsfil för DNS, och posterna nameserver anger vilka DNS-servrar resolvern ska fråga. Om DNS inte fungerar kan du tillfälligt byta till stabila offentliga resolverservrar för att bekräfta om det är problemet:

sudo nano /etc/resolv.conf

Exempel på tillfälligt test:

nameserver 1.1.1.1
nameserver 8.8.8.8

Nöj dig inte med ”internet fungerar på min bärbara dator”. CasaOS körs på servern, så det är serverns DNS-väg som spelar roll.

Kontrollera systemtiden innan du skyller på appbutiken

Felaktig systemtid kan orsaka problem med HTTPS och certifikatvalidering som ser ut som fel i appbutiken eller registret. Innan du ändrar Docker- eller CasaOS-konfigurationen kontrollerar du att serverklockan går rätt och att tidssynkronisering är aktiv.

timedatectl

Leta efter rader som dessa i utdata:

Systemklockan synkroniserad: ja
NTP-tjänst: aktiv

Om synkroniseringen är inaktiverad aktiverar du den:

sudo timedatectl set-ntp true

När du har aktiverat det väntar du en stund och kör timedatectl igen innan du försöker installera CasaOS-appen på nytt.

Kontrollera att CPU-arkitekturen matchar appavbilden

CasaOS kan köras på flera hårdvaruplattformar, bland annat x86-64- och ARM-enheter. Det betyder inte att alla Docker-appar i alla kataloger stöder alla arkitekturer. En Raspberry Pi, Orange Pi, ARM-minidator eller återanvänd Android-box kanske inte kan köra en avbild som endast byggts för linux/amd64.

Kontrollera värdens arkitektur:

uname -m
Resultat från uname -m Vanlig betydelse
x86_64 AMD64 / x86-64
aarch64 ARM64
armv7l 32-bitars ARM
i386 / i686 32-bitars x86

Säkerställ att containerkoden är kompatibel med värdens arkitektur, eftersom containrar delar värdkärna. Utan emulering kan du inte köra en linux/amd64-container på en arm64-värd. Multiplattformsavbilder löser detta genom att tillhandahålla varianter som linux/amd64 och linux/arm64 under en och samma avbild.

Om loggarna visar exec format error kontrollerar du avbildningssidan eller manifestet i registret för att se om ARM stöds. Om avbildningen inte stöder din plattform går det inte att lösa genom att ändra inställningarna i CasaOS. Du behöver en avbildning med stöd för flera arkitekturer, en annan tagg eller en annan app.

Kontrollera om det finns portkonflikter innan du installerar om

Vissa installationer av CasaOS-appar slutförs, men appen går ändå inte att öppna. I många fall har containern startat, men värdporten används redan eller har mappats fel.

Kontrollera aktiva lyssningsportar:

sudo ss -tulpn | grep LISTEN

Jämför sedan resultatet med appens portinställningar. Docker Compose definierar ports som mappningar mellan värddatorn och containrar, och dessa mappningar gör det möjligt att komma åt tjänster som körs inuti containrar utifrån.

En typisk portmappning ser ut så här:

ports:
  - "8080:80"
Del Betydelse
8080 Värdport: porten som du öppnar i webbläsaren
80 Containerport: porten som appen lyssnar på inuti containern

Om en annan tjänst redan använder värdporten 80 ska du inte ändra containerporten först. Ändra värdporten till ett ledigt värde:

ports:
  - "8080:80"

Detta är särskilt viktigt för appar som omvända proxyservrar, annonsblockerare, instrumentpaneler och webbservrar, eftersom de ofta använder portarna 80, 443, 8080 eller 3000 som standard.

En praktisk checklista för felsökning av CasaOS-appar

Använd den här checklistan innan du installerar om CasaOS eller tar bort containrar.

Kontroll Kommando Bra tecken Dåligt tecken
CasaOS tjänsteloggar journalctl -xeu casaos-app-management --no-pager Tydligt installationsförlopp eller specifikt fel Upprepade tjänstefel eller Docker API-fel
CasaOS live-loggar journalctl -u casaos -f Åtgärder i gränssnittet visas i loggarna Appåtgärden misslyckas tyst eller upprepas i en loop
Lista över Docker-containrar docker ps -a Containern har skapats och statusen visas Containern saknas eller startas om upprepade gånger
Containerloggar docker logs --tail 100 <container> Appen startar normalt Avsluts-, behörighets-, konfigurations- eller arkitekturfel
DNS-uppslagning getent hosts registry-1.docker.io IP-adresser returneras Inget resultat eller uppslagsfel
Hämtning av avbildning docker pull <image>:<tag> Avbildningar hämtas Tidsgränsen överskriden, TLS-, autentiserings- eller manifestfel
Systemtid timedatectl Klockan är synkroniserad, NTP är aktivt Felaktig tid eller inaktiv NTP
Arkitektur uname -m Matchar avbildningens plattform ARM-värd med enbart amd64-avbildning
Portar sudo ss -tulpn | grep LISTEN Värdporten är ledig Porten används redan

Vanliga felmönster och vad de oftast betyder

App Store laddas inte

Om App Store inte laddas börjar du med DNS och nätverksåtkomst. CasaOS är beroende av externa katalog- och bildkällor vid normal användning av appar, så servern måste kunna slå upp och nå dessa källor.

Kontrollera:

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

Om DNS misslyckas åtgärdar du serverns resolver. Om DNS fungerar men Docker-hämtningar misslyckas testar du åtkomsten till registret samt proxy- och brandväggsinställningarna.

Appinstallationen misslyckas vid hämtning av avbildning

Om installationen misslyckas när avbildningen hämtas kopierar du det exakta Docker-felet. Testa manuellt:

docker pull <image>:<tag>

Om den manuella hämtningen misslyckas med DNS- eller tidsgränsfel ligger problemet inte i CasaOS-gränssnittet. Om den misslyckas med ett arkitekturfel eller för att inget matchande manifest hittas kontrollerar du avbildningens plattform.

Appen installeras men går inte att öppna

Om appen verkar vara installerad men webbläsaren inte kan öppna den kontrollerar du portarna först. En felaktig eller upptagen värdport kan få en fungerande container att verka trasig.

Kontrollera:

docker ps
sudo ss -tulpn | grep LISTEN

Kontrollera sedan om appen är bunden till värdporten du försöker nå.

Appen startar och stannar omedelbart

Om containern finns men avslutas läser du containerloggarna:

docker logs --tail 100 <container>

Leta efter saknade miljövariabler, ogiltiga volymsökvägar, databasfel, behörighetsfel eller exec format error.

Loggarna visar fel med Docker API-versionen

Om loggarna nämner inkompatibilitet med Docker API-versionen ska du inte gissa. Kör först:

docker version

Problem med Docker API-versionen bör hanteras som ett avancerat felsökningsfall. Överväg bara att åsidosätta API-versionen om loggarna tydligt visar en versionskonflikt. Lägg inte till en systemd-åsidosättning bara för att en app har misslyckats en gång.

Docker- och behörighetsproblem i CasaOS-appar

Vissa appar misslyckas eftersom containern har skapats, men inte har förväntad åtkomst till en volym, enhet eller nätverkssökväg. Det här är vanligt när användare installerar anpassade mallar, flyttar appdata, monterar externa enheter eller ändrar värdmappar manuellt.

Kontrollera appens mappade sökvägar och loggar:

docker inspect <container_name_or_id>
docker logs --tail 100 <container_name_or_id>

Leta efter:

  • värdmappen saknas;
  • åtkomst nekad;
  • skrivskyddat filsystem;
  • databasen kan inte initieras;
  • konfigurationsfilen hittades inte;
  • enhetssökvägen saknas;
  • containerns användare kan inte skriva till den monterade volymen.

Om felet pekar på ett volym- eller behörighetsproblem åtgärdar du först sökvägen eller behörigheten. Om du installerar om appen utan att ändra den felaktiga sökvägen uppstår vanligtvis samma fel igen.

Misstag som försvårar felsökningen av CasaOS

Misstag 1: Att installera om appen innan du läser loggarna

En ominstallation kan dölja det ursprungliga felet och skapa dubbletter av containrar, föräldralösa volymer eller upprepade hämtningar av avbildningar. Läs först loggarna för CasaOS-tjänsten och Docker-containern.

Misstag 2: Att åtgärda DNS utan att testa namnuppslagningen

Att ändra DNS på måfå kan försvåra felsökningen. Testa namnuppslagningen först med getent hosts. Om servern inte kan slå upp registry- eller katalogdomäner justerar du resolverkonfigurationen.

Misstag 3: Att ignorera kompatibiliteten mellan ARM- och AMD64-avbildningar

CasaOS kan köras på ARM-enheter, men alla appavbildningar har inte stöd för ARM. Om din värd använder aarch64 eller armv7l och avbildningen bara finns för amd64 kan installationen misslyckas eller så kan containern avslutas med exec format error.

Misstag 4: Ändra containerportar i stället för värdportar

Om appens dokumentation säger att containern lyssnar på port 80 ska du inte ändra den interna containerporten om du inte vet att appen stöder det. Ändra i stället värdporten. Då behåller appens interna tjänst sitt förväntade beteende samtidigt som du undviker en konflikt på värdnivå.

Så försöker du installera igen på ett säkert sätt

När du har hittat den troliga orsaken försöker du igen på ett kontrollerat sätt:

  1. Spara det exakta felmeddelandet.
  2. Åtgärda bara ett steg i taget.
  3. Starta om den berörda tjänsten endast om det behövs.
  4. Försök installera appen igen.
  5. Följ loggarna medan du försöker igen.
  6. Kontrollera om containern finns.
  7. Kontrollera om appens port lyssnar.
  8. Öppna appen med rätt värd-IP-adress och värdport.

Så här kan ett säkert nytt försök se ut:

journalctl -u casaos -f

I en annan terminal:

docker ps -a
docker logs -f <container_name_or_id>

Försök sedan igen med appen i CasaOS. Då får du UI-åtgärden, CasaOS-tjänstens beteende och Docker-containerutdata samlade i en och samma körning.

Vanliga frågor

Varför säger CasaOS att appinstallationen misslyckades?

Det beror på att ett av stegen i installationskedjan misslyckades. Orsaken kan vara CasaOS-tjänsteloggar, hämtning av Docker-avbildningen, DNS, systemtid, CPU-arkitektur, portkonflikter, behörigheter eller Docker API-kompatibilitet. Börja med loggarna och testa sedan det steg som det första faktiska felet pekar ut.

Hur kontrollerar jag installationsloggar för CasaOS-appar?

Börja med:

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

Kontrollera sedan Docker:

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

Varför kan CasaOS inte läsa in appbutiken?

De vanligaste sakerna att kontrollera är DNS, utgående nätverksåtkomst, systemtid och CasaOS-tjänsteloggar. Testa DNS direkt från servern med getent hosts github.com och getent hosts registry-1.docker.io, kontrollera sedan timedatectl och journalctl -u casaos -f.

Vad betyder exec format error i CasaOS?

Det betyder oftast att Docker-avbildningen inte passar din CPU-arkitektur. En ARM-värd kanske till exempel försöker köra en avbildning som bara stöder amd64. Kontrollera med uname -m och bekräfta att avbildningen stöder din plattform.

Hur vet jag om en CasaOS-app misslyckades på grund av en portkonflikt?

Kontrollera vilka portar som redan lyssnar:

sudo ss -tulpn | grep LISTEN

Jämför sedan med appens värdport. Om en annan tjänst redan använder samma värdport ändrar du appens värdport till ett ledigt värde, samtidigt som du behåller containerporten som appen förväntar sig.

Ett installationsfel för en CasaOS-app blir mycket lättare att lösa om du ser UI-meddelandet som ett symtom, inte som grundorsaken. Läs loggarna först och kontrollera sedan DNS, tid, arkitektur, portar och Docker-kompatibilitet innan du installerar om appen eller ändrar systemomfattande inställningar.

Support och tips

Mer att läsa

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.