(권장) NGINX 프록시 설정

Mattermost v11.11번역일: 2026-09-02원본 보기

프록시 서버는 다른 서버의 리소스를 요청하는 클라이언트를 위해 중개자 역할을 하는 서버(컴퓨터 시스템 또는 애플리케이션)입니다. Mattermost는 보안과 성능을 높이고 Mattermost로 들어오는 트래픽을 모니터링·조절할 수 있도록 Mattermost 앞단에 프록시를 두는 것을 권장합니다.

  • 보안: 프록시 서버는 SSL/TLS 암호화를 관리하고 네트워크 트래픽이 Mattermost 서버로 라우팅되는 방식에 대한 정책을 설정할 수 있습니다.
  • 성능: 고가용성 구성에서 프록시 서버는 여러 Mattermost 서버에 네트워크 부하를 분산해 성능을 최적화합니다. SSL 암복호화 처리를 전담하는 장치를 갖춘 하드웨어 프록시로 성능을 높일 수도 있습니다.
  • 모니터링: 프록시 서버는 연결 트래픽을 모니터링하고, Kibana나 Splunk 같은 일반적인 모니터링 도구가 수집·보고할 수 있는 표준 감사 로그에 트래픽을 기록할 수 있습니다. 이렇게 수집할 수 있는 이벤트에는 Mattermost 서버 로깅 프로세스가 추적하지 않는 파일 업로드와 다운로드가 포함됩니다.

Mattermost는 NGINX 프록시를 지원합니다.

NGINX 프록시를 사용하는 Mattermost 아키텍처

NGINX 서버 설치

NGINX는 널리 쓰이는 웹 서버로, 인터넷에서 규모가 크고 트래픽이 많은 사이트 상당수를 호스팅하고 있습니다. 대부분의 경우 Apache보다 리소스 효율이 좋으며 웹 서버나 리버스 프록시로 사용할 수 있습니다.

프로덕션 환경에서는 Mattermost의 보안과 성능을 높이기 위해 프록시 서버 사용을 권장합니다.

  • SSL 종료
  • HTTP에서 HTTPS로의 리디렉션
  • :80 포트를 :8065로 매핑
  • 표준 요청 로그

Ubuntu Server에 NGINX 설치

  1. 프록시를 호스팅할 서버에 로그인하고 터미널 창을 엽니다.

  2. NGINX를 설치합니다.

    NGINX는 Ubuntu의 기본 저장소에서 제공되므로 apt 패키징 시스템으로 설치할 수 있습니다. 먼저 최신 패키지 목록에 접근할 수 있도록 로컬 apt 패키지 인덱스를 갱신한 뒤 nginx를 설치합니다.

    sudo apt update
sudo apt install nginx

    절차를 수락하면 apt가 NGINX와 필요한 의존성을 서버에 설치합니다.

  3. 설치를 마치면 필요한 것이 모두 갖춰집니다. 브라우저에서 서버 IP 주소로 접속하면 기본 NGINX 랜딩 페이지가 표시됩니다.

    기본 NGINX 랜딩 페이지 예시.

    이 페이지가 보인다면 웹 서버에 NGINX를 성공적으로 설치한 것입니다. 이 페이지는 서버가 정상 동작 중임을 보여주기 위해 NGINX에 포함되어 있습니다.

    curl http://localhost를 실행해 확인할 수도 있습니다.

    NGINX가 실행 중이라면 다음과 같은 출력이 표시됩니다.

    <!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
.
.
.
<p><em>Thank you for using nginx.</em></p>
</body>
</html>

NGINX 프로세스 관리

웹 서버를 실행했으니 기본적인 관리 명령을 살펴보겠습니다. 모두 명령줄 인터페이스에서 실행합니다.

웹 서버를 중지하려면 sudo systemctl stop nginx를 사용합니다.

중지된 웹 서버를 시작하려면 sudo systemctl start nginx를 사용합니다.

서비스를 중지했다가 다시 시작하려면 sudo systemctl restart nginx를 사용합니다.

단순히 구성만 변경한 경우라면 NGINX는 연결을 끊지 않고 다시 읽어들일 수 있는 경우가 많습니다. 이때는 sudo systemctl reload nginx를 사용합니다.

NGINX는 기본적으로 서버 부팅 시 자동으로 시작되도록 구성되어 있습니다. 이를 원하지 않는다면 sudo systemctl disable nginx로 비활성화할 수 있습니다.

