Next.js 방문 로그 (Referer, Reverse Proxy, document.referrer)

방문자 로그에 Referer를 추가하는 작업은 DB에 컬럼 하나 더 넣는 수준이라고 생각했습니다. 그런데 실제로 배포하고 나니 자기 사이트 주소가 계속 찍혔습니다. Synology Reverse Proxy를 의심했다가, Nginx 설정을 뒤졌다가, 결국 원인은 전혀 다른 곳에 있었습니다. 그 과정을 풀어봅니다.

Referer가 계속 자기 사이트로 찍히던 이유

저도 처음엔 Reverse Proxy(리버스 프록시)가 문제라고 확신했습니다. 리버스 프록시란 클라이언트와 실제 서버 사이에서 요청을 중계하는 서버를 말합니다. 저는 Synology NAS 위에서 Next.js를 돌리고 있었고, 앞단에 Synology가 제공하는 Nginx 기반 리버스 프록시가 있었습니다. 구조를 단순하게 표현하면 ‘브라우저 → Synology Nginx → Next.js → Prisma → MySQL’입니다.

문제를 확인하기 위해 Next.js Route Handler에서 모든 Request Header를 출력해봤습니다. 실제 서버에서 찍힌 결과를 보니 referer 값이 외부 사이트가 아니라 제 사이트 주소로 들어오고 있었습니다. 브라우저 개발자 도구의 Network 탭에서는 분명히 외부 사이트가 Referer로 보이는데, 서버에서는 달랐습니다.

그런데 헤더 전체를 확인하다 보니 중요한 단서를 발견했습니다. x-forwarded-for나 x-real-ip 값은 실제 방문자 IP로 정상적으로 들어오고 있었습니다. 즉, 리버스 프록시가 다른 헤더를 훼손하고 있다는 증거는 없었습니다. Referer 헤더 자체가 이미 제 사이트 주소로 들어오고 있었던 겁니다.

여기서 핵심이 있습니다. 제가 방문 로그를 저장하는 방식은 페이지가 로드된 뒤 JavaScript가 POST /api/visitor 엔드포인트를 호출하는 구조였습니다. HTTP Referer(레퍼러)란 현재 요청이 어디서 출발했는지를 나타내는 헤더입니다. 그런데 이 API 요청이 출발한 곳은 외부 사이트가 아니라, 이미 로드된 제 사이트 페이지입니다. 브라우저 입장에서는 당연히 현재 페이지 주소를 Referer로 붙여 보내는 겁니다.

즉, 리버스 프록시가 값을 바꾼 것이 아니었습니다. 브라우저가 이미 제 사이트 주소를 Referer로 보내고 있었고, Nginx는 그 값을 그대로 전달했을 뿐입니다.

Reverse Proxy 설정이 실제로 Referer를 막는 경우도 있는가

이 문제를 파고들다 보니 “리버스 프록시가 Referer를 강제로 바꾼다”고 생각하시는 분들도 있는데, 저는 그 가능성도 직접 확인해봤습니다. Nginx 설정에서 $http_referer라는 변수가 있습니다. $http_referer란 Nginx가 클라이언트로부터 받은 Referer 헤더 값을 읽을 수 있도록 제공하는 내장 변수입니다.

일반적으로 Synology 리버스 프록시의 기본 설정에는 proxy_set_header 지시문으로 Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto를 명시적으로 전달하는 내용이 포함되어 있습니다. Referer는 기본 설정에 따라 다르지만, 아래처럼 명시적으로 추가해줄 수 있습니다.

  1. proxy_set_header Host $http_host; — 요청 호스트 이름을 백엔드로 전달
  2. proxy_set_header X-Real-IP $remote_addr; — 실제 클라이언트 IP를 전달
  3. proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; — 중계 경로상의 IP 목록을 전달
  4. proxy_set_header X-Forwarded-Proto $scheme; — 요청 프로토콜(http/https)을 전달
  5. proxy_set_header Referer $http_referer; — 브라우저가 보낸 Referer를 백엔드로 전달

저도 처음엔 이 설정이 빠져서 문제가 생겼을 것이라고 봤습니다. 그래서 Referer 줄을 추가하고 테스트해봤는데, 결과는 똑같았습니다. 이유는 앞서 설명한 것과 동일합니다. Nginx의 $http_referer가 읽는 값 자체가 이미 브라우저가 API 요청에 담아 보낸 ‘현재 페이지 주소’이기 때문입니다. 없는 값을 만들어줄 수는 없는 노릇이었습니다.

Referrer Policy(레퍼러 정책)라는 개념도 여기서 연결됩니다. Referrer Policy란 브라우저가 요청을 보낼 때 Referer 헤더를 얼마나 상세하게 포함할지를 제어하는 정책입니다. 예를 들어 strict-origin-when-cross-origin 정책에서는 같은 오리진 요청에는 전체 URL을, 다른 오리진 요청에는 출처(origin)만 보내거나 아예 생략하기도 합니다. 이 정책 때문에 외부에서 들어온 최초 Referer가 의도치 않게 잘릴 수 있다는 시각도 있는데, 제 경험상 이 케이스에서는 정책 문제보다 “어느 요청의 Referer를 읽고 있는가”를 먼저 따지는 것이 훨씬 중요했습니다. MDN 문서에 따르면(출처: MDN Web Docs) Referer 헤더는 현재 요청을 유발한 페이지의 주소를 담는 것이 원칙입니다. API 호출을 유발한 페이지는 이미 제 사이트이니, 결과는 처음부터 정해져 있었던 셈입니다.

