시놀로지 WebStation Node.js 볼륨 마운트 오류 해결 가이드

시놀로지 WebStation Node.js 볼륨 마운트 오류 해결 가이드

📋 개요

시놀로지 WebStation에서 Node.js 애플리케이션을 배포할 때 발생하는 "Cannot find module" 오류의 근본적인 해결 방법을 다룹니다. 이 문제는 WebStation의 Docker 볼륨 마운트 경로와 Dockerfile의 작업 디렉토리 불일치에서 발생합니다.

🚨 문제 증상

발생하는 오류

Error: Cannot find module '/home/node/app.js'
MODULE_NOT_FOUND

원인 분석

• Docker Compose: 볼륨을 /home/node/src로 마운트
• Dockerfile: 작업 디렉토리가 /home/node로 설정
• 결과: 애플리케이션 파일을 찾을 수 없어서 컨테이너가 즉시 종료

🔧 해결 방법

1단계: SSH 접속 활성화

DSM 관리자 패널에서:

1. 제어판 → 터미널 및 SNMP
2. SSH 서비스 활성화 체크
3. 포트: 22 (기본값)
4. 적용 클릭

SSH 접속:

ssh admin@[NAS_IP주소]
# 예: ssh admin@192.168.1.100

2단계: 관리자 권한 획득

sudo -i
# 또는
sudo su -

3단계: WebStation Node.js 템플릿 파일 찾기

# Node.js Dockerfile 템플릿 위치 확인
ls -la /var/packages/WebStation/target/misc/node_dockerfile.mustache

# Docker Compose 템플릿 위치 확인
ls -la /var/packages/WebStation/target/misc/node_docker_compose.mustache

4단계: 현재 템플릿 내용 확인

cat /var/packages/WebStation/target/misc/node_dockerfile.mustache

기존 문제가 있는 템플릿:

FROM {{image_full_name}}

RUN mkdir -p /home/node
WORKDIR /home/node
RUN useradd -u {{user_id}} {{user}}

COPY package.json /home/node/
RUN npm install

ENV NODE_PATH /home/node/node_modules

cat /var/packages/WebStation/target/misc/node_docker_compose.mustache

Docker Compose 템플릿:

version: "2"
services:
    node:
        build: .
        volumes:
            - {{project_root}}:/home/node/src  # 여기가 문제!
        command: {{script_settings.command}}

5단계: 템플릿 백업

# 기존 템플릿 백업
cp /var/packages/WebStation/target/misc/node_dockerfile.mustache /var/packages/WebStation/target/misc/node_dockerfile.mustache.backup

6단계: Dockerfile 템플릿 수정

방법 1: vi 편집기 사용

vi /var/packages/WebStation/target/misc/node_dockerfile.mustache

1. i 키를 누르고 편집 모드로 전환
2. 다음과 같이 수정:
   • RUN mkdir -p /home/node → RUN mkdir -p /home/node/src
   • WORKDIR /home/node → WORKDIR /home/node/src
   • COPY package.json /home/node/ → COPY package.json /home/node/src/
   • ENV NODE_PATH /home/node/node_modules → ENV NODE_PATH /home/node/src/node_modules
3. ESC 키 누르고 :wq 입력 후 Enter

방법 2: echo 명령어 사용

echo 'FROM {{image_full_name}}

RUN mkdir -p /home/node/src
WORKDIR /home/node/src
RUN useradd -u {{user_id}} {{user}}

COPY package.json /home/node/src/
RUN npm install

ENV NODE_PATH /home/node/src/node_modules' > /var/packages/WebStation/target/misc/node_dockerfile.mustache

7단계: 수정 확인

cat /var/packages/WebStation/target/misc/node_dockerfile.mustache

올바르게 수정된 템플릿:

FROM {{image_full_name}}

RUN mkdir -p /home/node/src
WORKDIR /home/node/src
RUN useradd -u {{user_id}} {{user}}

COPY package.json /home/node/src/
RUN npm install

ENV NODE_PATH /home/node/src/node_modules

8단계: 기존 환경 정리

# 기존 Docker 컨테이너/이미지 정리
docker ps -a | grep your_project_name
docker rm -f $(docker ps -a | grep your_project_name | awk '{print $1}') 2>/dev/null
docker rmi -f $(docker images | grep your_project_name | awk '{print $3}') 2>/dev/null
docker system prune -af

# 기존 Node.js 프로필 정리 (선택사항)
rm -rf /volume1/@appconf/WebStation/node_profile/*/

9단계: 권한 설정 및 종료

# 템플릿 파일 권한 설정
chmod 644 /var/packages/WebStation/target/misc/node_dockerfile.mustache
chown root:root /var/packages/WebStation/target/misc/node_dockerfile.mustache

# SSH 세션 종료
exit

🚀 WebStation에서 프로젝트 재생성

1단계: 기존 프로젝트 삭제

1. WebStation 관리 패널 접속
2. 기존 Node.js 웹사이트 완전 삭제

2단계: 새 프로젝트 생성

1. 새 웹사이트 생성
2. 컨테이너화된 스크립트 언어 웹사이트 선택
3. Node.js 선택 (적절한 버전)
4. 프로젝트 설정:
   • 문서 루트: 프로젝트 폴더 경로
   • 포트: 3000 (또는 원하는 포트)
   • 입력 명령: node app.js 또는 npm start

3단계: 테스트

• 웹사이트 활성화
• 브라우저에서 접속 테스트
• 로그 확인 (정상 실행 여부)

🔍 문제 해결 검증

성공적인 로그 예시:

Container your_project-node-1  Starting
Container your_project-node-1  Started
Exit Code: 0

애플리케이션 로그 예시:

🚀 서버가 시작되었습니다
📍 포트: 3000
🌐 환경: production

📝 주의사항

백업 권장

• 수정 전 반드시 원본 템플릿 백업
• 중요한 프로젝트는 별도 백업 보관

버전 호환성

• DSM 7.x에서 검증됨
• WebStation 2.1 이상 권장
• Node.js 18.x 이상 권장

보안 고려사항

• SSH 사용 후 비활성화 권장
• 관리자 권한 최소 사용
• 불필요한 포트 노출 방지

🛠️ 추가 최적화 팁

1. package.json 최적화

{
  "engines": {
    "node": ">=18.0.0"  // 너무 엄격한 버전 제한 완화
  },
  "scripts": {
    "start": "node app.js"
  }
}

2. .dockerignore 생성

node_modules/
*.log
.env
.git/
README.md

3. 환경변수 설정

# Dockerfile에 추가 (필요시)
ENV NODE_ENV=production
ENV PORT=3000

🔄 문제가 계속 발생할 경우

임시 해결책

WebStation 설정에서 입력 명령을 다음과 같이 변경:

• npm start → node src/app.js
• node app.js → node src/app.js

로그 확인 방법

# Docker 로그 확인
docker logs container_name

# WebStation 로그 위치
/var/log/webstation/

📞 지원 및 문제 보고

이 가이드로 해결되지 않는 문제가 있다면:

1. WebStation 버전 확인
2. Node.js 버전 확인
3. 정확한 오류 메시지 수집
4. Docker 로그 수집

---

작성일: 2025-09-26
검증 환경: Synology DSM 7.x, WebStation 2.1+, Node.js 18+
적용 대상: 모든 시놀로지 NAS WebStation Node.js 프로젝트

💡 이 가이드는 근본적인 해결책을 제공합니다. 한 번 수정하면 이후 모든 Node.js 프로젝트가 정상 작동합니다.