문제 해결

증상을 찾고, 원인을 읽고, 해결 방법을 따라 하세요. 예시는 컨테이너 이름을 holyarrs로 씁니다. 이름이 다르면 쓰는 이름으로 바꾸세요.

먼저 확인할 3가지

1. 로그를 보세요: docker logs -f holyarrs. 비밀 값은 가려져 있습니다. 그만 보려면 Ctrl+C를 누르세요. 컨테이너는 계속 실행됩니다.
2. doctor를 실행하세요: docker exec holyarrs /holyarrs doctor. 줄마다 OK, WARN, FAIL 중 하나가 나오고, WARN과 FAIL에는 고치는 방법이 함께 나옵니다.
3. 그래도 안 되나요? 지원 번들을 다운로드해서 물어보세요. 지원 받기를 참고하세요.

웹 페이지가 열리지 않음

증상: 브라우저가 http://your-server:6262에 연결하지 못합니다.

원인: 컨테이너가 중지되었거나, 포트가 매핑되지 않았거나, 중간에 프록시가 있습니다.

해결:

1. docker ps를 실행하세요. holyarrs가 0.0.0.0:6262->6262와 함께 표시됩니다.
2. 계속 재시작한다면 docker logs holyarrs에서 이유를 확인하세요.
3. /holyarrs 같은 경로를 쓴다면 리버스 프록시와 URL base를 참고하세요.

권한 거부

증상: doctor가 폴더에 쓸 수 없다고 하거나, 가져오기가 권한 오류로 실패합니다.

원인: 호스트에 있는 폴더의 소유자가 PUID, PGID와 다릅니다.

해결: doctor가 알려 주는 chown을 실행하거나, PUID와 PGID를 폴더 소유자에 맞추세요. NAS에서는 권한 화면에서 해당 사용자에게 읽기와 쓰기 권한을 주세요. NAS, Synology, Unraid를 참고하세요.

아무것도 다운로드되지 않음

증상: 작품이 계속 누락 상태이고 다운로더로 아무것도 넘어가지 않습니다.

원인: 응답하는 소스가 없거나, 다운로더가 연결되지 않았거나, 선택 규칙을 통과하는 릴리스가 없습니다.

해결:

1. Settings > Downloaders(설정 > 다운로더)를 열고 다운로더에서 Test(테스트)를 누르세요. 통과해야 합니다.
2. Settings > Sources(설정 > 소스)를 열고 소스마다 Test를 누르세요.
3. 작품에서 Choose a release(릴리스 직접 고르기)를 열어 모든 결과와 선택되지 않은 이유를 확인하세요.

다운로더와 소스를 참고하세요.

다운로드는 됐는데 가져오지 않음

증상: 다운로더에서는 다운로드가 끝났는데 작품이 라이브러리에 없습니다.

원인: HolyArrs가 같은 경로에서 파일을 볼 수 없거나, 라이브러리 폴더에 쓸 수 없거나, 가져오기가 결정을 기다리고 있습니다.

해결:

1. HolyArrs와 다운로더에 같은 다운로드 폴더를 /downloads처럼 같은 경로로 주거나, 다운로더에서 Downloader’s path(다운로더의 경로)와 HolyArrs’ path(HolyArrs의 경로)를 설정하세요.
2. doctor를 실행하고 다운로드 폴더나 라이브러리 폴더에 나온 FAIL을 모두 고치세요.
3. 다운로드 목록에서 Needs a decision(결정 필요)으로 표시된 항목을 찾아 계획을 승인하거나 버리세요.

가져오기가 하드링크가 아니라 복사로 됨

증상: doctor가 하드링크가 안 된다고 하거나, 가져온 뒤 디스크 사용량이 두 배가 됩니다.

원인: 다운로드 폴더와 라이브러리 폴더가 서로 다른 디스크나 마운트에 있습니다.

해결: 폴더를 따로따로 마운트하지 말고 공통 상위 폴더 하나를 컨테이너에 마운트하세요. 폴더를 참고하세요.

HolyArrs가 시작되지 않음

증상: 컨테이너가 바로 멈추거나 재시작합니다.

원인: 로그에 이유가 나옵니다. 흔한 경우는 /config가 네트워크 공유 폴더나 FUSE 경로에 있거나, 파트 하나가 고장 난 것입니다.

해결:

