서브도메인 라우팅

서브도메인 매핑은 HTTP Host를 기준으로 여러 도메인을 로컬 웹 서비스에 분배하며 새 배포의 기본 라우팅 방식입니다. 다음 두 가지 네트워크 토폴로지에서 사용할 수 있습니다.

• 서브도메인 모드: 도메인이 접근 가능한 인터넷 진입점을 직접 가리킵니다.
• 리버스 프록시 모드 → 서브도메인 매핑: FRP 또는 Cloudflared가 각 서브도메인의 요청을 게이트웨이로 전달합니다.

두 방식 모두 auth.example.com을 로그인 진입점으로 사용하고 nas.example.com, alist.example.com 같은 서비스 Host가 하나의 게이트웨이를 공유합니다. 경로 매핑은 이전 배포와의 호환을 위한 방식이며 서브도메인 매핑의 사전 조건이 아닙니다.

요청 경로

브라우저 -> 공인 IP 직접 연결 또는 터널 -> fn-knock 게이트웨이 -> Host에 따라 일치 -> 로컬 대상(타깃)
                                  |
                                  +-> 공개 / 로그인 필요 / 고급 인증 임시 자격 증명

인터넷에서 직접 연결하고 기본 포트를 유지하면 일반적으로 https://nas.example.com:7999 형식으로 접근합니다. 앞단에 EdgeOne, ESA 또는 Cloudflared를 두면 방문자는 보통 표준 주소인 https://nas.example.com을 사용하지만 오리진은 실제 게이트웨이 포트로 연결됩니다.

설정 순서

1. 시스템 설정 → 모드에서 서브도메인 모드 또는 리버스 프록시 모드 → 서브도메인 매핑을 선택합니다.
2. 서브도메인 매핑에서 루트 도메인을 저장합니다. 예: example.com
3. 인증 서비스 추가를 클릭해 auth.example.com을 만듭니다.
4. 외부 DNS, 라우터 포워딩 또는 터널 공개 호스트 이름(Public Hostname)을 설정해 관련 Host가 모두 같은 게이트웨이로 들어오게 합니다.
5. 서비스 Host를 추가하고 각 매핑의 로그인 필요 활성화 여부를 결정합니다.
6. 출발지나 요청 특성에 따라 접근을 허용해야 한다면 매핑 오른쪽 메뉴에서 고급 인증을 엽니다.
7. 모바일 네트워크에서 로그인 리디렉션, 돌아오는 주소 및 요청 로그의 클라이언트 IP를 확인합니다.

공인 IP 직접 연결의 전체 절차는 서브도메인 모드 시작하기와 직접 연결 접속 튜토리얼을 참고합니다.

서브도메인 모드 설정

필드	역할	권장 사항
도메인	서비스 Host를 생성할 상위 도메인. 예: example.com	먼저 저장한 뒤 인증 서비스와 서비스 매핑 추가
현재 인증 서비스	로그인하지 않았을 때 사용하는 통합 로그인 진입점	auth.example.com을 사용하며 하나만 설정 가능
인증 서비스의 외부 HTTPS 포트	로그인 리디렉션 URL을 만들 때 사용하는 방문자 측 HTTPS 포트	방문자에게 실제로 표시되는 포트 입력
Edge 실제 IP 감지	공인 IP 직접 연결 서브도메인 모드에서 EdgeOne / ESA의 방문자 주소 읽기	해당 플랫폼에서 오리진에 연결할 때만 활성화

인증 서비스의 외부 HTTPS 포트는 외부 URL에만 영향을 주며 프로그램의 수신 포트를 바꾸지 않습니다. 라우터, 컨테이너 또는 엣지 플랫폼의 포트를 대신 열거나 NAT 포워딩을 만들지도 않습니다.

루트 도메인과 Host 매핑에는 *를 포함할 수 없습니다. 루트 도메인에는 example.com, 서비스 매핑에는 nas 또는 nas.example.com을 입력합니다. DNS에 *.example.com 와일드카드 레코드를 설정하는 것은 별도 계층의 설정이므로 fn-knock의 루트 도메인이나 Host에 와일드카드를 입력하지 않습니다.

EdgeOne / ESA

공인 IP 직접 연결 서브도메인 모드에서는 Tencent Cloud EdgeOne / Alibaba Cloud ESA 지원을 활성화할 수 있습니다. 활성화하면 공개 URL에서 :7999를 생략할 수 있으며 게이트웨이는 플랫폼 헤더에서 실제 클라이언트 IP를 읽습니다.

