웹 서비스

도메인별 리버스 프록시, 리다이렉트, 정적 파일, 고정 텍스트를 제공하는 Gately의 통합 웹 진입점입니다. 메뉴 위치: 사이드바 「웹 → 웹 서비스」.

구조: 리스너, 사이트, 기본 사이트

설정은 세 계층입니다.

1. 리스너: 수신 포트 하나. 네트워크(tcp 듀얼 스택, tcp4, tcp6), 수신 주소(비우면 모든 주소), 포트, HTTPS 스위치, 최소 TLS 버전(1.0 / 1.1 / 1.2 / 1.3), PROXY 프로토콜 수신 여부 필드가 있습니다.
2. 사이트: 리스너 아래에서 도메인으로 매칭되는 사이트. 도메인은 정확한 도메인, *.example.com(모든 단계의 서브도메인과 일치), *(모두 일치)를 지원하며 매칭 우선순위는 정확한 도메인, 와일드카드, * 순입니다.
3. 기본 사이트: 일치하는 사이트가 없을 때 사용되며 사용하지 않으면 404를 반환합니다.

사이트나 기본 사이트의 변경을 저장하면 사이트 목록이 그 자리에서 교체됩니다. 리스너는 계속 실행되고, 열려 있는 연결(WebSocket 포함)은 유지되며, 각 사이트의 통계도 그대로 이어집니다. 새 설정이 올바르지 않으면 이전 사이트가 계속 서비스됩니다. 리스너 자체의 설정(네트워크, 주소, 포트, HTTPS, 최소 TLS, HTTP/3, PROXY 프로토콜)을 바꾸면 해당 리스너가 재시작됩니다.

사이트 유형

유형	설명
리버스 프록시	하나 이상의 백엔드로 전달합니다. 백엔드 주소 형식은 http(s)://호스트:포트이며 WebSocket을 지원합니다
리다이렉트	전체 URL로 이동합니다. 상태 코드는 301 / 302 / 307 / 308(기본 302)이며 원래 경로와 쿼리 문자열을 유지할 수 있습니다. URL에 {host}를 넣으면 방문자가 사용한 도메인으로 바뀝니다. https://{host}에 「경로와 매개변수 유지」를 함께 쓰면 모든 HTTP 요청을 같은 도메인의 HTTPS로 보냅니다
정적 파일	디렉터리는 절대 경로여야 합니다. 「디렉터리 목록」을 끄면 index.html이 있을 때만 디렉터리 요청에 응답합니다. 「확장자 없는 URL」은 파일이 없을 때 경로.html과 경로/index.html을 시도합니다(VitePress 같은 생성기용이며 nginx의 try_files $uri $uri.html $uri/index.html과 같음). 「404 페이지」는 디렉터리 안의 경로(예: 404.html)이며 상태 코드 404로 반환됩니다
고정 텍스트	사용자 지정 내용, Content-Type(기본 text/plain; charset=utf-8), 상태 코드(100-599, 기본 200)

리버스 프록시 사이트의 다른 옵션은 다음과 같습니다.

• 백엔드 Host 사용: Host 헤더를 백엔드 주소로 바꿉니다. 끄면 클라이언트가 요청한 Host를 유지합니다.
• 백엔드 인증서 검증 건너뛰기, Keep-Alive 끄기
• 백엔드로 PROXY 프로토콜 전송(v2 헤더, 실제 클라이언트 IP 전달, 백엔드 지원 필요)
• X-Forwarded-For / X-Forwarded-Proto / X-Forwarded-Host / X-Forwarded-Port와 X-Real-IP 추가
• 접속 도메인을 SNI로 사용(HTTPS 백엔드 전용): 핸드셰이크에 방문자가 사용한 도메인을 보내고 인증서도 그 도메인으로 검증합니다. nginx의 proxy_ssl_server_name on; proxy_ssl_name $host와 같습니다. 백엔드가 SNI로 라우팅할 때(예: frp의 vhost_https) 켜세요. 백엔드마다 자체 연결 풀을 가지므로 도메인 간에 연결이 재사용되지 않습니다.

