Nginx로 소켓 연결하기 / Upgrade가 필요한 이유

실시간 통신(채팅, 알림, 대시보드 등)을 만들다 보면 WebSocket(또는 Socket.IO)이 필수죠. 그런데 Nginx 뒤에 두면 가끔 “연결이 안 붙는다”, “몇 분 후 끊긴다”, “polling만 되고 websocket으로 업그레이드가 안 된다” 같은 문제가 터집니다.

 

핵심은 단 하나: HTTP → WebSocket으로 “프로토콜 업그레이드(Upgrade)”가 제대로 이뤄져야 한다는 것.

이 글에서는 왜 Upgrade가 필요한지, Nginx에 무엇을 적어야 하는지,

환경별 베스트 프랙티스와 트러블슈팅까지 한 번에 정리합니다.

 

 

 

 

왜 Upgrade가 필요한가?

• WebSocket은 최초에 HTTP로 시작하고, 서버와 클라이언트가 Upgrade: websocket 헤더를 주고받아 프로토콜을 “스위칭”합니다.
• 이때 서버는 HTTP 101 Switching Protocols로 응답해야 하며, 이후부터는 지속 커넥션 위에서 양방향 통신을 합니다.
• 프록시(Nginx)가 사이에 있으면 이 Upgrade/Connection 헤더를 정확히 통과시켜야 하며, HTTP/1.1로 백엔드에 전달해야 합니다.

---

필수 디렉티브 요약(요 4개는 무조건)

# 1) HTTP/1.1로 백엔드에 보내기
proxy_http_version 1.1;

# 2) Upgrade 헤더 전달
proxy_set_header Upgrade $http_upgrade;

# 3) Connection: upgrade 설정(빈 Upgrade일 땐 close)
map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}
proxy_set_header Connection $connection_upgrade;

# 4) 타임아웃은 길게 (웹소켓은 장시간 유지됨)
proxy_read_timeout 3600;

 

 

왜 map?
일부 클라이언트/경로는 WebSocket이 아닐 수 있어서(예: Socket.IO의 polling) Upgrade가 비어 있을 때는 Connection: close로 맞춰 주는 게 안전합니다.