플랫폼	클라이언트 IP 헤더
Tencent Cloud EdgeOne	EO-Connecting-IP
Alibaba Cloud ESA	Ali-Real-Client-IP

ESA에서는 사이트의 관리형 변환에서 “실제 클라이언트 IP 헤더 추가”도 활성화합니다. 이 스위치는 EdgeOne / ESA만 지원하며 모든 CDN을 신뢰하는 범용 스위치가 아닙니다. Cloudflared에는 리버스 프록시 모드 → 서브도메인 매핑 전용 경로를 사용합니다.

엣지 플랫폼이 외부 80 / 443을 처리하더라도 오리진은 fn-knock의 실제 게이트웨이 포트를 가리키도록 구성합니다. 로그인 응답을 캐시하는 규칙은 끄고 WebSocket은 허용합니다. 인증서와 DNS는 각각 TLS 인증서와 DDNS 관리를 참고합니다.

Host 매핑

매핑에는 최소한 Host와 대상(타깃)을 입력합니다.

nas.example.com   -> http://127.0.0.1:5666
alist.example.com -> http://127.0.0.1:5244

필드	동작
Host / 서브도메인	요청의 Host와 일치. 루트 도메인을 저장했다면 nas만 입력 가능
대상(타깃)	fn-knock 실행 환경에서 접근할 수 있는 HTTP / HTTPS 업스트림 주소
로그인 필요	로그인하지 않았으면 인증 Host로 이동하고 완료 후 원래 주소로 돌아옴
비활성화 / 활성화 또는 비활성화 예약	직접 서비스를 내리거나 서버 로컬 시간을 기준으로 매일 공개 시간 제어
그룹	서비스 Host를 기존 그룹에 배치. 인증 서비스는 그룹에 넣을 수 없음
포털 표시	로그인 후 페이지의 서비스 전환 및 로그아웃 진입점 제어
표시 제목	목록, 포털 및 북마크의 표시 이름을 재정의
앱 아이콘	자동 수집 아이콘을 사용하거나 현재 서비스 Host의 사용자 지정 아이콘 업로드
Basic Auth 건너뛰기	업스트림 요청에 Basic Auth 사용자 이름과 비밀번호 삽입
접근 범위	전역 규칙 상속, 현재 Host 규칙으로 재정의 또는 현재 Host의 접근 범위 제한만 끄기
WAF 활성화	서비스 Host에서 기본적으로 활성화. 끄면 현재 Host가 전역 WAF를 건너뜀

서비스는 가능하면 루프백이나 사설망 주소에서만 수신 대기하도록 해 게이트웨이 우회를 방지합니다. Docker에서 127.0.0.1은 컨테이너 자체를 가리키므로 호스트 서비스를 프록시할 때는 컨테이너에서 접근할 수 있는 호스트 주소를 사용합니다. Docker 배포의 대상(타깃) 입력란에는 감지된 접근 가능한 LAN IP 후보가 표시되지만, 이 제안은 컨테이너 네트워크, 공개 포트 또는 업스트림 수신 범위를 변경하지 않습니다.

인증 서비스는 특별한 Host 매핑입니다. 공개 상태로 유지하고 로그인 필요나 Basic Auth 삽입을 활성화하지 않습니다. 그렇지 않으면 로그인 진입점에서 리디렉션 루프가 생기거나 자기 자신을 차단합니다.

그룹 보기

목록 위의 그룹 보기를 활성화하면 그룹 관리에서 그룹을 만들고 이름을 바꾸고 순서를 조정하거나 삭제할 수 있습니다. 개별 편집, 일괄 이동 또는 드래그 앤 드롭으로 서비스 Host를 그룹에 배치합니다. 그룹은 최대 32개까지 만들 수 있고 이름은 1～40자여야 하며 대소문자를 구분하지 않고 중복될 수 없습니다. 매핑이 남아 있는 그룹을 삭제해도 Host는 삭제되지 않고 “그룹 없음”으로 이동합니다.

그룹 순서와 Host 순서는 로그인 후 포털 및 내장 /__select__ 선택 페이지에 동기화됩니다. 브라우저 북마크를 내보낼 때도 같은 그룹 폴더가 만들어집니다. 목록 보기로 돌아가도 그룹 할당은 유지되지만 포털, 선택 페이지 및 새로 내보낸 북마크는 평면 순서를 사용합니다. 검색 중에는 일치하는 그룹과 Host만 표시하고 결과를 임시로 펼칩니다. 접기 상태는 현재 브라우저에만 저장됩니다.

