ZimaOS의 “사용자 지정 앱 설치” 양식은 일반적인 Docker Compose 개념을 필드로 변환하는 방식임을 이해하면 훨씬 사용하기 쉽습니다. 2026년 6월의 원본 스레드는 훌륭한 초보자용 예시입니다. 사용자는 이미 Jellyfin을 정상적으로 사용하고 있었고, 자막 처리를 위해 Subsyncarr를 추가하려 했으며, 기존 미디어 서버를 망가뜨릴까 걱정하고 있었습니다.
커뮤니티의 답변은 단순히 “Compose 파일을 붙여 넣으세요”라고 하지 않았습니다. Docker 이미지, 태그, 네트워크, 볼륨, 환경 변수, 장치 및 컨테이너 명령에 어떤 값을 입력해야 하는지, 그리고 무엇보다 SCAN_PATHS와 같은 환경 변수는 컨테이너 내부에서 볼 수 있는 경로를 사용해야 하는 이유를 설명했습니다.
ZimaOS 양식을 Docker 구성으로 이해하기
소스 예시에서 커뮤니티는 기본 Compose 필드를 대략 다음과 같이 매핑했습니다.
- Docker 이미지 →
mrorbitman/subsyncarr - 태그 → 원하는 릴리스 태그, 과거에는
latest - 제목 → 다음과 같이 알기 쉬운 앱 이름을 지정합니다
Subsyncarr - 네트워크 →
bridge단, 앱의 최신 지침에서 다른 방법을 요구하는 경우는 예외입니다
업스트림 Compose 예시를 기준 정보로 사용하세요
Subsyncarr는 계속 발전해 왔으므로, 설치하기 전에 예전 커뮤니티 스크린샷과 현재 Subsyncarr 컨테이너 설정을 비교하세요.
볼륨이 가장 중요한 부분입니다
Docker 볼륨에는 두 가지 측면이 있습니다.
- 호스트 경로: 영화, TV, 애니메이션 또는 애플리케이션 데이터가 포함된 실제 ZimaOS 폴더입니다.
- 컨테이너 경로: Subsyncarr가 자체 파일 시스템 내부에서 보는 경로입니다.
매핑은 개념적으로 다음과 같이 표시할 수 있습니다.
호스트: /DATA/Media/Movies
컨테이너: /movies정확한 호스트 폴더는 Jellyfin 라이브러리가 실제로 저장된 위치에 따라 달라집니다. 다른 사용자의 경로를 복사하지 마세요. ZimaOS Files 앱을 확인하거나 Jellyfin의 기존 볼륨 매핑을 검사하여 두 컨테이너가 동일한 미디어를 가리키도록 하세요.
사용자 지정 미디어 애플리케이션을 추가하기 전에 실제 ZimaOS 저장소 폴더가 컨테이너 경로가 되는 방식에 대한 현재 설명을 참고하면 유용합니다.
SCAN_PATHS는 컨테이너 측 경로와 일치해야 합니다
이것이 원래 답변의 핵심 교육 내용이었습니다. 호스트 폴더가 다음 위치에 매핑되어 있다면 컨테이너 내부의 /movies 그런 다음 Subsyncarr가 스캔해야 합니다 컨테이너 내부의 /movies.
올바른 예:
SCAN_PATHS=/movies,/tv,/anime해당 경로가 호스트 경로일 뿐이라면 잘못된 예:
SCAN_PATHS=/DATA/Media/Movies폴더를 컨테이너에 명시적으로 매핑하지 않으면 컨테이너는 임의의 ZimaOS 호스트 경로를 볼 수 없습니다.
환경 변수를 하나씩 번역하세요
원본 Compose 예시에는 시간대, cron 일정, 스캔 경로, 제외 디렉터리, 동기화 엔진과 같은 변수가 포함되어 있었습니다. 각 변수를 업스트림 애플리케이션이 요구하는 동일한 값 형식으로 환경 변수 섹션에 입력하세요.
번역하면서 cron 표현식을 “개선”하거나 컨테이너 경로의 이름을 변경하지 마세요. 먼저 업스트림 구성을 충실히 재현한 다음, 앱이 정상적으로 작동하는 것을 확인한 후 변경하세요.
현재 Subsyncarr 릴리스에는 Web UI가 있습니다
2026년 커뮤니티 답변에서는 문서에 애플리케이션이 노출하는 포트가 명시되어 있지 않은 한 Web UI와 포트를 비워 두라고 안내했습니다. 알 수 없는 애플리케이션에 대해서는 올바른 조언이었지만, 현재 Subsyncarr 릴리스는 이제 3000번 포트에서 Web UI와 영구 애플리케이션 데이터를 제공합니다.
대시보드를 사용하려면 호스트 포트를 컨테이너 포트 3000에 게시하고 ZimaOS 웹 UI 필드에 해당 호스트 주소를 설정하세요. 해당 포트가 이미 사용 중이라면 업스트림에서 내부 서비스 포트 자체를 구성할 수 있다고 하지 않는 한 호스트 측 포트만 변경하세요.
Subsyncarr 자체 애플리케이션 데이터 유지
중요한 볼륨은 미디어 폴더뿐이 아닙니다. 현재 Subsyncarr에는 자체 영구 데이터도 있습니다. 컨테이너 업데이트 후에도 유지되고 백업에 포함되도록 해당 애플리케이션 상태를 호스트 폴더에 보관하세요.
자막을 작성해야 할 때는 PUID와 PGID가 중요합니다
자막 처리기에는 읽기 권한 이상의 권한이 필요합니다. 미디어 옆에 자막 파일을 생성, 이름 변경 또는 수정해야 할 수 있습니다. 현재 Subsyncarr는 PUID와 PGID를 지원하므로, 스캔은 되지만 자막 쓰기에 실패한다면 컨테이너 사용자를 미디어 폴더의 소유자 또는 그룹 권한에 맞추세요.
업스트림에서 요구하지 않는 한 장치 및 컨테이너 명령은 비워 두세요
커뮤니티 답변에서는 존재한다는 이유만으로 모든 필드를 입력하지 말라고 올바르게 안내했습니다. 장치 매핑은 GPU나 직렬 장치 같은 하드웨어를 위한 것입니다. 컨테이너 명령은 이미지의 기본 시작 명령을 재정의합니다. 특정 업스트림 요구 사항이 없다면 어느 것도 추가하지 마세요.
이렇게 해도 Jellyfin이 중단되지 않는 이유
두 애플리케이션이 동일한 미디어 폴더를 읽는다고 해서 별도의 컨테이너를 추가하는 것만으로 Jellyfin이 수정되지는 않습니다. 더 큰 위험은 권한입니다. Subsyncarr에 파일 이름 변경 또는 쓰기 권한을 허용하는 경우, 설정이 의도한 미디어 및 자막 경로만 변경하도록 하세요.
애플리케이션이 전체 컬렉션을 대상으로 실행되도록 설정하기 전에 소규모 테스트 라이브러리부터 시작하세요.
ZimaOS 사용자 지정 앱 FAQ
SCAN_PATHS에는 호스트 경로와 컨테이너 경로 중 어느 것을 사용하나요?
볼륨 매핑으로 생성한 컨테이너 경로를 사용하세요.
ZimaOS 사용자 지정 앱 양식의 모든 필드를 입력해야 하나요?
아니요. 애플리케이션에 실제로 필요한 포트, 장치, 명령 및 기타 필드만 구성하세요.
현재 Subsyncarr에 웹 UI가 있나요?
예. 최신 릴리스에서는 포트 3000에서 대시보드를 제공합니다.
Subsyncarr가 Jellyfin과 동일한 미디어 폴더를 사용할 수 있나요?
예. 두 컨테이너가 동일한 실제 호스트 폴더를 매핑하고 권한이 적절하다면 가능합니다.
