경로별 고정 응답

시스템 설정 → 게이트웨이 → 경로 응답에서는 서비스 Host에 소수의 경로별 규칙을 추가할 수 있습니다. Host 라우트를 사용하는 서브도메인 모드에서만 편집할 수 있으며 공인 IP로 직접 연결하는 서브도메인 모드와 리버스 프록시 모드 → 서브도메인 매핑이 여기에 해당합니다. 경로 모드와 직접 연결 모드에는 이 항목이 없습니다. Host가 계속 기본 라우트 역할을 하므로 경로 규칙과 일치하지 않는 요청은 해당 Host 매핑의 기본 대상(타깃)으로 전달됩니다.

상태 확인, 고정 상태 응답 또는 같은 Host의 일부 API만 다른 업스트림으로 전달할 때 적합합니다. 많은 경로로 여러 애플리케이션을 구성해야 한다면 호환용 경로 매핑을 사용합니다. Host 라우트 위에 별도의 경로 게이트웨이를 다시 만들지 않는 것이 좋습니다.

일치 순서

api.example.com/healthz -> 고정 응답 200 ok
api.example.com/v2/*    -> http://127.0.0.1:8080
api.example.com/기타경로 -> Host 기본 대상(타깃)

먼저 기존 서비스 Host를 선택합니다. 인증 서비스 Host는 선택 목록에 표시되지 않습니다.

경로는 /로 시작해야 하지만 루트 경로 / 자체는 사용할 수 없습니다. 다음 경로는 인증, 공유 또는 내부 기능을 위해 예약되어 있으므로 설정할 수 없습니다.

• /__로 시작하는 경로
• /s
• /s/

Host 하나에는 같은 일치 방식과 같은 경로의 규칙을 하나만 만들 수 있습니다.

규칙 필드

필드	값	동작
일치 방식	정확히 일치 / 접두사 일치	전체 경로만 일치시키거나 해당 접두사와 하위 경로를 함께 일치
동작	리버스 프록시 / 고정 응답	다른 업스트림으로 전달하거나 게이트웨이가 직접 응답
대상 주소	HTTP / HTTPS URL	리버스 프록시 동작에만 사용
일치한 경로 제거	켜기 / 끄기	/api/users를 /users로 전달하거나 원래 경로 유지
HTML 경로 다시 쓰기	켜기 / 끄기	페이지 리소스에 경로 접두사를 추가. 일반 API에는 대개 불필요

고정 응답에는 100부터 599까지의 상태 코드, Content-Type, 본문 및 사용자 지정 응답 헤더를 설정할 수 있습니다. Connection, Content-Length, Content-Type, Transfer-Encoding, Upgrade 같은 전송 수준 헤더는 사용자 지정 헤더에서 덮어쓸 수 없습니다. 콘텐츠 유형은 전용 필드에서 설정합니다.

Host 접근 정책 상속

경로 응답은 현재 Host의 로그인 필요와 기존의 엄격한 허용 목록 규칙을 상속합니다. 접근 제어를 우회하는 엔드포인트가 아닙니다.

리버스 프록시 동작은 Host의 Basic Auth 건너뛰기 자격 증명을 실제 대상(타깃)으로 보내는 요청에 삽입하여 대상 서비스 자체의 Basic Auth를 통과합니다. fn-knock 방문자 로그인용 자격 증명은 아닙니다. 프록시 헤더와 Host 유지 여부는 이 실제 대상(타깃)이 공유하는 런타임 규칙에 따라 결정되므로 Host의 기본 대상(타깃) 설정과 다를 수 있습니다. 고정 응답에는 업스트림이 없으므로 Basic Auth, 프록시 헤더 또는 Host 유지 관련 요청 헤더를 보내지 않습니다.

출발지가 루프백, 사설망 또는 링크 로컬 주소라면 인증 서비스가 local_exempt를 반환합니다. 따라서 LAN에서는 로그인이나 엄격한 허용 목록 거부가 적용되지 않을 수 있습니다. 인터넷 정책은 실제 외부 네트워크에서 검증합니다.

예시

상태 확인:

경로       /healthz
일치       정확히
동작       고정 응답
상태 코드  200
Content-Type text/plain; charset=utf-8
본문       ok

API를 별도 오리진으로 전달:

경로       /api
일치       접두사
동작       리버스 프록시
대상       http://127.0.0.1:8080
경로 제거  켜기

플랫폼별 제한

경로 응답은 fnOS FPK, Docker, OpenWrt, Linux, Synology DSM 7 SPK 및 Windows의 Host 라우트 서브도메인 모드에서 사용할 수 있으며 리버스 프록시 모드 → 서브도메인 매핑도 포함됩니다. 방화벽 포트, DNS 레코드 또는 Docker 포트를 공개하지 않으며 접속할 수 없는 대상(타깃)을 접속 가능한 상태로 바꾸지도 않습니다.

문제 해결

1. 현재 Host 라우트를 사용하고 있고 올바른 서비스 Host를 선택했는지 확인합니다.
2. 경로 형식, 예약 경로 및 정확히 일치 / 접두사 일치 방식을 확인합니다.
3. 먼저 요청이 Host의 로그인 또는 허용 목록 정책에 차단되었는지 확인합니다.
4. fn-knock 실행 환경에서 리버스 프록시 대상(타깃)에 접속합니다.
5. 요청 로그에서 Host, 경로, 라우트 유형, 상태 코드 및 업스트림 대상(타깃)을 확인합니다.

Host 기본 라우트는 서브도메인 매핑, 관련 전역 옵션은 시스템 설정을 참고합니다.