Napraw błędy importowania Docker Compose w ZimaOS dla niestandardowych aplikacji

Jeśli ZimaOS odrzuca plik Docker Compose podczas Instalowania niestandardowej aplikacji → Importowania, nie zakładaj, że instalacja ZimaOS jest uszkodzona. W opisanym we wrześniu 2025 r. przypadku ponowna instalacja ZimaOS i ponowienie próby w trybie incognito nie przyniosły żadnego efektu. Rzeczywistym problemem był zapisany plik YAML Compose: formatowanie zostało uszkodzone podczas kopiowania do notatek, a wyeksportowana definicja zawierała więcej złożoności, niż aplikacja potrzebowała.

Użytkownik naprawił YAML, uprościł usługę Syncthing i potwierdził, że problem z importem został rozwiązany. Wątek podkreśla również ważny przypadek użycia ZimaOS: opcje takie jak tmpfs może nie mieć dedykowanego pola w edytorze wizualnym, dlatego import Compose pozostaje niezbędny w przypadku zaawansowanych ustawień kontenera.

Jak wyglądała awaria importu

Pierwotny użytkownik korzystał z ZimaOS 1.4.3 na urządzeniu Beelink Mini i odkrył, że wcześniej wyeksportowanej aplikacji niestandardowej nie można już było zaimportować po czystej reinstalacji.

Sprawdź poprawność YAML przed diagnozowaniem problemów z ZimaOS

YAML rozróżnia poziomy wcięć. Pojedynczy poziom przesunięty przez aplikację do robienia notatek może zmienić prawidłowy plik Compose w strukturę całkowicie odmienną.

Autor źródłowego tekstu ostatecznie zauważył, że zapisany eksport był nieprawidłowo sformatowany. Proces robienia notatek zmienił strukturę po skopiowaniu pliku Compose ze starej instalacji ZimaOS.

Przed wprowadzeniem zmian na hoście ZimaOS:

1. wklej plik Compose do walidatora YAML/Compose;
2. używaj spacji, a nie tabulatorów;
3. sprawdź wcięcia każdego elementu listy i właściwości podrzędnej;
4. potwierdź, że każde montowanie bind ma miejsce docelowe po stronie kontenera;
5. usuń zduplikowane klucze;
6. porównaj wynik z aktualną specyfikacją Docker Compose.

Kompletne montowanie bind wymaga zarówno źródła, jak i miejsca docelowego

Prawidłowe montowanie bind w długiej składni wygląda następująco:

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

Obecny Docker Compose obsługuje również opcjonalne ustawienia bind, takie jak:

bind:
  create_host_path: true

Najważniejsze jest, aby struktura YAML była prawidłowa oraz aby źródło i miejsce docelowe są zagnieżdżone pod tym samym wpisem montowania.

Usługi Docker Compose odwołują się do

Długa składnia portów jest prawidłowa, ale zachowaj prostotę

Stary eksport zawierał rozbudowane wpisy portów, takie jak:

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

Aktualny Docker Compose definiuje tryb w długiej składni portów, głównie na potrzeby publikowania w trybie Swarm. Oznacza to, że sam klucz nie jest uniwersalnie nieprawidłowy w Compose.

Jednak importer ZimaOS z 2025 roku oraz uszkodzony wyeksportowany plik YAML nie obsługiwały poprawnie zapisanej struktury. W przypadku zwykłej usługi ZimaOS działającej na jednym hoście prostsza składnia często ułatwia walidację:

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

Używaj bardziej zaawansowanej długiej składni tylko wtedy, gdy rzeczywiście potrzebujesz jej opcji.

Prawidłowe używanie sieci hosta

Jeśli aplikacja wymaga sieci hosta Docker, Compose udostępnia:

network_mode: host

Nie łącz network_mode z sieci list dla tej samej usługi; aktualny Docker Compose odrzuca takie połączenie.

Różni się to od zdefiniowania zwykłej sieci utworzonej przez użytkownika o nazwie host.

tmpfs to prawidłowa funkcja Docker Compose

Aplikacja autora źródła wymagała:

tmpfs:
  - /run

