ZimaOS Docker Compose 가져오기 오류: YAML 수정 방법

ZimaOS가 사용자 지정 앱 설치 → 가져오기 중 Docker Compose 파일을 거부하더라도 ZimaOS 설치가 손상되었다고 단정하지 마세요. 2025년 9월 커뮤니티 사례에서는 ZimaOS를 다시 설치하고 시크릿 브라우저에서 재시도해도 아무런 차이가 없었습니다. 실제 문제는 저장된 Compose YAML이었습니다. 메모에 복사하는 동안 형식이 손상되었고, 내보낸 정의에는 애플리케이션에 필요했던 것보다 더 많은 복잡성이 포함되어 있었습니다.

사용자는 YAML을 수정하고 Syncthing 서비스를 단순화한 다음 가져오기 문제가 해결되었음을 확인했습니다. 이 스레드는 중요한 ZimaOS 사용 사례도 보여 줍니다. 다음과 같은 옵션은 tmpfs 비주얼 편집기에 전용 필드가 없을 수 있으므로 고급 컨테이너 설정에는 Compose 가져오기가 여전히 필요합니다.

가져오기 실패 현상

원래 사용자는 Beelink Mini에서 ZimaOS 1.4.3을 실행하고 있었으며, 이전에 내보낸 사용자 지정 애플리케이션을 새로 설치한 후 더 이상 가져올 수 없다는 것을 발견했습니다.

Docker Compose 사용자 지정 앱을 제출한 후 오류를 표시하는 ZimaOS 브라우저 콘솔 — 저장된 Docker Compose 텍스트를 ZimaOS 사용자 지정 앱 가져오기 도구에 제출했을 때 첫 번째 증상이 나타났습니다.

ZimaOS 사용자 지정 앱 가져오기를 문제 해결하는 동안 캡처한 브라우저 개발자 콘솔 출력 — OS를 다시 설치하고 브라우저 세션을 변경해도 근본적인 Compose 문제는 해결되지 않았습니다.

ZimaOS 문제를 해결하기 전에 YAML 검증하기

YAML은 들여쓰기에 민감합니다. 메모 작성 앱에서 한 단계만 잘못 이동해도 유효한 Compose가 완전히 다른 구조로 바뀔 수 있습니다.

소스 작성자는 결국 저장한 내보내기 파일의 형식이 심각하게 잘못되었다는 사실을 알아차렸습니다. Compose 파일을 이전 ZimaOS 설치에서 복사한 후 메모 작성 작업으로 인해 구조가 변경되었습니다.

ZimaOS 호스트를 변경하기 전에:

Compose 파일을 YAML/Compose 검증기에 붙여 넣습니다.
탭이 아닌 공백을 사용합니다.
모든 목록 항목과 하위 속성의 들여쓰기를 확인합니다.
모든 bind 마운트에 컨테이너 측 대상이 있는지 확인합니다.
중복 키를 제거합니다.
결과를 현재 Docker Compose 사양과 비교합니다.

완전한 bind 마운트에는 소스와 대상이 모두 필요합니다

유효한 장문 형식의 bind 마운트는 다음과 같습니다.

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

현재 Docker Compose는 다음과 같은 선택적 bind 설정도 지원합니다.

bind:
  create_host_path: true

가장 중요한 요구 사항은 YAML 구조가 유효하고 소스 및 대상 동일한 마운트 항목 아래에 중첩됩니다.

Docker Compose services reference

Docker Compose 서비스는 다음을 참조합니다.

긴 포트 구문은 유효하지만 단순하게 유지하세요.

그러나 ZimaOS의 2025년 가져오기 기능과 손상된 내보내기 YAML은 저장된 구조를 제대로 처리하지 못했습니다. 일반적인 단일 호스트 ZimaOS 서비스에서는 더 간단한 구문이 검증하기 쉬운 경우가 많습니다.
  기존 내보내기에는 다음과 같이 장황한 포트 항목이 포함되어 있었습니다.
    - target: 8384
    published: "8384"
    protocol: tcp

mode: ingress 모드 현재 Docker Compose는 다음을 정의합니다.

주로 Swarm 게시 동작을 위해 긴 포트 구문에서 사용됩니다. 따라서 키 자체가 모든 Compose에서 보편적으로 유효하지 않은 것은 아닙니다.

그러나 ZimaOS의 2025년 가져오기 기능과 손상된 내보내기 YAML은 저장된 구조를 제대로 처리하지 못했습니다. 일반적인 단일 호스트 ZimaOS 서비스에서는 더 간단한 구문이 검증하기 쉬운 경우가 많습니다.
  - "8384:8384"
  포트:
  - "22000:22000/tcp"
  - "22000:22000/udp"

- "21027:21027/udp"

실제로 옵션이 필요할 때만 더 고급 긴 형식을 사용합니다.

호스트 네트워킹을 올바르게 사용하기

network_mode: host

결합하지 마세요 network_mode 애플리케이션에 Docker 호스트 네트워킹이 필요한 경우 Compose에서는 다음을 제공합니다. 네트워크 와 함께

이는 동일한 서비스에 대해 사용자가 생성한 일반 네트워크를 다음 이름으로 정의하는 것과는 다릅니다. 현재 Docker Compose에서는 이 조합을 거부합니다. 호스트.

tmpfs는 유효한 Docker Compose 기능입니다.

