npm 설치
npm은 로컬 컴퓨터에서 n8n을 빠르게 시작하는 방법 중 하나입니다. 반드시 Node.js가 설치되어 있어야 합니다. n8n은 Node.js 버전 20.19부터 24.x 사이(양 끝 버전 포함)를 필요로 합니다.
안정(Stable) 버전과 베타(Beta) 버전
n8n은 거의 매주 새로운 마이너 버전을 출시합니다. stable 버전은 프로덕션 환경에 적합하며, beta는 최신 출시된 버전으로 안정성이 보장되지 않을 수 있습니다. 문제를 보고하려면 커뮤니티 포럼을 이용해 주세요.
현재 stable 버전: 2.10.2
현재 beta 버전: 2.11.1
npx로 n8n 사용해보기
설치 없이 npx를 사용해 바로 n8n을 사용해볼 수 있습니다.
터미널에서 다음 명령어를 실행하세요:
npx n8n
이 명령어는 n8n을 실행하는 데 필요한 모든 파일을 다운로드합니다. 완료되면 브라우저에서 http://localhost:5678 을 열어 n8n에 접속하고 워크플로 구축을 시작할 수 있습니다.
npm으로 n8n 전역 설치
다음 명령어로 npm을 사용해 n8n을 전역으로 설치할 수 있습니다:
npm install n8n -g
@ 문법을 사용해 특정 버전을 지정하여 설치하거나 업데이트할 수 있습니다. 예를 들어:
npm install -g [email protected]
next 버전을 설치하려면:
npm install -g n8n@next
설치가 완료되면 다음 명령어로 n8n을 시작할 수 있습니다:
n8n
# 또는
n8n start
다음 단계
빠른 시작 가이드를 통해 n8n의 기능을 체험해 보세요.
업데이트
n8n 인스턴스를 latest 버전으로 업데이트하려면:
npm update -g n8n
next 버전을 설치하려면:
npm install -g n8n@next
n8n 터널(Tunnel) 사용하기
[주의]
이 기능은 로컬 개발 및 테스트 용도로만 사용해야 하며, 프로덕션 환경에는 적합하지 않습니다.
[참고]
터널 기능은 로컬 개발을 위한 편리한 도구이며, 내부 구현 방식은 n8n 버전 업데이트에 따라 변경될 수 있습니다.
GitHub 등의 외부 서비스와 연동되는 트리거 노드의 Webhook 기능을 사용하려면, n8n 인스턴스가 인터넷에서 접근 가능해야 합니다. n8n은 cloudflared를 활용해 터널 서비스를 제공하며, 이를 통해 외부 요청을 로컬 n8n 인스턴스로 리디렉션합니다. 터널 기능을 사용하려면 Docker가 필요합니다.
[요구 사항]
터널은 cloudflared를 사용하며, 이는 Docker 컨테이너로 실행됩니다. npm으로 n8n을 실행하더라도 시스템에 Docker가 설치되어 있어야 합니다.
npm 설치 방식의 경우, cloudflared만 별도 서비스로 실행하는 방식을 사용하세요: cloudflared를 독립적으로 실행한 후, 로컬에서 n8n을 실행합니다.
💡 이 명령어는 n8n 소스 코드를 클론하여 개발 환경에서 실행할 경우에만 사용됩니다. npm으로 전역 설치한 경우에는 이 방식을 사용할 수 없습니다.
# 터미널 1: cloudflared 터널 서비스 시작
pnpm --filter n8n-containers services --services cloudflared
# 터미널 2: 로컬에서 n8n 시작
pnpm dev
services 명령어는 cloudflared를 실행하고 공용 터널 URL을 획득한 후, WEBHOOK_URL과 N8N_PROXY_HOPS=1 설정이 포함된 .env 파일을 packages/cli/bin/.env 경로에 생성합니다. (이 경로는 n8n 소스 코드 기반 개발 환경에서만 유효합니다.) n8n은 시작 시 자동으로 이 .env 파일을 읽습니다.
작업 완료 후 정리하려면 다음 명령어를 실행하세요:
pnpm --filter n8n-containers services:clean
n8n과 cloudflared를 모두 컨테이너에서 실행하는 전체 스택(full-stack) 방식은 Docker 터널 설정 문서를 참고하세요.
이전 버전으로 되돌리기(롤백)
이전 버전으로 되돌리려면 해당 버전을 다시 설치하면 됩니다.
업그레이드 과정에서 데이터베이스 마이그레이션이 포함된 경우:
- 기능 문서 및 릴리스 노트를 확인하여 수동 조치가 필요한지 파악하세요.
- 현재 버전에서
n8n db:revert명령어를 실행해 데이터베이스를 롤백합니다. 여러 단계의 마이그레이션을 되돌려야 한다면, 이 작업을 반복해야 할 수 있습니다.
Windows 문제 해결
Windows에서 n8n 실행 시 문제가 발생한다면, Node.js 환경이 올바르게 설정되었는지 확인하세요. Microsoft의 Windows에서 Node.js 설치 가이드(한국어)를 참고하시기 바랍니다.