내부망 서버에서 Docker로 Node.js 배포하기 – npm_cache.tar.gz 활용법

date

Aug 10, 2025

slug

offline-npm-deploy-with-cache

author

status

Public

문제 상황

내부망 서버는 아웃바운드가 차단되어 있음

node_modules는 .gitignore로 인해 배포 대상이 아님

로컬에서 package.json 또는 package-lock.json이 변경되어 패키지 재설치 필요

하지만 빌드 서버에서는 npm install이 외부 접근 불가로 인해 실패

해결 방법: NPM 캐시 아카이브 만들기

0. 캐시 웜업

오프라인 설치가 성공하려면 필요한 버전의 패키지 tarball이 캐시에 모두 들어 있어야 합니다. 외부 네트워크가 되는 환경(로컬/별도 빌드 머신)에서 먼저:


npm ci

한 번 설치해 두면, 해당 시점의 lockfile 기준으로 필요한 tarball이 캐시에 채워집니다.

1. NPM 캐시 위치 확인

CLI로 정확한 캐시 경로를 받는 것이 가장 안전합니다.


npm config get cache

2. 캐시를 `.tar.gz`로 압축

Windows 10 이상은 기본 tar.exe가 있습니다.


$cache = (npm config get cache).Trim()
tar -czf npm_cache.tar.gz -C "$cache" .

Linux / macOS 예시


tar -czf npm_cache.tar.gz -C "$(npm config get cache)" .

위 명령은 캐시 디렉터리의 내용물만 루트에 담긴 npm_cache.tar.gz를 생성합니다.

3. Dockerfile에서 캐시 적용하기

npm_cache.tar.gz를 Docker 빌드 컨텍스트에 포함한 뒤, 캐시를 지정 경로에 풀어 npm ci를 오프라인 우선으로 실행합니다.


1) 캐시 주입
COPY npm_cache.tar.gz /tmp/npm_cache.tar.gz
RUN mkdir -p /root/.npm && tar -xzf /tmp/npm_cache.tar.gz -C /root/.npm

2) NPM 설정
ENV npm_config_cache=/root/.npm

3) 의존성 설치
COPY package*.json ./
RUN npm ci --prefer-offline --no-audit --progress=false

npm_config_cache를 설정하면 npm이 해당 경로를 캐시 디렉터리로 사용합니다. --prefer-offline은 캐시 우선 사용을 유도합니다. (캐시에 없으면 네트워크를 시도하므로, 웜업이 필수)

장점

외부 NPM 레지스트리 접근 없이 의존성 설치가 가능

node_modules를 직접 포함하지 않아 OS 차이로 인한 문제를 줄임

패키지 변경이 있을 때 캐시만 교체

대안 비교

방법	설명	장점	단점
`node_modules` 포함	완전한 의존성 포함	바로 실행 가능	OS/환경 차이로 호환성 문제 가능
내부 NPM 레지스트리	verdaccio, Nexus 등 운영	외부 접근 불필요, 안정적 관리 가능	별도 서버 유지보수 필요
npm_cache.tar.gz	캐시 기반 설치	설정만 하면 빠른 설치	캐시 경로, 버전 동기화 필요

`npm install` vs `npm ci` 차이

항목	`npm install`	`npm ci`
목적	개발 중 패키지 추가/변경	CI/CD 환경에서 빠르고 일관된 설치
`package-lock.json`	없으면 생성, 있어도 무시 가능	반드시 존재해야 하며, lock 파일 기준으로 설치
속도	느릴 수 있음 (의존성 재해석)	빠름 (lock 파일 기준 설치)
신뢰성	개발 환경마다 결과 다를 수 있음	항상 동일한 환경 보장
`node_modules` 처리	유지	자동 삭제 후 재설치

Docker 빌드나 CI/CD 환경에서는 npm ci 사용을 권장합니다.

사용 시 주의사항

1. Node.js 버전 맞추기

캐시는 Node.js 버전에 따라 호환되지 않을 수 있으므로, 로컬과 서버의 Node 버전을 맞춥니다.

2. .dockerignore 확인

npm_cache.tar.gz가 .dockerignore에 포함되어 있지 않도록 합니다.

3. 패키지 동기화

package-lock.json과 캐시 내용이 다르면 외부 요청이 발생할 수 있으므로 주기적으로 갱신합니다.

마무리

보안 환경에서는 npm install조차 장애 요인이 될 수 있습니다. 하지만 NPM 캐시를 미리 아카이브하고 Docker 빌드 시 적용하면, 외부 의존성 없이도 안정적인 배포가 가능합니다. 이는 CI/CD 환경뿐 아니라 오프라인 서버 배포에도 효과적으로 활용할 수 있습니다.