실시간 알림 구현 하기 : 3. 인프라 환경에서 백엔드 서버와 연결 테스트 (with. trouble shooting)

이전 글에서 백엔드 로컬 서버에서는 실행이 잘 되는 것을 확인하였다. 하지만 k8s 인프라 환경에 올렸을 때 문제가 발생하였다.

이번 글에서는 Next.js API Routes + SSE 프록시 구성 시 K8s 환경에서 localhost로 연결되던 문제에 대해 작성해보려 한다.

 

Next.js API Routes를 사용해 SSE(Server-Sent Events) 프록시를 구현하던 중, 로컬(Linux 서버)에서는 정상 동작하던 코드가 Kubernetes(K8s) 인프라 환경에 배포되자 localhost로 잘못 연결되며 실패하는 이슈가 발생했다.

 

이 글에서는 단순한 “env 설정 실수”를 넘어,IP 직접 접근 ↔ Service Name 기반 접근의 구조적 차이,
그리고 Next.js의 빌드·런타임 환경 변수 처리 방식이 어떻게 장애로 이어졌는지를 정리한다.

 

1. 문제 현상

K8s 환경에서 SSE 프록시 API를 호출하면 다음과 같은 에러가 발생했다.

 

유형	로그	결과
연결 거부	ECONNREFUSED ::1:80	SSE 연결 실패
잘못된 URL	_currentUrl: 'http://localhost/test/sse/event'	실제 백엔드가 아닌 localhost 연결

즉, 의도한 백엔드는 http://our-service-backend였으나, 실제 연결은 http://localhost로 시도되고 있었다.

 

2. 초반 추정: “SSE나 HTTP 클라이언트 문제인가?”

초기에  APM 로그를 확인하기 전에는 다음을 의심했다.

• HTTP 클라이언트의 SSE 스트리밍 미지원
• keep-alive, buffer, gzip 설정 문제

그러나 로그를 분석한 결과 문제는 네트워크 계층이나 SSE가 아니라, URL 자체가 잘못 만들어지고 있음이 드러났다.

_currentUrl: 'http://localhost/test/sse/event'

➡ 백엔드 주소를 못 찾은 상태에서 HTTP 클라이언트가 기본값인 localhost:80으로 폴백한 상황이었다.

 

3. 결정적인 차이: Linux 서버 vs Kubernetes 인프라

이번 이슈의 핵심은 단순한 env 누락이 아니라, “백엔드 엔드포인트를 IP로 직접 찔렀느냐, Service Name으로 접근했느냐”의 차이였다.

 

🔹 Linux 서버(로컬/온프레미스 환경)

http://43.xxx.xxx.xxx:9999

• 백엔드 서버 고정 IP 직접 접근
• DNS, Service, Proxy, Pod 개념 없음
• Next.js API Routes → 해당 IP로 바로 TCP 연결
• env가 일부 깨져도 IP 하드코딩이 살아 있어서 문제 미발생

➡ 구조적으로 “깨질 여지가 없는 단일 서버 통신”

 

🔹 Kubernetes 인프라 환경

 

http://our-service-backend

• 백엔드 접근은 K8s Service Name 기반
• 실제 물리 IP는 Pod 재기동, 스케일링 시마다 변경
• 반드시 다음이 전제됨:
  •  정상적인 DNS 해석
  •  올바른 Service Name
  •  env를 통한 정확한 baseURL 전달

하지만 이 중 env 전달이 깨지면서 baseURL이 undefined가 되었고, 그 결과 Axios가 상대경로로 요청을 해석하면서 localhost로 폴백했다.

➡ K8s 환경에서는 env 누락이 곧 “잘못된 네트워크 라우팅”으로 직결된다.

 

 

4. 근본 원인: Next.js API Routes에서 env가 유실됨

프록시 API Routes 내부에서 다음처럼 작성되어 있었다.

const baseUrl = process.env.CLOUD_BACKEND_URL;

K8s Deployment YAML에서는 분명 CLOUD_BACKEND_URL이 주입되어 있었지만, Next.js 서버(Node 프로세스)에서는 이 값이 undefined로 평가되고 있었다.

➡ 이로 인해 Axios는 다음과 같은 요청을 만들어버렸다.

http://localhost/test/sse/event

 

5. 해결 방법 - next.config.js를 통한 env 명시적 전달

Next.js는 일반 Node.js 서버와 달리 환경 변수를 빌드 타임 기준으로 번들에 포함하는 구조다.
따라서 K8s에서 주입된 env도 next.config.js를 통해 다시 명시적으로 전달해야 안정적이다.

// next.config.js
module.exports = {
  env: {
    BACKEND_URL: process.env.BACKEND_URL,
  },
};

이렇게 설정한 이후부터 API Routes에서도 다음이 안정적으로 동작했다.

 

 

Next.js API Routes에서 env가 민감한 이유

Next.js는 클라이언트 번들과 서버(Runtime) 영역이 완전히 분리된 빌드·실행 구조를 가지기 때문에, 환경변수를 어디에서 어떻게 불러올 수 있는지가 일반적인 Node.js와 다르다. Next.js에는 두 개의 실행 세계가 존재한다.

1) 클라이언트 번들(브라우저 실행)

• .env는 Node.js 서버에 존재
• 브라우저로 전달되는 환경변수는 빌드 타임에 정적으로 하드코딩된 값만 가능
• 따라서 클라이언트에서 env를 쓰려면 반드시 next.config.js.env에 지정해야 한다

2) 서버 번들(API Routes / SSR / Route Handlers)

• Node.js 기반으로 실행되기 때문에 원칙적으로는 .env 접근 가능
• 하지만 Next.js가 이 코드를 번들링 및 최적화한다는 특수성이 존재한다

즉, API Routes가 “그냥 Node.js”가 아니라 Next.js가 구성한 서버 런타임의 일부라는 점 때문에 환경변수 전달 방식이 다르게 동작할 수 있다.

 

 

API Routes도 Next.js에 의해 번들링된다

Next.js의 pages/api/*.ts는 Node.js에서 실행되지만, Next.js 빌드 파이프라인을 지나간다.

결과적으로:

• Next.js는 "사용되는 env"라고 판단하지 않으면 번들에서 제거할 수 있다
• 또는 output: "standalone" 같은 모드에서는 필요한 env만 포함시켜 실행 파일을 만든다
• 따라서 안정적인 접근을 위해 Next.js가 env를 직접 주입해야 한다

Next.js 공식 문서 명시:

API Routes는 서버에서 실행되지만 Next.js에 의해 최적화되므로, 모든 환경변수가 자동으로 포함되는 것은 아니다.

 

왜 next.config.js의 env에 넣으면 해결되는가?

next.config.js는 빌드 타임에 Node.js 환경에서 100% 실행되는 설정 파일이다.

 

여기서 env에 변수를 넣으면:

1. Next.js가 이를 “정적 환경 변수”로 인식
2. 서버·클라이언트 번들 모두에 embed
3. 빌드된 API Routes에서도 process.env.변수명으로 안정적으로 접근 가능

 

 

결론적으로, 이번 트러블 슈팅은 Next.js의 빌드 구조 + Kubernetes 네트워크 모델이 동시에 맞물려 발생한 구조적 장애였다.

따라서 api routes에서 .env 사용시는 주의가 필요함을 확인 할 수 있었다.