ZimaOS Docker Compose-importfel: YAML-korrigeringar

Om ZimaOS avvisar en Docker Compose-fil under Installera en anpassad app → Importera, anta inte att ZimaOS-installationen är skadad. I ett communityfall från september 2025 gjorde ominstallation av ZimaOS och ett nytt försök i ett inkognitofönster ingen skillnad. Det verkliga problemet var den sparade Compose-YAML-filen: formateringen hade skadats när den kopierades till anteckningar, och den exporterade definitionen innehöll mer komplexitet än applikationen behövde.

Användaren reparerade YAML-filen, förenklade Syncthing-tjänsten och bekräftade att importproblemet var löst. Tråden belyser också ett viktigt användningsområde för ZimaOS: alternativ som tmpfs kan sakna ett särskilt fält i den visuella redigeraren, så Compose-import förblir nödvändig för avancerade containerinställningar.

Så såg importfelet ut

Den ursprungliga användaren körde ZimaOS 1.4.3 på en Beelink Mini och upptäckte att en tidigare exporterad anpassad app inte längre gick att importera efter en ren ominstallation.

ZimaOS webbläsarkonsol som visar ett fel efter att en anpassad Docker Compose-app skickats in — Det första symptomet uppstod när den sparade Docker Compose-texten skickades till ZimaOS importverktyg för anpassade appar.

Utdata från webbläsarens utvecklarkonsol som fångades under felsökningen av ZimaOS importverktyg för anpassade appar — Att installera om operativsystemet och byta webbläsarsessioner tog inte bort det underliggande Compose-problemet.

Validera YAML-filen innan du felsöker ZimaOS

YAML är indrag6ningskänsligt. En enda nivå som flyttas av en anteckningsapp kan omvandla giltig Compose till en helt annan struktur.

Källförfattaren upptäckte så småningom att den sparade exporten var felaktigt formaterad. Arbetsflödet för anteckningar hade ändrat strukturen efter att Compose-filen kopierats från den gamla ZimaOS-installationen.

Innan ZimaOS-värden ändras:

klistra in Compose-filen i en YAML-/Compose-validator;
använd mellanslag, inte tabbar;
kontrollera indragningen för varje listobjekt och underordnad egenskap;
bekräfta att varje bind-montering har ett mål på containersidan;
ta bort dubblettnycklar;
jämför resultatet med den aktuella Docker Compose-specifikationen.

En komplett bind-montering behöver både källa och mål

En giltig bind-montering i långformat ser ut så här:

volumes:
  - type: bind
    source: /DATA/AppData/syncthing/data
    target: /var/syncthing

Aktuella Docker Compose stöder även valfria bind-inställningar som:

bind:
  create_host_path: true

Det huvudsakliga kravet är att YAML-strukturen är giltig och att källa och mål är nästlade under samma monteringspost.

Docker Compose-tjänster refererar till

Lång portsyntax är giltig, men håll den enkel

Den gamla exporten innehöll utförliga portposter som:

ports:
  - target: 8384
    published: "8384"
    protocol: tcp
    mode: ingress

Aktuell Docker Compose definierar faktiskt mode i lång portsyntax, främst för Swarm-publiceringsbeteende. Det innebär att själva nyckeln inte är ogiltig i all Compose.

ZimaOS importverktyg från 2025 och den skadade exporterade YAML-filen hanterade dock inte den sparade strukturen korrekt. För en vanlig ZimaOS-tjänst på en enda värd är enklare syntax ofta lättare att validera:

ports:
  - "8384:8384"
  - "22000:22000/tcp"
  - "22000:22000/udp"
  - "21027:21027/udp"

Använd den mer avancerade långa formen endast när du faktiskt behöver dess alternativ.

Använd värdnätverk korrekt

Om applikationen behöver nätverk via Docker-värden tillhandahåller Compose:

network_mode: host

Kombinera inte network_mode med en networks lista för samma tjänst; aktuell Docker Compose avvisar den kombinationen.

Detta skiljer sig från att definiera ett normalt användarskapat nätverk med namnet värd.

tmpfs är en giltig Docker Compose-funktion

Källförfattarens applikation krävde:

tmpfs:
  - /run

Aktuella Docker Compose har uttryckligt stöd för tmpfs monteringar. Det kan också acceptera alternativ:

tmpfs:
  - /run
  - /data:mode=755,uid=1000,gid=1000