그룹은 탐색 구조와 관리 순서만 바꾸며 인증, 접근 범위, WAF 또는 대상(타깃)은 변경하지 않습니다. 인증 서비스는 항상 그룹 밖에 있고 실제 접근은 자격 증명의 Host 서비스 범위에 따라 판단됩니다.

Basic Auth는 업스트림 자격 증명 삽입

Basic Auth 건너뛰기에는 대상 서비스 자체의 Basic Auth 자격 증명을 저장합니다. 게이트웨이는 요청을 프록시하거나 페이지 제목과 favicon을 가져올 때 이 자격 증명을 업스트림으로 전송해 브라우저에 Basic Auth 대화 상자가 다시 표시되지 않게 합니다.

fn-knock 계정을 만들거나 auth.example.com 로그인을 대신하지 않으며 로그인 필요 또는 기존 strict_whitelist 규칙도 바꾸지 않습니다. 자격 증명은 민감한 설정으로 취급하고 꼭 필요할 때만 저장합니다.

사용자 이름과 비밀번호를 모두 입력하고 사용자 이름에는 영문 콜론을 사용하지 않습니다. 불완전하거나 잘못된 설정을 저장하면 시스템은 일부만 설정된 상태를 남기는 대신 해당 기능을 끄고 자격 증명을 지웁니다.

앱 아이콘

일반 서비스 Host를 편집할 때 앱 아이콘을 열면 현재 아이콘 출처를 미리 보고, 업스트림 아이콘을 다시 수집하거나 사용자 지정 이미지를 업로드할 수 있습니다. PNG, JPG, WebP, AVIF, SVG 및 ICO를 지원하며 원본 파일은 5 MB를 넘을 수 없습니다. 브라우저는 SVG의 외부 콘텐츠를 정리하고 서버는 안전하지 않은 DOCTYPE 또는 엔터티 선언이 포함된 SVG를 거부합니다. 이후 이미지를 자르지 않은 채 정사각형 캔버스에 맞추고 128 KiB 이하의 내장 아이콘으로 변환합니다.

사용자 지정 아이콘은 서브도메인 목록과 포털에 우선 표시되며 브라우저 북마크를 내보낼 때도 포함됩니다. 자동 수집 복원을 클릭하면 사용자 지정 덮어쓰기를 지우고 대상(타깃)에서 다시 읽습니다. 대상에서 아이콘을 가져올 수 없으면 페이지에 아직 수집되지 않은 것으로 표시됩니다. 인증 서비스는 사용자 지정 아이콘을 지원하지 않습니다. 아이콘은 설정과 .knock 백업에 포함되므로 민감한 내부 이미지를 일반 문제 해결 첨부 파일로 공유하지 않습니다.

Host별 접근 범위 및 WAF

전역 게이트웨이 접근 범위를 활성화하면 서비스 Host의 고급 설정에서 “전역 접근 범위 상속”, “사용자 지정” 또는 “끄기”를 선택할 수 있습니다. 사용자 지정 규칙은 전역 규칙을 대체하고, 끄기는 현재 Host만 접근 범위 검사를 건너뛰게 합니다. 인증 Host는 전역 규칙을 상속합니다. 설정 방법과 롤백 권장 사항은 게이트웨이 접근 범위를 참고합니다.

서비스 Host에서는 WAF가 기본적으로 활성화되며 개별적으로 꺼서 전역 WAF를 건너뛸 수 있습니다. 전역 WAF 자체가 꺼져 있으면 이 스위치만으로 보호되지 않습니다. 인증 Host는 Host 설정을 통해 WAF를 우회할 수 없습니다. 자세한 정책은 WAF를 참고합니다.

고급 인증

로그인 필요를 활성화한 HTTP / HTTPS 서비스 Host의 오른쪽 메뉴에는 고급 인증이 표시됩니다. 출발지 IP, 지역, URL 경로, 요청 헤더, 쿼리 매개변수 또는 HTTP 메서드에 따라 현재 Host에서만 유효한 임시 자격 증명을 발급할 수 있습니다. 규칙과 일치하지 않는 요청은 일반 로그인 절차를 계속 사용합니다.