Aktualny Docker Compose oficjalnie obsługuje tmpfs wolumeny. Może również przyjmować opcje:

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

W źródłowej wersji ZimaOS formularz wizualny aplikacji niestandardowej nie udostępniał pola dla tej opcji, dlatego użytkownik musiał skorzystać z importu Compose zamiast ręcznie wprowadzać każde ustawienie.

Aktualny ZimaOS nadal obsługuje import Docker Compose

Aktualna dokumentacja ZimaOS opisuje ten proces:

1. otwórz pulpit nawigacyjny;
2. wybierz Zainstaluj aplikację niestandardową;
3. kliknij Importuj;
4. otwórz kartę Docker Compose;
5. wklej YAML;
6. prześlij i sprawdź wygenerowane ustawienia przed instalacją.

Dokumentacja aplikacji niestandardowych ZimaOS

Jak wyglądały uszkodzona i poprawiona wersja Compose

Prostsza struktura Syncthing

Prosty układ dla jednego hosta może wyglądać koncepcyjnie tak:

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

Użyj wartości PUID/PGID, ścieżek, ustawień sieci i tagu obrazu odpowiednich dla własnego wdrożenia. Wątek źródłowy używał identyfikatorów root podczas rozwiązywania problemu, ale nie oznacza to, że każdy kontener Syncthing powinien działać jako root.

Wyeksportowany plik Compose z ZimaOS nie jest nietykalnym formatem kopii zapasowej

Autor źródłowego wątku powiedział, że problematyczny plik pochodził z eksportu kontenerów przed reinstalacją ZimaOS. To przydatna kopia zapasowa, ale wyeksportowane definicje aplikacji mogą zawierać metadane wygenerowane przez ZimaOS lub składnię bardziej rozwlekłą niż ręcznie napisany stos Compose.

Zanim zaczniesz polegać na wyeksportowanych plikach w ramach odzyskiwania po awarii:

• przechowuj je w formacie zwykłego tekstu lub formacie obsługującym kod;
• umieść je w systemie kontroli wersji, jeśli jest to właściwe;
• weryfikuj je, dopóki oryginalny system nadal działa;
• twórz osobne kopie zapasowe trwałych folderów AppData.

Lista kontrolna importowania Compose w ZimaOS

1. Zweryfikuj YAML przed importem.
2. Zastąp tabulatory spacjami.
3. Sprawdź wcięcia list pod sekcjami ports, volumes, environment i networks.
4. Dla każdego montowania wiązanego podaj źródło i miejsce docelowe.
5. Użyj network_mode: host jeśli zamierzasz używać sieci hosta.
6. Nie łącz network_mode oraz usługę sieci.
7. Zachowaj tmpfs w Compose, jeśli wizualny interfejs użytkownika ich nie udostępnia.
8. Usuń wygenerowane lub zaawansowane opcje, których aplikacja nie potrzebuje.
9. Przechowuj osobną kopię zapasową danych aplikacji; sam plik Compose nie zawiera danych.

Najczęstsze pytania dotyczące importowania Docker Compose w ZimaOS

Czy pierwotny problem był spowodowany pamięcią podręczną przeglądarki?

Nie. Autor odtworzył problem po świeżej reinstalacji ZimaOS oraz w przeglądarce w trybie incognito, a następnie potwierdził, że rzeczywistą przyczyną były problemy z formatowaniem w zapisanym pliku Compose.

Czy ZimaOS obsługuje tmpfs w wizualnym formularzu aplikacji niestandardowej?

Wątek z 2025 roku wskazywał, że interfejs graficzny nie udostępniał tej opcji. Sam Docker Compose obsługuje tmpfs, dlatego import jest właściwą zaawansowaną ścieżką.

Czy `mode: ingress` i `protocol: tcp` są nieprawidłowe w Docker Compose?

Nie zawsze. Obecny Compose obsługuje składnię portów w długiej formie, w tym tryb. Praktyczna lekcja z opisanego przypadku jest taka, aby zweryfikować cały plik YAML i usunąć zbędną złożoność, gdy importer ZimaOS nie potrafi niezawodnie użyć wyeksportowanej postaci.