이 2025년 12월 스레드에서 중요한 사실은 ZimaBoard 2에 작동하는 AdGuard Home 설치가 완료되지 않았다는 점입니다. 원글 작성자는 커뮤니티의 제안을 시도한 뒤, 별도의 Umbrel 서버에서는 AdGuard Home이 작동했지만 ZimaOS 배포는 여전히 사용할 수 없다고 보고했습니다. 따라서 이는 해결된 설치 방법이 아니라 문제 해결을 다루는 글입니다.
스크린샷과 답변에는 여전히 몇 가지 유용한 점검 항목이 드러나 있습니다. 애플리케이션에는 DNS와 웹 인터페이스에 대한 별도의 포트 매핑이 있었고, 브리지 네트워킹으로 실행되고 있었으며, 커뮤니티에서는 UniFi 게이트웨이보다 포트 충돌에 초점을 맞췄습니다.
“Service Unavailable”이 알려 주는 것과 알려 주지 않는 것
Service Unavailable 페이지가 표시된다는 것은 어떤 HTTP 경로가 응답했다는 뜻일 뿐입니다. AdGuard 프로세스가 초기화를 완료했는지, 역방향 경로가 올바른 내부 포트를 가리키는지, DNS 포트 53이 정상적으로 바인딩되었는지는 알 수 없습니다.
서비스가 로컬 ZimaOS 호스트에서 정상 상태가 되지도 않은 상황에서는 라우터 설정 변경부터 시작하지 마세요.
원본 구성에서는 DNS 포트와 웹 포트를 별도로 게시했습니다
AdGuard Home 최초 설정에는 포트 3000이 사용됩니다
현재 AdGuard Home Docker 안내에서는 최초 설정 마법사와 일반 관리 인터페이스를 구분합니다. 새 컨테이너에서는 최초 설정 과정에 TCP 포트 3000이 사용됩니다. 구성이 완료되면 일반 HTTP 인터페이스는 사용자가 변경하지 않는 한 보통 포트 80을 사용합니다.
짧은 커뮤니티 답변에는 이 중요한 세부 사항이 빠져 있습니다. 8080:80과 같은 호스트 매핑은 설정 완료 후 UI에는 올바를 수 있지만, 새 컨테이너가 요구하는 최초 설정 엔드포인트를 노출하지 못할 수 있습니다.
라우터를 변경하기 전에 AdGuard Home의 최신 Docker 포트 및 볼륨 요구 사항과 애플리케이션 설정을 비교하세요.
DNS에는 TCP와 UDP 모두에서 포트 53이 필요합니다
커뮤니티 답변에서 AdGuard Home에 일반적인 DNS 서비스용 포트 53이 필요하다고 지적한 것은 정확합니다. 컨테이너가 LAN에 DNS를 제공하려면 TCP와 UDP를 모두 사용할 수 있어야 합니다.
다른 Pi-hole, AdGuard, 시스템 리졸버 또는 DNS 컨테이너가 이미 포트 53을 사용하고 있다면 새 서비스는 정상적으로 바인딩할 수 없습니다. 웹 UI 포트를 계속 변경하는 것보다 호스트에서 기존 리스너를 확인하는 편이 더 유용합니다.
웹 UI 포트와 DNS 포트는 서로 다른 문제입니다
포트 80 또는 3000의 충돌은 관리 인터페이스를 열지 못하게 할 수 있지만 DNS 자체는 정상일 수 있습니다. 포트 53의 충돌은 대시보드가 열리더라도 DNS 서비스가 시작되지 못하게 할 수 있습니다. 진단 중에는 이 두 문제를 별도의 경로로 구분하세요.
호스트 모드가 제안되었지만, 필수라는 사실은 입증되지 않았습니다
커뮤니티 답변자는 브리지 모드가 DNS 포트를 복잡하게 만드는 경우가 있다며 호스트 네트워크 모드를 시도해 보라고 권장했습니다. 그러나 원글 작성자는 해당 변경 후 ZimaOS에서 성공했다는 결과를 다시 알리지 않았습니다.
따라서 호스트 네트워킹을 필수 사항으로 제시해서는 안 됩니다. AdGuard Home의 유지 관리되는 Docker 배포는 명시적인 포트 매핑을 지원합니다. 필요한 포트가 비어 있고 올바르게 매핑되어 있다면 브리지 모드도 작동할 수 있습니다.
UniFi Cloud Gateway가 원인으로 지목되지는 않았습니다
사용자는 UniFi Cloud Gateway Max를 변경해야 하는지 구체적으로 질문했습니다. 커뮤니티의 답변은 AdGuard Home을 로컬에서 열고 구성하는 것만으로는 라우터를 변경할 필요가 없다는 것이었습니다.
라우터 변경은 나중에 LAN 클라이언트가 AdGuard Home을 DNS 또는 DHCP 서버로 사용하도록 결정할 때 진행합니다. 로컬 초기화를 완료하지 못하는 컨테이너를 라우터 변경으로 복구할 수는 없습니다.
/opt/adguardhome/work 및 /opt/adguardhome/conf을 영구적으로 유지하세요
AdGuard Home은 영구 디렉터리에 런타임 데이터와 구성을 저장합니다. 이러한 경로가 다시 생성되거나 읽기 전용으로 마운트되거나 예상하지 못한 위치를 가리키면 컨테이너가 새 설치처럼 동작하거나 재생성 후 설정을 잃을 수 있습니다.
원본 스크린샷에는 이미 영구 볼륨이 표시되어 있습니다. 따라서 전체 재설치를 진행할 때는 애플리케이션이 초기 상태로 시작한다고 가정하기보다 기존 폴더가 재사용되고 있는지 확인해야 합니다.
더 나은 진단 순서
- 컨테이너 로그에서 시작 또는 바인딩 오류를 확인합니다.
- 최초 설정에 포트 3000이 필요한지 확인합니다.
- 일반 웹 UI 매핑을 별도로 확인합니다.
- 호스트에서 TCP 및 UDP 포트 53이 비어 있는지 확인합니다.
- 영구 구성 및 work 볼륨에 쓰기 권한이 있는지 확인합니다.
- 그런 다음에만 브리지 네트워킹과 호스트 네트워킹을 비교해 봅니다.
- 로컬 서비스가 정상 상태가 될 때까지 라우터의 DNS 변경은 보류합니다.
원본 사례는 ZimaOS에서 해결되지 않은 상태로 남았습니다
12월 24일, 사용자는 Umbrel 서버에서 AdGuard Home을 작동시키는 데는 성공했지만 ZimaBoard 2 배포는 여전히 실행할 수 없다고 보고했습니다. 도움 요청을 종료한 이유는 서비스가 다른 곳에서 제공되었기 때문이지, ZimaOS 설치 문제가 해결되었기 때문이 아닙니다.
AdGuard Home Service Unavailable FAQ
최초 설정에는 어떤 포트가 사용되나요?
현재 AdGuard Home Docker 안내에서는 초기 구성 마법사에 TCP 포트 3000을 사용합니다.
일반 DNS에는 어떤 포트가 사용되나요?
TCP와 UDP 모두에서 포트 53을 사용합니다.
ZimaOS에서 AdGuard Home을 사용하려면 호스트 네트워킹이 필요한가요?
원본 스레드에서는 이를 입증하지 않았습니다. 호스트 네트워킹은 커뮤니티에서 제안한 문제 해결 방법이었습니다.
원래 ZimaOS 사례는 해결되었나요?
아니요. 사용자는 서비스를 다른 서버로 옮겼고, 작동하는 ZimaOS 구성 없이 스레드를 종료했습니다.