I den aktuella ZimaOS-versionen från källan innehöll formuläret för visuella anpassade appar inget fält för detta alternativ, vilket är anledningen till att användaren behövde importera Compose i stället för att ange varje inställning manuellt.

Aktuella ZimaOS stöder fortfarande import av Docker Compose

Den aktuella ZimaOS-dokumentationen beskriver detta arbetsflöde:

öppna kontrollpanelen;
välj Installera en anpassad app;
klicka på Importera;
öppna fliken Docker Compose;
klistra in YAML-filen;
skicka in och granska de genererade inställningarna före installationen.

Dokumentation för anpassade appar i ZimaOS

Så här såg den trasiga och korrigerade Compose-filen ut

Import av anpassad app i ZimaOS som visar felaktig Docker Compose-formatering från den sparade exporten — Källförfattaren upptäckte att den sparade Compose-texten hade förlorat sin avsedda YAML-struktur.

ZimaOS-fel som visades efter en delvis reparerad import av Syncthings Docker Compose — Att parsningen lyckas är bara det första steget; den resulterande tjänstedefinitionen måste också vara giltig för Docker och ZimaOS.

Compose Toolbox validerar och förenklar en Docker Compose-definition för ZimaOS — Communityn rekommenderade att validera och förenkla Compose-filen innan den importerades igen.

Rensad Syncthing-Docker-Compose-definition efter att onödig konfiguration tagits bort — En mindre Compose-definition baserad på standarder gjorde konfigurationen enklare att förstå och återställa.

En enklare Syncthing-struktur

En ren layout för en enda värd kan konceptuellt se ut så här:

services:
  syncthing:
    image: syncthing/syncthing:2.0
    container_name: syncthing
    restart: unless-stopped
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - /DATA/AppData/syncthing/data:/var/syncthing
      - /media/SLOT4/Syncthing:/media/data/syncthing
    tmpfs:
      - /run

Använd PUID/PGID, sökvägar, nätverk och imagetagg som passar din egen distribution. Källtråden använde root-ID:n vid felsökningen, men det är ingen anledning att köra alla Syncthing-containrar som root.

En exporterad ZimaOS Compose-fil är inte ett orörbart säkerhetskopieringsformat

Källförfattaren uppgav att den problematiska filen kom från export av containrar före ominstallationen av ZimaOS. Det är en användbar säkerhetskopia, men exporterade programdefinitioner kan innehålla ZimaOS-genererade metadata eller syntax som är mer omfattande än en handskriven Compose-stack.

Innan du förlitar dig på exporterade filer för katastrofåterställning:

lagra dem i ett vanlig textformat eller ett kodmedvetet format;
lägg dem i versionshantering om det är lämpligt;
validera dem medan det ursprungliga systemet fortfarande fungerar;
säkerhetskopiera beständiga AppData-mappar separat.

Checklista för import av Compose i ZimaOS

Validera YAML-filen före import.
Ersätt tabbar med mellanslag.
Kontrollera indenteringen under ports, volumes, environment och networks.
Se till att varje bind-montering innehåller en källa och ett mål.
Använd network_mode: host om värdnätverk är avsett.
Kombinera inte network_mode och service networks.
Behåll tmpfs i Compose om det visuella gränssnittet inte visar det.
Ta bort genererade/avancerade alternativ som programmet inte behöver.
Ha en separat säkerhetskopia av programdata; en Compose-fil innehåller inte själva datan.

Vanliga frågor om import av Docker Compose i ZimaOS

Orsakades det ursprungliga problemet av webbläsarens cache?

Nej. Författaren återskapade problemet efter en ren ominstallation av ZimaOS och i en inkognitowebbläsare, och bekräftade sedan att formateringsproblemen i den sparade Compose-filen var det verkliga problemet.

Har ZimaOS stöd för tmpfs i formuläret för visuella anpassade appar?

Tråden från 2025 uppgav att det grafiska gränssnittet inte visade det alternativet. Docker Compose stöder tmpfs, så import är den lämpliga avancerade vägen.

Är mode: ingress och protocol: tcp ogiltiga i Docker Compose?

Inte universellt. Aktuell Compose stöder lång portsydax, inklusive modeDen praktiska lärdomen från källfallet är att validera hela YAML-filen och ta bort onödig komplexitet när ZimaOS-importören inte kan använda det exporterade formatet på ett tillförlitligt sätt.