1. 로그에 그렇게 나오면 /config를 로컬 디스크로 옮기세요. HolyArrs는 공유 폴더에서 데이터베이스를 실행하지 않습니다.
2. 그렇지 않으면 안전 모드로 시작해서 Settings(설정)에서 고친 다음 평소처럼 재시작하세요.

기능이 보이지 않음

증상: 문서에서 읽은 기능이 앱에 없습니다.

원인: 이번 릴리스에서 보류된 기능일 수 있습니다.

해결: 보류된 기능을 참고하세요.

페이지에 이름이나 이미지가 없음

증상: 작품이 포스터나 상세 정보 없이 표시됩니다.

원인: 메타데이터 서버에 연결할 수 없습니다.

해결: DNS와 방화벽을 확인하세요. doctor의 Network 항목에서 서버가 응답하는지 볼 수 있습니다.

고급 사용자용

doctor 점검 항목과 옵션

doctor는 컨테이너 안에서 HolyArrs와 같은 사용자로 실행되므로, HolyArrs가 겪는 문제를 그대로 겪습니다.

항목	보여 주는 것
App	버전, 사용자와 그룹, umask, 컨테이너에서 실행 중인지 여부.
Config folder	소유자, 권한, 여유 공간, 로컬 디스크에 있는지 여부.
Library and download folders	존재 여부, 소유자, 쓰기 가능 여부, 여유 공간, 다운로드 폴더와 라이브러리 폴더 사이의 하드링크.
Network	메타데이터 서버의 이름이 조회되고 서버가 응답하는지 여부.
Clock	시간, 시간대(TZ), 시계가 확실히 틀렸을 때의 경고.

옵션	하는 일
-config <folder>	/config가 아닌 다른 HolyArrs 설정 폴더를 점검합니다.
-json	보고서를 JSON으로 출력합니다.

종료 코드 0은 실패가 없다는 뜻이고, 1은 FAIL인 줄이 있다는 뜻입니다. 보고서에는 키, 비밀번호, 토큰이 절대 나오지 않습니다. 읽기만 하며, 작은 테스트 파일 하나를 썼다가 지우는 것만 예외입니다. root로 시작하면 평소 시작할 때처럼 설정 폴더의 소유자를 PUID:PGID로 넘기기도 합니다.

HolyArrs가 계속 재시작하면 docker exec가 실패합니다. 같은 폴더를 쓰는 새 컨테이너에서 doctor를 실행하세요:

docker run --rm --volumes-from holyarrs -e PUID=<puid> -e PGID=<pgid> -e TZ=<tz> holyarrs/holyarrs:<tag> doctor

Compose를 쓴다면: docker compose run --rm holyarrs doctor.

시작 시 폴더 점검

HolyArrs는 시작할 때 폴더를 점검하고 folders: 4 ok, 1 not writable 같은 요약 한 줄을 로그에 남긴 다음, 문제가 있는 폴더마다 해결 방법과 함께 한 줄씩 남깁니다. 시작이 멈추지 않도록 점검은 3초 뒤에 끝납니다. 응답이 너무 느린 폴더는 점검하지 않은 것으로 칩니다. 대개 절전 상태에서 깨어나는 디스크이거나 느린 네트워크 공유 폴더입니다. doctor는 시간 제한 없이 점검합니다. 로그를 참고하세요.

이미지에 셸이 없음

이미지에는 HolyArrs 프로그램만 들어 있어서 크기가 작고 공격자가 쓸 만한 것도 적습니다. docker exec holyarrs sh는 의도적으로 실패합니다. 더 자세히 보려면 옆에 일회용 도우미 컨테이너를 띄우세요:

docker run --rm -it --pid container:holyarrs --network container:holyarrs --volumes-from holyarrs busybox sh

이 컨테이너는 HolyArrs 프로세스를 볼 수 있고, 네트워크를 함께 쓰며, 같은 폴더를 같은 경로로 가집니다. root로 실행되므로 보기만 하고 바꾸지는 마세요. root로 쓴 파일은 HolyArrs가 읽지 못할 수 있습니다. HolyArrs 사용자로 테스트하려면 --user <PUID>:<PGID>를 추가하세요.

버전 확인

docker inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' holyarrs

doctor의 App 항목에도 같은 내용이 나옵니다.

관련 문서

• 지원 받기
• 로그
• 상태 점검