모든 유형의 사이트에 접근 로그, 교차 출처(CORS), 사용자 지정 요청 헤더와 응답 헤더(한 줄에 Key: Value, Value를 비우면 해당 헤더 삭제)를 설정할 수 있으며 WAF 방화벽 인스턴스 하나를 참조할 수 있습니다(인스턴스가 없거나 비활성화되어 있으면 통과).

전송 및 프로토콜

• HTTPS: SSL 인증서 모듈에서 해당 도메인을 포함하는 인증서를 사용합니다.
• HTTP/3(QUIC): HTTPS를 켠 리스너에서 활성화하면 같은 포트 번호의 UDP로 HTTP/3도 제공하고 Alt-Svc 응답 헤더로 브라우저에 알립니다. 방화벽과 포트 포워딩에서 해당 UDP 포트를 허용해야 합니다.
• WebSocket: 리버스 프록시에서 자동으로 지원합니다.
• PROXY 프로토콜: 리스너가 업스트림(haproxy, frp 등)이 보낸 PROXY 헤더를 받을 수 있으며 「전역 설정 → 신뢰할 PROXY 출처」에 나열된 IP 또는 대역만 신뢰합니다. 비워 두면 어떤 출처도 신뢰하지 않습니다. 리버스 프록시는 백엔드로 PROXY 헤더를 보낼 수 있습니다.

인증

사이트 편집 창의 「보안」 탭에서 설정합니다.

• 웹 인증: 브라우저에 로그인 페이지를 표시합니다.
• 기본 인증: HTTP Basic
• 사용자: 한 줄에 사용자 이름:비밀번호. 비밀번호에는 bcrypt 해시를 쓸 수 있습니다. 기본 인증을 켜면 사용자가 최소 한 명 필요하고, 웹 인증을 켜면 사용자나 서드파티 로그인 ID가 최소 하나 필요합니다.
• 서드파티 로그인: GitHub, Google, QQ, OIDC를 지원하며 직접 만든 OAuth 앱을 사용합니다. 허용할 ID는 한 줄에 하나씩 제공자 식별자:계정 형식으로 쓰며 예를 들어 github:octocat, google:me@gmail.com처럼 입력합니다. 줄 끝에 #을 붙여 메모를 남길 수 있고 github:*는 해당 제공자의 모든 계정을 뜻합니다.

