Synology NAS Container Manager에서 n8n 완벽 설치 가이드 목차
n8n은 코딩 없이도 다양한 서비스와 애플리케이션을 연결하여 업무를 자동화할 수 있는 강력한 워크플로우 자동화 플랫폼입니다. 특히 Synology NAS에 n8n을 설치하면 클라우드 서비스 비용 없이 24시간 안정적으로 자동화 시스템을 운영할 수 있어, 개인 사용자부터 소규모 기업까지 폭넓게 활용할 수 있습니다.
이 가이드에서는 DSM 7.2 이전 버전에서 활용되던 Docker가 현재는 Container Manger로 변경되었습니다. DSM 7.2의 Container Manager를 활용하여 n8n을 설치하는 전체 과정을 초보자도 쉽게 따라할 수 있도록 상세히 설명합니다. 기존 Docker 패키지 사용자를 위한 Container Manager 전환 방법부터 Docker Compose를 활용한 고급 설치, PostgreSQL 데이터베이스 연동, 역방향 프록시 설정까지 프로덕션 환경에 필요한 모든 내용을 다룹니다.
또한 실제 설치 과정에서 발생할 수 있는 7가지 주요 문제 상황에 대한 트러블슈팅 가이드와 Synology NAS의 화면 캡쳐 지시사항을 포함하여, 누구나 막힘없이 설치를 완료할 수 있도록 구성했습니다. 이제 여러분의 Synology NAS를 강력한 자동화 허브로 변신시켜 보세요.
"n8n 워크플로우 자동화 플랫폼과 Synology NAS의 조화 - 드래그 앤 드롭으로 손쉽게 자동화 구현"
| Synology NAS의 Container Manager(Docker)를 활용해 손쉽게 n8n서비스를 구축해 보세요 |
|
[ 차례 ]
|
1. n8n과 Synology NAS Docker 소개
n8n이란 무엇인가요?
n8n(엔에잇엔)은 오픈소스 기반의 워크플로우 자동화 플랫폼으로, 다양한 애플리케이션과 서비스를 연결하여 반복적인 작업을 자동화할 수 있게 해주는 강력한 도구입니다. 사용자 친화적인 드래그 앤 드롭 인터페이스를 제공하기 때문에, 복잡한 코딩 지식 없이도 자동화 워크플로우를 설계하고 실행할 수 있습니다. n8n은 400개 이상의 서비스와 통합이 가능하며, Slack, Google Sheets, Gmail, OpenAI 등 널리 사용되는 서비스들과 쉽게 연동할 수 있어서 업무 효율성을 크게 향상시킬 수 있습니다.
n8n의 가장 큰 장점 중 하나는 셀프 호스팅이 가능하다는 점입니다. 이는 모든 데이터가 사용자의 서버에 저장되므로 민감한 정보를 외부 클라우드 서비스에 노출시키지 않아도 된다는 것을 의미합니다. 또한 클라우드 서비스 이용료를 절약할 수 있으며, 네트워크 환경에 따른 제약 없이 24시간 안정적으로 워크플로우를 실행할 수 있습니다. 특히 AI 통합 기능이 강화되어 Claude, ChatGPT, Gemini 등의 AI 모델을 워크플로우에 손쉽게 연결할 수 있어서, 현대적인 AI 기반 자동화 시나리오를 구현하기에 매우 적합합니다.
Synology NAS에서 Docker를 사용하는 이유
Synology NAS는 가정과 소규모 비즈니스 환경에서 널리 사용되는 네트워크 스토리지 장치로, Docker 컨테이너를 실행할 수 있는 강력한 기능을 제공합니다. Docker는 애플리케이션을 격리된 환경에서 실행할 수 있게 해주는 컨테이너 기술로, 복잡한 의존성 문제를 해결하고 손쉬운 배포와 업데이트를 가능하게 합니다. Synology NAS의 Container Manager(이전 명칭: Docker 패키지)를 활용하면, 별도의 서버 없이도 n8n과 같은 자동화 도구를 24시간 운영할 수 있어서 매우 경제적이고 효율적입니다.
Synology NAS에서 n8n을 실행하면 여러 가지 이점을 누릴 수 있습니다.
- 첫째, 이미 운영 중인 NAS를 활용하므로 추가적인 하드웨어 구매 비용이 들지 않습니다.
- 둘째, Synology의 내장 역방향 프록시 기능을 사용하여 안전한 HTTPS 접속을 쉽게 구성할 수 있습니다.
- 셋째, NAS의 저전력 특성 덕분에 24시간 운영에도 전기 요금 부담이 크지 않습니다.
- 넷째, Synology의 안정적인 DSM 운영체제 위에서 동작하므로 시스템 안정성이 높습니다.
가이드 대상
이 가이드는 Synology NAS를 보유하고 있으면서 n8n을 활용한 워크플로우 자동화에 관심이 있는 분들을 위해 작성되었습니다. Docker에 대한 기본적인 이해가 있으면 도움이 되지만, 초보자도 따라할 수 있도록 각 단계를 상세하게 설명하고 있습니다. Linux 명령어나 네트워크 설정에 익숙하지 않더라도, 이 가이드의 순서대로 따라하면 성공적으로 n8n을 설치하고 운영할 수 있을 것입니다. 중간중간 발생할 수 있는 문제 상황과 그 해결 방법도 함께 안내하고 있으므로, 막히는 부분이 있을 때 참고하시기 바랍니다.
2. 사전 준비사항 및 의존성 라이브러리
하드웨어 요구사항
n8n을 안정적으로 운영하기 위해서는 Synology NAS의 하드웨어 사양이 일정 수준 이상이어야 합니다. Docker를 지원하는 Synology NAS 모델은 일반적으로 x86_64 또는 ARM64 아키텍처를 사용하며, 대표적인 지원 모델로는 DS218+, DS220+, DS420+, DS920+, DS1621+ 등이 있습니다. 최소 2GB 이상의 RAM을 권장하며, 워크플로우의 복잡도와 동시 실행 수에 따라 4GB 이상을 추천합니다. n8n 공식 문서에 따르면 유휴 상태에서 약 100MB의 메모리를 사용하지만, 대용량 데이터를 처리하거나 여러 워크플로우를 동시에 실행할 경우 메모리 사용량이 크게 증가할 수 있습니다.
스토리지 측면에서는 n8n 애플리케이션 자체는 크지 않지만, 워크플로우 실행 기록과 데이터베이스 저장을 위해 최소 20GB 이상의 여유 공간을 확보하는 것이 좋습니다. 특히 PostgreSQL 데이터베이스를 함께 사용할 경우, 워크플로우 실행 히스토리가 누적되면서 저장 공간이 점차 증가하게 됩니다. SSD 기반의 NAS를 사용하면 데이터베이스 읽기/쓰기 성능이 향상되어 전반적인 응답 속도가 빨라지므로, 예산이 허용한다면 SSD 볼륨에 Docker 데이터를 저장하는 것을 고려해 보시기 바랍니다.
Docker(Container Manager) 설치 확인
Synology NAS에서 Docker 기능을 사용하려면 먼저 Container Manager 패키지가 설치되어 있어야 합니다. DSM 7.2 이상에서는 기존의 'Docker' 패키지가 'Container Manager'로 명칭이 변경되었으므로, 패키지 센터에서 해당 이름으로 검색해야 합니다. 설치 방법은 매우 간단한데, DSM 관리 화면에서 패키지 센터를 열고 검색창에 'Container Manager'를 입력한 후 설치 버튼을 클릭하면 됩니다. 설치가 완료되면 메인 메뉴에 Container Manager 아이콘이 나타나게 됩니다.
Container Manager가 정상적으로 설치되었는지 확인하려면, 애플리케이션을 실행하여 대시보드가 표시되는지 살펴보면 됩니다. 대시보드에서는 현재 실행 중인 컨테이너 목록과 리소스 사용량 등을 확인할 수 있습니다. 만약 NAS 모델이 Docker를 지원하지 않는 경우에는 Container Manager 패키지가 패키지 센터에 표시되지 않으므로, 이런 경우에는 다른 방법을 모색해야 합니다. Synology 공식 웹사이트에서 본인의 NAS 모델이 Docker를 지원하는지 사전에 확인하시기 바랍니다.
DSM 버전별 Docker와 Container Manager 전환 가이드
Synology NAS를 사용하시는 분들 중에는 이미 이전 버전의 DSM에서 Docker 패키지를 사용하고 계신 경우가 많습니다. DSM 7.2부터 기존 'Docker' 패키지가 'Container Manager'로 명칭이 변경되고 기능이 대폭 개선되었는데, 이 과정에서 기존 컨테이너와 데이터가 어떻게 되는지 궁금해하시는 분들이 많습니다. 결론부터 말씀드리면, DSM 업데이트 시 Docker는 자동으로 Container Manager로 전환되며, 기존 컨테이너, 이미지, 볼륨, 네트워크는 모두 그대로 유지됩니다. 별도의 마이그레이션 작업이나 재설치는 필요하지 않습니다.
DSM 버전별 Docker 패키지 현황
| DSM 버전 | 패키지 이름 | Docker 엔진 버전 | 주요 특징 |
| DSM 6.2.x | Docker | 18.09.x ~ 20.10.x | 기본 컨테이너 관리 UI |
| DSM 7.0 ~ 7.1 | Docker | 20.10.x | DSM 7 보안 강화 적용 |
| DSM 7.2 이상 | Container Manager | 20.10.x → 24.x.x | 새로운 UI, Docker Compose 지원, 프로젝트 기능 |
시나리오 1 : DSM 7.2 이전에서 Docker를 이미 사용 중인 경우
DSM 7.0이나 7.1에서 Docker 패키지를 사용하고 계시다가 DSM 7.2로 업데이트하면, Docker 패키지가 자동으로 Container Manager로 업그레이드됩니다. 이 과정에서 사용자가 별도로 해야 할 작업은 없습니다. 업데이트가 완료되면 메인 메뉴에서 'Docker' 아이콘 대신 'Container Manager' 아이콘이 표시되며, 기존에 실행 중이던 모든 컨테이너가 그대로 동작합니다. Docker 엔진도 20.10.x 버전에서 24.x.x 버전으로 자동 업그레이드되어 더 나은 성능과 보안을 제공합니다.
전환 시 유지되는 항목 :
- 모든 Docker 이미지 (다운로드한 이미지들)
- 모든 컨테이너 및 설정 (포트, 볼륨, 환경 변수 등)
- Docker 네트워크 구성
- Docker 볼륨 및 마운트된 데이터
- 컨테이너 내부 데이터 (볼륨 마운트된 경우)
전환 후 변경되는 사항 :
- UI가 완전히 새로워짐 (더 현대적인 인터페이스)
- '프로젝트(Project)' 기능 추가 (Docker Compose 네이티브 지원)
- 컨테이너 편집 방식 변경 (중지 후 편집 대신 복제 후 수정)
- 이미지 업데이트 알림 기능 추가
시나리오 2: DSM 6.2.x에서 DSM 7.x로 업그레이드하는 경우
DSM 6.2.x 버전을 사용하고 계신 경우, DSM 7.x로 업그레이드할 때 몇 가지 주의사항이 있습니다. 먼저, DSM 메이저 버전 업그레이드는 단계별로 진행해야 합니다. 예를 들어 DSM 6.2.4에서 바로 DSM 7.2로 업그레이드할 수 없으며, 반드시 DSM 7.0.1을 거쳐야 합니다. Synology 다운로드 센터에서 중간 버전을 먼저 다운로드하여 순차적으로 업데이트를 진행해야 합니다.
DSM 6.2.x → 7.x 업그레이드 순서 :
DSM 6.2.4 → DSM 7.0.1 → DSM 7.2.x → (필요시) 최신 업데이트
Docker 컨테이너와 관련하여, DSM 6.2.x에서 7.x로의 업그레이드 과정에서도 기존 컨테이너는 유지됩니다. 다만 DSM 7의 보안 정책 변경으로 인해 일부 패키지(특히 Plex Media Server)는 별도의 마이그레이션 절차가 필요할 수 있습니다. Docker 컨테이너 자체는 별다른 문제 없이 전환되지만, 안전을 위해 업그레이드 전에 아래의 사전 준비를 권장합니다.
업그레이드 전 권장 사전 준비 :
# 1. 현재 실행 중인 컨테이너 확인 및 기록
docker ps -a
# 2. 컨테이너 설정 백업 (docker-autocompose 도구 사용)
# SSH로 NAS 접속 후 실행
pip install docker-autocompose
docker-autocompose <컨테이너이름> > container_backup.yml
# 3. 볼륨 마운트 폴더 백업
# File Station 또는 Hyper Backup으로 /volume1/docker 폴더 전체 백업
# 4. 모든 컨테이너 중지 (안전을 위해)
docker stop $(docker ps -q)시나리오 3 : Container Manager가 이미 설치되어 있고 Docker 패키지가 없는 경우
DSM 7.2 이상에서 처음 NAS를 설정했거나, 이미 Container Manager만 설치되어 있는 경우에는 별도의 전환 작업이 필요 없습니다. Container Manager가 Docker의 모든 기능을 포함하고 있으므로, 그대로 사용하시면 됩니다. 이 가이드의 나머지 부분을 따라 n8n을 설치하시면 됩니다.
Docker에서 Container Manager로 전환 시 주요 UI 변경사항
Container Manager로 전환하면 인터페이스가 상당히 달라지므로, 기존 Docker 패키지 사용자분들은 약간의 적응 시간이 필요할 수 있습니다. 가장 큰 변화는 컨테이너 편집 방식인데, 기존 Docker 패키지에서는 컨테이너를 중지한 후 직접 설정을 편집할 수 있었지만, Container Manager에서는 컨테이너를 '복제(Duplicate)'하여 새로운 설정으로 생성해야 합니다. 이 방식이 번거롭게 느껴질 수 있지만, 설정 변경으로 인한 문제 발생 시 원래 컨테이너로 쉽게 롤백할 수 있다는 장점이 있습니다.
기존 Docker 패키지 vs Container Manager 비교 :
| 기능 | Docker(구버전) | Container Manager(신버전) |
| 컨테이너 생성 | 이미지 → 실행 | 이미지 → 실행 (동일) |
| 컨테이너 편집 | 중지 → 편집 → 시작 | 복제 → 수정 → 새 컨테이너 생성 |
| Docker Compose | 미지원 (CLI만 가능) | 프로젝트 기능으로 네이티브 지원 |
| 이미지 업데이트 | 수동 확인 필요 | 자동 알림 및 원클릭 업데이트 |
| 멀티 컨테이너 관리 | 개별 관리 | 프로젝트로 그룹 관리 가능 |
| 컨테이너 로그 | 기본 로그 뷰어 | 개선된 로그 뷰어 |
전환 후 기존 컨테이너를 Docker Compose(프로젝트)로 마이그레이션하기
Container Manager로 전환한 후, 기존에 UI로 생성한 컨테이너들을 Docker Compose 기반의 프로젝트로 마이그레이션하면 관리가 훨씬 편리해집니다. 필수 작업은 아니지만, 설정 백업과 버전 관리가 용이해지므로 시간이 될 때 진행하시는 것을 권장합니다.
마이그레이션 절차 :
# 1. SSH로 NAS 접속
ssh admin@NAS_IP
# 2. 기존 컨테이너 설정을 Docker Compose 형식으로 추출
# docker-autocompose 설치 (Python 필요)
sudo pip install docker-autocompose
# 3. 특정 컨테이너의 설정 추출
docker-autocompose n8n > /volume1/docker/n8n/docker-compose.yml
# 4. 추출된 파일 확인 및 수정
cat /volume1/docker/n8n/docker-compose.yml
또는 Container Manager UI에서 수동으로 Docker Compose 파일을 작성할 수 있습니다. 기존 컨테이너의 설정(포트, 볼륨, 환경 변수 등)을 확인하여 YAML 형식으로 옮기면 됩니다. 이 가이드의 [ Docker Compose를 활용한 고급 설치 ] 섹션에서 제공하는 예제를 참고하시면 됩니다.
자주 묻는 질문: Docker/Container Manager 전환 관련
Q: DSM 업데이트 후 기존 컨테이너가 사라졌습니다. 어떻게 해야 하나요?
Container Manager를 열고 '컨테이너' 탭을 확인하세요. 컨테이너가 '중지됨' 상태일 수 있습니다. '시작' 버튼을 클릭하여 다시 실행해 보세요. 만약 컨테이너 목록에 보이지 않는다면, SSH로 접속하여 docker ps -a 명령으로 확인해 보세요. 드물게 UI에 표시되지 않는 경우가 있습니다.
Q: Container Manager에서 기존 Docker 명령어를 사용할 수 있나요?
네, SSH로 접속하면 기존과 동일하게 docker 및 docker-compose 명령어를 사용할 수 있습니다. CLI와 Container Manager UI는 같은 Docker 엔진을 공유하므로, 어느 쪽에서 생성한 컨테이너든 양쪽에서 모두 관리할 수 있습니다.
Q: DSM 7.2 이상인데 패키지 센터에 'Docker'가 보입니다. Container Manager와 다른 건가요?
DSM 7.2 이상에서는 패키지 센터에 'Docker'가 아닌 'Container Manager'만 표시되어야 합니다. 만약 'Docker'가 보인다면 DSM 버전을 다시 확인해 보세요. 또는 패키지 센터 캐시 문제일 수 있으므로, 브라우저 캐시를 삭제하고 다시 시도해 보세요.
Q: Container Manager로 전환 후 특정 컨테이너만 문제가 생겼습니다.
Docker 엔진 버전 업그레이드(20.10.x → 24.x.x)로 인해 일부 오래된 이미지에서 호환성 문제가 발생할 수 있습니다. 해당 컨테이너의 이미지를 최신 버전으로 업데이트해 보세요. Container Manager의 '레지스트리'에서 이미지를 다시 다운로드하고 컨테이너를 재생성하면 대부분 해결됩니다.
Node.js 의존성에 대한 이해
많은 분들이 n8n을 설치할 때 Node.js를 별도로 설치해야 하는지 궁금해하십니다. Docker 컨테이너를 사용하여 n8n을 설치하는 경우, Node.js를 별도로 설치할 필요가 전혀 없습니다. n8n 공식 Docker 이미지(n8nio/n8n)에는 n8n 실행에 필요한 Node.js 런타임과 모든 의존성 라이브러리가 이미 포함되어 있기 때문입니다. 이것이 바로 Docker를 사용하는 가장 큰 장점 중 하나로, 복잡한 의존성 설치 과정을 완전히 건너뛸 수 있습니다.
만약 Docker 없이 직접 NAS에 n8n을 설치하려는 경우에는 Node.js 18 버전 이상이 필요합니다. 하지만 이 방법은 Synology에서 공식적으로 지원하지 않으며, DSM 업데이트 시 문제가 발생할 수 있어서 권장하지 않습니다. 또한 직접 설치 방식은 npm 패키지 관리, 프로세스 매니저(PM2) 설정 등 추가적인 복잡한 설정이 필요합니다. 따라서 특별한 사유가 없는 한 Docker 방식을 사용하시기를 강력히 권장합니다. Docker 방식은 설치와 업데이트가 간편하고, 시스템과 완전히 격리되어 있어서 안정성도 뛰어납니다.
3. n8n 컨테이너 설치하기
폴더 구조 생성
n8n 컨테이너를 설치하기 전에, 데이터를 영구적으로 저장할 폴더 구조를 먼저 생성해야 합니다. 컨테이너가 재시작되거나 업데이트되어도 워크플로우와 자격 증명 데이터가 유지되려면, 호스트 시스템(NAS)의 특정 폴더를 컨테이너 내부 경로에 마운트해야 합니다. Synology NAS의 File Station을 열고 docker 폴더 안에 다음과 같은 하위 폴더들을 생성합니다. 폴더 이름은 반드시 소문자로 입력해야 하며, 대문자를 사용하면 예상치 못한 오류가 발생할 수 있습니다.
/volume1/docker/n8n/
├── data/ # n8n 설정 및 워크플로우 데이터
├── files/ # 업로드 파일 및 첨부 파일
└── db/ # PostgreSQL 데이터베이스 (선택사항)
각 폴더의 역할을 설명하면 다음과 같습니다.
- data 폴더는 n8n의 핵심 설정 파일, 워크플로우 정의, 암호화 키 등을 저장하는 가장 중요한 폴더입니다.
- files 폴더는 워크플로우에서 처리하는 파일들을 임시로 저장하는 용도로 사용됩니다.
- db 폴더는 PostgreSQL 데이터베이스를 함께 사용할 경우에만 필요하며, 기본 SQLite 데이터베이스를 사용할 경우에는 생략해도 됩니다. 이 폴더들은 컨테이너의 생명 주기와 무관하게 데이터를 보존하므로, 반드시 백업 계획에 포함시켜야 합니다.
Container Manager UI를 통한 설치
Synology의 Container Manager UI를 사용하면 명령줄 없이도 n8n 컨테이너를 설치할 수 있습니다. 먼저 Container Manager를 실행하고 왼쪽 메뉴에서 '레지스트리(Registry)'를 클릭합니다. 검색창에 'n8nio/n8n'을 입력하면 공식 n8n Docker 이미지가 나타나는데, 이것을 선택하고 '다운로드' 버튼을 클릭합니다. 태그 선택 창이 나타나면 'latest'를 선택하여 최신 안정 버전을 다운로드합니다. 다운로드가 완료되면 '이미지(Image)' 메뉴에서 해당 이미지가 표시됩니다.
다운로드한 이미지를 기반으로 컨테이너를 생성하려면, '이미지' 탭에서 n8nio/n8n 이미지를 선택하고 '실행(Launch)' 버튼을 클릭합니다. 컨테이너 생성 마법사가 시작되면 컨테이너 이름을 'n8n'으로 입력하고, 자동 재시작 옵션을 활성화하여 NAS 재부팅 시에도 자동으로 컨테이너가 시작되도록 설정합니다. 그 다음 단계에서는 포트 설정, 볼륨 마운트, 환경 변수 설정을 진행하게 되는데, 이 부분은 다음 섹션에서 자세히 다루겠습니다. 마법사의 각 단계를 완료하고 '완료'를 클릭하면 컨테이너가 생성되고 실행됩니다.
컨테이너 생성 마법사 - 일반 설정
위치 : Container Manager > 이미지 > 실행 > 일반 설정
- '이미지' 탭에서 n8nio/n8n을 선택하고 '실행'을 클릭합니다
- 컨테이너 생성 마법사의 첫 번째 화면(일반 설정)을 확인합니다
- 컨테이너 이름 입력란에 'n8n'을 입력합니다.
- '자동 재시작 활성화' 체크박스를 활성화하여 NAS 재시작 시 n8n컨테이너가 자동 실행되게 합니다.
컨테이너 생성 마법사 - 포트 설정
위치 : Container Manager > 컨테이너 생성 > 포트 설정
- 마법사의 '포트 설정' 단계로 이동합니다
- 로컬 포트와 컨테이너 포트 입력란을 확인합니다.
- 로컬 포트 : 5678, 컨테이너 포트 : 5678로 설정합니다.
- 프로토콜이 TCP로 설정된 것도 확인합니다
컨테이너 생성 마법사 - 볼륨 설정
위치: Container Manager > 컨테이너 생성 > 볼륨 설정
- 마법사의 '볼륨 설정' 또는 '저장소 설정' 섹션으로 이동합니다
- '폴더 추가' 버튼을 클릭하여 볼륨 매핑을 추가합니다
- 다음 두 개의 볼륨 매핑이 설정된 화면을 캡쳐합니다:
- /volume1/docker/n8n/data → /home/node/.n8n
- /volume1/docker/n8n/files → /files
- 읽기/쓰기 권한 설정도 확인 합니다
컨테이너 생성 마법사 - 환경 변수 설정
위치: Container Manager > 컨테이너 생성 > 환경 변수
- 마법사의 '환경' 또는 '환경 변수' 섹션으로 이동합니다
- '변수 추가' 버튼을 클릭하여 환경 변수를 추가합니다
- 주요 환경 변수들이 아래와 같이 설정되도록 환경변수를 [추가]합니다.
- GENERIC_TIMEZONE=Asia/Seoul
- TZ=Asia/Seoul
- N8N_PORT=5678
- 변수 이름과 값 입력 필드가 정확히 입력되었는지 확인합니다.
Container Manager 마법사를 통해 설치한 경우의 트러블 슈팅
n8n서버가 실행되지 않는 경우 (폴더 권한 및 N8N_ENCRYPTION_KEY관련)
1) No encryption key found - Auto-generating and saving to: /home/node/.n8n/config
2) Error: EACCES: permission denied, open '/home/node/.n8n/config'
이 오류는 Synology NAS에서 n8n 설치 시 가장 흔하게 발생하는 볼륨 권한 문제입니다. n8n 컨테이너는 내부적으로 node 사용자(UID 1000)로 실행되는데, 마운트된 폴더의 소유권이 맞지 않아서 파일을 생성할 수 없는 것입니다.
해결 방법 1 : 폴더 권한 수정 (권장)
SSH로 NAS에 접속하여 마운트 폴더의 소유권을 변경합니다:
# SSH로 NAS 접속
ssh admin@NAS_IP
# 폴더 소유권을 UID 1000 (node 사용자)으로 변경
sudo chown -R 1000:1000 /volume1/docker/n8n/data
sudo chown -R 1000:1000 /volume1/docker/n8n/files
sudo chmod -R 755 /volume1/docker/n8n/
# 권한 확인
ls -la /volume1/docker/n8n/권한 변경 후 Container Manager에서 컨테이너를 재시작하면 정상 작동합니다.
방법 2 : 환경변수 추가 (UI 마법사에서 설정)
Container Manager 마법사에서 컨테이너 생성 시 환경변수에 다음 항목을 추가합니다:
| 변수명 | 값 | 설명 |
| N8N_ENCRYPTION_KEY | your-32-character-random-string | 암호화 키를 미리 지정하여 자동 생성 방지 |
암호화 키 생성 예시 :
# 1. 암호화 키 생성
openssl rand -hex 16
# 출력 예시: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
# 2. 환경설정 변수에 적용 또는 docker-compose.yml에 적용
# N8N_ENCRYPTION_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6중요: 이 방법만으로는 근본적인 권한 문제가 해결되지 않을 수 있습니다. 방법 1과 함께 사용하시는 것을 권장합니다.
방법 3 : Docker Compose로 설치 (가장 확실한 해결책)
Docker Compose를 사용하면 user 옵션으로 권한 문제를 깔끔하게 해결할 수 있습니다:
version: '3.8'
services:
n8n:
image: n8nio/n8n:latest
container_name: n8n
restart: unless-stopped
# 권한 문제 해결: root로 실행 후 내부에서 node 사용자로 전환
user: "0:0" # root로 실행 (또는 "1000:1000"으로 node 사용자 지정)
ports:
- "5678:5678"
environment:
- N8N_HOST=0.0.0.0
- N8N_PORT=5678
- N8N_PROTOCOL=http
- GENERIC_TIMEZONE=Asia/Seoul
- TZ=Asia/Seoul
# 암호화 키를 명시적으로 설정 (32자 이상 랜덤 문자열)
- N8N_ENCRYPTION_KEY=your-32-character-random-string-here
volumes:
- /volume1/docker/n8n/data:/home/node/.n8n
- /volume1/docker/n8n/files:/files
권장 조치 순서
- 먼저 SSH로 폴더 권한 수정 (방법 1)
- 환경변수에 N8N_ENCRYPTION_KEY 추가 (방법 2)
- 컨테이너 재시작 또는 재생성
# 전체 해결 명령어 (SSH 접속 후)
sudo chown -R 1000:1000 /volume1/docker/n8n/data
sudo chown -R 1000:1000 /volume1/docker/n8n/files
sudo chmod -R 755 /volume1/docker/n8n/Secure Cookie 설정 관련 보안 문제
Your n8n server is configured to use a secure cookie, however you are either visiting this via an insecure URL, or using Safari. To fix this, please consider the following options: * Setup TLS/HTTPS (recommended), or * If you are running this locally, and not using Safari, try using localhost instead * If you prefer to disable this security feature (not recommended), set the environment variable N8N_SECURE_COOKIE to false
이 오류는 n8n이 기본적으로 보안 쿠키(Secure Cookie)를 사용하도록 설정되어 있는데, HTTPS가 아닌 HTTP로 접속하기 때문에 발생합니다. 해결 방법은 3가지가 있습니다.
해결 방법 1 : 환경변수 추가 (빠른 해결 - 내부망 전용)
Container Manager에서 컨테이너를 중지하고, 환경변수에 다음 항목을 추가합니다:
| 변수명 | 값 |
| N8N_SECURE_COOKIE | false |
Docker Compose 사용 시 :
environment:
- N8N_HOST=0.0.0.0
- N8N_PORT=5678
- N8N_PROTOCOL=http
- GENERIC_TIMEZONE=Asia/Seoul
- TZ=Asia/Seoul
- N8N_ENCRYPTION_KEY=your-32-character-random-string
- N8N_SECURE_COOKIE=false # 이 줄 추가
주의: 이 방법은 내부 네트워크에서만 사용할 때 적합합니다. 외부에서 접속하거나 민감한 자격 증명을 다룰 경우 HTTPS 설정을 권장합니다.
해결 방법 2: HTTPS 설정 (권장 - 외부 접속 시)
Synology NAS의 역방향 프록시를 활용하여 HTTPS를 설정하는 것이 가장 안전한 방법입니다.
설정 순서 :
- 제어판 > 로그인 포털 > 고급 > 역방향 프록시 이동
- 생성 클릭 후 다음과 같이 설정 :
| 구분 | 항목 | 값 |
| 소스 | 프로토콜 | HTTPS |
| 호스트명 | n8n.yourdomain.synology.me | |
| 포트 | 443 | |
| 대상 | 프로토콜 | HTTP |
| 호스트명 | localhost | |
| 포트 | 5678 |
- [사용자 지정 머리글] 탭에서 WebSocket을 지정하면 WebSocket 헤더가 아래와 같이 자동으로 추가됩니다 :
| 헤더 이름 | 값 |
| Upgrade | $http_upgrade |
| Connection | $connection_upgrade |
- n8n 환경변수 수정 (HTTPS 사용 시):
environment:
- N8N_HOST=n8n.yourdomain.synology.me
- N8N_PORT=5678
- N8N_PROTOCOL=https # http → https로 변경
- WEBHOOK_URL=https://n8n.yourdomain.synology.me/
- N8N_EDITOR_BASE_URL=https://n8n.yourdomain.synology.me/
- N8N_SECURE_COOKIE=true # true로 유지 (기본값)
해결 방법 3: localhost로 접속 (임시 테스트용)
NAS에 직접 접속 가능한 경우, 브라우저에서 IP 대신 localhost로 접속하면 보안 쿠키 문제를 우회할 수 있습니다. 단, 이 방법은 NAS 자체에서 브라우저를 실행할 때만 가능합니다.
권장 설정 조합
| 사용 환경 | 권장 설정 |
| 내부망에서만 사용 | N8N_SECURE_COOKIE=false |
| 외부 접속 필요 | 역방향 프록시 + HTTPS + N8N_SECURE_COOKIE=true |
| 웹훅 사용 예정 | 반드시 HTTPS + WEBHOOK_URL 설정 |
빠른 해결을 위한 전체 환경변수 예시 (내부망 접속만 권장 - HTTP)
environment:
# 서버 바인딩 설정 (내부 설정)
- N8N_HOST=0.0.0.0 # 어디서든 접속 허용 (그대로 유지)
- N8N_PORT=5678 # 내부 포트
- N8N_PROTOCOL=http # 내부 프로토콜
# 외부 접속 URL 설정 (웹훅, 링크 생성에 사용)
- WEBHOOK_URL=http://192.168.1.100:5678/ # 실제 접속 주소 (NAS/외부공인+포트포워딩)
- N8N_EDITOR_BASE_URL=http://192.168.1.100:5678/ # 에디터 URL
# 기타 설정
- GENERIC_TIMEZONE=Asia/Seoul
- TZ=Asia/Seoul
- N8N_ENCRYPTION_KEY=your-32-character-key
- N8N_SECURE_COOKIE=false
빠른 해결을 위한 전체 환경변수 예시 (외부 접속용 - HTTPS + 역방향 프록시)
environment:
- N8N_HOST=0.0.0.0 # 그대로 유지
- N8N_PORT=5678
- N8N_PROTOCOL=https
- WEBHOOK_URL=https://n8n.yourdomain.com/ # 실제 도메인
- N8N_EDITOR_BASE_URL=https://n8n.yourdomain.com/
- GENERIC_TIMEZONE=Asia/Seoul
- TZ=Asia/Seoul
- N8N_ENCRYPTION_KEY=your-32-character-key
- N8N_SECURE_COOKIE=true
환경변수 추가 후 컨테이너를 재시작하면 정상적으로 접속할 수 있습니다. 정상적으로 접속하여 로그인을 하는 경우 'Activation Key'가 사용자ID(이메일)로 전달되고 해당 활성화키를 등록하시면 정상적인 사용이 가능합니다.
4. Docker Compose를 활용한 고급 설치
Docker Compose란 무엇인가요?
Docker Compose는 여러 컨테이너로 구성된 애플리케이션을 정의하고 실행하기 위한 도구입니다. YAML 형식의 설정 파일 하나로 애플리케이션의 모든 서비스, 네트워크, 볼륨을 정의할 수 있어서, 복잡한 멀티 컨테이너 환경도 간단하게 관리할 수 있습니다. Container Manager의 UI를 통한 설치는 직관적이지만, 설정을 일일이 클릭해야 하고 설정 내용을 백업하거나 공유하기 어렵다는 단점이 있습니다.
반면 Docker Compose를 사용하면 설정 파일 하나로 모든 것을 관리할 수 있어서, 버전 관리와 재현성 측면에서 훨씬 유리합니다.
Synology의 Container Manager는 DSM 7.2부터 '프로젝트(Project)' 기능을 통해 Docker Compose를 네이티브로 지원합니다. 이전 버전에서는 SSH로 접속하여 명령줄에서 docker-compose 명령을 실행해야 했지만, 이제는 웹 UI에서 바로 Docker Compose 파일을 작성하고 실행할 수 있습니다.
프로젝트 기능을 사용하면 관련된 컨테이너들을 그룹으로 관리할 수 있고, 한 번의 클릭으로 전체 스택을 시작하거나 중지할 수 있어서 매우 편리합니다.
Docker Compose 파일 기본 구조 이해하기
Docker Compose 파일을 작성하기 전에, 기본 구조와 각 섹션의 역할을 이해하는 것이 중요합니다. Docker Compose 파일은 YAML 형식으로 작성되며, 들여쓰기로 계층 구조를 표현합니다. 아래는 Docker Compose 파일의 기본 구조와 각 섹션에 대한 상세 설명입니다. 실제 n8n 설치에 사용할 파일을 이해하기 위한 기초가 되므로, 각 항목의 의미를 잘 파악해 두시기 바랍니다.
# Docker Compose 파일 버전 (필수)
# 버전에 따라 지원되는 기능이 다름
# 3.8은 대부분의 기능을 지원하는 안정적인 버전
version: '3.8'
# 서비스 정의 섹션 (필수)
# 실행할 컨테이너들을 정의
services:
# 서비스 이름 (사용자 정의)
# 다른 서비스에서 이 이름으로 참조 가능
service-name:
# 사용할 Docker 이미지 (필수)
image: image-name:tag
# 컨테이너 이름 (선택)
# 지정하지 않으면 자동 생성됨
container_name: my-container
# 재시작 정책 (권장)
# no: 재시작 안함
# always: 항상 재시작
# unless-stopped: 수동 중지 전까지 재시작
# on-failure: 오류 시에만 재시작
restart: unless-stopped
# 포트 매핑 (호스트:컨테이너)
ports:
- "호스트포트:컨테이너포트"
# 볼륨 마운트 (호스트경로:컨테이너경로)
volumes:
- /host/path:/container/path
# 환경 변수 설정
environment:
- VARIABLE_NAME=value
# 의존성 정의 (다른 서비스가 먼저 시작되어야 함)
depends_on:
- other-service
# 네트워크 연결
networks:
- network-name
# 네트워크 정의 섹션 (선택)
networks:
network-name:
driver: bridge
# 볼륨 정의 섹션 (선택)
volumes:
volume-name:n8n 단독 설치용 Docker Compose (SQLite 사용)
가장 기본적인 n8n 설치 구성입니다. SQLite 데이터베이스를 사용하여 별도의 데이터베이스 서버 없이 n8n만 실행합니다. 소규모 환경이나 테스트 용도로 적합하며, 설정이 간단하고 리소스 사용량이 적습니다. 아래 설정 파일의 각 항목에 대해 상세히 설명하겠습니다.
##############################################
# n8n 단독 설치 (SQLite 데이터베이스)
# 용도: 소규모 환경, 테스트, 개인 사용
# 특징: 간단한 설정, 낮은 리소스 사용
##############################################
version: '3.8'
services:
n8n:
# 공식 n8n Docker 이미지 사용
# latest: 최신 안정 버전 (권장)
# 특정 버전 고정 예시: n8nio/n8n:1.20.0
image: n8nio/n8n:latest
# 컨테이너 이름 설정
# Container Manager에서 이 이름으로 표시됨
container_name: n8n
# 재시작 정책: 수동으로 중지하지 않는 한 항상 재시작
# NAS 재부팅 후에도 자동으로 컨테이너 시작
restart: unless-stopped
# 포트 매핑
# 호스트의 5678 포트를 컨테이너의 5678 포트에 연결
# 형식: "호스트포트:컨테이너포트"
ports:
- "5678:5678"
# 환경 변수 설정
# n8n의 동작을 제어하는 핵심 설정들
environment:
#-----------------------------------------
# 호스트 및 URL 설정
#-----------------------------------------
# 외부에서 접근할 호스트명 (도메인 또는 IP), 모든 접근 통로를 오픈
- N8N_HOST=0.0.0.0
# 역방향 프록시 사용 시 해당 도메인으로 설정할 수 있음
# - N8N_HOST=n8n.yourdomain.com 특정 도메인에서의 접근으로 제한
# n8n이 사용할 포트 (기본값: 5678)
- N8N_PORT=5678
# 프로토콜 설정 (http 또는 https)
# 역방향 프록시에서 SSL 처리 시 https로 설정
- N8N_PROTOCOL=https
# 웹훅 URL (외부 서비스가 호출할 URL)
# 반드시 외부에서 접근 가능한 전체 URL로 설정
# 끝에 슬래시(/) 포함 필수
- WEBHOOK_URL=https://n8n.yourdomain.com/
# 에디터 기본 URL
# OAuth 콜백 등에 사용됨
- N8N_EDITOR_BASE_URL=https://n8n.yourdomain.com/
#-----------------------------------------
# 시간대 설정 (한국 시간)
#-----------------------------------------
# 워크플로우 시간대 (스케줄 트리거에 영향)
- GENERIC_TIMEZONE=Asia/Seoul
# 시스템 시간대
- TZ=Asia/Seoul
#-----------------------------------------
# 데이터베이스 설정
#-----------------------------------------
# 데이터베이스 유형: sqlite (기본값) 또는 postgresdb
- DB_TYPE=sqlite
#-----------------------------------------
# 보안 설정
#-----------------------------------------
# 암호화 키 (자격 증명 암호화에 사용)
# 최소 32자 이상의 랜덤 문자열 권장
# 중요: 이 키를 반드시 별도로 백업하세요!
# 키 분실 시 저장된 모든 자격 증명 복구 불가
- N8N_ENCRYPTION_KEY=your-very-secure-32-character-key-here
#-----------------------------------------
# 바이너리 데이터 처리
#-----------------------------------------
# 파일 데이터 저장 방식
# filesystem: 파일 시스템에 저장 (메모리 효율적)
# default: 메모리에 저장 (작은 파일에 적합)
- N8N_DEFAULT_BINARY_DATA_MODE=filesystem
# 바이너리 데이터 저장 경로
- N8N_DEFAULT_BINARY_DATA_FOLDER=/files
# 볼륨 마운트 (데이터 영구 저장)
# 형식: 호스트경로:컨테이너경로:옵션
volumes:
# n8n 핵심 데이터 (워크플로우, 자격증명, 설정, SQLite DB)
# /home/node/.n8n은 n8n의 기본 데이터 디렉토리
- /volume1/docker/n8n/data:/home/node/.n8n
# 파일 저장소 (업로드/다운로드되는 파일)
- /volume1/docker/n8n/files:/files
# 헬스체크 설정 (컨테이너 상태 모니터링)
healthcheck:
# 헬스체크 명령어
# nc(netcat)로 5678 포트 연결 테스트
test: ["CMD-SHELL", "nc -z 127.0.0.1 5678 || exit 1"]
# 체크 간격 (10초마다)
interval: 10s
# 타임아웃 (5초 내 응답 없으면 실패)
timeout: 5s
# 재시도 횟수 (3번 실패 시 unhealthy)
retries: 3
# 시작 대기 시간 (컨테이너 시작 후 90초간 헬스체크 안함)
start_period: 90sContainer Manager 프로젝트 생성 및 Docker Compose 편집기
위치: Container Manager > 프로젝트 > 생성
- Container Manager의 왼쪽 메뉴에서 '프로젝트'를 클릭합니다
- 상단의 '생성' 버튼을 클릭합니다
- '소스' 옵션에서 'docker-compose.yml 작성(만들기)'을 선택합니다
- Docker Compose 파일 편집 화면으로 이동합니다
- YAML 코드를 통해 환경 설정값을 입력합니다.
- 편집기 영역과 하단의 '다음' 또는 '빌드' 버튼을 선택합니다.가능하다면 구문 하이라이팅이 적용된 상태를 보여줍니다
주의 : Docker Compose 편집기에 설정 파일 내용을 붙여넣습니다. 들여쓰기에 주의하며 Tab 대신 스페이스를 사용해야 합니다.
다음 화면에서 등장하는 '웹포털 구성'은 아래의 내용을 참조합니다.
웹 포털 설정
Synology Container Manager에서 프로젝트 생성 시 나타나는 옵션입니다.
| 항목 | 설명 |
| 기능 | Web Station과 연동하여 역방향 프록시 자동 설정 |
| 효과 | n8n.nas.local 같은 도메인으로 접속 가능 |
| 필수 여부 | 선택사항 |
웹 포털 설정 비교
| 구분 | 웹 포털 미사용 | 웹 포털 사용 |
| 접속 방식 | http://NAS_IP:5678 | http://n8n.nas.local |
| 추가 설정 | 없음 | Web Station 필요 |
| 복잡도 | 단순 | 약간 복잡 |
| 권장 상황 | 내부망, 테스트 | 여러 서비스 운영 시 |
상용서비스가 아닌 포트로 직접 접속할 거라면 웹 포털 설정은 건너뛰세요.
n8n + PostgreSQL 설치용 Docker Compose (프로덕션 권장)
프로덕션 환경이나 대규모 워크플로우 운영을 위해서는 PostgreSQL 데이터베이스를 함께 사용하는 것이 좋습니다. PostgreSQL은 동시 접속과 복잡한 쿼리 처리에 강점이 있으며, 데이터 안정성과 백업/복구 측면에서도 SQLite보다 유리합니다. 아래는 n8n과 PostgreSQL을 함께 구성한 Docker Compose 파일입니다.
##############################################
# n8n + PostgreSQL 설치 (프로덕션 권장)
# 용도: 프로덕션 환경, 대규모 워크플로우
# 특징: 높은 안정성, 동시성 처리 우수
##############################################
version: '3.8'
services:
#============================================
# PostgreSQL 데이터베이스 서비스
#============================================
db:
# PostgreSQL 17 버전 사용 (최신 안정 버전)
# 특정 버전 고정으로 예기치 않은 업그레이드 방지
image: postgres:17
# 컨테이너 이름
container_name: n8n-db
# 호스트명 설정 (네트워크 내에서 식별용)
hostname: n8n-db
# 보안 옵션: 새로운 권한 획득 방지
security_opt:
- no-new-privileges:true
# 재시작 정책
restart: unless-stopped
# 환경 변수 (데이터베이스 초기 설정)
environment:
# 생성할 데이터베이스 이름
- POSTGRES_DB=n8n
# 데이터베이스 사용자 이름
# 보안을 위해 기본값(postgres) 대신 별도 사용자 생성
- POSTGRES_USER=n8n_user
# 데이터베이스 비밀번호
# 반드시 강력한 비밀번호로 변경하세요!
# 영문 대소문자, 숫자, 특수문자 조합 권장
- POSTGRES_PASSWORD=YourStrongPassword123!
# 시간대 설정
- TZ=Asia/Seoul
# 볼륨 마운트 (데이터베이스 영구 저장)
volumes:
# PostgreSQL 데이터 디렉토리
# :rw는 읽기/쓰기 권한 (기본값이므로 생략 가능)
- /volume1/docker/n8n/db:/var/lib/postgresql/data:rw
# 헬스체크 (데이터베이스 준비 상태 확인)
healthcheck:
# pg_isready: PostgreSQL 연결 가능 여부 테스트
# -U: 사용자명, -d: 데이터베이스명
test: ["CMD-SHELL", "pg_isready -U n8n_user -d n8n"]
# 체크 간격
interval: 10s
# 타임아웃
timeout: 5s
# 재시도 횟수
retries: 5
# 네트워크 연결
networks:
- n8n-network
#============================================
# n8n 자동화 플랫폼 서비스
#============================================
n8n:
image: n8nio/n8n:latest
container_name: n8n
hostname: n8n
# 보안 옵션
security_opt:
- no-new-privileges:true
restart: unless-stopped
# 의존성 설정
# db 서비스가 healthy 상태가 될 때까지 대기
depends_on:
db:
condition: service_healthy
# 포트 매핑
ports:
- "5678:5678"
# 환경 변수
environment:
#-----------------------------------------
# 데이터베이스 연결 설정
#-----------------------------------------
# 데이터베이스 유형: PostgreSQL 사용
- DB_TYPE=postgresdb
# 데이터베이스 호스트
# Docker 네트워크 내에서 서비스 이름으로 접근
- DB_POSTGRESDB_HOST=db
# PostgreSQL 기본 포트
- DB_POSTGRESDB_PORT=5432
# 데이터베이스 이름 (위 PostgreSQL 설정과 일치)
- DB_POSTGRESDB_DATABASE=n8n
# 데이터베이스 사용자 (위 PostgreSQL 설정과 일치)
- DB_POSTGRESDB_USER=n8n_user
# 데이터베이스 비밀번호 (위 PostgreSQL 설정과 일치)
- DB_POSTGRESDB_PASSWORD=YourStrongPassword123!
# 데이터베이스 스키마 (기본값: public)
- DB_POSTGRESDB_SCHEMA=public
# 연결 풀 크기 (동시 연결 수)
# NAS 사양에 따라 조절 (기본값: 5)
- DB_POSTGRESDB_POOL_SIZE=5
#-----------------------------------------
# 호스트 및 URL 설정
#-----------------------------------------
- N8N_HOST=n8n.yourdomain.com
- N8N_PORT=5678
- N8N_PROTOCOL=https
- WEBHOOK_URL=https://n8n.yourdomain.com/
- N8N_EDITOR_BASE_URL=https://n8n.yourdomain.com/
# 역방향 프록시 사용 시 설정
# 프록시 단계 수 (일반적으로 1)
- N8N_PROXY_HOPS=1
#-----------------------------------------
# 시간대 설정
#-----------------------------------------
- GENERIC_TIMEZONE=Asia/Seoul
- TZ=Asia/Seoul
#-----------------------------------------
# 보안 설정
#-----------------------------------------
# 암호화 키 (반드시 변경하고 백업!)
- N8N_ENCRYPTION_KEY=your-32-char-encryption-key-change-this
# 보안 쿠키 사용 (HTTPS 환경에서 활성화)
- N8N_SECURE_COOKIE=true
# Code 노드에서 환경 변수 접근 차단
- N8N_BLOCK_ENV_ACCESS_IN_NODE=true
#-----------------------------------------
# 실행 데이터 관리
#-----------------------------------------
# 오래된 실행 기록 자동 삭제
- EXECUTIONS_DATA_PRUNE=true
# 실행 기록 보관 기간 (시간 단위, 336 = 14일)
- EXECUTIONS_DATA_MAX_AGE=336
# 동시 실행 제한 (NAS 사양에 따라 조절)
- N8N_CONCURRENCY_PRODUCTION_LIMIT=10
#-----------------------------------------
# 바이너리 데이터 처리
#-----------------------------------------
- N8N_DEFAULT_BINARY_DATA_MODE=filesystem
- N8N_DEFAULT_BINARY_DATA_FOLDER=/files
#-----------------------------------------
# 로깅 설정
#-----------------------------------------
# 로그 레벨: info, warn, error, debug
- N8N_LOG_LEVEL=info
# 로그 출력 대상: console, file
- N8N_LOG_OUTPUT=console
# 볼륨 마운트
volumes:
- /volume1/docker/n8n/data:/home/node/.n8n
- /volume1/docker/n8n/files:/files
# 헬스체크
healthcheck:
test: ["CMD-SHELL", "nc -z 127.0.0.1 5678 || exit 1"]
interval: 10s
timeout: 5s
retries: 3
start_period: 90s
# 네트워크 연결
networks:
- n8n-network
#============================================
# 네트워크 정의
#============================================
networks:
# n8n과 PostgreSQL이 통신할 내부 네트워크
n8n-network:
# bridge: 기본 네트워크 드라이버
# 같은 네트워크의 컨테이너끼리 서비스명으로 통신 가능
driver: bridgeDocker Compose 환경 변수 파일 분리 (.env 파일 활용)
보안을 강화하고 설정 관리를 용이하게 하려면, 민감한 정보를 별도의 환경 변수 파일(.env)로 분리하는 것이 좋습니다. Docker Compose는 같은 디렉토리의 .env 파일을 자동으로 읽어서 변수를 대체합니다. 이 방식을 사용하면 비밀번호나 API 키 같은 민감한 정보를 Docker Compose 파일에서 분리하여 관리할 수 있습니다.
.env 파일 (같은 폴더에 생성):
##############################################
# n8n 환경 변수 파일
# 이 파일은 Docker Compose와 같은 폴더에 저장
# 주의: 이 파일을 Git 등에 커밋하지 마세요!
##############################################
# 도메인 설정
N8N_DOMAIN=n8n.yourdomain.com
# PostgreSQL 설정
POSTGRES_DB=n8n
POSTGRES_USER=n8n_user
POSTGRES_PASSWORD=YourVeryStrongPassword123!
# n8n 암호화 키 (최소 32자)
# 생성 방법: openssl rand -hex 32
N8N_ENCRYPTION_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
# 시간대
TIMEZONE=Asia/Seoul
환경 변수 파일을 사용하는 Docker Compose :
version: '3.8'
services:
db:
image: postgres:17
container_name: n8n-db
restart: unless-stopped
environment:
# .env 파일의 변수 참조
- POSTGRES_DB=${POSTGRES_DB}
- POSTGRES_USER=${POSTGRES_USER}
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
- TZ=${TIMEZONE}
volumes:
- /volume1/docker/n8n/db:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
networks:
- n8n-network
n8n:
image: n8nio/n8n:latest
container_name: n8n
restart: unless-stopped
depends_on:
db:
condition: service_healthy
ports:
- "5678:5678"
environment:
# 데이터베이스 설정 (.env 변수 참조)
- DB_TYPE=postgresdb
- DB_POSTGRESDB_HOST=db
- DB_POSTGRESDB_PORT=5432
- DB_POSTGRESDB_DATABASE=${POSTGRES_DB}
- DB_POSTGRESDB_USER=${POSTGRES_USER}
- DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
# 호스트 설정 (.env 변수 참조)
- N8N_HOST=${N8N_DOMAIN}
- N8N_PORT=5678
- N8N_PROTOCOL=https
- WEBHOOK_URL=https://${N8N_DOMAIN}/
- N8N_EDITOR_BASE_URL=https://${N8N_DOMAIN}/
# 기타 설정
- GENERIC_TIMEZONE=${TIMEZONE}
- TZ=${TIMEZONE}
- N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
volumes:
- /volume1/docker/n8n/data:/home/node/.n8n
- /volume1/docker/n8n/files:/files
networks:
- n8n-network
networks:
n8n-network:
driver: bridge
Docker Compose 프로젝트 실행 및 관리
Docker Compose 파일 작성이 완료되면 Container Manager에서 프로젝트를 빌드하고 실행합니다. 프로젝트가 성공적으로 시작되면 '프로젝트' 목록에서 상태를 확인할 수 있습니다. 프로젝트 관리 기능을 통해 전체 스택을 한 번에 시작, 중지, 재시작할 수 있으며, 로그 확인과 설정 수정도 가능합니다.
프로젝트 빌드 및 프로젝트 상태 확인
위치: Container Manager > 프로젝트
- Docker Compose 파일 작성 후 '다음' 버튼을 클릭합니다
- 환경설정이 정상적이라면 빌드 진행 시 에러없이 진행됩니다.
- 프로젝트 빌드가 완료된 후 프로젝트 목록을 확인합니다
- n8n 관련 프로젝트가 '실행 중' 상태로 표시됩니다.
- 프로젝트에 포함된 컨테이너 수와 상태값을 확인합니다.
- 해당 프로젝트를 선택한 후, 마우스 우클릭시 해당 프로젝트에 대한 '시작', '중지', '재빌드' 등의 관리 버튼을 확인합니다.
5. n8n 컨테이너 환경 설정
기본 환경 변수 설정
n8n의 동작을 세밀하게 제어하려면 환경 변수를 적절히 설정해야 합니다. 가장 기본적인 환경 변수들부터 살펴보겠습니다.
- N8N_HOST는 n8n이 외부에 노출될 호스트명을 지정하며, 역방향 프록시를 사용하는 경우 해당 도메인을 입력합니다. 일반적으로 내부/외부에서의 접근을 고려해 특정 도메인을 지정 하는것 보다 '0.0.0.0'으로 지정하는 것이 유리합니다.
- N8N_PORT는 n8n 웹 인터페이스가 사용할 포트 번호로, 기본값은 5678입니다.
- N8N_PROTOCOL은 HTTP 또는 HTTPS 중 하나를 선택하며, 보안을 위해 HTTPS 사용을 강력히 권장합니다.
- GENERIC_TIMEZONE과 TZ 변수를 모두 'Asia/Seoul'로 설정하면, 스케줄 트리거와 로그 기록이 한국 시간 기준으로 동작합니다.시간대 관련 설정은 매우 중요합니다. 이 설정을 하지 않으면 UTC 기준으로 동작하여 예약 작업이 의도한 시간에 실행되지 않을 수 있습니다.
- N8N_DEFAULT_BINARY_DATA_MODE는 바이너리 데이터(파일) 처리 방식을 지정하는데, 'filesystem'으로 설정하면 메모리 사용을 줄이고 대용량 파일 처리가 가능해집니다.
고급 환경 변수 설정
n8n의 동작을 더욱 세밀하게 제어하고 싶다면 고급 환경 변수들을 활용할 수 있습니다. 아래는 프로덕션 환경에서 권장되는 고급 설정들입니다.
#================================================
# 고급 환경 변수 설정 (프로덕션 권장)
#================================================
environment:
#-----------------------------------------
# 암호화 및 보안
#-----------------------------------------
# 자격 증명 암호화 키 (필수 백업!)
# 최소 32자 이상의 랜덤 문자열
# 생성 명령: openssl rand -hex 32
- N8N_ENCRYPTION_KEY=a1b2c3d4e5f6789012345678901234567890abcdef
# HTTPS 환경에서 보안 쿠키 사용
- N8N_SECURE_COOKIE=true
# SameSite 쿠키 설정 (CSRF 방어)
# strict: 같은 사이트에서만 전송
# lax: 안전한 HTTP 메서드에서 허용 (기본값)
# none: 항상 전송 (HTTPS 필수)
- N8N_SAMESITE_COOKIE=lax
# Code 노드에서 환경 변수 접근 차단
# 보안상 true 권장
- N8N_BLOCK_ENV_ACCESS_IN_NODE=true
# 파일 시스템 접근 제한
# 허용할 디렉토리만 지정
- N8N_RESTRICT_FILE_ACCESS_TO=/files
# n8n 파일에 대한 접근 차단
- N8N_BLOCK_FILE_ACCESS_TO_N8N_FILES=true
#-----------------------------------------
# 실행 관리
#-----------------------------------------
# 워크플로우 실행 모드
# regular: 일반 모드 (기본값)
# queue: 큐 모드 (대규모 환경)
- EXECUTIONS_MODE=regular
# 단일 워크플로우 실행 타임아웃 (초)
# 무한 루프 방지
- EXECUTIONS_TIMEOUT=3600
# 최대 실행 타임아웃 (초)
- EXECUTIONS_TIMEOUT_MAX=7200
# 실행 데이터 자동 정리
- EXECUTIONS_DATA_PRUNE=true
# 실행 기록 보관 기간 (시간)
# 336 = 14일
- EXECUTIONS_DATA_MAX_AGE=336
# 오류 발생 시 실행 데이터 저장
# all: 모두 저장
# none: 저장 안함
- EXECUTIONS_DATA_SAVE_ON_ERROR=all
# 성공 시 실행 데이터 저장
- EXECUTIONS_DATA_SAVE_ON_SUCCESS=all
# 수동 실행 데이터 저장
- EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS=true
# 동시 실행 워크플로우 수 제한
# NAS 사양에 따라 조절 (낮은 사양: 5, 높은 사양: 20)
- N8N_CONCURRENCY_PRODUCTION_LIMIT=10
#-----------------------------------------
# 로깅 및 모니터링
#-----------------------------------------
# 로그 레벨
# silent: 로그 없음
# error: 오류만
# warn: 경고 이상
# info: 정보 이상 (기본값)
# debug: 디버그 포함 (개발용)
- N8N_LOG_LEVEL=info
# 로그 출력 대상
# console: 콘솔 출력 (Docker 환경 권장)
# file: 파일 저장
- N8N_LOG_OUTPUT=console
# 로그 파일 위치 (file 출력 시)
- N8N_LOG_FILE_LOCATION=/home/node/.n8n/logs/n8n.log
# 로그 파일 최대 크기 (MB)
- N8N_LOG_FILE_SIZE_MAX=16
# 보관할 로그 파일 수
- N8N_LOG_FILE_COUNT_MAX=100
#-----------------------------------------
# 메트릭스 (선택적 모니터링)
#-----------------------------------------
# Prometheus 메트릭스 활성화
- N8N_METRICS=false
# 메트릭스 엔드포인트 프리픽스
- N8N_METRICS_PREFIX=n8n_
#-----------------------------------------
# 웹훅 설정
#-----------------------------------------
# 웹훅 페이로드 최대 크기 (MB)
- N8N_PAYLOAD_SIZE_MAX=16
#-----------------------------------------
# 사용자 관리
#-----------------------------------------
# 사용자 등록 비활성화 (첫 사용자 생성 후)
- N8N_USER_MANAGEMENT_DISABLED=false
#-----------------------------------------
# 텔레메트리 (선택)
#-----------------------------------------
# 익명 사용 통계 전송 비활성화
- N8N_DIAGNOSTICS_ENABLED=false
#-----------------------------------------
# 템플릿 (워크플로우 템플릿 갤러리)
#-----------------------------------------
# 템플릿 기능 활성화
- N8N_TEMPLATES_ENABLED=true6. 네트워크 설정
포트 설정 및 포트포워딩
n8n 컨테이너는 기본적으로 5678 포트에서 웹 인터페이스를 제공합니다.
같은 로컬 네트워크 내에서만 n8n에 접속할 계획이라면 컨테이너의 5678 포트를 호스트의 5678 포트에 매핑하는 것만으로 충분합니다. Container Manager의 포트 설정에서 로컬 포트와 컨테이너 포트를 모두 5678로 설정하면 됩니다. 그러면 http://NAS의IP주소:5678로 접속할 수 있게 됩니다. 다른 애플리케이션이 이미 5678 포트를 사용 중이라면, 로컬 포트를 다른 번호(예: 5679)로 변경할 수 있습니다.
외부 인터넷에서 n8n에 접속하거나 웹훅을 수신하려면 포트포워딩 설정이 필요합니다.
가정용 인터넷 환경에서는 공유기(라우터)의 관리 화면에 접속하여 포트포워딩 규칙을 추가해야 합니다. 외부 포트 5678을 NAS의 내부 IP 주소와 포트 5678로 포워딩하면 외부에서 직접 접속이 가능해집니다. 하지만 보안상의 이유로 직접 포트포워딩보다는 역방향 프록시를 사용하여 HTTPS로 접속하는 것을 강력히 권장합니다. 역방향 프록시를 사용하면 SSL 인증서 적용이 용이하고, 추가적인 보안 레이어를 제공받을 수 있습니다.
Synology 역방향 프록시 설정
Synology DSM에는 역방향 프록시 기능이 내장되어 있어서 별도의 Nginx나 Traefik 설치 없이도 안전한 HTTPS 접속을 구성할 수 있습니다. 역방향 프록시를 설정하려면 DSM의 '제어판 > 로그인 포털 > 고급 > 역방향 프록시'로 이동합니다. '생성' 버튼을 클릭하고 다음과 같이 설정합니다.
설정위치: DSM > 제어판 > 로그인 포털 > 고급
- DSM "제어판 > 로그인 포털 > 고급 탭에서 '역방향 프록시' 버튼을 클릭하여 설정 화면으로 이동합니다."
- 역방향 프록시 목록에서 '생성' 버튼을 클릭합니다
- 역방향 프록시 규칙 생성 화면을 캡쳐합니다
- 다음 설정이 입력된 상태를 보여줍니다:
- 설명: n8n
- 소스 프로토콜: HTTPS
- 소스 호스트명: n8n.yourdomain.synology.me
- 소스 포트: 443
- 대상 프로토콜: HTTP
- 대상 호스트명: localhost
- 대상 포트: 5678
HSTS 활성화 설정
HSTS (HTTP Strict Transport Security)는 웹 브라우저에게 "이 사이트는 항상 HTTPS로만 접속하라"고 강제하는 보안 정책입니다.
작동 방식
1. 사용자가 http://n8n.yourdomain.synology.me 접속 시도
2. HSTS가 활성화되어 있으면 브라우저가 자동으로 https://로 변환
3. 이후 해당 도메인은 HTTP 접속 자체가 차단됨
HSTS 활성화 시 장단점
장점 : 중간자 공격(MITM) 방지, HTTP 다운그레이드 공격 차단, 보안 강화
단점 : HTTPS 인증서 만료/오류 시 접속 불가, 설정 해제 후에도 브라우저 캐시 기간 동안 유지
권장 설정
처음에는 HSTS를 비활성화 한 상태로 설정을 완료하고, n8n이 정상 동작하는 것을 확인한 후에 필요하다면 나중에 활성화하세요. HSTS는 한번 활성화되면 브라우저에 캐시되어 해제하기 번거로울 수 있습니다.
WebSocket 헤더 설정
n8n은 실시간 통신을 위해 WebSocket을 사용하므로, 역방향 프록시에 WebSocket 헤더 설정을 추가해야 합니다. 역방향 프록시 규칙을 생성한 후 '사용자 정의 헤더' 탭으로 이동하여 '생성' 버튼을 클릭하고 드롭다운 메뉴에서 'WebSocket'을 선택합니다. 이렇게 하면 Upgrade와 Connection 헤더가 자동으로 추가됩니다. 이 설정이 없으면 n8n 에디터에서 연결 끊김 현상이 발생하거나, 웹훅 테스트 리스닝이 정상적으로 동작하지 않을 수 있습니다. 추가로 '제어판 > 네트워크 > 연결성' 탭에서 'HTTP/2 활성화'를 체크하면 성능이 향상됩니다.
설정 위치 : DSM > 역방향 프록시 > 사용자 정의 헤더
- 역방향 프록시 규칙 편집 화면에서 '사용자 정의 헤더' 탭을 클릭합니다
- '생성' > 'WebSocket'을 선택하여 WebSocket 헤더를 추가합니다
- Upgrade와 Connection 헤더가 자동으로 추가되며, 기본값 그대로 사용합니다.
- n8n 에디터의 실시간 통신을 위해 이 설정이 필수입니다."
역방향 프록시 설정 요약:
[소스(외부)]
프로토콜: HTTPS
호스트명: n8n.yourdomain.synology.me
포트: 443
[대상(내부)]
프로토콜: HTTP
호스트명: localhost
포트: 5678
[사용자 정의 헤더]
Upgrade: $http_upgrade
Connection: $connection_upgradeWebhook URL 설정의 중요성
n8n을 역방향 프록시 뒤에서 운영할 때 가장 흔히 발생하는 문제가 웹훅 URL 설정과 관련되어 있습니다. n8n은 내부적으로 N8N_PROTOCOL, N8N_HOST, N8N_PORT를 조합하여 웹훅 URL을 생성하는데, 역방향 프록시 환경에서는 이것이 실제 외부 접속 URL과 일치하지 않게 됩니다. 예를 들어, n8n은 내부적으로 5678 포트에서 실행되지만 역방향 프록시는 443 포트로 외부에 노출합니다. 이런 불일치를 해결하기 위해 WEBHOOK_URL 환경 변수를 반드시 설정해야 합니다.
7. 기존 PostgreSQL 컨테이너와 n8n 연동
두 가지 아키텍처 패턴
n8n과 PostgreSQL을 연동하는 방식은 크게 두 가지가 있습니다.
┌─────────────────────────────────────────────────────────────────────┐
│ 패턴 A: 전용 DB 방식 │
│ (n8n 프로젝트 내에 DB 포함) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ /volume1/docker/n8n/ │
│ ├── compose.yaml ← n8n + PostgreSQL 함께 정의 │
│ ├── data/ ← n8n 애플리케이션 데이터 │
│ ├── db/ ← PostgreSQL 데이터 (n8n 전용) │
│ └── files/ ← n8n 파일 저장소 │
│ │
│ 장점: 독립적, 백업/이전 용이 │
│ 단점: DB 리소스 중복 (여러 앱이 각자 DB 운영) │
│ │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ 패턴 B: 공유 DB 방식 (권장) │
│ (독립 PostgreSQL + 여러 앱 연결) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ /volume1/docker/postgresql/ │
│ ├── compose.yaml ← PostgreSQL만 정의 │
│ └── data/ ← 모든 DB 데이터 통합 저장 │
│ ├── n8n DB │
│ ├── nextcloud DB │
│ └── 기타 앱 DB... │
│ │
│ /volume1/docker/n8n/ │
│ ├── compose.yaml ← n8n만 정의 (DB 없음) │
│ ├── data/ ← n8n 애플리케이션 데이터 │
│ └── files/ ← n8n 파일 저장소 │
│ (db/ 폴더 불필요!) │
│ │
│ 장점: 리소스 효율적, 중앙 집중 관리, 백업 단순화 │
│ 단점: DB 장애 시 모든 앱 영향 │
│ │
└─────────────────────────────────────────────────────────────────────┘볼륨 경로의 의미
| 경로 | 용도 | 필요 시점 |
| /volume1/docker/n8n/db/ | n8n 전용 PostgreSQL 데이터 | 패턴 A (전용 DB) 사용 시만 |
| /volume1/docker/postgresql/data/ | 공유 PostgreSQL 데이터 | 패턴 B (공유 DB) 사용 시 |
| /volume1/docker/n8n/data/ | n8n 워크플로우, 설정, 암호화 키 | 항상 필요 |
| /volume1/docker/n8n/files/ | n8n에서 처리하는 파일들 | 파일 노드 사용 시 |
핵심 포인트:
공유 PostgreSQL을 사용하면 /volume1/docker/n8n/db/ 폴더는 필요 없습니다!
PostgreSQL은 자체적으로 데이터베이스와 테이블을 관리하며, 모든 데이터는 PostgreSQL 컨테이너의 볼륨(/volume1/docker/postgresql/data/)에 저장됩니다.
기존 PostgreSQL 컨테이너 확인
먼저 현재 실행 중인 PostgreSQL 정보를 확인합니다.
# PostgreSQL 컨테이너 확인
docker ps | grep postgres
# 컨테이너 상세 정보 (네트워크, 포트 등)
docker inspect [postgresql_컨테이너_이름] | grep -A 20 "NetworkSettings"
# 접속 테스트
docker exec -it [postgresql_컨테이너_이름] psql -U postgres -c "\l"
연동 방법 A : 같은 Docker 네트워크 사용 (권장)
Step 1: 공유 네트워크 생성 (없는 경우)
docker network create shared-networkStep 2: PostgreSQL을 공유 네트워크에 연결
방법 1 - 기존 컨테이너에 네트워크 추가:
docker network connect shared-network [postgresql_컨테이너_이름]
방법 2 - PostgreSQL compose.yaml 수정 (권장):
# /volume1/docker/postgresql/compose.yaml
version: '3.8'
services:
postgres:
image: postgres:latest
container_name: postgresql
restart: unless-stopped
ports:
- "5432:5432"
environment:
- TZ=Asia/Seoul
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=your_secure_password
volumes:
- /volume1/docker/postgresql:/var/lib/postgresql # version 17에서는 /data 추가
networks:
- shared-network
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
networks:
shared-network:
name: shared-network
driver: bridgeStep 3: n8n용 데이터베이스 생성
# PostgreSQL 컨테이너에서 n8n용 DB와 사용자 생성
docker exec -it postgresql psql -U postgres
# SQL 명령어 실행
CREATE DATABASE n8n;
CREATE USER n8n_user WITH ENCRYPTED PASSWORD 'n8n_secure_password';
GRANT ALL PRIVILEGES ON DATABASE n8n TO n8n_user;
ALTER DATABASE n8n OWNER TO n8n_user;
# 종료
\q
Step 4: n8n compose.yaml 작성
# /volume1/docker/n8n/compose.yaml
version: '3.8'
services:
n8n:
image: n8nio/n8n:latest
container_name: n8n-automation
restart: unless-stopped
ports:
- "5678:5678"
environment:
# 시간대
- TZ=Asia/Seoul
- GENERIC_TIMEZONE=Asia/Seoul
# 서버 설정
- N8N_HOST=0.0.0.0
- N8N_PORT=5678
- N8N_PROTOCOL=https
# 외부 URL
- WEBHOOK_URL=https://n8n.custom-domain.com/
- N8N_EDITOR_BASE_URL=https://n8n.custom-domain.com/
# 데이터베이스 연결 (외부 PostgreSQL)
- DB_TYPE=postgresdb
- DB_POSTGRESDB_HOST=postgresql # 컨테이너 이름으로 접근!
- DB_POSTGRESDB_PORT=5432
- DB_POSTGRESDB_DATABASE=n8n
- DB_POSTGRESDB_USER=n8n_user
- DB_POSTGRESDB_PASSWORD=n8n_secure_password
# 보안
- N8N_ENCRYPTION_KEY=256bf84bdc1c32c1031fc4a88933a61f
- N8N_SECURE_COOKIE=true
volumes:
- /volume1/docker/n8n/data:/home/node/.n8n
- /volume1/docker/n8n/files:/files
# db/ 폴더는 필요 없음!
networks:
- shared-network
healthcheck:
test: ["CMD-SHELL", "wget -qO- http://localhost:5678/healthz || exit 1"]
interval: 30s
timeout: 10s
retries: 3
networks:
shared-network:
external: true # 이미 존재하는 네트워크 사용연동 방법 B: 호스트 IP로 직접 연결
Docker 네트워크 설정 없이 NAS IP로 직접 연결하는 방법입니다.
# /volume1/docker/n8n/compose.yaml
services:
n8n:
image: n8nio/n8n:latest
container_name: n8n-automation
# ... 기타 설정 ...
environment:
# 데이터베이스 연결 (호스트 IP 사용)
- DB_TYPE=postgresdb
- DB_POSTGRESDB_HOST=192.168.111.4 # NAS 내부 IP
- DB_POSTGRESDB_PORT=5432
- DB_POSTGRESDB_DATABASE=n8n
- DB_POSTGRESDB_USER=n8n_user
- DB_POSTGRESDB_PASSWORD=n8n_secure_password
| 방법 | 장점 | 단점 |
| 네트워크 사용 (A) | 컨테이너 이름으로 통신, 보안적 | 네트워크 설정 필요 |
| 호스트 IP (B) | 설정 단순 | IP 변경 시 수정 필요, 포트 노출 |
폴더 구조 비교
불필요한 구조 (n8n 전용 DB 방식의 잔재)
/volume1/docker/n8n/
├── compose.yaml
├── data/ ← n8n 앱 데이터 (필요)
├── db/ ← 공유 PostgreSQL 사용 시 불필요!
└── files/ ← n8n 파일 (필요)권장 구조 (공유 DB 방식)
/volume1/docker/
│
├── postgresql/ # PostgreSQL 전용 프로젝트
│ ├── compose.yaml
│ └── data/ # 모든 DB 데이터 저장
│ ├── base/ # PostgreSQL 내부 구조
│ ├── global/
│ └── ...
│
├── n8n/ # n8n 프로젝트
│ ├── compose.yaml
│ ├── data/ # 워크플로우, 설정
│ └── files/ # 파일 노드용
│ (db/ 폴더 없음!)
│
└── nextcloud/ # 다른 앱도 같은 PostgreSQL 사용 가능
├── compose.yaml
└── data/데이터 저장 위치 이해
┌──────────────────────────────────────────────────────────────┐
│ PostgreSQL 컨테이너 │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ /var/lib/postgresql/data/ (컨테이너 내부 경로) │ │
│ │ ├── n8n 데이터베이스 │ │
│ │ ├── nextcloud 데이터베이스 │ │
│ │ └── 기타 데이터베이스... │ │
│ └───────────────────────┬────────────────────────────────┘ │
└──────────────────────────┼───────────────────────────────────┘
│ 볼륨 마운트
▼
┌──────────────────────────────────────────────────────────────┐
│ /volume1/docker/postgresql/data/ (NAS 실제 저장 위치) │
│ - 모든 데이터베이스가 여기에 물리적으로 저장됨 │
│ - 백업 시 이 폴더만 복사하면 됨 │
└──────────────────────────────────────────────────────────────┘자주 묻는 질문
Q: /volume1/docker/n8n/db/를 별도로 지정하는 예제가 있는 이유는?
그 예제들은 n8n 프로젝트 내에 전용 PostgreSQL을 함께 포함하는 "올인원" 방식입니다. 이 경우 n8n과 PostgreSQL이 하나의 compose.yaml에 정의되고, DB 데이터는 n8n 폴더 하위에 저장됩니다.
Q: 공유 PostgreSQL 사용 시 장점은?
| 항목 | 전용 DB(앱마다 별도) | 공유 DB (하나로 통합) |
| 메모리 사용 | 앱 × PostgreSQL 개수 | PostgreSQL 1개만 |
| 백업 | 각 앱 폴더마다 | PostgreSQL 폴더만 |
| 관리 | 분산됨 | 중앙 집중 |
| 장애 영향 | 해당 앱만 | 모든 앱 |
Q: 기존 n8n 데이터(SQLite)를 PostgreSQL로 마이그레이션하려면?
# n8n 내장 마이그레이션 명령어
docker exec -it n8n-automation n8n export:workflow --all --output=/files/workflows.json
docker exec -it n8n-automation n8n export:credentials --all --output=/files/credentials.json
# 새 PostgreSQL 연결 후 import
docker exec -it n8n-automation n8n import:workflow --input=/files/workflows.json
docker exec -it n8n-automation n8n import:credentials --input=/files/credentials.json실행 순서
# 1. PostgreSQL 먼저 실행 (이미 실행 중이면 생략)
cd /volume1/docker/postgresql
docker compose up -d
# 2. PostgreSQL 정상 동작 확인
docker compose ps
docker exec -it postgresql pg_isready -U postgres
# 3. n8n 실행
cd /volume1/docker/n8n
docker compose up -d
# 4. 연결 확인
docker compose logs -f n8n | grep -i database8. PostgreSQL 연동 설정
SQLite vs PostgreSQL 비교
SQLite
n8n은 기본적으로 SQLite 데이터베이스를 사용하여 워크플로우, 자격 증명, 실행 기록 등을 저장합니다. SQLite는 별도의 데이터베이스 서버 없이 파일 기반으로 동작하므로 설정이 간단하고 리소스 사용량이 적습니다. 소규모 환경이나 테스트 용도로는 SQLite가 충분히 적합합니다. 하지만 워크플로우 수가 증가하고 실행 빈도가 높아지면 SQLite의 성능 한계에 부딪힐 수 있습니다. 특히 동시 쓰기 작업이 많은 환경에서는 데이터베이스 잠금으로 인한 성능 저하가 발생할 수 있습니다.
PostgreSQL
PostgreSQL은 엔터프라이즈급 오픈소스 관계형 데이터베이스로, 높은 동시성과 복잡한 쿼리 처리에 강점이 있습니다. n8n 공식 문서에서도 프로덕션 환경에서는 PostgreSQL 사용을 권장하고 있습니다. PostgreSQL을 사용하면 다중 사용자 환경에서의 안정성이 향상되고, 대량의 실행 기록을 효율적으로 관리할 수 있습니다. 또한 PostgreSQL의 백업 및 복구 기능이 더 강력하여 데이터 안전성 측면에서도 유리합니다. 다만 PostgreSQL을 사용하려면 별도의 데이터베이스 컨테이너를 함께 운영해야 하므로 설정이 다소 복잡해지고 시스템 리소스도 더 많이 필요합니다.
PostgreSQL 환경 변수 상세 설명
#================================================
# PostgreSQL 연동 환경 변수 상세
#================================================
environment:
#-----------------------------------------
# 필수 설정
#-----------------------------------------
# 데이터베이스 유형
# sqlite: 기본값, 파일 기반
# postgresdb: PostgreSQL 사용
- DB_TYPE=postgresdb
# PostgreSQL 서버 호스트
# Docker Compose: 서비스 이름 (예: db)
# 외부 서버: IP 주소 또는 도메인
- DB_POSTGRESDB_HOST=db
# PostgreSQL 포트 (기본값: 5432)
- DB_POSTGRESDB_PORT=5432
# 데이터베이스 이름
- DB_POSTGRESDB_DATABASE=n8n
# 데이터베이스 사용자
- DB_POSTGRESDB_USER=n8n_user
# 데이터베이스 비밀번호
- DB_POSTGRESDB_PASSWORD=your_secure_password
#-----------------------------------------
# 선택적 설정
#-----------------------------------------
# 스키마 이름 (기본값: public)
# 여러 n8n 인스턴스 분리 시 유용
- DB_POSTGRESDB_SCHEMA=public
# 연결 풀 크기 (동시 연결 수)
# 기본값: 5
# 높은 동시성 환경: 10-20
- DB_POSTGRESDB_POOL_SIZE=5
# 연결 타임아웃 (밀리초)
# 기본값: 10000 (10초)
- DB_POSTGRESDB_CONNECTION_TIMEOUT_MS=10000
# 유휴 연결 제거 시간 (밀리초)
- DB_POSTGRESDB_IDLE_TIMEOUT_MS=10000
#-----------------------------------------
# SSL 설정 (외부 PostgreSQL 사용 시)
#-----------------------------------------
# SSL 사용 여부
- DB_POSTGRESDB_SSL_ENABLED=false
# SSL 인증서 검증 거부 여부
# true: 자체 서명 인증서 허용
- DB_POSTGRESDB_SSL_REJECT_UNAUTHORIZED=true
# SSL CA 인증서 경로
- DB_POSTGRESDB_SSL_CA=/path/to/ca.pem
# SSL 클라이언트 인증서 경로
- DB_POSTGRESDB_SSL_CERT=/path/to/cert.pem
# SSL 클라이언트 키 경로
- DB_POSTGRESDB_SSL_KEY=/path/to/key.pem
n8n 주요 테이블 구조
n8n이 처음 실행되면 n8n 데이터베이스 안에 다음 테이블들을 자동 생성합니다:
| 테이블명 | 저장 내용 |
| workflow_entity | 워크플로우 정의 (노드, 연결, 설정) |
| execution_entity | 워크플로우 실행 기록 |
| credentials_entity | 암호화된 자격 증명 (API 키 등) |
| user | 사용자 계정 정보 |
| settings | n8n 인스턴스 설정 |
| webhook_entity | 웹훅 URL 매핑 |
| tag_entity | 워크플로우 태그 |
| variables | 환경 변수 |
| shared_workflow | 워크플로우 공유 설정 |
| shared_credentials | 자격 증명 공유 설정 |
9. 추가 기능 설정
사용자 인증 및 SMTP 설정
n8n을 외부 인터넷에 노출하는 경우, 무단 접근을 방지하기 위한 인증 설정이 필수입니다. n8n은 이메일 기반의 사용자 관리 시스템을 기본으로 제공하며, 처음 접속 시 관리자 계정을 생성하도록 안내합니다. 추가 사용자를 초대하려면 n8n 설정에서 SMTP 이메일 서버를 구성해야 합니다.
#================================================
# SMTP 및 사용자 관리 설정
#================================================
environment:
#-----------------------------------------
# SMTP 설정 (이메일 발송용)
#-----------------------------------------
# SMTP 서버 호스트
# Gmail: smtp.gmail.com
# Outlook: smtp.office365.com
# Naver: smtp.naver.com
- N8N_SMTP_HOST=smtp.gmail.com
# SMTP 포트
# TLS: 587 (권장)
# SSL: 465
- N8N_SMTP_PORT=587
# SMTP 사용자 (이메일 주소)
- N8N_SMTP_USER=your-email@gmail.com
# SMTP 비밀번호
# Gmail: 앱 비밀번호 사용 (2단계 인증 필요)
- N8N_SMTP_PASS=your-app-specific-password
# 발신자 이메일 주소
- N8N_SMTP_SENDER=your-email@gmail.com
# SSL 사용 여부 (포트 465 사용 시 true)
- N8N_SMTP_SSL=false
#-----------------------------------------
# 사용자 관리 설정
#-----------------------------------------
# 사용자 관리 기능 비활성화
# true: 사용자 관리 없이 단일 사용자로 운영
- N8N_USER_MANAGEMENT_DISABLED=false
# 이메일 기반 초대 기능 활성화
- N8N_EMAIL_MODE=smtp10. Synology NAS에서의 n8n 성능
NAS 모델별 성능 고려사항
Synology NAS 모델에 따라 n8n 실행 성능에 상당한 차이가 있을 수 있습니다. 저가형 모델(DS218, DS220j 등)은 ARM 프로세서와 512MB~1GB의 제한된 RAM을 탑재하고 있어서, 복잡한 워크플로우나 대량 데이터 처리에는 적합하지 않습니다. 이런 모델에서 n8n을 실행하면 메모리 부족으로 컨테이너가 재시작되거나, 응답 속도가 매우 느려질 수 있습니다. 반면 플러스 시리즈(DS220+, DS420+, DS920+ 등)나 비즈니스 시리즈는 Intel/AMD 프로세서와 충분한 RAM을 탑재하고 있어서 n8n을 원활하게 실행할 수 있습니다.
#================================================
# NAS 사양별 권장 설정
#================================================
# 저사양 NAS (2GB RAM, ARM)
# DS218j, DS220j 등
environment:
- N8N_CONCURRENCY_PRODUCTION_LIMIT=3
- EXECUTIONS_DATA_MAX_AGE=72 # 3일
- N8N_LOG_LEVEL=warn # 로그 최소화
- DB_TYPE=sqlite # SQLite 권장
# 중간 사양 NAS (4GB RAM, x86)
# DS220+, DS420+ 등
environment:
- N8N_CONCURRENCY_PRODUCTION_LIMIT=5
- EXECUTIONS_DATA_MAX_AGE=168 # 7일
- N8N_LOG_LEVEL=info
- DB_TYPE=sqlite # SQLite 또는 PostgreSQL
# 고사양 NAS (8GB+ RAM, x86)
# DS920+, DS1621+ 등
environment:
- N8N_CONCURRENCY_PRODUCTION_LIMIT=15
- EXECUTIONS_DATA_MAX_AGE=336 # 14일
- N8N_LOG_LEVEL=info
- DB_TYPE=postgresdb # PostgreSQL 권장11. Webhook 테스트
외부 서비스와의 연동에서 핵심이 되는 웹훅 기능을 테스트합니다.
# 웹훅 테스트 명령어 (터미널에서 실행)
# URL은 본인의 n8n 웹훅 URL로 변경
# 기본 POST 요청
curl -X POST https://n8n.yourdomain.com/webhook/test-webhook \
-H "Content-Type: application/json" \
-d '{"name": "Test User", "action": "test"}'
# 상세 출력 포함
curl -v -X POST https://n8n.yourdomain.com/webhook/test-webhook \
-H "Content-Type: application/json" \
-d '{"message": "Hello from curl!"}'
# 파일 업로드 테스트
curl -X POST https://n8n.yourdomain.com/webhook/file-upload \
-F "file=@/path/to/file.txt"12. 트러블슈팅 완벽 가이드
컨테이너 시작 실패 문제
증상 1: 컨테이너가 계속 재시작됨
오류 로그 확인 방법:
# SSH로 NAS 접속 후 Docker 로그 확인
docker logs n8n --tail 100
# 실시간 로그 모니터링
docker logs n8n -f원인 1: 메모리 부족 (Out of Memory)
# 오류 메시지 예시
FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory
해결 방법:
# Docker Compose에 메모리 제한 설정 추가
services:
n8n:
# ... 기존 설정 ...
deploy:
resources:
limits:
memory: 2G
reservations:
memory: 512M
environment:
# Node.js 힙 메모리 증가
- NODE_OPTIONS=--max-old-space-size=1536원인 2: 볼륨 마운트 경로 오류
# 오류 메시지 예시
Error: EACCES: permission denied, mkdir '/home/node/.n8n'
Error: ENOENT: no such file or directory
해결 방법:
# SSH로 NAS 접속
ssh admin@NAS_IP
# 폴더 권한 확인
ls -la /volume1/docker/n8n/
# 권한 수정 (필요한 경우)
sudo chown -R 1000:1000 /volume1/docker/n8n/data
sudo chown -R 1000:1000 /volume1/docker/n8n/files원인 3: 포트 충돌
# 오류 메시지 예시
Error: listen EADDRINUSE: address already in use :::5678
해결 방법:
# 5678 포트를 사용 중인 프로세스 확인
sudo netstat -tlnp | grep 5678
# 또는 다른 포트 사용 (Docker Compose 수정)
ports:
- "5679:5678" # 호스트 포트를 5679로 변경
데이터베이스 연결 문제
증상 2: PostgreSQL 연결 실패
오류 메시지 예시:
Error: connect ECONNREFUSED 172.18.0.2:5432
Error: FATAL: password authentication failed for user "n8n_user"
Error: FATAL: database "n8n" does not exist
진단 방법:
# PostgreSQL 컨테이너 상태 확인
docker ps | grep n8n-db
# PostgreSQL 로그 확인
docker logs n8n-db --tail 50
# PostgreSQL 컨테이너 내부에서 연결 테스트
docker exec -it n8n-db psql -U n8n_user -d n8n
해결 방법 체크리스트:
# 1. 환경 변수 일치 여부 확인
# PostgreSQL 컨테이너 설정
db:
environment:
- POSTGRES_DB=n8n # ← 일치해야 함
- POSTGRES_USER=n8n_user # ← 일치해야 함
- POSTGRES_PASSWORD=MyPass # ← 일치해야 함
# n8n 컨테이너 설정
n8n:
environment:
- DB_POSTGRESDB_DATABASE=n8n # ← 위와 동일
- DB_POSTGRESDB_USER=n8n_user # ← 위와 동일
- DB_POSTGRESDB_PASSWORD=MyPass # ← 위와 동일
# 2. 호스트 이름 확인
# Docker Compose 내에서는 서비스 이름 사용
- DB_POSTGRESDB_HOST=db # 'localhost' 아님!
# 3. 네트워크 연결 확인
# 두 서비스가 같은 네트워크에 있어야 함
networks:
- n8n-network웹훅 동작 문제
증상 3: 웹훅이 응답하지 않음
진단 단계:
# 1. 내부에서 웹훅 테스트 (NAS SSH 접속 후)
curl -v http://localhost:5678/webhook/test
# 2. 외부에서 웹훅 테스트
curl -v https://n8n.yourdomain.com/webhook/test
# 3. DNS 확인
nslookup n8n.yourdomain.com
# 4. 포트 개방 확인
nc -zv n8n.yourdomain.com 443
원인 및 해결 방법:
# 원인 1: WEBHOOK_URL 미설정 또는 잘못된 설정
# 해결: 환경 변수 확인
environment:
- WEBHOOK_URL=https://n8n.yourdomain.com/ # 끝에 / 필수!
- N8N_EDITOR_BASE_URL=https://n8n.yourdomain.com/
# 원인 2: 역방향 프록시 WebSocket 헤더 누락
# 해결: Synology 역방향 프록시에 WebSocket 헤더 추가
# 원인 3: 워크플로우 비활성화
# 해결: 워크플로우가 'Active' 상태인지 확인
# 비활성화 상태에서는 Production URL이 동작하지 않음
자격 증명 복호화 오류
증상 4: "Credentials could not be decrypted" 오류
오류 메시지:
Error: Credentials could not be decrypted.
The likely reason is that a different "encryptionKey" was used to encrypt the data.
원인:
- N8N_ENCRYPTION_KEY 환경 변수가 변경됨
- 컨테이너 재생성 시 암호화 키가 달라짐
- 데이터 마이그레이션 시 키 불일치
해결 방법:
# 1. 현재 암호화 키 확인 (컨테이너 내부)
docker exec -it n8n cat /home/node/.n8n/config
# 2. 기존 키 복원
# Docker Compose에 정확한 키 설정
environment:
- N8N_ENCRYPTION_KEY=원래_사용하던_암호화_키
# 3. 키 복구 불가 시: 자격 증명 재생성 필요
# 기존 자격 증명 삭제 후 새로 생성
예방 방법:
# Docker Compose에 명시적으로 암호화 키 설정
# 이 키를 안전한 곳에 별도 백업!
environment:
- N8N_ENCRYPTION_KEY=a1b2c3d4e5f6789012345678901234567890abcd
# .env 파일로 분리 관리 권장
# .env 파일:
# N8N_ENCRYPTION_KEY=a1b2c3d4e5f6789012345678901234567890abcd
# docker-compose.yml:
environment:
- N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}성능 관련 문제
증상 5: 워크플로우 실행이 느림 또는 타임아웃
진단 명령:
# 컨테이너 리소스 사용량 확인
docker stats n8n n8n-db
# 실시간 모니터링
docker stats --no-stream
최적화 설정:
# 성능 최적화 환경 변수
environment:
# 동시 실행 제한
- N8N_CONCURRENCY_PRODUCTION_LIMIT=5
# 실행 타임아웃 설정 (초)
- EXECUTIONS_TIMEOUT=1800 # 30분
- EXECUTIONS_TIMEOUT_MAX=3600 # 1시간
# 메모리 효율적인 파일 처리
- N8N_DEFAULT_BINARY_DATA_MODE=filesystem
# 실행 기록 자동 정리
- EXECUTIONS_DATA_PRUNE=true
- EXECUTIONS_DATA_MAX_AGE=168 # 7일
# 로그 레벨 낮춤 (디버그 로그 비활성화)
- N8N_LOG_LEVEL=warn네트워크 연결 문제
증상 6: 외부 API 호출 실패
오류 메시지 예시:
Error: getaddrinfo ENOTFOUND api.example.com
Error: connect ETIMEDOUT
Error: self signed certificate in certificate chain
진단 및 해결:
# 컨테이너 내부에서 네트워크 테스트
docker exec -it n8n sh
# DNS 확인
nslookup api.example.com
# 연결 테스트
wget -O- https://api.example.com/health
# NAS DNS 설정 확인 필요할 수 있음
# DSM > 제어판 > 네트워크 > 일반 > DNS 서버# DNS 서버 명시적 설정 (Docker Compose)
services:
n8n:
dns:
- 8.8.8.8
- 8.8.4.4업데이트 후 문제
증상 7: 버전 업데이트 후 오류 발생
안전한 업데이트 절차:
# 1. 현재 버전 확인
docker exec n8n n8n --version
# 2. 데이터 백업
cp -r /volume1/docker/n8n /volume1/docker/n8n_backup_$(date +%Y%m%d)
# 3. 이미지 업데이트
docker pull n8nio/n8n:latest
# 4. 컨테이너 재생성
cd /volume1/docker/n8n
docker-compose down
docker-compose up -d
# 5. 로그 확인
docker logs n8n --tail 50 -f
롤백 방법 (문제 발생 시):
# 1. 현재 컨테이너 중지
docker-compose down
# 2. 백업 데이터 복원
rm -rf /volume1/docker/n8n/data
cp -r /volume1/docker/n8n_backup_날짜/data /volume1/docker/n8n/
# 3. 이전 버전 이미지로 실행
# docker-compose.yml에서 이미지 태그 변경
image: n8nio/n8n:1.19.0 # 이전 안정 버전
# 4. 재시작
docker-compose up -d13. 자주 묻는 질물 | FAQ
Q1: n8n 업데이트는 어떻게 하나요?
Container Manager의 '레지스트리'에서 n8nio/n8n 이미지를 다시 다운로드(Pull)합니다. 기존 컨테이너를 중지하고 삭제한 후, 동일한 설정으로 새 컨테이너를 생성합니다. Docker Compose를 사용하면 docker-compose pull && docker-compose up -d 명령으로 간편하게 업데이트할 수 있습니다.
Q2: 워크플로우 백업은 어떻게 하나요?
가장 간단한 방법은 /volume1/docker/n8n/data 폴더 전체를 Synology Hyper Backup으로 정기 백업하는 것입니다. 또는 n8n UI에서 워크플로우를 JSON 파일로 개별 내보내기할 수 있습니다. PostgreSQL을 사용하는 경우 pg_dump 명령으로 데이터베이스도 함께 백업하세요.
Q3: 여러 n8n 인스턴스를 운영할 수 있나요?
네, 가능합니다. 각 인스턴스마다 다른 포트, 다른 데이터 폴더, 다른 암호화 키를 사용하도록 설정하면 됩니다. PostgreSQL을 사용하는 경우 각 인스턴스별로 별도의 데이터베이스 또는 스키마를 사용하는 것이 좋습니다.
Q4: ARM 기반 NAS에서도 n8n을 실행할 수 있나요?
네, n8nio/n8n 이미지는 multi-architecture를 지원하므로 ARM64 기반 NAS에서도 실행됩니다. 다만 ARM 프로세서는 x86에 비해 성능이 낮을 수 있으므로, 복잡한 워크플로우 실행에는 한계가 있을 수 있습니다.
마무리
이 가이드를 통해 Synology NAS의 Docker 환경에서 n8n을 성공적으로 설치하고 구성하는 방법을 살펴보았습니다. n8n은 강력한 워크플로우 자동화 플랫폼으로, 올바르게 설정하면 일상적인 반복 작업을 자동화하고 업무 효율성을 크게 향상시킬 수 있습니다. 셀프 호스팅의 장점을 활용하여 데이터 프라이버시를 유지하면서도 클라우드 서비스 못지않은 자동화 기능을 활용해 보시기 바랍니다.
처음에는 설정 과정이 복잡해 보일 수 있지만, 한 번 제대로 구성하면 이후에는 안정적으로 운영할 수 있습니다. 문제가 발생했을 때는 이 가이드의 트러블슈팅 섹션을 참고하시고, n8n 공식 커뮤니티 포럼에서도 많은 도움을 받을 수 있습니다. 워크플로우 자동화의 세계로 첫 발을 내딛으신 것을 환영합니다!
참고 자료
- n8n 공식 문서: https://docs.n8n.io
- n8n Docker 설치 가이드: https://docs.n8n.io/hosting/installation/docker/
- n8n 환경 변수 레퍼런스: https://docs.n8n.io/hosting/configuration/environment-variables/
- n8n 커뮤니티 포럼: https://community.n8n.io
- Synology Container Manager 도움말: https://kb.synology.com/en-global/DSM/help/ContainerManager
'AI 활용' 카테고리의 다른 글
| AI 시대의 업무 자동화 플랫폼 | n8n 가이드 (1) | 2025.12.15 |
|---|---|
| [Claude] Agent Skill, Custom Instruction, MCP 완벽 비교 (3) | 2025.11.06 |
| [제조 AI] 8) RAG 시스템 구축 기초 - 제조업 기술문서 활용 (10) | 2025.10.01 |
| Google AI Studio 나노바나나를 활용한 건축 디자인 (11) | 2025.09.27 |
| [제조 AI] 7-2) 임베디드 AI 구축 사례 - 정밀 가공 실시간 품질 모니터링 (14) | 2025.09.18 |