규칙과 일치하면 해당 규칙을 발생시킨 경로나 요청만이 아니라 현재 Host 전체를 허용합니다. 시스템 로그인도 아니므로 포털을 만들거나 다른 Host에 권한을 부여하지 않습니다. 설정하기 전에 서브도메인 고급 인증을 읽습니다.

접근 정책 및 local_exempt

현재 화면 설정	권한이 없는 인터넷 요청
로그인 필요 끄기(현재 로그인 우선 매핑)	업스트림으로 바로 이동
로그인 필요 켜기	유효한 출발지 IP 접근 권한이나 세션이 없으면 인증 Host로 이동
로그인 필요와 고급 인증 켜기	규칙과 일치하면 현재 Host의 임시 자격 증명을 발급하고, 일치하지 않으면 출발지 권한과 로그인을 계속 확인

백엔드는 기존 설정의 strict_whitelist 규칙과 계속 호환됩니다. 이 규칙은 로그인 필요를 꺼도 반드시 공개되는 것이 아니며 수동 또는 로그인 후 자동 생성된 유효 출발지 접근 권한 레코드를 기준으로 판단합니다. 브라우저 세션 쿠키만으로는 출발지 조건을 대신할 수 없습니다. 현재 Host 편집 화면에는 엄격한 허용 목록 규칙을 새로 만들거나 전환하는 컨트롤이 없습니다. 이 규칙을 사용하지 않으려면 전체 매핑을 기록한 뒤 현재 화면에서 다시 만듭니다. 새 매핑에서는 수동 출발지 접근 권한으로 독립적으로 허용할 수 있습니다. 자동 IP 접근 권한은 일반적으로 같은 출발지의 계속된 접근을 허용하지만 이미 적용된 서비스 범위 거부를 무시하지는 않습니다. IP 허용 목록은 엄격한 출발지 제한 스위치가 아닙니다. 요청이 매핑에 도달하기 전에 출발지 범위를 좁히려면 게이트웨이 접근 범위나 외부 네트워크 계층 규칙을 사용합니다.

로그인 자격 증명에서 접근 가능한 Host 범위를 제한할 수 있습니다. 하나의 자격 증명으로 로그인에 성공했다고 해서 모든 서비스 서브도메인에 자동으로 접근할 수 있는 것은 아닙니다.

인증 서비스는 게이트웨이가 식별한 출발지 IP를 먼저 판단합니다. 루프백, 사설망 및 링크 로컬 등의 출발지는 local_exempt를 반환하고 일반 로그인과 엄격한 허용 목록 검사를 건너뜁니다. 즉, LAN은 기본 신뢰 경계에 속합니다.

• 기존 엄격한 허용 목록 규칙도 LAN 출발지에 로그인을 강제하지 않습니다.
• 자격 증명의 Host 서비스 범위도 로컬 예외 출발지를 제한하는 데 사용되지 않습니다. 이는 네트워크 신뢰 경계이므로 자격 증명 범위를 검증하는 데 적합하지 않습니다.
• LAN 테스트만으로는 인터넷 정책이 적용되었다고 판단할 수 없습니다.
• 앞단에 FRP, Cloudflared, EdgeOne 또는 ESA를 두었다면 요청 로그에서 실제 공인 IP가 게이트웨이까지 전달되었는지 확인합니다. 프록시의 사설 주소를 방문자 출발지로 잘못 인식하면 접근 권한 결과가 달라집니다.

출발지 네트워크 설정은 IP 허용 목록과 게이트웨이 접근 범위를 참고합니다.

일괄 등록 및 유지 관리

서비스 검색은 허용된 로컬 IPv4 네트워크 대역을 스캔하고 후보 Host를 만듭니다. 스캔에는 최대 16개 CIDR과 전체 1024대의 호스트를 포함할 수 있습니다. 루프백, 네트워크 인터페이스, Docker 호스트, 기존 매핑 및 직접 저장한 로컬 범위만 스캔하며 인터넷을 탐색하지 않습니다.

스캔 창에서는 “기기 권장 설정 사용”(기본값) 또는 낮음, 중간, 높음, 매우 높음 강도를 선택할 수 있습니다. 단계는 동시 실행 수, 속도 및 기기 부하만 바꾸며 스캔 범위나 검색 결과는 바꾸지 않습니다. 기본값에서는 CPU, 사용 가능한 메모리 및 파일 디스크립터 한도를 바탕으로 비교적 안전한 단계를 선택합니다. NAS나 라우터처럼 자원이 부족한 기기에서는 자동 또는 낮음 강도를 우선 유지합니다.

