이것저것 👩‍💻

정적 모듈 vs 동적 모듈

정적 모듈: Nginx 컴파일 시 소스코드에 포함되어 함께 빌드되며, 항상 메모리에 로드되어 있어서 사용하지 않아도 리소스를 차지한다. 정적모듈은 적용 시 무중단이 불가능하다.

동적 모듈: 별도의 .so 파일로 컴파일되어 필요할 때만 로드하며 유연성이 높고 메모리 효율적이다. 동적모듈은 적용 시 무중단이 가능하다.

동적모듈 예시

• ngx_http_image_filter_module: 이미지 처리
• ngx_http_geoip_module: IP 기반 지리 정보
• ngx_http_xslt_module: XML/XSLT 변환
• ngx_stream_module: TCP/UDP 로드밸런싱
• ngx_http_perl_module: Perl 스크립트 실행

so 파일은 뭘까?

.so 파일은 Shared Object 파일이며, 리눅스/유닉스 시스템에서 사용하는 동적 링크 라이브러리(Dynamic Link Library) 파일이다. 동적모듈 최종 파일이라고 보면 된다.

동적모듈의 장점

• 런타임에 로드: 프로그램 실행 중에 필요할 때 메모리에 적재
• 코드 공유: 여러 프로그램이 동일한 .so 파일을 공유해서 사용 가능
• 메모리 효율: 중복 코드를 메모리에 한 번만 로드
• 독립적 업데이트: 메인 프로그램 재컴파일 없이 라이브러리만 교체 가능
• 무중단 배포 가능

1. 동적모듈 소스 다운로드

nginx version을 확인해서 이와 맞는 모듈 소스코드를 다운받아 서버에 업로드 한 뒤 파일의 압축을 푼다.

나는 nginx version이 1.28이라서 해당 tar.gz 파일을 다운받았다. (버전이 맞지 않는다면 nignx -t에서 오류 발생하기에 버전 확인 필수!)

C 파일(.c)과 헤더 파일(.h), config 파일 등으로 구성되어 있다.

공식 다운로드 사이트: https://nginx.org/download/

tar -xzvf nginx-1.28.0.tar.gz

2. 동적모듈 빌드

동적모듈을 빌드할때 각종 오류가 나는데 보통 의존성 라이브러리가 설치되어있지 않아 오류가 발생했다.

어떤 모듈인지에 따라 필요한 의존성 라이브러리는 각각 다르며, 오류 문구에서 나오는 라이브러리를 설치하면 된다.

# Nginx 소스 디렉토리로 이동
cd /usr/local/src/nginx-1.28.0

# configure 실행 (동적 모듈 추가)
# 의존성 라이브러리 설치가 모두 완료되어야 오류없이 실행 가능
./configure --with-compat --with-http_xslt_module=dynamic

# 모듈에 따라 실행 문법 확인
./configure --help | grep {모듈명}

# 모듈만 빌드
# 이 명령으로 .so 파일(공유 라이브러리)이 생성 
# 빌드된 .so 파일은 objs/ 디렉토리에 생성
make modules

# 빌드된 .so 파일을 모듈 디렉토리로 복사
# 모듈을 빌드하면 nginx-1.28.0/objs 디렉토리 밑에 so 파일이 생성된다.
cp objs/ngx_http_geoip2_module.so /usr/lib64/nginx/modules/

⭐ 동적모듈 빌드 옵션 설명

./configure

Nginx 빌드 환경을 설정하는 스크립트입니다. Makefile을 /usr/local/src/nginx-1.28.0 디렉토리 안에 생성합니다.

--with-compat

호환성 모드 활성화

• Nginx 바이너리와 동적 모듈 간의 ABI(Application Binary Interface) 호환성을 보장 ( 이미 설치된 Nginx에 나중에 동적 모듈만 따로 추가할 때 필수 옵션)
• 이게 없으면 모듈이 제대로 로드되지 않을 수 있음

--with-http_xslt_module=dynamic

XSLT 모듈을 동적 모듈로 빌드

• 모듈에 따라서 --with-{모듈명}=dynamic 형식
• --with-http_xslt_module: XSLT 모듈 포함
• =dynamic: 정적이 아닌 동적 모듈(.so 파일)로 빌드하라는 의미
• =dynamic을 안 붙이면 정적 모듈로 컴파일되며, make modules이 안 먹히고, so 파일도 안 만들어진다.

3. 모듈 로드 및 사용

# nginx.conf 파일 수정
vi /etc/nginx/nginx.conf

