n8n 설치 방법? 초보자 로컬 배포 및 최초 실행 완전 튜토리얼
n8n 설치 자체는 어렵지 않다. 어려운 건 설치 후에 "데이터가 사라지지 않을까" 하는 문제다. 나는 너무 많은 사람이 명령어 한 줄로 실행하고 일주일 쓰다가 컨테이너를 삭제하고 재생성했더니 워크플로가 전부 사라진 걸 봤다 — 데이터 볼륨을 제대로 mount하지 않았기 때문이다.
이 글에서는 세 가지 일반적인 설치 방법을 "가장 적게 삽질하는" 순서로 정리한다: Docker, Docker Compose, npm. 설치 후에는 브라우저에서 열 수 있는 n8n이 생기고, 데이터는 로컬에 저장되어 사라지지 않으며, 시간대도 맞게 된다.
누구에게 적합한지, 시작 전에 무엇이 필요한지
서비스를 한 번도 배포해본 적 없는 사람에게 적합하지만, 터미널을 열고 명령어를 입력할 수 있어야 한다. Windows, macOS, Linux 모두 설치 가능하며, 이 글은 Docker를 중심으로 한다. 이후 업그레이드와 마이그레이션이 가장 간편하기 때문이다.
다른 사람의 머신에서 잠깐 테스트만 해보고 장기적으로 사용하지 않을 거라면 바로 세 번째 섹션의 npm 방식으로 넘어가라. 두 줄 명령어로 실행되지만, 중요한 데이터를 거기에 두지는 마라.
먼저 어디에 설치할지 결정하라
| 방식 | 적합한 대상 | 장점 | 대가 |
|---|---|---|---|
| Docker (단일 container) | 개인 컴퓨터, 경량 사용 | 격리가 깔끔하고, 삭제하면 그만이며, 업그레이드는 image만 교체 | Docker를 조금 배워야 함 |
| Docker Compose | 장기 실행, 데이터베이스 연결 필요 | 설정을 파일에 작성하여 버전 관리가 가능하고 재시작 시 자동으로 올라옴 | yaml 하나를 더 유지보수해야 함 |
| npm 전역 설치 | 이미 Node 환경이 있고 리소스를 절약하고 싶을 때 | container를 사용하지 않고 호스트에 직접 연결하여 성능 손실 최소화 | 시스템 Node 버전에 의존하므로 업그레이드 시 꼬이기 쉬움 |
내 제안: 개인용은 Docker Compose를 선택하고 단일 docker run은 쓰지 마세요. 이유는 실질적입니다 — 단일 명령으로 실행한 후 두 달이 지나면 당시 어떤 파라미터를 설정했는지 절대 기억나지 않습니다. Compose는 파라미터를 파일에 작성하므로 문제가 생기면 확인하고, 수정하고, 백업할 수 있습니다.
환경 확인
먼저 Docker가 있는지 확인합니다. 터미널에서 실행:
docker -v버전 번호(형식: Docker version 29.5.3, build d1c06ef)가 보이면 설치된 것입니다. Windows와 macOS는 Docker Desktop 설치 시 포함되어 있고, Linux는 Docker Engine을 사용합니다.
다음으로 5678 port가 점유되지 않았는지 확인합니다. Linux:
ss -lntp | grep 5678macOS 또는 Linux에서는 lsof -i :5678도 사용할 수 있습니다. 출력이 있으면 점유된 것이므로 다른 port로 변경하세요. 예: -p 5679:5678. Windows 사용 netstat -ano | findstr 5678。
방법 1: docker run 한 줄로 실행하기
먼저 데이터 볼륨을 만들고, 그다음 컨테이너를 시작한다. 이 두 단계를 하나로 합치지 말고, 볼륨은 따로 만들어 두면 나중에 컨테이너를 삭제하고 다시 만들어도 데이터가 사라지지 않는다:
docker volume create n8n_data
docker run -d --name n8n
-p 5678:5678
-e GENERIC_TIMEZONE="Asia/Shanghai"
-e TZ="Asia/Shanghai"
-e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
-e N8N_DEFAULT_LOCALE=zh-CN
-v n8n_data:/home/node/.n8n
--restart unless-stopped
n8nio/n8n각 파라미터가 무엇을 하는지 하나씩 설명한다. 이것들이 실제로 문제가 생기는 지점이다:
-d: 백그라운드 실행. 공식 문서에 나온 것은-it --rm(포그라운드 실행, 종료 시 삭제)이며, 이는 테스트용이다. 장기 사용 시 반드시-d --restart unless-stopped로 바꿔야 하며, 서버 재시작 후 컨테이너가 자동으로 올라온다.-p 5678:5678: 컨테이너 내부의 5678을 호스트에 매핑한다. 왼쪽이 호스트 port이므로 왼쪽만 바꾸면 된다.GENERIC_TIMEZONE和TZ: 둘 다 설정해야 한다.TZ는 컨테이너 안 시스템 명령의 시간을 관리하고,GENERIC_TIMEZONE는 스케줄 유형 노드(예: Schedule Trigger)가 어느 타임존 기준으로 계산되는지를 관리한다. 하나만 설정하면 "내가 설정한 오전 9시인데 실제로는 오후 5시에 실행됨" 같은 문제가 발생한다.-v n8n_data:/home/node/.n8n：가장 중요한 줄. n8n의 SQLite 데이터베이스, 암호화 키, 로그가 모두 이 디렉터리에 있다. 볼륨을 mount하지 않으면 컨테이너 삭제 시 전부 사라진다.N8N_DEFAULT_LOCALE=zh-CN: 인터페이스 기본 언어는 중국어. n8n의 중국어는 껍데기만 번역되었고 노드 파라미터는 여전히 영어라는 점에 주의.
시작 후 브라우저에서 열기 http://localhost:5678. 처음에 관리자 계정을 만들라고 하는데, 비밀번호는 최소 8자리입니다. 이 계정은 로컬에 저장되므로 잊어버리면 재설정만 가능하니 잘 기억해 두세요.
방식 2: Docker Compose (권장)
디렉터리를 하나 만들고 그 안에 넣습니다 docker-compose.yml：
services:
n8n:
image: n8nio/n8n:latest
container_name: n8n
restart: unless-stopped
ports:
- "5678:5678"
environment:
- GENERIC_TIMEZONE=Asia/Shanghai
- TZ=Asia/Shanghai
- N8N_DEFAULT_LOCALE=zh-CN
- N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
- N8N_SECURE_COOKIE=false
volumes:
- ./n8n_data:/home/node/.n8n그런 다음 이 디렉터리에서 실행합니다:
docker compose up -d몇 가지 설명:
N8N_SECURE_COOKIE=false 이 줄은 「로컬에서 http로 접속」할 때만 필요합니다. 이미 도메인과 HTTPS를 설정했다면 삭제하세요—HTTPS를 켜 놓고 false라고 쓰면 오히려 보안성이 떨어집니다. 많은 사람이 로컬 설치 후 로그인 페이지가 계속 로딩만 도는 것은 바로 이 cookie 설정에 걸리기 때문입니다.
데이터 디렉터리는 ./n8n_data를 사용합니다, 즉 yml과 같은 레벨의 폴더입니다. 장점은 백업 시 이 디렉터리를 그대로 압축하면 되고, Docker 볼륨이 어디에 숨어 있는지 추측할 필요가 없다는 것입니다.
로그 확인, 실행 여부 판단:
docker compose logs -f --tail=50편집기 주소와 버전 번호가 있는 줄이 보이면 실행된 것입니다. Ctrl+C를 누르면 로그만 종료되고 container는 계속 실행 중입니다.
방식 3: npm 전역 설치
제가 직접 쓰는 그 인스턴스가 바로 이 방식이며, container 없이 호스트 머신에서 직접 실행합니다. 전제는 Node.js 환경이 있어야 하고, n8n 2.x는 Node 20 이상을 요구합니다 (제 것은 Node 24.21.0입니다).
npm install -g n8n
n8n start하지만 이렇게 바로 실행하면 문제가 하나 있습니다: 데이터가 기본적으로 현재 사용자 디렉터리 아래의 .n8n에 떨어지고, 터미널을 닫으면 멈춥니다. 프로덕션 환경에서는 보통 환경 변수로 데이터 디렉터리를 지정하고 systemd 또는 pm2로 관리합니다. 이 인스턴스가 실제로 사용하는 핵심 변수는 다음과 같습니다 (값은 본인 것으로 변경하세요):
N8N_USER_FOLDER=/data/n8n
N8N_HOST=127.0.0.1
N8N_PORT=5678
N8N_PROTOCOL=http
N8N_EDITOR_BASE_URL=https://你的域名/
N8N_DEFAULT_LOCALE=zh-CNN8N_HOST=127.0.0.1 함께 N8N_EDITOR_BASE_URLn8n을 Nginx 뒤에 숨기고 포트를 직접 노출하지 않는 일반적인 방법이며, 다음 글에서 서버에 배포할 때 자세히 다룬다. 본机에서만 사용한다면 HOST를 localhost 로 설정하면 된다.
설치 후 모습
로그인하면 「개요」 페이지로 들어간다. 왼쪽은 기능 내비게이션, 가운데는 워크플로, 실행, 자격 증명 탭, 오른쪽 상단은 「워크플로 만들기」 버튼이다.
「워크플로 만들기」를 클릭하면 빈 캔버스가 나오고, 가운데에 「첫 단계 추가」 한 줄만 있다:
첫 번째 워크플로: 세 개의 노드
캔버스 가운데의 플러스를 클릭하면 오른쪽에 노드 라이브러리가 나타난다. 검색창에 manual를 입력하고 「Manual Trigger(수동 트리거)」를 선택하면 이것이 이 흐름의 시작점이다.
이어서 수동 트리거 노드 오른쪽의 작은 플러스에서 「Edit Fields(필드 편집)」를 추가하고, 아무 필드 두 개를 작성한다. 예를 들어 city 에 「푸저우」를 입력하고,temp 에 27을 입력한다. 다시 오른쪽에 「Code(코드)」 노드를 추가하고 코드 상자에 붙여넣는다:
return items.map(item => ({
json: {
message: `${item.json.city} 现在 ${item.json.temp} 度`
}
}));마지막으로 캔버스 아래의 「실행」 버튼을 클릭한다. 세 노드가 차례로 켜지고 모두 녹색 체크 표시로 바뀌면 전체 체인이 연결된 것이다. 이때 아무 노드나 클릭하면 오른쪽 출력 영역에서 실제 데이터를 볼 수 있다.
이 단계의 목적은 코드 작성법을 배우는 것이 아니라, 설치한 이 세트가 실제로 실행되는지 확인하는 것이다.
진짜 설치 성공 여부를 판단하는 방법
인터페이스가 열린다고 성공은 아니다. 아래 네 가지를 순서대로 진행해 모두 통과해야 성공이다:
- 편집기를 열 수 있어야 한다: 브라우저에서 오류 없이 접속되고 워크플로 목록이 보여야 한다.
- 저장이 되어야 한다: 새 워크플로를 만들고 아무 노드나 추가한 뒤 자동 저장을 기다렸다가 페이지를 새로고침했을 때 내용이 그대로 있어야 한다.
- 재시작해도 유지되어야 한다：
docker compose restart, 다시 새로고침했을 때 방금 그 워크플로가 여전히 있어야 한다. 이 항목이 데이터 볼륨이 제대로 mount되었는지 확인하는 유일한 방법이다. - 실행이 되어야 한다: 수동 워크플로를 한 번 실행해서 노드가 초록색으로 변하고, 클릭했을 때 출력 데이터가 보여야 한다.
세 번째 항목이 가장 쉽게 건너뛰어지면서도 가장 치명적이다. 재시작 후 워크플로가 사라졌다면 n8n을 의심하지 말고 -v 뒤의 경로가 잘못 작성되었는지, 또는 익명 볼륨을 사용했는지 확인하라.
흔한 오류
port가 이미 사용 중임.오류 메시지에 port is already allocated가 포함되어 있습니다. 호스트 port를 변경하세요. 예: -p 5679:5678, 그런 다음 5679로 접속합니다.
열리지만 로그인 시 로딩만 돕니다.로컬에서 http로 접속할 때, 만약 N8N_SECURE_COOKIE 가 기본값 true이면 브라우저가 cookie 쓰기를 거부합니다. 로컬 테스트 시 false로 설정하고, HTTPS 구성 후에는 이 줄을 삭제하세요.
스케줄 작업 시간이 맞지 않습니다.만 설정하고 TZ 를 설정하지 않으면 GENERIC_TIMEZONE, 스케줄 노드가 UTC 기준으로 계산됩니다. 둘 다 Asia/Shanghai。
로 설정하세요. 재시작 후 container가 올라오지 않습니다.추가하는 것을 잊었거나 yml의 --restart unless-stopped 를 forgot restart. 서버 재시작 후 수동으로 해야 합니다. docker start n8n。
image pull이 매우 느리거나 실패합니다.중국 네트워크에서 Docker Hub를 pull할 때 자주 타임아웃이 발생하므로, 미러 가속기를 설정한 후 다시 pull하거나 docker pull n8nio/n8n 시간을 두고 기다리면 된다. image가 수백 MB이다.
중국어가 적용되지 않았다.N8N_DEFAULT_LOCALE 새 세션의 기본 언어에만 영향을 미치며, 기존 계정은 직접 설정에서 변경해야 한다. 또한 앞서 말한 것처럼 인터페이스 껍데기만 중국어이다.
먼저 공인망에 노출하지 마라
설치 후 바로 휴대폰으로 접속하고 싶어서 5678 port를 공인망에 개방하는데, 이것이 가장 흔한 실수이다. n8n에는 각종 시스템의 API Key가 들어 있어 공인망에 그대로 노출하는 것은 열쇠를 문 앞에 걸어두는 것과 같다.
올바른 방법은: 먼저 로컬 또는 내부망에서 사용하고, 장기 사용을 확인한 후 다음 편의 절차에 따라 도메인을 바인딩하고 HTTPS를 적용하며 Nginx reverse proxy를 사용하고, 127.0.0.1만 listen하도록 하는 것이다.
또한 첫 로그인 후 바로 관리자 비밀번호를 강력한 비밀번호로 변경하고, admin123 이런 것은 사용하지 마라.
버전에 관하여
n8n은 매주 마이너 버전을 배포한다. 이 글을 작성할 때 공식 문서에 표시된 안정 버전은 2.44.5이고, beta는 2.45.2이며, 내 이 instance는 2.43.7을 실행 중이고 인터페이스 스크린샷은 모두 여기서 가져왔다.
권장 사항:프로덕션 환경에서는 latest를 사용하지 마라. image를 구체적인 버전 번호에 고정하라. 예를 들어 n8nio/n8n:2.44.5업그레이드할 때는 숫자를 바꿔서 다시 pull하면 된다. latest를 쓰면 어느 날 재시작했을 때 버전이 조용히 바뀌어 워크플로 동작도 따라 바뀌고, 문제를 찾기가 매우 힘들다.
자신의 버전을 확인하는 방법: 로그인 후 왼쪽 맨 아래에서 설정으로 들어가거나, 실행 docker exec n8n n8n --version。
다음 단계
설치했으면 먼저 10분 정도 인터페이스를 한 번 익혀 보자:n8n 인터페이스 둘러보기: 캔버스, 노드, 실행 기록이 각각 무엇을 말하는지. 익힌 뒤 오늘 설치한这套로 위의 3노드 예제를 한 번 따라 쳐 보자. 손이 눈보다 더 잘 기억한다.
만약 「왜 배울 가치가 있는지」를 먼저 이해하고 싶다면, 이전 글을 다시 봐라:n8n이란 무엇인가, 제로 기초 입문과 응용 시나리오。
참고 자료
최종 업데이트: 2026년 10월 22일. Docker 관련 명령 몇 개는 공식 문서를 대조해 확인했다(당시 표기된 안정 버전은 2.44.5). 스크린샷은 내가 직접 쓰는 2.43.7에서 찍었다.
