Nginx WebSocket 설정 시 겪었던 이슈와 해결 과정

1. Nginx와 WebSocket, 왜 함께 사용해야 하는가?

안녕하세요, 개발자 여러분. 오늘은 Nginx 리버스 프록시 환경에서 웹소켓(WebSocket)을 설정하며 겪었던 문제와 해결 방법을 공유하려 합니다. 웹소켓은 실시간 양방향 통신을 위해 필수적인 기술이며, Nginx는 여러 서비스를 한 서버에서 관리하는 데 매우 유용합니다. 하지만 이 둘을 함께 사용하려면 몇 가지 특별한 설정이 필요합니다.

2. 발생한 문제들

문제 1: 400 Bad Request 에러

가장 먼저 마주친 문제는 400 Bad Request 에러였습니다. 웹소켓 연결 요청 시 브라우저 콘솔에 이 에러가 뜨면서 연결이 끊어졌습니다.

원인: Nginx가 웹소켓 요청을 일반 HTTP 요청으로 인식하여 프록시 헤더를 제대로 전달하지 못했기 때문입니다. 웹소켓 프로토콜은 Upgrade 및 Connection 헤더를 통해 핸드셰이크를 수행하는데, Nginx가 이 정보를 무시하고 다음 서버로 전달하지 않았던 것입니다.

다음으로는 CORS 에러가 발생했습니다. Nginx는 웹소켓 요청의 Origin을 막아서 요청이 차단되었습니다.

원인: 브라우저 보안 정책에 따라, 다른 도메인으로 요청을 보낼 때 서버에서 해당 도메인을 허용해야 합니다. Nginx에 CORS 관련 헤더 설정이 누락되어 있어 웹소켓 연결이 거부되었습니다.

3. 해결책

위 문제를 해결하기 위해 Nginx 설정 파일(nginx.conf 또는 sites-available 내의 설정 파일)에 다음 내용을 추가했습니다.

웹소켓 프록시 헤더 설정

웹소켓 핸드셰이크가 정상적으로 동작하도록 Upgrade와 Connection 헤더를 포함시키는 설정입니다. 이 부분이 400 Bad Request 에러를 해결하는 핵심입니다.

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $host;

proxy_set_header Upgrade $http_upgrade;: 웹소켓 업그레이드 요청을 다음 서버로 전달하도록 합니다.
proxy_set_header Connection "Upgrade";: HTTP/1.1에서 웹소켓 프로토콜로 전환하겠다는 신호를 보냅니다.

타임아웃 및 버퍼 설정

오랫동안 사용되지 않는 웹소켓 연결이 끊기지 않도록 타임아웃 설정을 추가했습니다. 이 설정은 502 Bad Gateway나 504 Gateway Timeout 에러를 방지하는 데 도움을 줍니다.

proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
proxy_http_version 1.1;

proxy_read_timeout 및 proxy_send_timeout: 웹소켓 연결의 유지 시간을 설정합니다.
proxy_http_version 1.1: HTTP/1.1을 사용하도록 명시하여 웹소켓 업그레이드를 지원합니다.

최종 Nginx 설정 예시

위의 내용을 종합한 최종 설정 예시입니다. <your_domain.com>을 자신의 도메인으로, <backend_port>를 웹소켓 서버의 포트로 변경하면 됩니다.

server {
    listen 80;
    server_name <your_domain.com>;

    location / {
        proxy_pass http://localhost:<backend_port>;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;

        # 추가적인 타임아웃 설정
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

4. 결론

Nginx와 웹소켓을 함께 사용하려면 웹소켓 프로토콜을 위한 Upgrade와 Connection 헤더 설정이 필수적입니다. 이 외에도 타임아웃, CORS 등 다양한 요소를 고려해야 합니다. 이 글이 여러분의 웹소켓 설정 문제를 해결하는 데 도움이 되기를 바랍니다.