스캔 포트, 허용 CIDR 범위, Docker 네트워크 관점 및 일괄 저장 규칙은 서비스 검색 및 일괄 등록을 참고합니다.

목록에서는 다음 작업을 사용할 수 있습니다.

• 아이콘 및 제목 새로 고침: 업스트림 메타데이터를 다시 가져옵니다.
• 만료된 서비스 정리: 먼저 HEAD, 실패하면 GET으로 HTTP / HTTPS 업스트림을 검사하고 관리자가 확인한 뒤 접근할 수 없는 매핑을 삭제합니다.
• 북마크로 내보내기: 인증 서비스를 제외한 서비스 Host를 내보냅니다.
• 모든 설정 지우기: 두 번 확인한 뒤 인증 서비스와 모든 Host 매핑을 삭제하고 루트 도메인 등의 모드 설정은 유지합니다.

Host별 트래픽 세부 정보에서 실시간 트래픽과 활성 IP를 확인하고 비정상 출발지를 일반 차단 목록에 추가할 수 있습니다.

Host 라우트 보완 기능

• 경로 응답은 특정 Host에 소수의 특수 경로만 추가하며 일치하지 않으면 해당 Host의 기본 대상(타깃)으로 돌아갑니다.
• 프로토콜 매핑은 공인 IP 직접 연결 서브도메인 모드에 TCP / UDP 포트를 추가하며 리버스 프록시 모드의 서브도메인 매핑에는 적용되지 않습니다.
• fnOS 공유 우회는 유효한 fnOS /s/... 공유 경로만 우회하며 사이트 전체를 공개하지 않습니다.

이러한 기능을 사용해도 Host가 웹의 기본 라우트라는 사실은 바뀌지 않습니다.

플랫폼별 지원 범위

• Host 라우트는 fnOS FPK, Docker, OpenWrt, Linux, Synology DSM 7 SPK 및 Windows에서 사용할 수 있습니다. 실제 인터넷 접근 가능 여부는 각 플랫폼의 포트 공개와 네트워크 경로에 달려 있습니다.
• 호스트 방화벽 자동 규칙 추가와 Smart Connect에는 호스트 관리 기능이 필요하며 Docker는 이러한 기능을 제공하지 않습니다.
• 프로토콜 매핑은 공인 IP 직접 연결 서브도메인 모드에서만 표시됩니다. Docker에서 추가 포트를 공개해도 fn-knock가 호스트 방화벽을 관리하지 않습니다.
• root 호스트 기능을 갖춘 OpenWrt에서는 방화벽을 관리할 수 있습니다. Smart Connect는 기존 dnsmasq와 /etc/dnsmasq.d/를 포함하는 설정에 의존하며 페이지의 apt-get 자동 설치는 사용할 수 없습니다. SSH 보안, 웹 터미널 또는 웹 관리 패널 FPK 업데이트도 제공하지 않습니다.
• fn-knock는 업스트림 서비스의 기존 공인 수신 포트를 자동으로 닫지 않으며 업스트림 업데이트, 백업 및 최소 권한 설정을 대신하지도 않습니다.

확인 및 문제 해결

요청 경로를 따라 다음 순서로 확인합니다.

1. DNS 또는 터널 공개 호스트 이름이 현재 Host를 올바른 게이트웨이 포트로 보내는지 확인합니다.
2. 요청 로그의 Host와 클라이언트 IP가 올바른지 확인합니다.
3. 인증 서비스가 존재하고 로그인 필요나 Basic Auth가 활성화되지 않았는지 확인합니다.
4. 서비스 매핑이 활성화되어 있고 현재 시각이 공개 시간 안에 있는지 확인합니다.
5. fn-knock 실행 환경에서 대상(타깃)에 접근할 수 있는지 확인합니다.
6. 로그인 자격 증명에서 현재 Host를 허용하는지 확인합니다. 고급 인증을 활성화했다면 규칙 그룹, 조건 및 임시 자격 증명 상태도 확인합니다.
7. 이전의 엄격한 허용 목록 규칙이 있다면 현재 인터넷 출발지가 허용되었는지 확인합니다.
8. HTTPS 인증서가 현재 Host를 포함하는지, 앞단 플랫폼에서 WebSocket을 허용하고 인증 응답을 캐시하지 않는지 확인합니다.

서비스 한두 개를 먼저 연결해 외부 네트워크 확인을 마친 뒤 일괄 검색과 접근 정책 강화를 진행합니다.