부팅 시 시작하도록 다시 활성화하려면 sudo systemctl enable nginx를 사용합니다.

다음에 할 일

  1. DNS 서버/서비스에서 mattermost.example.com 같은 정규화된 도메인 이름(FQDN)이 NGINX 서버를 가리키도록 매핑합니다.
  2. 인터넷에서 들어오는 연결을 Mattermost 서버로 프록시하도록 NGINX를 구성합니다.

Mattermost 서버용 프록시로 NGINX 구성

NGINX는 /etc/nginx/sites-available 디렉터리의 파일로 구성합니다. 이 파일을 만든 뒤 활성화해야 합니다. 파일을 만들 때는 Mattermost 서버의 IP 주소와 Mattermost 웹사이트의 정규화된 도메인 이름(FQDN)이 필요합니다.

  1. NGINX를 호스팅하는 서버에 로그인하고 터미널 창을 엽니다.

  2. 다음 명령을 실행해 Mattermost용 구성 파일을 만듭니다.

    Ubuntu에서는 sudo touch /etc/nginx/sites-available/mattermost

    RHEL 8에서는 sudo touch /etc/nginx/conf.d/mattermost

  3. /etc/nginx/sites-available/mattermost(Ubuntu) 또는 /etc/nginx/conf.d/mattermost(RHEL 8) 파일을 root 사용자로 텍스트 편집기에서 열고, 내용이 있다면 다음 내용으로 교체합니다. Mattermost 서버 IP 주소와 server_name의 FQDN에는 반드시 사용자 환경의 값을 사용하세요.

제공된 구성 예시에는 SSL과 HTTP/2가 활성화되어 있습니다.

참고
  • Let's Encrypt로 SSL 인증서를 관리할 예정이라면 3단계에서 멈추고 NGINX HTTP/2 및 SSL 제품 문서를 참고하세요.
  • NGINX가 인증서를 올바르게 고정(pin)하려면 유효한 SSL 인증서가 필요합니다. 또한 브라우저가 해당 인증서를 유효한 CA 서명 인증서로 수락할 수 있어야 합니다.
  • 이 문서의 예시에 포함된 IP 주소는 사용자의 네트워크 구성과 다를 수 있습니다.
  • Mattermost와 같은 머신에서 NGINX를 실행하고 있고 NGINX가 localhost를 둘 이상의 IP 주소(IPv4 또는 IPv6)로 해석한다면 localhost 대신 127.0.0.1을 사용하는 것을 권장합니다.
upstream backend {
   server 10.10.10.2:8065;
   keepalive 32;
}

server {
  listen 80 default_server;
  server_name   mattermost.example.com;
  return 301 https://$server_name$request_uri;
}

server {
   listen 443 ssl http2;
   listen [::]:443 ssl http2;
   server_name    mattermost.example.com;

   ssl_certificate /etc/letsencrypt/live/{domain-name}/fullchain.pem;
   ssl_certificate_key /etc/letsencrypt/live/{domain-name}/privkey.pem;
   ssl_session_timeout 1d;

   # Enable TLS versions (TLSv1.3 is required upcoming HTTP/3 QUIC).
   ssl_protocols TLSv1.2 TLSv1.3;

   # Enable TLSv1.3's 0-RTT. Use $ssl_early_data when reverse proxying to
   # prevent replay attacks.
   #
   # @see: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data
   ssl_early_data on;

   ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384';
   ssl_prefer_server_ciphers on;
   ssl_session_cache shared:SSL:50m;
   # HSTS (ngx_http_headers_module is required) (15768000 seconds = six months)
   add_header Strict-Transport-Security max-age=15768000;
   # OCSP Stapling ---
   # fetch OCSP records from URL in ssl_certificate and cache them
   ssl_stapling on;
   ssl_stapling_verify on;

   add_header X-Early-Data $tls1_3_early_data;

   location ~ /api/v[0-9]+/(users/)?websocket$ {
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       client_max_body_size 50M;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Frame-Options SAMEORIGIN;
       proxy_buffers 256 16k;
       proxy_buffer_size 16k;
       client_body_timeout 60s;
       send_timeout 300s;
       lingering_timeout 5s;
       proxy_connect_timeout 90s;
       proxy_send_timeout 300s;
       proxy_read_timeout 90s;
       proxy_http_version 1.1;
       proxy_pass http://backend;
   }

   location / {
       client_max_body_size 100M;
       proxy_set_header Connection "";
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Frame-Options SAMEORIGIN;
       proxy_buffers 256 16k;
       proxy_buffer_size 16k;
       proxy_read_timeout 600s;
       proxy_http_version 1.1;
       proxy_pass http://backend;
   }
}

