{"time":1747569635937,"blocks":[{"id":"1VZjaqgQFB","type":"warning","data":{"title":"서비스 중 특정 서버의 장애로 인해 전체 서비스에 영향이 가는 경험이 있었는데요, 이를 해결하기 위해 Nginx Upstream Check Module 을 도입하게 되었습니다.","message":""}},{"id":"UPHHYpzaNW","type":"header","data":{"text":"들어가며 ","level":2}},{"id":"kLL7v8u5yU","type":"paragraph","data":{"text":"웹 서비스를 운영하다 보면 예상치 못한 서버 장애를 마주하게 됩니다. 특히 Nginx를 리버스 프록시로 사용하는 환경에서는, 백엔드 서버 중 하나가 응답하지 않더라도 Nginx 가 해당 서버로 트래픽을 계속 보내기 때문에 사용자에게 500 에러가 발생할 수 있습니다."}},{"id":"01m-KONjwL","type":"paragraph","data":{"text":"이 글에서는 그런 상황을 예방하고자 Nginx Upstream Check Module 을 적용한 경험을 정리했습니다. 실습 중심으로 구성했기 때문에, 쉽게 따라오실 수 있을겁니다."}},{"id":"EdwKYI9-_Z","type":"customHeader","data":{"text":"문제 상황 "}},{"id":"bl9py2Kjwa","type":"paragraph","data":{"text":"Nginx 는 기본적으로 upstream 서버들의 상태를 확인하지 않습니다. 즉, 백엔드 서버가 죽었더라도 Nginx는 이를 인지하지 못하고 계속 요청을 보냅니다. "}},{"id":"6KvPu_BfWR","type":"header","data":{"text":"이슈 포인트","level":3}},{"id":"JTqt-6XpY6","type":"list","data":{"style":"unordered","meta":{},"items":[{"content":"백엔드 중 한대가 장애 나도 트래픽은 계속 전송됨 ","meta":{},"items":[]},{"content":"결과적으로 500 오류 발생 -> 사용자 신뢰도 하락 ","meta":{},"items":[]},{"content":"장애 탐지 및 대응이 수동적이고 늦음 ","meta":{},"items":[]}]}},{"id":"jWTX94iCPn","type":"paragraph","data":{"text":"실제로 부엉이 개발자 블로그를 운영함에 있어서 해당 이슈가 발생 했었고, 여러 재발 방지 방법을 찾는 과정중 자동으로 서버 상태를 확인해주는 Upstream Health Check 기능을 적용하게 되었습니다."}},{"id":"9eTOrpbCnw","type":"customHeader","data":{"text":"Nginx Upstream Check Module "}},{"id":"h1f9219mTD","type":"paragraph","data":{"text":"Nginx 유료버전에서는 백엔드(업스트림) 서버의 상태를 주기적으로 확인할 수 있도록 해주는 서드파티 모듈이 존재합니다. 하지만 무료버전에서 해당 기능을 대신하는 Nginx Upstream Check Module 을 적용하면 아래와 같은 기능을 사용할 수 있습니다."}},{"id":"JhyUuV6Arp","type":"list","data":{"style":"unordered","meta":{},"items":[{"content":" 주기적으로 HTTP 요청을 전송하여 서버 상태 확인 ","meta":{},"items":[]},{"content":" 일정 조건에 따라 서버를 비정상 상태로 간주 ","meta":{},"items":[]},{"content":" 비정상 서버는 자동으로 트래픽 대상에서 제외","meta":{},"items":[]}]}},{"id":"LvRdpE0FE1","type":"paragraph","data":{"text":"이 모듈은 오픈소스로서 Nginx 의 upstream 설정에 헬스 체크 기능을 추가해줍니다."}},{"id":"UkMvep9BXJ","type":"customLink","data":{"url":"https://github.com/yaoweibin/nginx_upstream_check_module","title":"GitHub - yaoweibin/nginx_upstream_check_module: Health checks upstreams for nginx","description":"Health checks upstreams for nginx. Contribute to yaoweibin/nginx_upstream_check_module development by creating an account on GitHub.","image":"https://opengraph.githubassets.com/6a1d46c4cbc63436333c25cb73e0ad1e4e72dde96e95be661b48fb7f2c44b648/yaoweibin/nginx_upstream_check_module"}},{"id":"w-wuKtl-LX","type":"delimiter","data":{}},{"id":"g1K-Huqe9d","type":"customHeader","data":{"text":"적용 과정 "}},{"id":"5M2-jzlo7r","type":"header","data":{"text":"1. 모듈 clone ","level":3}},{"id":"29s25o_a1c","type":"code","data":{"code":"git clone https://github.com/yaoweibin/nginx_upstream_check_module.git\n\n"}},{"id":"_mvbSbRG1n","type":"header","data":{"text":"2.의존성 패키지 설치","level":3}},{"id":"j2WsIA9JOa","type":"code","data":{"code":"sudo apt update\nsudo apt install build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev\n"}},{"id":"4oeTxU5KuB","type":"list","data":{"style":"unordered","meta":{},"items":[{"content":"build-essential: C/C++ 컴파일에 필요한 gcc, make 등의 도구를 포함합니다.\n","meta":{},"items":[]},{"content":"libpcre3 및 libpcre3-dev: Nginx의 정규표현식 처리에 필요한 PCRE 라이브러리와 개발 파일을 제공합니다.\n","meta":{},"items":[]},{"content":"zlib1g 및 zlib1g-dev: 압축 관련 기능을 위한 zlib 라이브러리와 개발 파일입니다.\n","meta":{},"items":[]},{"content":"libssl-dev: SSL/TLS 지원을 위해 OpenSSL 라이브러리의 개발 파일을 포함합니다.","meta":{},"items":[]}]}},{"id":"-sMIOL74Jz","type":"delimiter","data":{}},{"id":"E4kEeQ6mHX","type":"header","data":{"text":"3. Nginx 1.20.1 버전 설치","level":3}},{"id":"mU7geNW67v","type":"paragraph","data":{"text":"라즈베리파이에서 sudo apt-get 으로 설치된 Nginx 는 이미 컴파일된 바이너리 형태로 설치되기 때문에, 해당 버전에 별도의 패치를 적용하는 것이 불가능 합니다.따라서 upstream check module 을 사용하려면 직접 파일을 받아 컴파일해야 합니다"}},{"id":"eV2Feq17TL","type":"header","data":{"text":"4.소스에서 컴파일하기","level":3}},{"id":"IG6-rSwMfH","type":"paragraph","data":{"text":" 기존 Nginx 패키지를 제거하거나 다른 경로에 설치하고, 소스코드를 다운로드한 후 yaoweibin/nginx_upstream_check_module 를 포함하여 직접 컴파일 합니다. 이경우 기존 설정과 충돌이 없도록 주의해야 합니다. "}},{"id":"Fcwm7rbo7V","type":"code","data":{"code":"cd /home/pi \nwget 'http://nginx.org/download/nginx-1.20.1.tar.gz'\ntar -xzvf nginx-1.20.1.tar.gz"}},{"id":"Vse-0W6fsY","type":"paragraph","data":{"text":"다운 받은 'nginx_upstream_check_module' 폴더와 'nginx' 폴더 경로 "}},{"id":"qnRI5YxF8r","type":"image","data":{"caption":"","withBorder":true,"withBackground":false,"stretched":true,"file":{"url":"https://backend.owl-dev.me/images/nginx_upstream.png"}}},{"id":"5DhKHgWVxF","type":"delimiter","data":{}},{"id":"yeO_YYFuPY","type":"header","data":{"text":"5. 헬스 체크 모듈 패치하기","level":3}},{"id":"EqczaQtU7j","type":"paragraph","data":{"text":" 압축 푼 Nginx 디렉터리에 들어가서 위와 같이 헬스 체크 모듈을 patch 해줍니다. (Nginx 버전에 맞는 *.patch 파일을 설정해줍니다 ) "}},{"id":"2Jsv_rbMpl","type":"code","data":{"code":"cd ./nginx-1.20.2\npatch -p1 < ../nginx_upstream_check_module/check_1.20.1+.patch"}},{"id":"WwOIOW-Mze","type":"header","data":{"text":"6. configure 및 컴파일 make","level":3}},{"id":"vSXJApqWno","type":"code","data":{"code":"./configure --with-http_v2_module --with-http_ssl_module --add-module=/home/pi/nginx_upstream_check_module\n\nmake\nsudo make install"}},{"id":"LSsO5R1GUI","type":"paragraph","data":{"text":"- http_v2_module : HTTP2 를 사용하기 위해 필요."}},{"id":"r8xQo42wiI","type":"paragraph","data":{"text":"- http_ssl_module : SSL 인증서를 사용하기 위해 필요."}},{"id":"t5Yfc4DOrl","type":"paragraph","data":{"text":"이 작업이 완료되면 /usr/local/nginx 경로에 관련 파일이 설치되어 있는 것을 확인할 수 있습니다."}},{"id":"Mace_4Ul0P","type":"list","data":{"style":"unordered","meta":{},"items":[{"content":"conf: 설정 파일 ","meta":{},"items":[]},{"content":"html: index 와 500 에러 관련 html (정적 파일)","meta":{},"items":[]},{"content":"logs: 로그 디렉터리 (기본)","meta":{},"items":[]},{"content":"sbin: nginx 실행 파일 디렉터리 ","meta":{},"items":[]}]}},{"id":"wDx8Uc8a2k","type":"delimiter","data":{}},{"id":"WQAa_7OsQd","type":"header","data":{"text":"7. Nginx 설정 ","level":3}},{"id":"2vrjJ1kJ6A","type":"paragraph","data":{"text":"이제 헬스체크 모듈을 포함한 Nginx 를 설치했으니, 아래와 같이 설정을 해줍니다. "}},{"id":"AC38YlNxn7","type":"paragraph","data":{"text":"/usr/local/nginx/conf/nginx.conf"}},{"id":"51-PJ2ZFwm","type":"code","data":{"code":"worker_processes auto;\n\nevents {\n worker_connections 1024;\n}\n\nhttp {\n include mime.types;\n default_type application/octet-stream;\n access_log /var/log/nginx/access.log;\n error_log /var/log/nginx/error.log;\n\n sendfile on;\n tcp_nopush on;\n keepalive_timeout 65;\n\n upstream backend {\n server localhost:8080;\n server localhost:8081;\n }\n\n server {\n listen 443 ssl http2;\n server_name api.trendy-tracker.kr;\n\n ssl_certificate /etc/letsencrypt/live/api.trendy-tracker.kr/fullchain.pem;\n ssl_certificate_key /etc/letsencrypt/live/api.trendy-tracker.kr/privkey.pem;\n add_header Strict-Transport-Security \"max-age=31536000\" always;\n\n client_max_body_size 10M;\n\n location / {\n proxy_pass http://backend;\n\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n }\n }\n}\n"}},{"id":"UuI6ZKbobS","type":"header","data":{"text":"8. Nginx 실행 ","level":3}},{"id":"rBtX3MNxI1","type":"code","data":{"code":"./sbin/nginx -t\n./sbin/nginx -c ./conf/nginx.conf"}},{"id":"4XbckhLPQN","type":"paragraph","data":{"text":"- t 를 통해 설정 파일을 테스트한다."}},{"id":"wTEMCvJgHF","type":"paragraph","data":{"text":"- c 를 통해 설정 파일 위치를 지정해주고 실행해준다."}},{"id":"9glbgpAArP","type":"delimiter","data":{}},{"id":"RzBZFwRSet","type":"customHeader","data":{"text":"4. 결과 "}},{"id":"mI4riDpKUi","type":"paragraph","data":{"text":"/status 로 확인한 Health-Check 화면 "}},{"id":"bv3dejKjf-","type":"image","data":{"caption":"","withBorder":true,"withBackground":false,"stretched":true,"file":{"url":"https://backend.owl-dev.me/images/health-check.png"}}},{"id":"NtbxagWeGG","type":"paragraph","data":{"text":"Nginx Upstream Check Module은 비공식 모듈이지만, 단순한 설정만으로 운영 안정성을 크게 높일 수 있는 강력한 도구입니다. 개발자로 일을 하다보면, 개발뿐만 아니라 모니터링도 중요한 업무중 하나인데요, 기회가 되시면 한번 적용해보시길 추천드립니다."}},{"id":"mfc5KxX2z4","type":"delimiter","data":{}},{"id":"IahPVXhSIa","type":"header","data":{"text":"참고 문서","level":2}},{"id":"3q5UH2wrzQ","type":"customLink","data":{"url":"https://github.com/yaoweibin/nginx_upstream_check_module","title":"GitHub - yaoweibin/nginx_upstream_check_module: Health checks upstreams for nginx","description":"Health checks upstreams for nginx. Contribute to yaoweibin/nginx_upstream_check_module development by creating an account on GitHub.","image":"https://opengraph.githubassets.com/316363c6f872809076ea75484f4502ced51a394314e1d01279e543fe2e756d14/yaoweibin/nginx_upstream_check_module"}},{"id":"OfWcKmqH9M","type":"customLink","data":{"url":"https://nginx.org/en/docs/","title":"nginx documentation","description":"","image":""}}],"version":"2.31.0-rc.7"}

Tag List