경로 기반 리버스 프록시(호환 모드)

경로 매핑은 리버스 프록시 모드 → 경로 모드에서만 기본 라우트로 사용됩니다. 하나의 외부 Host 아래에 있는 경로 접두사를 서로 다른 HTTP 업스트림으로 전달하며, 예를 들어 /alist를 AList로 보낼 수 있습니다.

새로 배포할 때는 서브도메인 매핑을 우선 사용합니다. Host 라우트를 사용하면 각 애플리케이션이 루트 경로에서 그대로 작동하므로 일반적으로 경로 다시 쓰기보다 안정적입니다. 경로 모드는 기존 URL을 유지해야 하거나 당장 여러 서브도메인을 구성하기 어려운 환경에 적합합니다.

라우팅 방식

https://example.com/alist    -> http://127.0.0.1:5244
https://example.com/jellyfin -> http://127.0.0.1:8096

게이트웨이는 가장 긴 경로 접두사를 기준으로 일치시킵니다. /app과 /app-admin이 함께 있으면 /app-admin/users 요청은 /app-admin과 일치합니다.

경로 접두사는 브라우저 URL에도 포함됩니다. 애플리케이션이 /, 콜백 주소, Service Worker 범위 또는 WebSocket 주소를 하드코딩했다면 다시 쓰기를 활성화해도 문제가 생길 수 있습니다. 이 경우에는 규칙을 계속 덧붙이지 말고 Host 라우트로 이전합니다.

매핑 추가

경로 매핑으로 이동해 서비스 검색으로 후보 규칙을 만들거나 직접 입력할 수 있습니다.

필드	역할
트리거 경로	/로 시작하는 외부 경로 접두사
대상 주소	http, https, ws 또는 wss 업스트림 URL
인증 필요	권한이 없으면 먼저 fn-knock 로그인 절차로 이동
경로 접두사 제거	/alist/users를 /users로 바꿔 업스트림에 전달
HTML 다시 작성	일부 페이지의 리소스 참조에 외부 경로 접두사를 추가
루트 모드	일치한 매핑을 기록한 뒤 브라우저를 /로 보내 루트 디렉터리 실행만 지원하는 서비스와 호환

대상 주소에는 fn-knock 실행 환경에서 접근 가능한 주소를 입력합니다. 보통 루프백이나 LAN 주소를 사용합니다. Docker에서 127.0.0.1은 컨테이너 자체를 가리키므로 호스트에서 실행되는 서비스에는 컨테이너가 접근할 수 있는 주소를 사용합니다.

서비스 검색에서 제안하는 인증, 다시 쓰기 및 접두사 제거 옵션은 권장값일 뿐입니다. 저장하기 전에 대상 애플리케이션의 기본 경로 지원 여부에 맞게 조정합니다.

검색 창에서는 “기기 권장 설정 사용” 또는 낮음, 중간, 높음, 매우 높음 강도를 선택할 수 있습니다. 모든 단계의 검색 범위와 결과는 같고 동시 실행 수, 소요 시간 및 기기 부하만 달라집니다. 자원이 부족한 기기에서는 자동 또는 낮음 강도를 우선 사용합니다.

검색에는 로컬 IPv4 CIDR만 사용할 수 있으며 후보 설정은 자동으로 적용되지 않습니다. 대상 출처, 포트 범위, 동시 실행 제한 및 문제 해결 절차는 서비스 검색 및 일괄 등록을 참고합니다.

접근 정책

인증 필요를 끄면 해당 경로가 공개됩니다. 켜면 외부 네트워크 방문자가 fn-knock에 먼저 로그인한 뒤 업스트림에 접근합니다. 경로 매핑에는 별도의 엄격한 허용 목록 정책이 없습니다. IP 허용 목록은 출발지에 권한을 부여하지만 “인증 필요” 경로를 해당 출발지만 접근할 수 있도록 바꾸지는 않습니다. 요청이 경로에 도달하기 전에 출발지 범위를 좁혀야 한다면 게이트웨이 접근 범위나 외부 네트워크 계층 규칙을 사용합니다.

게이트웨이가 루프백, 사설망 또는 링크 로컬 출발지로 인식하면 인증 결과가 local_exempt가 되어 일반 로그인 검사를 건너뜁니다. 따라서 LAN에서 경로가 바로 열린다는 사실만으로 인터넷 인증이 적용되었다고 판단할 수는 없습니다. FRP나 다른 프록시를 거칠 때는 요청 로그에서 실제 인터넷 클라이언트 IP가 유지되는지 확인합니다.

Host 매핑의 Basic Auth 건너뛰기는 대상 서비스에 업스트림 자격 증명을 삽입하는 기능이며 fn-knock 로그인이 아닙니다. 경로 매핑에서 브라우저 Basic Auth를 게이트웨이 인증의 대안으로 사용하면 안 됩니다.

기본 라우트

기본 라우트는 루트 경로 /를 처리합니다. 서비스 검색은 보통 fnOS를 기본 서비스로 설정합니다. 루트 경로를 다른 애플리케이션으로 보내야 할 때만 변경합니다.

여러 매핑이나 기본 라우트를 변경한 뒤 경로 동기화를 클릭하면 현재 설정을 게이트웨이에 다시 전송할 수 있습니다. 규칙 하나를 저장할 때는 일반적으로 이미 동기화가 실행됩니다.

Host 라우트로 이전해야 할 때

다음 중 하나라도 해당하면 이전을 우선 고려합니다.

• 정적 리소스, WebSocket 또는 로그인 콜백이 계속 루트 경로로 이동합니다.
• 애플리케이션에서 기본 경로를 설정할 수 없습니다.
• 여러 애플리케이션의 접두사, 쿠키 또는 Service Worker가 서로 영향을 줍니다.
• 서비스마다 로그인 필요, 예약 공개 또는 업스트림 Basic Auth 삽입을 따로 설정합니다.

리버스 프록시 모드 → 서브도메인 매핑으로 전환하면 기존 경로 규칙은 유지되지만 메뉴에서 숨겨집니다. Host 연결이 안정적인지 확인한 뒤 이전 규칙을 정리합니다.

문제 해결

1. 현재 모드가 리버스 프록시 모드 → 경로 모드인지 확인합니다.
2. fn-knock 실행 환경에서 대상 URL에 직접 접근합니다.
3. 가장 긴 접두사가 예상한 규칙과 일치하는지 확인합니다.
4. 업스트림이 받은 URI를 기준으로 경로 접두사 제거를 활성화할지 결정합니다.
5. 페이지 리소스를 불러오지 못하면 HTML 다시 작성을 확인하고, 그래도 실패하면 Host 라우트로 이전할지 검토합니다.
6. 요청 로그에서 클라이언트 IP, 일치한 경로, 상태 코드 및 업스트림 대상을 확인합니다.

네트워크 진입점은 NAT 통과 및 터널을, 설정 절차는 리버스 프록시 모드 시작하기와 리버스 프록시 접속 튜토리얼을 참고합니다.