# This block is useful for debugging TLS v1.3. Please feel free to remove this
# and use the `$ssl_early_data` variable exposed by NGINX directly should you
# wish to do so.
map $ssl_early_data $tls1_3_early_data {
  "~." $ssl_early_data;
  default "";
}

  1. sudo rm /etc/nginx/sites-enabled/default(Ubuntu) 또는 sudo rm /etc/nginx/conf.d/default(RHEL 8)를 실행해 기존 기본 sites-enabled 파일을 제거합니다.

  2. sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost(Ubuntu) 또는 sudo ln -s /etc/nginx/conf.d/mattermost /etc/nginx/conf.d/default.conf(RHEL 8)를 실행해 mattermost 구성을 활성화합니다.

  3. sudo systemctl restart nginx를 실행해 NGINX를 재시작합니다.

  4. curl https://localhost를 실행해 프록시를 통해 Mattermost가 보이는지 확인합니다. 정상이라면 Mattermost 가입 페이지의 HTML이 표시됩니다.

  5. 8065 포트에 대한 접근을 제한합니다.

    기본적으로 Mattermost 서버는 네트워크의 모든 머신에서 8065 포트로 들어오는 연결을 수락합니다. NGINX를 호스팅하는 머신과 Mattermost 서버를 관리하는 데 사용하는 머신을 제외한 모든 머신에 대해 방화벽으로 8065 포트 연결을 차단하세요. Amazon Web Services에 설치한다면 보안 그룹(Security Groups)으로 접근을 제한할 수 있습니다.

이제 NGINX가 설치되어 실행 중이므로 SSL을 사용하도록 구성하면 HTTPS 연결과 HTTP/2 프로토콜을 사용할 수 있습니다.

SSL 및 HTTP/2로 NGINX 구성

NGINX는 /etc/nginx/sites-available 디렉터리의 파일로 구성합니다. 이 파일을 만든 뒤 활성화해야 합니다. 파일을 만들 때는 Mattermost 서버의 IP 주소와 Mattermost 웹사이트의 정규화된 도메인 이름(FQDN)이 필요합니다.

SSL을 사용하면 Mattermost 클라이언트와 Mattermost 서버 간 통신이 암호화되어 보안이 강화됩니다. 또한 NGINX가 HTTP/2 프로토콜을 사용하도록 구성할 수 있습니다.

SSL 없이도 HTTP/2를 구성할 수는 있지만, Firefox와 Chrome 브라우저는 보안 연결에서만 HTTP/2를 지원합니다.

원하는 인증서를 사용해도 되지만, 이 지침에서는 무료 인증 기관인 Let's Encrypt에서 인증서를 내려받아 설치하는 방법을 설명합니다.

참고

Let's Encrypt를 활성화한 경우, Let's Encrypt 인증을 완료하려면 방화벽에서 80 포트를 포워딩하고 config.json의 Forward80To443 설정을 true로 지정해야 합니다. 추가 도움말은 Let's Encrypt/Certbot 문서를 참고하세요.

  1. NGINX를 호스팅하는 서버에 로그인하고 터미널 창을 엽니다.

  2. Mattermost의 nginx.conf 파일을 root 권한으로 텍스트 편집기에서 열고, upstream backend의 {ip} 주소를 Mattermost를 가리키도록(예: 127.0.0.1:8065) 수정한 뒤 server_name을 Mattermost 도메인으로 변경합니다.

    참고
    • Ubuntu에서 이 파일은 /etc/nginx/sites-available/에 있습니다. 파일이 없다면 sudo touch /etc/nginx/sites-available/mattermost를 실행하세요.
    • CentOS/RHEL에서 이 파일은 /etc/nginx/conf.d/에 있습니다. 파일이 없다면 sudo touch /etc/nginx/conf.d/mattermost를 실행하세요.
    • 이 문서의 예시에 포함된 IP 주소는 사용자의 네트워크 구성과 다를 수 있습니다.
    • Mattermost와 같은 머신에서 NGINX를 실행하고 있고 NGINX가 localhost를 둘 이상의 IP 주소(IPv4 또는 IPv6)로 해석한다면 localhost 대신 127.0.0.1을 사용하는 것을 권장합니다.
    upstream backend {
    server {ip}:8065;
    keepalive 32;
    }