서드파티 로그인 제공자는 「전역 설정」에서 구성합니다. 직접 발급한 Client ID / Secret을 입력해 활성화하고, 콜백 주소(Gately의 어떤 리스너가 제공해야 하며 예: https://auth.example.com)도 설정합니다. GitHub / Google / QQ에 등록할 콜백 URL은 다음과 같습니다.

https://auth.example.com/__gately_auth/oauth/callback

관리 콘솔 자체의 서드파티 로그인은 「설정 → 계정 및 보안」에서 따로 설정합니다.

포워드 인증(Authelia 등)

인증을 외부 서비스에 맡깁니다. nginx의 auth_request나 Traefik의 forwardAuth와 같은 방식입니다. 「보안」 탭에서 「포워드 인증」을 체크합니다. 같은 사이트에서 기본 인증이나 웹 인증과 함께 쓸 수 없습니다.

필드	설명
url	확인용 엔드포인트. 예: Authelia의 http://127.0.0.1:9091/api/authz/auth-request
loginUrl	엔드포인트가 401을 반환할 때 방문자를 보낼 주소. 예: https://auth.example.com/?rd={url}&rm={method}. {url}은 원래 주소(URL 인코딩됨), {method}는 요청 메서드입니다. 비우면 엔드포인트의 응답을 그대로 반환합니다
copyHeaders	엔드포인트 응답에서 백엔드 요청으로 복사할 신원 헤더. 기본값은 Remote-User, Remote-Groups, Remote-Email, Remote-Name

동작 방식은 다음과 같습니다.

• 모든 요청은 먼저 url로 본문 없는 GET으로 전송됩니다. 방문자의 헤더(쿠키, Authorization 등)에 더해 X-Original-Method, X-Original-URL, X-Forwarded-Method, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Uri, X-Forwarded-For, X-Real-Ip가 붙습니다. 타임아웃은 10초입니다.
• 2xx 응답이면 요청을 통과시키고 신원 헤더를 추가합니다. 401은 loginUrl로 리다이렉트합니다(상태 코드 302). 403이나 리다이렉트 같은 다른 응답은 방문자에게 그대로 반환하며, 서비스에 연결할 수 없으면 502가 됩니다.
• 방문자가 보낸 신원 헤더는 항상 제거되므로 위조할 수 없습니다.
• 경로 규칙과 「인증 범위」를 지원하므로 일부 경로(예: /admin)에서만 로그인을 요구할 수 있으며, 임시 공유 링크와도 함께 쓸 수 있습니다.

공유 사용자: TOTP와 통합 로그인

계정을 한 번 정의해 여러 사이트에서 쓰며, TOTP 2단계 인증을 선택적으로 추가할 수 있습니다. 많은 사람이 Authelia를 쓰는 목적을 이것으로 해결할 수 있습니다.

「전역 설정 → 공유 사용자」에서 다음을 설정합니다.

• 사용자를 추가하려면 사용자 이름과 비밀번호를 입력합니다. 비밀번호는 bcrypt 해시로 저장되며 API가 반환하지 않습니다. TOTP를 추가하려면 「TOTP 사용」을 누르고 인증 앱(Google Authenticator, 1Password 등)으로 QR 코드를 스캔한 뒤 저장합니다. 키를 다시 생성하면 이전 키는 무효가 됩니다.
• 통합 로그인(SSO) 도메인(예: example.com): 이 도메인이나 하위 도메인의 사이트 중 하나에서 로그인하면 그곳의 다른 사이트에서는 다시 로그인할 필요가 없습니다. 상위 도메인 쿠키(gately_sso, 유효 기간 7일)를 사용하며 이 쿠키는 백엔드로 전달되지 않습니다. 비우면 사이트마다 따로 로그인합니다.

사이트에서 웹 인증이나 기본 인증 옆의 「공유 사용자 사용」을 체크합니다. 사이트 자체 사용자도 계속 사용할 수 있습니다.

동작은 다음과 같습니다.

• 공유 사용자 중 TOTP를 쓰는 사용자가 있으면 로그인 페이지에 인증 코드 입력란이 표시됩니다. 각 코드는 한 번만 사용할 수 있습니다.
• 사용자의 비밀번호나 TOTP 키를 바꾸면 해당 사용자의 세션이 종료됩니다.
• 기본 인증에서는 TOTP가 없는 공유 사용자만 사용할 수 있습니다. 브라우저의 비밀번호 입력창에는 코드를 입력할 곳이 없기 때문입니다.
• 실패한 시도는 다른 로그인과 같은 속도 제한과 자동 차단에 집계됩니다.

접근 제어

IP 허용·차단 목록

사이트 「보안」 탭의 「IP 접근 제어」에서 끄기, 허용 목록, 차단 목록 중에서 선택하며 목록에는 한 줄에 IP 또는 대역(예: 192.168.1.0/24)을 하나씩 씁니다. 구독 IP 목록도 함께 참조할 수 있습니다.

구독 IP 목록

「전역 설정 → 구독 IP 목록」에서 목록을 추가합니다. 다운로드 URL과 새로고침 간격(기본 24시간)을 입력하면 Gately가 주기적으로 내려받아 설정 디렉터리에 캐시하므로, 재시작한 뒤에도 네트워크 없이 사용할 수 있습니다. 내용은 한 줄에 IP, CIDR 또는 시작-끝 범위 하나이며, #, ;, // 뒤는 주석입니다. 예를 들어 중국 성·시 IP 대역은 metowolf/iplist의 https://metowolf.github.io/iplist/data/cncity/440000.txt(광둥성)를 쓸 수 있습니다.

• 사이트와 경로 규칙의 허용 목록, 차단 목록은 여러 목록을 참조할 수 있으며, 직접 입력한 IP 대역과 함께 판단해 하나라도 일치하면 목록에 있는 것으로 봅니다.
• 내려받은 내용을 해석할 수 없으면(예: 오류 페이지가 반환된 경우) 이전 목록을 유지하고 목록에 원인을 표시하며, 1시간 후 다시 시도합니다.
• 목록을 처음 내려받기 전에는 빈 목록으로 처리합니다. 따라서 허용 목록은 접근을 거부하고, 차단 목록은 추가로 차단하는 것이 없습니다.
• 사이트에서 참조 중인 목록은 삭제할 수 없습니다.

경로 규칙

「보안」 탭의 「경로 규칙」에서 경로 접두사별로 사이트의 인증과 IP 설정을 덮어씁니다.

필드	값
prefix	/로 시작하는 경로 접두사. 예: /admin
auth	사이트 설정 따름(비움), off(인증 불필요), on(인증 필수)
ipMode / ipList	사이트 설정 따름(비움), whitelist, blacklist, 그리고 IP 또는 대역 목록

매칭 규칙은 다음과 같습니다.

• 가장 긴 접두사가 우선합니다.
• 경로 세그먼트 경계로 매칭하므로 /admin은 /admin과 /admin/x에 일치하고 /administrator에는 일치하지 않습니다.
• 요청 경로를 먼저 정규화(., .., 중복 슬래시 제거)한 뒤 매칭하므로 /public/../admin은 /admin으로 처리됩니다.
• 같은 접두사에는 규칙을 하나만 설정할 수 있습니다.

「인증 범위」 옵션(authOptional): 체크하면 인증이 규칙에서 「인증 필수」로 표시된 경로에만 적용되고 나머지 경로는 공개됩니다. 이 옵션을 쓰려면 먼저 기본 인증이나 웹 인증을 켜야 합니다.

임시 공유 링크

기본 인증이나 웹 인증을 켜면 사이트에 공유 링크를 만들어 방문자가 계정 없이 접근하게 할 수 있습니다.

필드	설명
이름	메모용 이름. 예: 「홍길동에게」
만료 시간	비우면 만료되지 않습니다
사용 횟수 maxUses	교환할 수 있는 최대 횟수이며 0은 무제한입니다. 재시작하면 카운트가 초기화됩니다
경로 제한 pathPrefix	비어 있지 않으면 링크로 해당 접두사 아래 경로만 접근할 수 있으며 /로 시작해야 합니다

방문자가 https://도메인/임의경로?_gs=토큰에 접속하면 세션으로 교환됩니다. 교환에 성공하면 서버가 로그인 불필요 쿠키를 설정하고 _gs 매개변수를 제거한 주소로 이동시키며, 세션은 최대 24시간이고 링크의 만료 시간을 넘지 않습니다. 토큰이 유효하지 않으면 일반 접근으로 처리하며 실패 이유를 알려 주지 않습니다. 링크를 삭제하면 이미 발급된 세션도 즉시 무효가 됩니다. 토큰은 저장한 뒤에 생성되며(16자 이상) UI에서 전체 링크를 복사할 수 있습니다.

인증 실패 제한과 자동 차단

• 같은 출처 IP가 15분 안에 인증에 10번 실패하면 한동안 더 이상의 시도를 거부합니다.
• 「전역 설정 → 자동 차단 → 인증 실패 차단」에 분 단위 값(0~43200)을 입력하면 10번 실패한 출처 IP를 그 시간 동안 차단합니다. 0이면 차단하지 않고 제한만 합니다.
• 자동 차단이 발동하면 AuthBanned 이벤트가 발행되며 알림 센터로 푸시할 수 있습니다.
• IPv6 주소는 /64 대역 단위로 집계하고 차단합니다.

차단 목록

「전역 설정」의 차단 목록에는 현재 차단된 IP, 사유(인증 연속 실패 또는 수동 차단), 만료 시간이 표시되며 「해제」를 누를 수 있습니다. 수동으로 차단할 수도 있습니다. IP와 시간(1~720시간, 최대 30일)을 입력하며 API의 기본 기간은 24시간입니다.

차단 목록은 침입 방지와 공유됩니다. 침입 방지 모듈이 켜져 있으면 여기에는 차단 수만 표시되고 침입 방지 페이지에서 관리합니다. 차단은 포트 포워딩, STUN 등에도 적용되며, 방화벽 동기화를 켜면 시스템 방화벽에서 삭제됩니다. "LAN 주소 무시"를 켜면 LAN 주소는 자동으로 차단되지 않습니다.

GeoIP 국가 필터

사이트 「국가 필터」에는 끄기, 허용만, 거부의 세 가지 모드가 있으며 두 글자 ISO 국가 코드를 쉼표로 구분해 입력합니다(예: CN, HK, US). 사용하려면 국가를 하나 이상 입력해야 합니다.

• 필터링은 GeoIP 데이터베이스가 필요하므로 먼저 「전역 설정 → GeoIP 데이터베이스」에서 가져와야 합니다. .mmdb 파일을 업로드하거나 다운로드 주소를 입력합니다. MaxMind GeoLite2, DB-IP 등의 국가 DB나 도시 DB를 지원하며 업로드 제한은 129 MB입니다.
• 데이터베이스가 로드되지 않았으면 필터가 동작하지 않고(모든 방문자 통과) UI에 안내가 표시됩니다.
• 내부망 주소는 항상 통과합니다.
• 「거부」 모드에서 DB에서 국가를 찾을 수 없는 주소는 통과합니다.

경로별 백엔드

리버스 프록시 사이트에서 경로 접두사별로 다른 백엔드로 요청을 보냅니다. nginx의 location /api/ { proxy_pass ...; }와 같습니다. 사이트 편집 창 「기본」 탭의 「경로별 백엔드」에서 추가합니다.

필드	설명
prefix	/api/ 같은 경로 접두사. 경로 세그먼트 경계로 매칭하므로 /api와 /api/ 모두 /api와 /api/x에 일치하고 /apix에는 일치하지 않습니다
targets	이 경로의 백엔드이며 사이트의 백엔드와 같은 방식으로 씁니다. 비우면 사이트의 백엔드를 사용하고 아래 헤더만 추가합니다
requestHeaders	이 경로에 추가할 요청 헤더. 한 줄에 Key: Value 하나씩. 사이트 헤더 뒤에 적용되며 이름이 같은 헤더는 사이트의 값을 덮어씁니다

• 가장 긴 접두사가 우선하며 경로는 그대로 전달됩니다(접두사를 제거하지 않음).
• Host 옵션, 인증서 검증, 전달 헤더, PROXY 프로토콜, 로드 밸런싱 정책, 헬스 체크 등 사이트의 다른 설정은 모든 경로별 백엔드에 적용됩니다.
• 압축, 속도 제한, 캐시, 재작성은 사이트 전체에 적용됩니다.

리버스 프록시 고급 기능

이 옵션들은 사이트 편집 창의 「트래픽」 탭에 있습니다.

백엔드, 가중치, 예비

백엔드 목록은 한 줄에 주소 하나이며 주소 뒤에 매개변수를 붙일 수 있습니다.

http://10.0.0.2:8080 weight=3
http://10.0.0.3:8080 backup

• weight=N: 가중치, 1~100 정수, 기본값 1
• backup: 예비 백엔드로, 예비가 아닌 백엔드가 모두 사용 불가일 때만 활성화됩니다. 모든 백엔드가 사용 불가이면 예비가 아닌 백엔드 전체로 되돌아가 계속 시도합니다.

로드 밸런싱 정책

UI 옵션	lbPolicy	설명
라운드 로빈 (가중치 적용)	비움	기본값
랜덤 (가중치 적용)	random
IP 해시 (세션 유지)	ip_hash	같은 클라이언트 IP가 같은 백엔드로 갑니다
최소 연결	least_conn	「연결 수 / 가중치」가 가장 작은 백엔드를 선택합니다

헬스 체크

액티브 체크 스위치는 기본적으로 꺼져 있습니다. 켰을 때의 필드와 기본값은 다음과 같습니다.

필드	기본값	범위
방식 mode	http	http(체크 경로를 요청하고 상태 코드가 400 미만이면 정상으로 판단) 또는 tcp(연결만 테스트)
경로 path	/	/로 시작, http 방식에서만 사용
간격 interval	10초	1~3600
타임아웃 timeout	3초	1~60
연속 실패 fails	3회 연속이면 사용 불가	1~20
연속 성공 passes	2회 연속이면 복구	1~20

백엔드로 PROXY 프로토콜을 보내도록 설정하면 HTTP 체크는 자동으로 TCP로 바뀝니다.

패시브 체크는 항상 동작합니다. 백엔드가 여러 개일 때 연속 3번 연결에 실패한 백엔드는 30초간 중단한 뒤 다시 시도합니다(백엔드가 하나뿐이고 액티브 체크도 꺼져 있으면 제외하지 않습니다). 액티브 체크를 켜면 복구는 전적으로 체크 결과에 따라 결정됩니다. 백엔드 상태가 바뀌면 업스트림 사용 불가 / 복구 이벤트가 발행되며 알림 센터로 푸시할 수 있습니다.

압축

리버스 프록시, 정적 파일, 고정 텍스트 사이트에서 압축을 켤 수 있습니다(리다이렉트 사이트 제외). Accept-Encoding에 따라 br을 우선하고 그다음 gzip을 선택합니다.

• 텍스트 계열 콘텐츠만 압축합니다: text/*, JSON, JavaScript, XML, XHTML, RSS / Atom, WebAssembly, SVG. text/event-stream은 제외됩니다.
• 선언된 Content-Length가 256바이트 미만인 응답은 그대로 둡니다.
• 이미 Content-Encoding이 있는 응답은 그대로 두며 WebSocket 업그레이드 요청은 바로 통과시킵니다.
• 압축 후에는 강한 ETag가 약한 ETag로 바뀝니다.

IP별 속도 제한

클라이언트 IP별 토큰 버킷 방식의 속도 제한이며 필드는 다음과 같습니다.

필드	설명
rate	초당 허용하는 요청 수
burst	버스트 용량. rate를 설정하고 burst가 0이면 자동으로 rate를 정수로 내린 값에 1을 더한 값을 사용합니다
maxConns	IP 하나당 동시 요청 상한이며 0은 무제한입니다

속도 제한을 켤 때는 rate와 maxConns 중 최소 하나를 설정해야 합니다.

메모리 응답 캐시

리버스 프록시 사이트에서만 동작하며 캐시는 메모리에 저장되고 LRU 방식으로 제거됩니다.

필드	기본값	범위
ttl 기본 시간	0	0~30일(초 단위). 업스트림이 캐시 지시자를 선언하지 않았을 때 200 응답을 이 시간 동안 캐시합니다. 0이면 업스트림이 명시적으로 허용한 응답만 캐시합니다
maxMb 캐시 용량	64	1~4096 MB

캐시 규칙은 다음과 같습니다.

• GET 요청만 캐시하며 요청에 Authorization, Cookie, Range 헤더나 Cache-Control: no-cache가 없어야 합니다.
• 상태 코드 200 응답만 캐시합니다. 응답에 Set-Cookie, Vary: *가 있거나 Cache-Control이 no-store / private / no-cache이면 건너뜁니다.
• s-maxage를 따르고 그다음 max-age를 따릅니다.
• 항목 하나의 상한은 4 MB이며 전체 용량의 4분의 1을 넘지 않습니다.
• 캐시 적중 시 X-Cache: HIT와 Age 헤더를 반환하고 미적중이면 X-Cache: MISS입니다.
• 캐시 키에는 Host, 전체 요청 URI, Accept-Encoding이 포함됩니다.

경로 재작성과 리다이렉트

규칙은 순서대로 매칭하며 첫 번째로 일치하는 규칙에서 멈춥니다.

필드	설명
pattern	요청 경로와 매칭할 정규식. 예: ^/old/(.*)$
to	치환 결과이며 $1로 그룹을 참조할 수 있습니다
redirect	끄면 내부 재작성(재작성된 경로가 백엔드로 전송되며 대상은 /로 시작해야 함), 켜면 리다이렉트
code	리다이렉트 상태 코드 301 / 302 / 307 / 308, 기본 302

리다이렉트는 원래 쿼리 매개변수를 유지합니다. 리다이렉트 대상에는 방문자가 사용한 도메인을 뜻하는 {host}를 넣을 수 있습니다. 리다이렉트 규칙은 인증보다 먼저 실행되므로(nginx의 location = / { return 302 ...; }와 같음) / 같은 경로는 로그인을 요구하지 않고 방문자를 다른 곳으로 보낼 수 있습니다.

접속 통계 및 모니터링

사이트 통계

실행 중인 리스너에서 사이트 행의 「통계」를 누르면 통계 창이 열리며 최근 1시간, 6시간, 24시간 중에서 선택할 수 있습니다.

• 분 단위 접속 통계: 1분에 점 하나, 최근 24시간 보관, 요청 수 곡선과 4xx / 5xx 오류 곡선 포함
• 상태 코드 분포 2xx / 3xx / 4xx / 5xx, 누적 응답 트래픽
• 출처 IP 상위 10개와 국가 상위 10개(국가 통계에는 GeoIP 데이터베이스를 가져와 두어야 함)
• 리버스 프록시 사이트는 백엔드별 상태, 가중치, 예비 여부, 현재 연결 수를 표시

통계는 메모리에 저장되며 재시작하거나 리스너 자체의 설정을 바꾸면 다시 집계합니다. 사이트를 수정해도 카운터는 유지됩니다. 순위표는 서로 다른 출처를 최대 5000개까지 집계합니다.

Prometheus 메트릭

전역 메트릭 엔드포인트 GET /api/metrics는 모든 모듈의 메트릭을 모아 제공합니다. 모니터링 메트릭을 참고하세요. 아래 모듈 엔드포인트에는 웹 서비스 메트릭만 포함됩니다.

메트릭 엔드포인트는 GET /api/webservice/metrics이며 Prometheus 텍스트 형식입니다. 로그인 자격 증명이나 API 토큰이 필요합니다.

curl -H "Authorization: Bearer gtl_xxxx" http://localhost:16680/api/webservice/metrics

메트릭	유형	설명
gately_site_requests_total	counter	사이트 누적 요청 수
gately_site_errors_total	counter	사이트 백엔드 오류 수
gately_site_active_requests	gauge	진행 중인 요청 수
gately_site_response_bytes_total	counter	누적 응답 바이트 수
gately_site_responses_total	counter	상태 클래스(레이블 class: 2xx~5xx)별 응답 수
gately_upstream_up	gauge	백엔드 정상 여부, 1은 정상, 0은 사용 불가(레이블 upstream 포함)

모든 메트릭에는 레이블 listener(리스너 이름#리스너 key)와 site(사이트 이름, 이름이 없으면 첫 번째 도메인)가 붙습니다.

nginx 설정 가져오기

페이지 상단의 「nginx 가져오기」로 기존 nginx 사이트를 Gately의 리스너와 사이트로 변환할 수 있습니다. nginx가 있는 호스트에서 nginx -T를 실행하고 전체 출력을 붙여넣는 방식을 권장합니다. 출력에는 include된 모든 파일이 들어 있으며, Gately는 nginx와 같은 방식으로 include를 펼칩니다.

• 먼저 미리 봅니다. 수신 포트별로 묶어 각 사이트의 유형, 백엔드 또는 디렉터리, 원본 파일과 줄 번호, 주의할 점(변수를 쓰는 지시어, 정규식 location, 인증서가 없는 도메인 등)을 보여 주며, 변환할 수 없는 사이트는 그 이유를 알려 줍니다.
• 포트가 같은 사이트는 기존 리스너에 병합하고, 그 밖에는 새 리스너를 만듭니다. 이미 있는 도메인은 건너뛰므로 여러 번 가져와도 됩니다.
• 기본적으로 비활성 상태로 가져오므로 nginx와 병행하면서 하나씩 확인한 뒤 활성화할 수 있습니다. 「가져온 후 바로 활성화」를 체크하면 즉시 적용됩니다(nginx가 같은 포트를 쓰고 있으면 새 리스너는 시작되지 않습니다).
• 변환되는 내용: proxy_pass(upstream의 가중치, 예비, 로드 밸런싱 정책 포함), root / alias 정적 디렉터리(autoindex, try_files $uri.html, error_page 404), return 리다이렉트와 고정 내용, 사이트 전체 rewrite 리다이렉트, add_header, proxy_set_header, gzip, allow / deny, location 단위의 경로별 백엔드·접근 제어·리다이렉트, listen ... proxy_protocol과 quic.
• auth_request는 포워드 인증으로 변환됩니다. 인증 엔드포인트는 인증 하위 요청 location의 proxy_pass에서 가져오고(set 변수 지원), 로그인 리디렉션은 error_page 401 =302에서 가져오므로 Authelia의 일반적인 설정은 그대로 변환됩니다. 일부 location에서만 쓰는 경우에는 「인증 범위」에서 지정한 경로만 인증하도록 변환합니다.
• auth_basic은 공유 사용자를 쓰는 기본 인증으로 변환됩니다. nginx의 사용자 파일은 읽지 않으므로 사용자를 추가하기 전에는 아무도 통과할 수 없습니다.
• stream의 TCP/UDP 전달은 포트 포워딩에서 설정하세요. 인증서는 가져오지 않습니다. HTTPS 사이트에 인증서가 없으면 미리 보기에서 nginx가 쓰는 인증서 파일을 보여 주므로 인증서 페이지에서 파일 경로로 추가할 수 있습니다.

haproxy와 nginx 대체

포트 포워딩과 웹 서비스를 함께 쓰면 haproxy + nginx 조합을 대체할 수 있습니다. 흔한 구성은 443 포트에 SNI 라우팅 규칙을 하나 두어 VPN 같은 TLS 서비스는 곧바로 백엔드로, 나머지는 모두 PROXY 프로토콜을 받는 웹 서비스 리스너로 보내는 것입니다. 여기에 80 포트에 리다이렉트 사이트(https://{host})를 둔 웹 서비스 리스너를 추가합니다.

nginx 설정을 옮기는 방법은 다음과 같습니다.

nginx	Gately
server_name이 있는 server	해당 도메인을 지정한 사이트
proxy_pass가 다른 location	경로별 백엔드
auth_request(Authelia)	포워드 인증, 또는 TOTP를 쓰는 공유 사용자
proxy_ssl_name $host	접속 도메인을 SNI로 사용
return 301 https://$host$request_uri	https://{host}와 「경로와 매개변수 유지」를 지정한 리다이렉트 사이트
location = /의 return 302 /admin	「리디렉션」을 켠 재작성, 패턴 ^/$
try_files $uri $uri.html $uri/index.html과 error_page 404	확장자 없는 URL과 404 페이지를 설정한 정적 파일
add_header	응답 헤더

배포 팁

웹 서비스는 호스트의 80 / 443 등의 포트를 수신해야 하므로 Docker 배포에서는 --network host를 권장합니다.