원문 작성자의 애플리케이션에는 다음이 필요했습니다.

tmpfs:
  - /run

현재 Docker Compose는 이를 명시적으로 지원합니다. tmpfs 마운트입니다. 다음 옵션도 사용할 수 있습니다.

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

원문의 ZimaOS 버전에서는 시각적 사용자 지정 앱 양식에 이 옵션을 입력하는 필드가 없었기 때문에, 사용자는 모든 설정을 수동으로 입력하는 대신 Compose 가져오기를 사용해야 했습니다.

현재 ZimaOS에서도 Docker Compose 가져오기를 지원합니다.

현재 ZimaOS 문서에서는 다음 워크플로를 설명합니다.

대시보드를 엽니다.
사용자 지정 앱 설치를 선택합니다.
가져오기를 클릭합니다.
Docker Compose 탭을 엽니다.
YAML을 붙여넣습니다.
설치하기 전에 생성된 설정을 제출하고 검토합니다.

ZimaOS 사용자 지정 앱 문서

손상된 Compose와 수정된 Compose의 모습

저장된 내보내기 파일에서 잘못된 Docker Compose 형식을 보여 주는 ZimaOS 사용자 지정 앱 가져오기 화면 — 원문 작성자는 저장된 Compose 텍스트에서 원래 의도한 YAML 구조가 사라졌다는 사실을 발견했습니다.

부분적으로 복구된 Syncthing Docker Compose를 가져온 후 표시된 ZimaOS 오류 — 성공적으로 파싱하는 것은 첫 단계일 뿐이며, 생성된 서비스 정의가 Docker와 ZimaOS에서도 유효해야 합니다.

Compose Toolbox에서 ZimaOS Docker Compose 정의를 검증하고 단순화하는 과정 — 커뮤니티에서는 다시 가져오기 전에 Compose 파일의 유효성을 검사하고 단순화할 것을 권장했습니다.

불필요한 구성을 제거한 후 Syncthing Docker Compose 정의를 정리했습니다. — 구성을 더 쉽게 이해하고 복원할 수 있도록 더 작고 표준 기반의 Compose 정의를 사용했습니다.

더 간단한 Syncthing 구조

깔끔한 단일 호스트 구성은 개념적으로 다음과 같을 수 있습니다.

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

자신의 배포에 적합한 PUID/PGID, 경로, 네트워킹 및 이미지 태그를 사용하세요. 소스 스레드에서는 문제를 해결하는 동안 루트 ID를 사용했지만, 그렇다고 모든 Syncthing 컨테이너를 루트로 실행해야 하는 것은 아닙니다.

내보낸 ZimaOS Compose 파일은 절대 수정할 수 없는 백업 형식이 아닙니다

소스 작성자는 문제가 된 파일이 ZimaOS를 재설치하기 전에 컨테이너를 내보내는 과정에서 생성되었다고 말했습니다. 이는 유용한 백업이지만, 내보낸 애플리케이션 정의에는 ZimaOS가 생성한 메타데이터나 직접 작성한 Compose 스택보다 더 장황한 구문이 포함될 수 있습니다.

재해 복구를 위해 내보낸 파일에 의존하기 전에:

일반 텍스트 또는 코드 인식 형식으로 저장하세요.
적절한 경우 버전 관리에 추가하세요.
원래 시스템이 아직 작동할 때 유효성을 검사하세요.
영구 AppData 폴더는 별도로 백업하세요.

ZimaOS Compose 가져오기 체크리스트

가져오기 전에 YAML을 검증하세요.
탭을 공백으로 바꾸세요.
ports, volumes, environment, networks 아래의 목록 들여쓰기를 확인하세요.
모든 바인드 마운트에 소스와 대상이 포함되어 있는지 확인하세요.
사용하세요 network_mode: host 호스트 네트워킹을 사용하려는 경우.
결합하지 마세요 network_mode 서비스와 네트워크.
유지하세요 tmpfs 시각적 UI에 해당 옵션이 표시되지 않는 경우 Compose에서 사용하세요.
애플리케이션에 필요하지 않은 생성된 옵션이나 고급 옵션은 제거하세요.
애플리케이션 데이터는 별도로 백업하세요. Compose만으로는 데이터가 백업되지 않습니다.

ZimaOS Docker Compose 가져오기 FAQ

원래 문제는 브라우저 캐시 때문에 발생했나요?

아니요. 작성자는 ZimaOS를 새로 설치한 후와 시크릿 브라우저에서 이 문제를 재현했고, 저장된 Compose의 형식 문제가 실제 원인임을 확인했습니다.

ZimaOS는 시각적 커스텀 앱 양식에서 tmpfs를 지원하나요?

2025년 스레드에서는 GUI에 해당 옵션이 표시되지 않는다고 했습니다. 하지만 Docker Compose 자체는 다음을 지원합니다. tmpfs따라서 가져오기가 적절한 고급 방법입니다.

mode: ingress와 protocol: tcp는 잘못된 Docker Compose 구문인가요?

항상 그런 것은 아닙니다. 현재 Compose는 다음을 포함한 긴 포트 구문을 지원합니다. 모드소스 사례에서 얻을 수 있는 실질적인 교훈은 전체 YAML을 검증하고, ZimaOS 가져오기가 내보낸 형식을 안정적으로 사용할 수 없을 때 불필요한 복잡성을 제거하는 것입니다.