ZimaOS에서 Homepage가 시작되었지만 브라우저에 호스트 검증 실패만 표시된다면 컨테이너는 정상적으로 실행 중일 수 있습니다. 이 오류는 Homepage 자체의 보안 검사이며, ZimaOS 방화벽이나 포트 문제라고 단정할 수 없습니다.
Homepage가 ZimaOS IP를 거부하는 이유
localhost에서 항상 허용되는 주소가 아닌 호스트 이름이나 IP를 통해 Homepage에 접속하는 경우, Homepage에는 HOMEPAGE_ALLOWED_HOSTS가 필요합니다. 이 값은 Homepage가 요청에서 확인하는 호스트와 일치해야 하며, 경우에 따라 포트도 포함해야 합니다.
현재 Homepage 프로젝트에서는 이 변수가 쉼표로 구분된 목록이라고 설명하며, 이 오류가 발생한 사용자는 애플리케이션 로그에서 거부된 호스트를 정확히 복사하라고 안내합니다.
값을 선택할 때는 Homepage 프로젝트의 최신 호스트 검증 규칙을 참고하세요.
컨테이너를 변경하기 전에 오류 로그 확인
커뮤니티 답변에서 유용했던 문제 해결 순서는 Homepage가 3000번 포트에서 실행 중인지 확인한 다음, 환경 변수를 변경하기 전에 컨테이너 로그를 확인하는 것이었습니다. 일반적으로 로그에 거부된 호스트가 표시됩니다.
예를 들어 로그에서 192.168.1.20:3000을 거부한다면 다른 IP나 도메인 이름만 추가해서는 해당 요청이 허용되지 않습니다. 실제로 브라우저에서 접속하는 호스트를 정확히 사용하세요.
앱 환경에서 HOMEPAGE_ALLOWED_HOSTS 설정
ZimaOS 앱 설정에서 환경 변수를 추가하거나 수정하여 사용할 LAN IP, 호스트 이름, 리버스 프록시 이름 또는 쉼표로 구분한 여러 호스트를 입력하세요.
HOMEPAGE_ALLOWED_HOSTS=192.168.1.20:3000위의 정확한 값은 예시일 뿐입니다. 사용 중인 Homepage 로그에 표시된 호스트를 입력하세요.
기본 해결 방법으로 * 사용하지 않기
변수를 *로 설정하면 Homepage의 호스트 검사를 비활성화할 수 있지만, 현재 안내에서는 이를 권장하지 않는다고 명시합니다. 호스트 검사는 예기치 않은 Host 헤더로부터 애플리케이션의 API 프록시를 보호하는 데 도움이 됩니다.
Homepage를 신뢰할 수 있는 LAN 외부에 노출하는 경우, 업스트림 프로젝트에서는 인증과 TLS를 적용하는 리버스 프록시 또는 VPN도 권장합니다.
리버스 프록시에는 별도의 허용 호스트가 필요합니다
일반적으로 Nginx Proxy Manager, Traefik 또는 다른 프록시 뒤의 도메인을 통해 Homepage를 연다면 Homepage가 인식하는 호스트는 직접 접속하는 ZimaOS IP와 다를 수 있습니다. 브라우저 URL만 보고 추측하지 말고, 컨테이너 로그에 실제로 표시된 값을 추가하세요.
Homepage 호스트 검증 FAQ
이 오류는 3000번 포트가 닫혀 있다는 뜻인가요?
반드시 그렇지는 않습니다. Homepage 오류 페이지가 로드된다면 요청은 이미 애플리케이션에 도달한 것입니다.
HOMEPAGE_ALLOWED_HOSTS에는 어떤 값을 입력해야 하나요?
Homepage가 거부했다고 표시한 정확한 호스트 이름 또는 IP를 입력하세요. 로그에 포트가 포함되어 있다면 포트도 함께 입력해야 합니다.
HOMEPAGE_ALLOWED_HOSTS=*로 설정해도 되나요?
Homepage에서는 허용하지만 권장하지 않습니다. 가능한 경우 명시적인 허용 목록을 사용하세요.
이 게시글에서 ZimaOS 관련 버그가 확인되었나요?
아니요. 커뮤니티의 단일 답변은 일반적인 Homepage 호스트 검증을 원인으로 지목했으며, 현재 업스트림 Homepage의 동작도 이 설명을 뒷받침합니다.
