리눅스 Nginx 서버 구축 및 Vue 프로젝트 빌드 방법

2025-08-21

리눅스 Nginx 설치 시 참고
https://nginx.org/en/linux_packages.html
Nginx 공식 홈페이지에서 리눅스 OS 종류별 Nginx 웹서버 설치 방법을 자세히 알려주고 있습니다.

우분투 Nginx 서버 설치 방법 (인터넷O)

인터넷이 가능한 서버에서만 가능한 방법입니다.

Nginx 저장소 필수 패키지 설치

sudo apt install curl gnupg ca-certificates lsb-release ubuntu-keyring

nginx 저장소 추가 시 필요한 필수 패키지들을 다운로드하여 준비합니다.

Nginx 공식 서명 키 등록

curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
    | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

Nginx 패키지가 공식 저장소 nginx.org에서 서명한 것인지 검증하기 위해 GPG 서명 키를 다운로드해서 저장합니다.
GPG 키를 등록하지 않으면, apt가 보안상 믿을 수 없다고 설치를 거부하게 됩니다.

GPG 서명 키 검증

gpg --dry-run --quiet --no-keyring --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg

방금 받은 서명 키가 nginx.org에서 제공한 키인지 확인합니다.

573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62

위와 같은 출력이 포함되면 정상 키입니다.

Nginx 공식 저장소 추가

Stable 버전 추가 명령어

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

최신이 아닐 수 있지만, 안정적인 버전의 Nginx 저장소를 추가합니다.

Mainline 버전 추가 명령어

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/mainline/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

실험적일 수 있지만, 최신 버전의 Nginx 저장소를 추가합니다.

Pinning 설정

echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
    | sudo tee /etc/apt/preferences.d/99nginx

Ubuntu 기본 저장소에 있는 Nginx가 아니라, nginx.org 저장소에서 받은 패키지를 우선 설치하도록 설정합니다.

NginX 설치

sudo apt update
sudo apt install nginx

apt update 명령어로 추가된 저장소 목록을 최신화 후, Nginx를 설치합니다.

우분투 Nginx 서버 설치 방법 (인터넷X)

인터넷 연결이 불가한 운영서버에서 Nginx를 설치하는 방법입니다.

Nginx 설치 패키지 파일 다운로드

https://nginx.org/packages/ubuntu/pool/nginx/n/nginx
위 링크는 nginx 공식 패키지 저장소에서 우분투 nginx 패키지가 모여 있는 풀 디렉토리입니다.
리눅스 OS 버전 및 CPU 종류에 맞는 Nginx 설치 패키지 파일을 다운로드 합니다.
nginx-dbg 파일은 개발 및 디버깅용이므로, nginx_1.28.0-1~noble_amd64.deb 같은 파일을 받아야 합니다.

Nginx 설치

cd /deb파일위치
sudo apt install ./nginx_1.28.0-1~noble_amd64.deb

윈도우에서 다운받은 Nginx 설치 패키지 deb 파일을 파일질라로 서버에 올리고 설치합니다.
dpkg -i 명령어와 달리, apt i 명령어는 .deb 파일 의존성도 자동으로 설치됩니다.

파일 접근 권한 관련 에러 메시지

N: Download is performed unsandboxed as root as file '/home/ncloud/insatall/nginx_1.28.0-1~noble_amd64.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)

위와 같은 에러가 발생해도 Nginx 설치 및 동작에는 영향이 없으므로 무시해도 됩니다.

Nginx 설치 확인

nginx -v
또는
sudo systemctl status nginx

nginx 설치가 정상적으로 되었는지 확인할 수 있습니다.

Nginx 서버 실행 및 종료

Nginx 서버 실행

systemctl start nginx

Nginx 실행파일 위치 확인

which nginx

일반적으로 /usr/sbin/nginx 폴더에 nginx 실행파일이 저장됩니다.

nginx 기본 페이지 확인

curl -i http://localhost:80

현재 리눅스 서버에서 실행중인 Nginx에 HTTP 요청을 보내서 기본 HTML을 확인할 수 있습니다.

Nginx 서버 종료

systemctl stop nginx