server {
    listen 80 default_server;
    server_name mattermost.example.com;

    location ~ /api/v[0-9]+/(users/)?websocket$ {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        client_max_body_size 50M;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Frame-Options SAMEORIGIN;
        proxy_buffers 256 16k;
        proxy_buffer_size 16k;
        client_body_timeout 60s;
        send_timeout 300s;
        lingering_timeout 5s;
        proxy_connect_timeout 90s;
        proxy_send_timeout 300s;
        proxy_read_timeout 90s;
        proxy_pass http://backend;
    }

    location / {
        client_max_body_size 50M;
        proxy_set_header Connection "";
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Frame-Options SAMEORIGIN;
        proxy_buffers 256 16k;
        proxy_buffer_size 16k;
        proxy_read_timeout 600s;
        proxy_http_version 1.1;
        proxy_pass http://backend;
    }
}

  3. sudo rm /etc/nginx/sites-enabled/default(Ubuntu) 또는 sudo rm /etc/nginx/conf.d/default(RHEL 8)를 실행해 기존 기본 sites-enabled 파일을 제거합니다.

  4. sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost(Ubuntu) 또는 sudo ln -s /etc/nginx/conf.d/mattermost /etc/nginx/conf.d/default.conf(RHEL 8)를 실행해 Mattermost 구성을 활성화합니다.

  5. sudo nginx -t를 실행해 구성이 올바른지 확인합니다. 오류가 발생하면 NGINX 구성을 확인하고 /etc/nginx/sites-available/mattermost 파일을 필요에 맞게 수정하세요.

  6. sudo systemctl start nginx를 실행해 NGINX를 재시작합니다.

  7. curl http://localhost를 실행해 프록시를 통해 Mattermost가 보이는지 확인합니다.

    정상이라면 Mattermost 가입 페이지의 HTML이 표시됩니다. IP나 localhost로 접근하면 인증서가 유효하지 않다고 표시됩니다. SSL 인증서가 올바르게 고정되고 유효한지 확인하려면 전체 FQDN 도메인을 사용하세요.

  8. sudo snap install core; sudo snap refresh core를 실행해 Snap을 설치하고 업데이트합니다.

  9. sudo snap install --classic certbot을 실행해 Certbot 패키지를 설치합니다.

  10. sudo ln -s /snap/bin/certbot /usr/bin/certbot을 실행해 Certbot을 실행할 수 있도록 심볼릭 링크를 추가합니다.

  11. sudo certbot certonly --dry-run을 실행해 Let's Encrypt 설치 관리자를 시험 실행하고 DNS가 올바르게 구성되었는지 확인합니다.

    이 과정에서 이메일 입력, 이용 약관 동의, 이메일 공유 여부 선택, certbot을 활성화할 도메인 선택을 요청받습니다. 이를 통해 DNS가 이 서버를 올바르게 가리키는지, 인증서를 정상적으로 생성할 수 있는지 검증합니다. 성공적으로 끝나면 12단계로 진행하세요.

  12. sudo certbot을 실행해 Let's Encrypt 설치 관리자를 실행합니다. certbot이 실행되며 선택한 사이트의 NGINX 구성 파일을 자동으로 편집합니다.

  13. curl https://{your domain here}를 실행해 SSL이 올바르게 구성되었는지 확인합니다.

  14. 마지막으로 구성 파일을 다시 편집해 Let's Encrypt 기본값보다 SSL 보안 설정을 강화하는 것을 권장합니다. 위 2단계와 동일한 파일이며, 아래와 같이 편집합니다.

    upstream backend {
    server {ip}:8065;
   keepalive 32;
    }

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;