document.referrer로 최초 유입 정보를 직접 기록하는 방법

원인을 파악하고 나니 해결책은 생각보다 명확했습니다. 서버에서 API 요청의 Referer 헤더에 의존하지 말고, 페이지가 처음 로드된 시점에 브라우저에서 직접 최초 유입 정보를 읽어오면 됩니다. 이때 사용하는 것이 document.referrer입니다. document.referrer란 현재 페이지로 넘어오기 직전에 사용자가 있었던 페이지의 URL을 문자열로 반환하는 브라우저 API입니다.

외부 사이트에서 제 사이트로 링크를 타고 들어왔다면 document.referrer에는 그 외부 사이트의 URL이 담겨 있습니다. 직접 주소창에 입력하거나 북마크로 접근했다면 빈 문자열이 반환됩니다. 이 값을 페이지 진입 시점에 읽어서 API 요청 body에 포함시키면, 서버에서는 별도로 가공할 필요 없이 그대로 DB에 저장할 수 있습니다.

실제로 이렇게 바꾸고 나서야 외부 유입 경로가 정상적으로 기록되기 시작했습니다. 솔직히 이건 예상 밖이었습니다. 처음엔 서버 설정 문제라고 굳게 믿었는데, 결국 핵심은 브라우저에서 어느 시점에 어느 값을 읽느냐였습니다.

Next.js 환경에서는 useEffect 내부에서 document.referrer를 읽고, 그 값을 fetch 호출 body에 담아 보내는 방식이 가장 자연스럽습니다. 서버 컴포넌트나 SSR 구간에서는 window 객체에 접근할 수 없으므로, 반드시 클라이언트 사이드에서 처리해야 합니다. 이 점을 놓치면 빌드 오류가 나거나 값이 항상 비어있는 상황이 생길 수 있어서 주의가 필요합니다.

Nginx 공식 문서에서도(출처: Nginx 공식 문서) proxy_set_header 지시문의 역할은 프록시가 백엔드로 전달하는 헤더를 재정의하거나 추가하는 것이라고 명시하고 있습니다. 즉, 브라우저가 보내지 않은 값을 Nginx가 새로 만들어줄 수는 없습니다. 이 원칙을 이해하고 나면 “왜 proxy_set_header Referer를 추가해도 안 되는가”에 대한 답이 자연스럽게 나옵니다.

자주 묻는 질문

Q. Synology 리버스 프록시를 쓰면 Referer 헤더가 자동으로 바뀌나요?

A. 그렇지 않습니다. Synology의 Nginx 기반 리버스 프록시는 브라우저가 보낸 Referer를 그대로 전달합니다. 다만 proxy_set_header 설정에 Referer가 명시되어 있지 않으면 전달이 생략될 수 있으므로, proxy_set_header Referer $http_referer;를 명시적으로 추가해두는 편이 안전합니다. 리버스 프록시가 값을 조작하는 것이 아니라 브라우저가 이미 어떤 값을 보내는지가 핵심입니다.

Q. 서버에서 방문자의 최초 유입 사이트를 알고 싶은데, API 요청의 Referer 헤더로 알 수 있나요?

A. 불가능한 경우가 많습니다. 페이지 진입 후 JavaScript가 API를 호출하면 그 API 요청의 Referer는 현재 사이트가 됩니다. 최초 유입 정보를 기록하려면 페이지가 처음 로드될 때 브라우저의 document.referrer 값을 읽어 API body에 담아 전달하는 방식이 더 정확합니다.

Q. Next.js에서 document.referrer를 사용할 때 주의할 점이 있나요?

A. document.referrer는 브라우저 환경에서만 사용할 수 있는 Web API입니다. Next.js의 서버 컴포넌트나 getServerSideProps 같은 서버 실행 구간에서는 접근할 수 없습니다. useEffect 내부에서 읽거나 클라이언트 컴포넌트에서만 사용해야 합니다. 이를 무시하면 빌드 타임 오류 또는 런타임 undefined 오류가 발생할 수 있습니다.

Q. Nginx의 $http_referer 변수는 무엇인가요?

A. Nginx가 클라이언트 요청에서 Referer 헤더를 읽어오는 내장 변수입니다. HTTP 요청 헤더는 일반적으로 $http_헤더명 형태로 Nginx에서 접근할 수 있으며, Referer는 $http_referer로 읽습니다. 이 변수 자체는 정상 작동하지만, 브라우저가 빈값이나 현재 사이트 주소를 보내면 그 값이 그대로 반영됩니다.

이번 작업에서 가장 오래 걸렸던 부분은 사실 코드 수정이 아니었습니다. “어느 요청의 Referer를 읽고 있는가”를 구분하지 않은 채 Nginx 설정만 반복해서 뒤졌던 시간이 제일 길었습니다. Synology Reverse Proxy를 운영하면서 IP가 제대로 넘어오지 않거나 헤더 값이 이상하다면, Nginx 설정보다 먼저 브라우저가 실제로 어떤 값을 보내고 있는지를 확인하는 것이 순서입니다. 문제의 원인이 프록시가 아닌 요청 구조 자체에 있는 경우가 생각보다 많습니다.

—
참고: https://www.reddit.com/r/synology/comments/eva3tu/solved_synology_reverse_proxy_how_to_set_proxy/?tl=ko

Similar Posts