Nginx 서버 자동시작 설정

systemctl enable nginx

Nginx 서버 자동시작 여부 확인

systemctl is-enabled nginx

enable라고 나오면 리눅스 서버 재기동 시 Nginx 서버도 자동시작됩니다.

Nginx 서버 설정

Nginx 설정파일 종류

/etc/nginx/nginx.conf	Nginx 메인 설정 파일 Nginx 실행 시 가장 먼저 읽는 설정입니다.
/etc/nginx/conf.d/*.conf	공통 설정 또는 추가 서버 설정 파일 Ubuntu 보다는 CentOS 계열에서 주로 사용합니다. 해당 파일은 없어도 정상 동작합니다.
/etc/nginx/sites-available/도메인명	사이트별 가상호스트 설정 파일 (원본)
/etc/nginx/sites-enabled/도메인명	활성화된 사이트 설정 파일 (심볼릭 링크) Nginx가 실제로 참조하는 파일입니다.

Ubuntu 계열 Nginx 디렉토리 구조입니다.

Nginx 메인 설정 파일 수정

vi /etc/nginx/nginx.conf

아래처럼, nginx.conf 파일 http 블록에 활성화된 사이트 설정 파일 폴더 include를 추가합니다.

user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;
pid        /run/nginx.pid;

events {
  worker_connections  1024;
}

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

  log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

  access_log  /var/log/nginx/access.log  main;

  sendfile        on;
  #tcp_nopush     on;

  keepalive_timeout  65;

  #gzip  on;

  include /etc/nginx/conf.d/*.conf;
  include /etc/nginx/sites-enabled/*;
}

sites-enabled 폴더가 실제 사이트별 설정 파일이 위치하는 곳입니다.

기본 서버 블록 삭제

cd /etc/nginx/conf.d
rm -rf default.conf

nginx 설치 시 자동으로 생성되는 기본 서버 블록을 삭제합니다.
curl localhost:80 시 Nginx welcom 페이지가 나오도록 설정된 파일입니다.

사이트별 설정 파일 폴더 생성

mkdir /etc/nginx/sites-available
mkdir /etc/nginx/sites-enabled

nginx 설치 시 위 폴더들이 생성되지 않은 경우, 직접 생성해 줍니다.

사이트별 설정 파일 작성

cd /etc/nginx/sites-available
vi Vue서버도메인명.co.kr

Vue 사이트 Nginx 설정을 아래와 같이 작성합니다.

server {
  # 서버에서 받을 요청 설정
  listen 80; # 생략 가능 (기본값 : 80)
  server_name localhost Vue서버도메인명.co.kr; # 생략 가능, 여러 도메인 처리 가능

  # Vue.js 정적 파일 서빙 설정
  root /var/www/프로젝트명_current;
  index index.html;

  # 모든 경로 요청이 index.html로 넘어가 Vue 라우터가 처리
  location / {
      try_files $uri $uri/ /index.html;
  }

  # 백엔드 서버 프록시 설정
  location /api/ { # 현재 서버 URL 뒤 /api/ 요청이 들어오면,
    proxy_pass http://127.0.0.1:8087; # 현재 서버에 8087 포트로 실행 중인 스프링부트 백엔드 서버로 연결
    proxy_redirect off;
    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-NginX-Proxy true;
    client_max_body_size 10m;
  }

  # 웹소켓 백엔드 서버 프록시 설정
  location /socket.io/ { # 현재 서버 URL 뒤 /socket.io/ 요청이 들어오면,
    proxy_pass https://프로젝트명-websocket.도메인명.co.kr:8082; # 웹소켓 서버용 도메인으로 연결 (로드밸런서로 이중화)
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_redirect off;

    proxy_buffers 8 32k;
    proxy_buffer_size 64k;

    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host;
    proxy_set_header X-NginX-Proxy true;
  }
}

Nginx 기본 웹 루트 폴더 /var/www/html는 다른 폴더로 변경이 가능합니다.
‘root /var/www/프로젝트명_current’으로 작성하면 됩니다.

server_name이 없는 서버 블록은 default 서버 블록으로 취급됩니다.
클라이언트 요청 시 Host 헤더가 server_name과 매칭되는 서버 블록이 없으면,
Nginx는 default 서버 블록으로 요청을 처리합니다.

Nginx 전체 서버 블록 확인 방법

sudo nginx -T | grep -A 10 server

현재 Nginx에 적용된 서버 블록 목록을 확인해볼 수 있습니다.

사이트별 설정 파일 복사 (활성화)

cp Vue서버도메인명.co.kr /etc/nginx/sites-enabled

sites-available 폴더에 작성한 파일을 sites-enabled 폴더에도 복사합니다.
심볼릭 링크 방식이 보안 조치로 막히는 운영서버에서는 파일 복사하여 사용해야 합니다.

심볼릭 링크 방식 사용 시

ln -s /etc/nginx/sites-available/Vue서버도메인명.co.kr /etc/nginx/sites-enabled/

위와 같이, 원본 파일을 가리키는 심볼릭 링크를 sites-enabled 폴더에 생성하면 됩니다.

Nginx 설정 적용

sudo systemctl reload nginx

리눅스 서비스 매니저 systemd를 통해 현재 실행 중인 Nginx 서비스에 reload 명령을 전달합니다.
이제 Vue 프로젝트를 배포하면, http://서버도메인또는IP 접속 시 Vue 앱이 나오게 됩니다.

Nginx 설정 문법 정상 확인

sudo nginx -t

아래와 같은 메시지가 나오면, Nginx 설정 파일이 정상적으로 작성된 것입니다.

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

Vue 프로젝트 빌드 및 배포 방법

Vue 프로젝트 빌드 스크립트 작성

"scripts": {
  "build": "vite build",
  "dev-build": "vite build --mode development",
}

Vue 프로젝트 package.json 파일 스크립트에 위와 같이 운영 빌드, 개발 빌드 스크립트를 작성합니다.
mode 옵션은 빌드 시 사용할 환경변수 .env 파일을 지정하는 용도입니다.
mode를 지정하지 않으면, production 모드로 자동 설정됩니다.

Vue 프로젝트 빌드 명령어

npm run build(스크립트명)

프로젝트 빌드 시 .vue 파일들이 정적 HTML, JS, CSS 파일로 변환되어 dist 폴더에 생성됩니다.
적용된 .env 파일 환경변수 값은 import 된 JS 소스에서 확인할 수 있습니다.

dist 폴더 압축 후 서버 업로드

로컬에서 dist 폴더를 zip 파일로 압축 후, 파일질라로 리눅스 서버에 올립니다.

dist 폴더 압축 해제

cd /파일업로드경로
unzip dist.zip -d /var/www/프로젝트명_v버전명

위 명령어로 압축을 해제하여 신규 배포 폴더를 생성합니다.
-d 옵션으로 지정한 폴더가 없으면 자동 생성됩니다.

심볼릭 링크 생성 및 교체

ln -sfn /var/www/프로젝트명_v버전명 /var/www/프로젝트명_current

웹 루트 폴더로 접근하면 실제 파일이 있는 폴더로 연결되는 심볼릭 링크를 생성합니다.
fn 옵션으로 인해 같은 이름의 심볼릭링크가 있으면 덮어쓰기 됩니다.

Nginx 설정 재적용 및 워커 재로드

sudo nginx -s reload

Nginx는 웹 루트로 설정된 심볼릭 링크 경로를 계속 참조하므로, Nginx 재시작 없이도 신규 소스가 반영됩니다.
그러나, Nginx 워커가 이미 열고 있는 파일도 최신 파일로 반영하려면 reload 하는 것이 좋습니다.
Nginx 마스터 프로세스가 설정 파일을 다시 읽고, 새로운 워커 프로세스가 띄워집니다.
기존 워커가 기존 연결을 모두 처리한 뒤 종료되므로 사용자 접속 끊김이 거의 없는 방식입니다.

기존 배포 폴더 삭제

cd /var/www
rm -rf 프로젝트명_v기존버전명

신규 배포 후 안정화 기간이 지나도 문제가 없는 경우, 기존 배포 폴더는 삭제하는 것이 권장됩니다.