# nginx.conf 파일 최상단에 추가
# 모듈을 사용하기 위함
include /usr/share/nginx/modules/*.conf;

/usr/share/nginx/modules/ 안에 conf 파일을 만들어서 모듈을 로드한다.

# conf 파일 생성 후 파일 안에 load_module 추가
vi /usr/share/nginx/modules/mod-http-image-filter.conf

# 파일 안에 추가
load_module "/usr/lib64/nginx/modules/ngx_http_image_filter_module.so";

4. 설정 확인 및 재시작

# 설정 파일 문법 검사
nginx -t

# Nginx 재시작 (무중단)
systemctl reload nginx

설정파일 문법 검사 시, 아래와 같이 OK와 successful을 확인했다면 재시작한다.

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

정적/동적에 따른 Nginx 재시작 방법

# 정적모듈: Nginx 바이너리 자체가 교체되므로 재시작 필요 (중지 발생)
systemctl restart nginx  

# 동적모듈: .so 파일만 교체 후 reload만으로 가능 (무중단)
systemctl reload nginx

우선 Nginx 설정 파일은 크게 2가지로 나뉜다.

구조를 나눔으로써 운영 영향도를 줄이고 설정 충돌 방지, 서비스 추가/삭제가 쉬우며 롤백이 쉽다.

nginx 설정 구조

/etc/nginx/
├── nginx.conf          # 메인 설정 파일
├── conf.d/                # 서버별 설정 include
│   ├── default.conf
│   └── api.conf

│   └── web.conf

수정 시 영향도 확인

• nginx.conf 수정 → nginx 전체 영향
• conf.d/*.conf 수정 → 해당 서비스만 영향

1. 메인 설정 (Main Config) - /etc/nginx/nginx.conf 

-> nginx 전체 프로세스/동작 방식을 정의하는 루트 설정

1-1. 전역(Global) 설정

user  nginx;
worker_processes  auto;
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

• user : nginx 프로세스 실행 계정
• worker_processes : 워커 프로세스 개수
• error_log : 에러 로그
• pid : PID 파일

2-2. 이벤트 블록

동시에 처리 가능한 커넥션 수

events {
    worker_connections  1024;
}

2-3. http 블록

HTTP 서버 전역 설정

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format main '$remote_addr - $remote_user ...';
    access_log /var/log/nginx/access.log main;

    sendfile        on;
    keepalive_timeout 65;

    include /etc/nginx/conf.d/*.conf; //서비스 설정파일 include
    
    map $http_upgrade $connection_upgrade {
    default upgrade;   # 1순위: 아무것도 매칭 안 되면 이거
    '' close;          # 2순위: 빈 문자열이면 이거
    }
}

• MIME 타입
• 로그 포맷
• gzip
• proxy 관련 기본값
• SSL 기본값
• upstream 정의 가능
• 중요! 서비스별 설정을 직접 다 넣기보다는 include 로 분리하는 구조

트러블슈팅

만약에 WebSoket을 사용하는 시스템이라면 서비스 설정 파일 안에 해당 Proxy header가 들어있을것이다.

       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection $connection_upgrade;

그렇다면 메인 설정 파일의 http 블록 안에 아래 코드가 들어가야하며 그렇지 않으면 오류 발생한다.

    map $http_upgrade $connection_upgrade {
    default upgrade;   # 1순위: 아무것도 매칭 안 되거나 빈 문자열이 아니면 이거
    '' close;          # 2순위: 빈 문자열이면 이거
    }

케이스 1: WebSocket 요청

• $http_upgrade = "websocket" (Upgrade 헤더 값)
• 매칭 확인:
  • close 매칭 ❌ (빈 문자열 아님)
  • default upgrade 매칭 ⭕
• 결과: $connection_upgrade = "upgrade"

케이스 2: 일반 HTTP 요청

• $http_upgrade = "" (빈 문자열, Upgrade 헤더 없음)
• 매칭 학인:
  • close 매칭 ⭕ (여기서 끝!)
• 결과: $connection_upgrade = "close"
• default는 확인조차 안 함

케이스 3: 이상한 값이 들어온 경우

• $http_upgrade = "something-weird"
• 매칭 확인:
  • close 매칭 ❌ (빈 문자열 아님)
  • default upgrade 매칭 ⭕
• 결과: $connection_upgrade = "upgrade"

2. 서비스 설정 (Service / Virtual Host) - /etc/nginx/conf.d/*.conf

HTTPS + WebSocket 예시

아래 코드는 nginx를 proxy server로 사용한 예시이다.

server {
    listen 443 ssl;
    server_name chat.example.com;
    
    # SSL 해독처리로 HTTPS 여기서 처리!
    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    
    location / {
        proxy_pass http://localhost:8080; # proxy server
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade; # HTTP/WebSocket 처리
        proxy_set_header Connection $connection_upgrade; # HTTP/WebSocket 처리
        proxy_set_header Host $host;
    }
}

1. HTTPS 요청 (일반 웹페이지)

브라우저 → https://chat.example.com (443 포트)
         → nginx (SSL 해독)
         → http://localhost:8080 (평문 HTTP로 전달)

2. WebSocket 연결 (wss://)

브라우저 → wss://chat.example.com (443 포트)
         → nginx (SSL 해독 + WebSocket 업그레이드)
         → ws://localhost:8080 (평문 WebSocket으로 전달)

Proxy Server란 뭘까?

-> 중간 다리 역할을 해주는 서버이다.

-> Apache (with mod_proxy), Caddy, Envoy 같은 Proxy Server가 존재한다.

사용자 브라우저 → nginx (80포트) → Node.js 앱 (3000포트)

사용자는 80, 443 인터넷 포트만 알고 접속하면 알아서 여러 서버의 포트로 연결시켜준다.

• 보안: 실제 서버(3000포트) 직접 노출 안 함
• 로드밸런싱: 여러 서버에 트래픽 분산
• SSL 처리: nginx가 HTTPS 처리, 앱은 HTTP만
• 정적 파일: 이미지 같은 건 nginx가 직접 서빙

왜 nginx가 정적 파일 서빙에 빠를까?

-> 이미지 요청 → nginx가 디스크에서 바로 읽어서 전송하기 때문!

• 엄청 빠름: C로 작성됨, 파일 읽기에 최적화
• 백엔드 부하 감소: Node.js가 파일 처리 안 해도 됨 ( 이미지 요청 → nginx → Node.js → 파일 읽기 → nginx → 브라우저 ) 
• 효율적 메모리: 파일 캐싱, sendfile 시스템콜 사용