server {
    server_name mattermost.example.com;

    location ~ /api/v[0-9]+/(users/)?websocket$ {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        client_max_body_size 50M;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Frame-Options SAMEORIGIN;
        proxy_buffers 256 16k;
        proxy_buffer_size 16k;
        client_body_timeout 60s;
        send_timeout 300s;
        lingering_timeout 5s;
        proxy_connect_timeout 90s;
        proxy_send_timeout 300s;
        proxy_read_timeout 90s;
        proxy_http_version 1.1;
        proxy_pass http://backend;
    }

    location / {
        client_max_body_size 50M;
        proxy_set_header Connection "";
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Frame-Options SAMEORIGIN;
        proxy_buffers 256 16k;
        proxy_buffer_size 16k;
        proxy_read_timeout 600s;
        proxy_http_version 1.1;
        proxy_pass http://backend;
    }

    listen 443 ssl http2; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/mattermost.example.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/mattermost.example.com/privkey.pem; # managed by Certbot
    # include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

    ssl_session_timeout 1d;

    # Enable TLS versions (TLSv1.3 is required upcoming HTTP/3 QUIC).
    ssl_protocols TLSv1.2 TLSv1.3;

    # Enable TLSv1.3's 0-RTT. Use $ssl_early_data when reverse proxying to
    # prevent replay attacks.
    #
    # @see: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data
    ssl_early_data on;

    ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:50m;
    # HSTS (ngx_http_headers_module is required) (15768000 seconds = six months)
    add_header Strict-Transport-Security max-age=15768000;
    # OCSP Stapling ---
    # fetch OCSP records from URL in ssl_certificate and cache them
    ssl_stapling on;
    ssl_stapling_verify on;
}


