Jellyfin을 리버스 프록시의 하위 경로에서 사용할 수 있나요?

Eva Wong 는 테크니컬 라이터 이자 상주 메이커 로 ZimaSpace에서 활동합니다. 평생 기술을 사랑해 온 그녀는 홈랩과 오픈 소스 소프트웨어에 열정을 품고 있으며, 복잡한 기술 개념을 누구나 이해하기 쉬운 실습 가이드로 풀어내는 데 전문성을 갖추고 있습니다. Eva는 셀프 호스팅이 어렵고 부담스러운 일이 아니라 즐거워야 한다고 믿습니다. 그녀는 튜토리얼을 통해 커뮤니티가 하드웨어 설정의 어려움을 풀어내고, 첫 NAS를 조립하는 것부터 Docker 컨테이너를 능숙하게 다루는 것까지 도전하도록 돕습니다.

네. Jellyfin은 https://example.com/jellyfin 같은 하위 경로에서 리버스 프록시 뒤에 둘 수 있지만, Jellyfin과 프록시에서 동일한 기본 경로를 사용해야 합니다.

하위 경로 문제는 보통 사이트가 일부만 작동하는 형태로 나타납니다. 로그인 페이지는 로드되지만 JavaScript, 이미지, WebSocket, 리디렉션 또는 네이티브 클라이언트가 작동하지 않을 수 있습니다. 경로 불일치와 TLS 또는 프록시 ID 문제를 구분할 수 있도록 Base URL, 프록시 경로, 전달 헤더와 클라이언트 주소 순으로 계층별로 테스트하세요.

Jellyfin Base URL을 공개 하위 경로에 맞추기

Jellyfin의 Base URL을 사용하려는 정확한 공개 접두 경로(예: /jellyfin)로 설정하세요. 프록시에서 이름이 지정된 location 블록을 사용한다는 이유로 다른 내부 접두 경로를 추가하지 마세요. 브라우저에 표시되는 경로와 Jellyfin Base URL은 동일한 애플리케이션 루트를 가리켜야 합니다.

Jellyfin의 Apache 리버스 프록시 문서에는 하위 경로 예제가 명시적으로 나와 있으며, 클라이언트를 전체 주소에 연결하기 전에 Base URL을 /jellyfin으로 설정하라고 안내합니다. 공식 하위 경로 예제

Base URL을 변경한 후 Jellyfin을 다시 시작하고, 새 시크릿 브라우저 창에서 공개 하위 경로를 여세요. 처음 리디렉션할 때 /jellyfin이 바로 사라지거나 두 번 붙는다면 WebSocket이나 인증 설정을 건드리기 전에 Base URL을 수정하세요.

리버스 프록시에서 동일한 접두 경로로 라우팅하기

공개 접두 경로로 시작하는 요청이 별도의 경로 변환 없이 Jellyfin으로 전달되도록 리버스 프록시를 구성하세요. 가장 간단한 구성은 공개 접두 경로 하나, 이에 일치하는 Jellyfin Base URL 하나, 업스트림 서비스 하나를 사용하는 것입니다.

Caddy의 Jellyfin 가이드에도 동일한 패턴이 나와 있습니다. Jellyfin 기본 경로를 설정하고, 끝에 슬래시가 붙은 형식으로 기본 접두 경로를 리디렉션한 다음, 해당 접두 경로 아래의 요청을 Jellyfin 백엔드로 프록시합니다. 일치하는 기본 경로와 프록시 경로

Jellyfin이 요청을 기록하기 전에 브라우저가 프록시에서 404를 받는다면 프록시 계층의 라우팅이 잘못된 것입니다. Jellyfin이 요청을 수신했지만 접두 경로가 없는 링크를 생성한다면 애플리케이션 계층의 Base URL이 잘못된 것입니다. 이 두 가지 오류 패턴은 구분해서 확인하세요.

로그인 페이지뿐 아니라 정적 에셋과 WebSocket도 확인하세요

성공적인 HTML 응답만으로는 하위 경로 설정이 정상이라고 볼 수 없습니다. 개발자 도구나 프록시 로그를 열고 JavaScript, CSS, 이미지, API, WebSocket 요청이 모두 동일한 공개 접두 경로 아래에 유지되는지 확인하세요.

Jellyfin의 리버스 프록시 예시에는 WebSocket 처리가 포함되어 있습니다. 대화형 클라이언트는 일반 HTTP 요청 외에도 소켓 연결을 유지하기 때문입니다. 따라서 페이지 요청만 처리하는 프록시 규칙은 제대로 작동하는 것처럼 보이다가 재생 상태, 세션 업데이트 또는 실시간 UI 동작에 문제가 생길 수 있습니다. 리버스 프록시 요구사항

통과 조건은 간단합니다. 접두 경로가 포함된 에셋에서 404/502 응답이 반복되지 않고, WebSocket이 성공적으로 업그레이드되며, 탐색 중 사이트 루트로 빠지지 않아야 합니다. 특정 요청 유형에서만 실패한다면 Jellyfin의 라이브러리나 인증 설정을 변경하는 대신 해당 프록시 규칙을 수정하세요.

프록시를 통해 클라이언트 ID 유지하기

경로가 작동하면 전달된 클라이언트 정보를 확인하세요. Jellyfin은 프록시 신뢰 설정에 따라 전달된 주소와 프로토콜을 허용할지 결정하며, 이는 로컬 및 원격 동작과 외부 접속 규칙에 영향을 줍니다.

Jellyfin 네트워킹 가이드에서는 신뢰할 수 없는 프록시에서 전달된 헤더는 무시되며, Known Proxies에 프록시 주소를 설정할 것을 권장합니다. Known Proxies 설정 사이트는 작동하지만 모든 요청의 출처가 프록시로 표시된다면, 별도의 클라이언트 IP 확인 절차가 유용합니다.

모든 사설 서브넷이나 전달된 헤더를 신뢰하도록 설정해 ID 문제를 해결하려 하지 마세요. 실제 프록시 홉이나 관리되는 프록시 네트워크만 추가한 다음, Jellyfin 로그에서 LAN 요청 하나와 원격 요청 하나를 비교해 예상대로 분류되는지 확인하세요.

브라우저와 네이티브 클라이언트 주소를 별도로 테스트하세요

Jellyfin 클라이언트에서 서버 URL을 입력하라는 메시지가 표시되면 하위 경로를 포함한 전체 서버 주소를 입력하세요. https://example.com으로 저장된 클라이언트는 Jellyfin이 /jellyfin 경로에 있다는 사실을 알아낼 수 없습니다.

LAN에서 브라우저 하나와 네이티브 클라이언트 하나를 테스트한 다음, 공용 호스트 이름을 통해서도 다시 테스트하세요. 호스트 이름은 작동하지만 로컬 IP로 직접 접속할 수 없다면, 프록시 경로와 인증서가 호스트 이름에 종속되어 있어 예상되는 동작일 수 있습니다. 호스트 이름과 IP 비교 테스트를 통해 프록시 보안을 약화하지 않고 이 경우를 파악할 수 있습니다.

로그인, 탐색, WebSocket 사용, 재생 과정에서 접두 경로가 포함된 URL이 유지되는지 실제 지원하는 클라이언트에서 확인하세요. 브라우저와 다른 클라이언트에서는 통과하는데 클라이언트 하나에서만 실패한다면, 제대로 작동하는 프록시 구성을 다시 작성하기보다 클라이언트 주소 또는 호환성 문제로 판단하세요.

지원 및 팁

더 읽어보기

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.