server {
    if ($host = mattermost.example.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    listen 80 default_server;
    server_name mattermost.example.com;
    return 404; # managed by Certbot

}

  15. SSL 인증서가 올바르게 설정되었는지 확인합니다.

    • https://www.ssllabs.com/ssltest/index.html 같은 사이트에서 SSL 인증서를 테스트하세요.
    • 체인이나 인증서 경로가 누락되었다는 오류가 발생한다면 포함되어야 할 중간 인증서가 빠져 있을 가능성이 높습니다.

고성능 확장 구성

여러 대의 Mattermost 서버와 높은 트래픽 부하를 다루는 대규모 배포에서는 추가적인 NGINX 최적화를 권장합니다. 이 구성은 대규모 Mattermost 배포에 대한 성능 테스트를 바탕으로 합니다.

참고

이 설정은 고성능 환경을 위한 것입니다. 일반적인 배포에는 위의 기본 구성으로 충분합니다.

NGINX 기본 구성 최적화

NGINX 기본 구성 파일(/etc/nginx/nginx.conf)을 다음과 같은 성능 최적화 설정으로 갱신합니다.

user www-data;
worker_processes auto;
worker_rlimit_nofile 100000;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

events {
  worker_connections 20000;
  use epoll;
}

http {
  map $status $loggable {
    ~^[23] 0;
    default 1;
  }

  sendfile on;
  tcp_nopush on;
  tcp_nodelay off;
  keepalive_timeout 75s;
  keepalive_requests 16384;
  types_hash_max_size 2048;
  include /etc/nginx/mime.types;
  default_type application/octet-stream;
  ssl_prefer_server_ciphers on;
  access_log /var/log/nginx/access.log combined if=$loggable;
  error_log /var/log/nginx/error.log;
  gzip on;
  include /etc/nginx/sites-enabled/*;
}

이 구성의 주요 최적화 항목은 다음과 같습니다.

  • worker_processes auto: CPU 코어 수에 맞춰 워커 프로세스 수를 자동으로 설정합니다.
  • worker_rlimit_nofile 100000: 높은 동시성을 위해 파일 디스크립터 한계를 늘립니다.
  • worker_connections 20000: 각 워커가 더 많은 동시 연결을 처리할 수 있게 합니다.
  • use epoll: Linux에서 효율적인 연결 처리를 활성화합니다.
  • keepalive_timeout 75s와 keepalive_requests 16384: 연결 재사용을 최적화합니다.
  • 조건부 로깅: 오류와 2xx/3xx 이외의 응답만 기록해 로그 양을 줄입니다.

다중 노드 백엔드 구성

Mattermost 애플리케이션 서버가 여러 대인 배포에서는 사이트 파일(/etc/nginx/sites-available/mattermost)에 부하 분산을 구성합니다.

upstream backend {
  server 172.27.205.186:8065 max_fails=0;
  server 172.27.213.167:8065 max_fails=0;
  # Add additional Mattermost servers as needed

  keepalive 256;
}

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=60m use_temp_path=off;

server {
  listen 80 reuseport;
  server_name _;

  location ~ /api/v[0-9]+/(users/)?websocket$ {
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    include /etc/nginx/snippets/proxy.conf;
  }

  location ~ /api/v[0-9]+/users/[a-z0-9]+/image$ {
    proxy_set_header Connection "";
    include /etc/nginx/snippets/proxy.conf;
    include /etc/nginx/snippets/cache.conf;
    proxy_ignore_headers Cache-Control Expires;
    proxy_cache_valid 200 24h;
  }

  location / {
    proxy_set_header Connection "";
    include /etc/nginx/snippets/proxy.conf;
    include /etc/nginx/snippets/cache.conf;
  }
}

NGINX 프록시 구성 스니펫

여러 location에서 재사용할 수 있도록 최적화된 프록시 구성 스니펫을 만듭니다.

/etc/nginx/snippets/proxy.conf를 생성합니다.

client_max_body_size 50M;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Frame-Options SAMEORIGIN;
proxy_buffers 256 16k;
proxy_buffer_size 16k;
client_body_timeout 60s;
send_timeout 300s;
lingering_timeout 5s;
proxy_connect_timeout 30s;
proxy_send_timeout 90s;
proxy_read_timeout 90s;
proxy_http_version 1.1;
proxy_pass http://backend;

/etc/nginx/snippets/cache.conf를 생성합니다.

proxy_cache mattermost_cache;
proxy_cache_revalidate on;
proxy_cache_min_uses 2;
proxy_cache_use_stale timeout;
proxy_cache_lock on;

주요 성능 최적화

고성능 구성에는 다음과 같은 핵심 최적화가 포함됩니다.

부하 분산:

  • max_fails=0: 서버가 사용 불가 상태로 표시되는 것을 방지합니다.
  • keepalive 256: 백엔드 서버와의 지속 연결을 유지합니다.
  • reuseport: 여러 워커 프로세스가 같은 포트에 바인딩할 수 있게 합니다.

캐싱 전략:

  • 사용자 이미지 24시간 캐싱: 정적 콘텐츠에 대한 애플리케이션 서버 부하를 줄입니다.
  • 캐시 재검증: 성능을 유지하면서 콘텐츠를 최신 상태로 보장합니다.
  • 캐시 잠금: 캐시 스탬피드 상황을 방지합니다.

버퍼 및 타임아웃 최적화:

  • proxy_buffers 256 16k: 높은 처리량의 데이터 전송을 효율적으로 처리합니다.
  • 타임아웃 최적화: 응답성과 리소스 사용 사이의 균형을 맞춥니다.
  • HTTP/1.1 keepalive: 연결 오버헤드를 줄입니다.

리소스 한계:

  • 50M client_max_body_size: 대용량 파일 업로드를 수용합니다.
  • 파일 디스크립터 한계 상향: 높은 동시성 시나리오를 지원합니다.

구현 시 참고 사항

  1. IP 주소 교체: 백엔드 서버 IP(172.27.205.186, 172.27.213.167)를 실제 Mattermost 서버 주소로 변경하세요.

  2. 캐시 디렉터리 생성: 캐시 디렉터리가 존재하고 적절한 권한을 갖고 있는지 확인하세요.

    sudo mkdir -p /var/cache/nginx
sudo chown -R www-data:www-data /var/cache/nginx

  3. 구성 테스트: 적용 전에 항상 구성을 테스트하세요.

    sudo nginx -t

  4. 성능 모니터링: NGINX 접근 로그와 모니터링 도구로 성능 개선 효과를 확인하세요.

  5. 점진적 확장: 이러한 최적화를 단계적으로 적용하고 배포 환경에 미치는 영향을 관찰하세요.

NGINX 구성 FAQ

"Too many redirects" 오류가 표시되는 이유는 무엇인가요?

Mattermost를 하위 경로(sub-path)에 설정한 경우 이 오류가 표시될 수 있습니다. 해결하려면 HEAD 요청에 다음 블록을 추가하세요.

location ~* ^/sub-path {
    client_max_body_size 250M;
    proxy_set_header Connection "";

    if ($request_method = HEAD) {
        return 200;
    }
}

WebSocket 연결이 403 오류를 반환하는 이유는 무엇인가요?

교차 출처(cross-origin) 검사에 실패했을 가능성이 높습니다. WebSocket 코드에서는 Origin 헤더가 host 헤더와 동일한지 검사하며, 다르면 403 오류를 반환합니다. /etc/nginx/sites-available/mattermost 파일을 root 권한으로 텍스트 편집기에서 열고, 프록시에서 설정하는 host 헤더가 동적으로 지정되어 있는지 확인하세요.

location ~ /api/v[0-9]+/(users/)?websocket$ {
  proxy_pass            http://backend;
  (...)
  proxy_set_header      Host $host;
  proxy_set_header      X-Forwarded-For $remote_addr;
}

그런 다음 config.json에서 AllowCorsFrom 설정을 클라이언트가 사용하는 도메인에 맞게 지정합니다. 클라이언트가 보낼 수 있는 호스트 이름의 변형을 추가해야 할 수도 있습니다. NGINX 로그가 문제를 진단하는 데 도움이 됩니다.

"EnableUserAccessTokens": false,
"AllowCorsFrom": "domain.com domain.com:443 im.domain.com",
"SessionLengthWebInDays": 30,

Mattermost Docker 설치에서 NGINX 프록시를 설정하려면 어떻게 하나요?

  1. Mattermost 네트워크의 이름을 찾아 NGINX 프록시에 연결합니다.

    docker network ls
# Grep the name of your Mattermost network like "mymattermost_default".
docker network connect mymattermost_default nginx-proxy

  2. Mattermost Docker 컨테이너를 재시작합니다.

    docker-compose stop app
docker-compose start app
    팁

    NGINX 프록시가 수신 요청을 처리하므로 'web' 컨테이너를 실행할 필요는 없습니다.

  3. docker-compose.yml 파일에 새 환경 변수 VIRTUAL_HOST와 expose 지시문을 추가합니다.

    environment:
  # set same as db credentials and dbname
  - MM_USERNAME=mmuser
  - MM_PASSWORD=mmuser-password
  - MM_DBNAME=mattermost
  - VIRTUAL_HOST=mymattermost.tld
expose:
  - "80"
  - "443"

Azure에서 Mattermost와 함께 GitLab CE를 설치할 때 NGINX가 실패하는 이유는 무엇인가요?

GitLab 인스턴스 내 Mattermost 애플리케이션 항목의 콜백 URL을 갱신해야 할 수 있습니다.

  1. 관리자 계정으로 GitLab 인스턴스에 로그인합니다.
  2. Admin > Applications로 이동합니다.
  3. GitLab-Mattermost에서 Edit를 선택합니다.
  4. 콜백 URL을 새 도메인/URL로 갱신합니다.
  5. 변경 사항을 저장합니다.
  6. /etc/gitlab/gitlab.rb 구성 파일에서 GitLab과 Mattermost의 외부 URL을 갱신합니다.

Certbot이 http-01 챌린지에 실패하는 이유는 무엇인가요?

Requesting a certificate for yourdomain.com
Performing the following challenges:
http-01 challenge for yourdomain.com
Waiting for verification...
Challenge failed for domain yourdomain.com
http-01 challenge for yourdomain.com
Cleaning up challenges
Some challenges have failed.

위와 같은 오류가 보인다면 대개 Certbot이 80 포트에 접근하지 못했기 때문입니다. 방화벽이나 다른 DNS 구성이 원인일 수 있습니다. A/AAAA 레코드가 이 서버를 가리키는지, NGINX 구성의 server_name에 리디렉션이 걸려 있지 않은지 확인하세요.

참고

Cloudflare를 사용한다면 force traffic to https를 비활성화해야 합니다.

Certbot 요청 제한

certbot을 독립 실행형으로 운영한다면 다음 오류가 표시됩니다.

Error: Could not issue a Let's Encrypt SSL/TLS certificate for example.com.
One of the Let's Encrypt rate limits has been exceeded for example.com.
See the related Knowledge Base article for details.
Details
Invalid response from https://acme-v02.api.letsencrypt.org/acme/new-order.
Details:
Type: urn:ietf:params:acme:error:rateLimited
Status: 429
Detail: Error creating new order :: too many failed authorizations recently: see https://letsencrypt.org/docs/rate-limits/

Mattermost 내부에서 Let's Encrypt를 사용한다면 다음 오류가 표시됩니다.

{"level":"error","ts":1609092001.752515,"caller":"http/server.go:3088","msg":"http: TLS handshake error from ip:port: 429 urn:ietf:params:acme:error:rateLimited: Error creating new order :: too many failed authorizations recently: see https://letsencrypt.org/docs/rate-limits/","source":"httpserver"}

이는 인증서를 너무 여러 번 생성하려고 시도했다는 뜻입니다. 자세한 내용은 여기에서 확인할 수 있습니다.