n8n 로컬 서버 기동 가이드

AI탐사대·2026년 1월 10일

Agent Builder (n8n 기반) - 로컬 설치 및 실행 가이드

목차

  1. 빠른 시작
  2. 사전 요구사항
  3. 프로젝트 클론 및 설치
  4. 서버 실행
  5. 설치된 패키지 상세
  6. 트러블슈팅

빠른 시작

새로운 PC에서 5분 안에 Agent Builder를 실행하세요.

# 1. Git Repository 클론
git clone https://github.com/ai-exploration-25/n8n_new_project.git
cd n8n_new_project/n8n

# 2. 의존성 설치
npx pnpm@10.22.0 install

# 3. 프로젝트 빌드
npx pnpm@10.22.0 build

# 4. 서버 실행
# 터미널 1: 프론트엔드 개발 서버
npx pnpm@10.22.0 dev

# 터미널 2: 백엔드 API 서버
npx pnpm@10.22.0 start

# 5. 브라우저에서 접속
# http://localhost:5678

사전 요구사항

필수 소프트웨어

소프트웨어최소 버전확인 명령어설치 가이드
Node.js>= 22.16node --versionnodejs.org
Git최신 버전git --versiongit-scm.com

참고: pnpm은 자동으로 npx를 통해 사용되므로 별도 설치 불필요

시스템 요구사항

  • 메모리: 최소 4GB RAM (권장 8GB 이상)
  • 디스크 공간: 최소 2GB 여유 공간
  • OS: macOS, Linux, Windows (WSL2 권장)

프로젝트 클론 및 설치

1단계: Repository 클론

# HTTPS 방식 (권장)
git clone https://github.com/ai-exploration-25/n8n_new_project.git

# 또는 SSH 방식
git clone git@github.com:ai-exploration-25/n8n_new_project.git

# 프로젝트 디렉토리로 이동
cd n8n_new_project/n8n

2단계: 의존성 설치

# pnpm을 사용하여 모든 패키지 설치 (약 3-5분 소요)
npx pnpm@10.22.0 install

설치되는 패키지 수:

  • 직접 의존성: 87개
  • 전체 패키지 (의존성 포함): 약 1,500개

3단계: 프로젝트 빌드

# Turbo를 사용한 모노레포 빌드 (약 2-3분 소요)
npx pnpm@10.22.0 build

빌드되는 패키지: 39개 (n8n 모노레포 전체)

서버 실행

개발 모드 (권장)

옵션 1: 전체 개발 환경 (프론트엔드 + 백엔드)

두 개의 터미널이 필요합니다:

# 터미널 1: 프론트엔드 개발 서버 (Vue + Vite)
npx pnpm@10.22.0 dev

# 터미널 2: 백엔드 API 서버 (Express + n8n)
npx pnpm@10.22.0 start

옵션 2: 백엔드만 실행

npx pnpm@10.22.0 dev:be
npx pnpm@10.22.0 start

옵션 3: 프론트엔드만 실행

npx pnpm@10.22.0 dev:fe

프로덕션 모드

# 빌드된 파일로 실행
npx pnpm@10.22.0 start

접속 URL

서버가 정상적으로 실행되면 다음 주소로 접속할 수 있습니다:

서비스URL용도
Agent Builder 메인http://localhost:5678프로덕션/통합 화면
프론트엔드 개발 서버http://localhost:8080Vite HMR 개발 화면
백엔드 APIhttp://localhost:5678REST API 엔드포인트
Task Brokerhttp://127.0.0.1:5679내부 작업 큐

프로젝트 개요

브랜딩

이 프로젝트는 n8n 워크플로우 자동화 플랫폼을 기반으로 Agent Builder로 리브랜딩되었습니다.

주요 변경사항:

  • n8n 로고 → 다른 로고
  • 이메일 템플릿 브랜딩 변경
  • UI 텍스트 및 레이블 커스터마이징

Git 커밋 히스토리

1953adb5 feat: Replace n8n logo with Other logo in email templates
76e24ef0 feat: Replace n8n logo with Agent Builder branding
5fc3cb5a chore: Add gitignore and lefthook configuration
ffb751cc feat: Add Korean localization for n8n frontend
b5179ec0 Initial commit: n8n agent builder project

설치된 패키지 상세 분류

1. 핵심 워크플로우 패키지

패키지명버전용도
n8n-workflow^1.120.4n8n 워크플로우 핵심 타입 및 인터페이스

2. 스키마 검증 및 타입 안정성

패키지명버전용도
zod^3.25.76런타임 타입 검증 및 스키마 정의
zod-class^0.0.18Zod와 클래스 기반 DTO 통합
class-validator^0.14.3클래스 기반 유효성 검증
class-transformer^0.5.1객체 변환 라이브러리
json-schema^0.4.0JSON 스키마 정의
jest-expect-message^1.1.3Jest 테스트 메시지 확장 (devDependency)

3. Vue.js 프론트엔드 생태계

패키지명버전용도
vue^3.5.26Vue.js 3 프레임워크
pinia^3.0.4Vue 3 상태 관리 라이브러리
vue-router^4.6.4Vue 라우팅
@vueuse/core^14.1.0Vue 컴포지션 유틸리티
@vue-flow/core^1.48.1Vue 기반 플로우 차트 컴포넌트
@vue/test-utils^2.4.6Vue 컴포넌트 테스팅
@vitejs/plugin-vue^6.0.3Vite Vue 플러그인

4. LangChain AI/ML 생태계

패키지명버전용도
@langchain/core^1.1.12LangChain 핵심 기능
@langchain/classic^1.0.8LangChain 클래식 체인
@langchain/community^1.1.3LangChain 커뮤니티 통합
@langchain/langgraph^1.0.14LangChain 그래프 기반 워크플로우
@langchain/openai^1.2.1OpenAI 통합
@langchain/anthropic^1.3.7Anthropic Claude 통합
@langchain/aws^1.1.1AWS 서비스 통합
@langchain/cohere^1.0.1Cohere 통합
@langchain/textsplitters^1.0.1텍스트 분할 유틸리티

5. AI/ML 서비스 클라이언트

패키지명버전용도
@n8n_io/ai-assistant-sdk^1.20.0n8n AI 어시스턴트 SDK
@huggingface/inference^4.13.5HuggingFace 추론 API
@modelcontextprotocol/sdk^1.25.2Model Context Protocol SDK

6. 벡터 데이터베이스 및 임베딩

패키지명버전용도
@pinecone-database/pinecone^6.1.3Pinecone 벡터 DB 클라이언트
@qdrant/js-client-rest^1.16.2Qdrant 벡터 DB 클라이언트
@supabase/supabase-js^2.90.1Supabase 클라이언트

7. 백엔드 프레임워크 및 서버

패키지명버전용도
express^5.2.1Node.js 웹 프레임워크
ws^8.19.0WebSocket 서버/클라이언트
bull^4.16.5Redis 기반 작업 큐
amqplib^0.10.9RabbitMQ 클라이언트

8. 데이터 처리 및 변환

패키지명버전용도
lodash^4.17.21JavaScript 유틸리티 라이브러리
luxon^3.7.2날짜/시간 처리
moment-timezone^0.6.0타임존 처리
uuid^13.0.0UUID 생성
nanoid^5.1.6짧은 고유 ID 생성
change-case^5.4.4문자열 케이스 변환
xml2js^0.6.2XML ↔ JSON 변환
cheerio^1.1.2서버사이드 HTML 파싱

9. 보안 및 인증

패키지명버전용도
jsonwebtoken^9.0.3JWT 토큰 생성/검증
bcryptjs^3.0.3비밀번호 해싱
basic-auth^2.0.1HTTP Basic 인증
xss^1.0.15XSS 방지

10. 테스팅 프레임워크

패키지명버전용도
vitest^4.0.16빠른 단위 테스트 프레임워크
jest-mock-extended^4.0.0Jest 목 확장
vitest-mock-extended^3.1.0Vitest 목 확장
@playwright/test^1.57.0E2E 테스팅
@pinia/testing^1.0.3Pinia 상태 테스팅
nock^14.0.10HTTP 목킹
miragejs^0.1.48API 목 서버
testcontainers^11.11.0컨테이너 기반 통합 테스트

11. 개발 도구

패키지명버전용도
@typescript-eslint/utils^8.52.0TypeScript ESLint 유틸리티
@typescript-eslint/rule-tester^8.52.0ESLint 룰 테스터
@storybook/vue3-vite^10.1.11Storybook Vue 3 통합
@faker-js/faker^10.2.0페이크 데이터 생성

12. HTTP 클라이언트 및 네트워크

패키지명버전용도
axios^1.13.2HTTP 클라이언트
form-data^4.0.5멀티파트 폼 데이터

13. 파서 및 컴파일러

패키지명버전용도
acorn^8.15.0JavaScript 파서
acorn-walk^8.3.4AST 순회
@lezer/common^1.5.0Lezer 파서 공통 유틸
@lezer/highlight^1.2.3구문 강조
@lezer/lr^1.4.7LR 파서

14. UI 컴포넌트 및 시각화

패키지명버전용도
chart.js^4.5.1차트 라이브러리
ag-grid-community^35.0.0데이터 그리드
@dagrejs/dagre^1.1.8그래프 레이아웃
@clack/prompts^0.11.0CLI 프롬프트
cli-progress^3.12.0CLI 프로그레스 바

15. 유틸리티 및 헬퍼

패키지명버전용도
callsites^4.2.0콜스택 추적
fast-glob^3.3.3빠른 파일 글로빙
chokidar^5.0.0파일 시스템 감시
cache-manager^7.2.8캐싱 관리
bowser^2.13.1브라우저 감지
picocolors^1.1.1터미널 색상
@mozilla/readability^0.6.0웹 페이지 가독성 추출
@internationalized/date^3.10.1국제화 날짜 처리
minifaker^1.34.1경량 페이커

16. 데이터베이스 및 스트리밍

패키지명버전용도
alasql^4.17.0JavaScript SQL 데이터베이스
@kafkajs/confluent-schema-registry^3.9.0Kafka 스키마 레지스트리

17. 모니터링 및 에러 추적

패키지명버전용도
@sentry/vue^10.32.1Sentry Vue 통합
@sentry/node^10.32.1Sentry Node.js 통합
@sentry/core^10.32.1Sentry 핵심
@rudderstack/rudder-sdk-node^3.0.0RudderStack 분석

설치 통계

  • 총 설치된 패키지 수: 87개 (직접 의존성 86개 + devDependency 1개)
  • 전체 패키지 수 (의존성 포함): 1,500개
  • 주요 카테고리:
    • Vue.js 생태계: 7개
    • LangChain AI/ML: 9개
    • 테스팅: 9개
    • 데이터 처리: 8개
    • 보안: 4개
    • 백엔드: 4개

주요 사용 패턴

프론트엔드 아키텍처

Vue 3 + Pinia + Vue Router + VueUse
└── 컴포넌트 테스팅: Vue Test Utils
└── UI 컴포넌트: Vue Flow, Chart.js, AG Grid
└── 빌드: Vite + Vue Plugin

AI/ML 스택

LangChain Core
├── OpenAI, Anthropic, Cohere (LLM 제공자)
├── HuggingFace (모델 추론)
├── Pinecone, Qdrant (벡터 DB)
└── Text Splitters (텍스트 처리)

백엔드 스택

Express (웹 서버)
├── Bull (작업 큐)
├── JWT (인증)
├── WebSocket (실시간 통신)
└── Axios (HTTP 클라이언트)

테스팅 스택

Vitest (단위 테스트)
├── Playwright (E2E)
├── Nock (HTTP 목킹)
├── Testcontainers (통합 테스트)
└── MirageJS (API 목킹)

설치 명령어 히스토리

# 1차: n8n-workflow 핵심 패키지
npm install n8n-workflow --cache /tmp/npm-cache

# 2차: XSS, AI SDK 등 보안 및 AI 패키지
npm install xss minifaker @n8n_io/ai-assistant-sdk --cache /tmp/npm-cache

# 3차: LangChain 생태계
npm install jest-mock-extended @langchain/core @langchain/langgraph @langchain/classic @langchain/openai @langchain/textsplitters picocolors --cache /tmp/npm-cache

# 4차: Vue 및 핵심 유틸리티
npm install vue pinia vue-router express lodash luxon uuid moment-timezone axios vitest nock nanoid class-validator form-data xml2js jsonwebtoken ws fast-glob json-schema change-case @pinia/testing @vueuse/core @vue-flow/core @faker-js/faker @vue/test-utils vitest-mock-extended --cache /tmp/npm-cache

# 5차: 테스팅 및 UI 라이브러리
npm install @typescript-eslint/utils @typescript-eslint/rule-tester @playwright/test @storybook/vue3-vite miragejs testcontainers @lezer/common @lezer/highlight @lezer/lr @dagrejs/dagre @clack/prompts --cache /tmp/npm-cache

# 6차: LangChain 커뮤니티 및 벡터 DB
npm install @langchain/community @langchain/anthropic @langchain/aws @langchain/cohere @pinecone-database/pinecone @qdrant/js-client-rest @supabase/supabase-js @huggingface/inference @kafkajs/confluent-schema-registry --cache /tmp/npm-cache

# 7차: 유틸리티 패키지
npm install bcryptjs cheerio acorn acorn-walk bull cache-manager class-transformer cli-progress bowser basic-auth chart.js callsites chokidar amqplib alasql ag-grid-community --cache /tmp/npm-cache

# 8차: 모니터링 및 도구
npm install @modelcontextprotocol/sdk @sentry/vue @sentry/node @sentry/core @rudderstack/rudder-sdk-node @internationalized/date @mozilla/readability @vitejs/plugin-vue --cache /tmp/npm-cache

# 9차: 테스트 유틸리티
npm install jest-expect-message --save-dev --cache /tmp/npm-cache

n8n 로컬 실행 가이드

사전 요구사항

  • Node.js >= 22.16
  • pnpm >= 10.22.0

실행 단계

# 1. n8n 디렉토리로 이동
cd /Users/user/Desktop/n8n_repository/n8n_new_project/n8n

# 2. pnpm으로 의존성 설치 (npx 사용)
npx pnpm@10.22.0 install

# 3. 프로젝트 빌드
npx pnpm@10.22.0 build

# 4. 개발 서버 실행 (옵션 선택)
npx pnpm@10.22.0 dev           # 전체 개발 환경
npx pnpm@10.22.0 dev:be        # 백엔드만
npx pnpm@10.22.0 dev:fe        # 프론트엔드만
npx pnpm@10.22.0 dev:ai        # AI 기능만

# 또는 프로덕션 모드로 실행
npx pnpm@10.22.0 start

TypeScript 설정 수정 내역

1. composite 설정 추가

  • 파일: packages/workflow/tsconfig.build.esm.json
  • 변경: "composite": true 추가
  • 이유: TypeScript 프로젝트 참조 요구사항

2. extends 경로 수정

  • 파일: packages/@n8n/api-types/tsconfig.json
  • 변경: "@n8n/typescript-config/tsconfig.common.json" → "../typescript-config/tsconfig.common.json"
  • 이유: 상대 경로로 올바르게 해석되도록 수정

보안 권고사항

설치 중 발견된 취약점:

  • 2개의 critical severity 취약점 발견
  • 권장 조치: npm audit fix --force 실행 고려
  • 주의: 일부 deprecated 패키지 경고 발생 (glob@7.2.3, rimraf@3.0.2 등)

추가 참고사항

n8n 원본 프로젝트 특징

  • 패키지 매니저: pnpm (workspace 기반 모노레포)
  • 빌드 시스템: Turbo
  • Node 버전: >= 22.16
  • 총 TypeScript 파일: 약 8,990개
  • 주요 디렉토리:
    • packages/nodes-base: 3,259개 노드 파일
    • packages/cli: 1,172개 백엔드 파일
    • packages/frontend/editor-ui: 1,075개 프론트엔드 파일

현재 프로젝트 환경

  • 작업 디렉토리: /Users/user/Desktop/n8n_repository/n8n_new_project
  • 패키지 매니저: npm (pnpm 대신)
  • 캐시 우회: --cache /tmp/npm-cache 사용 (권한 문제 회피)

마이그레이션 노트

n8n 원본은 모노레포 구조로 workspace:* 프로토콜을 사용하여 내부 패키지를 참조합니다:

  • @n8n/permissions
  • @n8n/config
  • @n8n/db
  • @n8n/di
  • 기타 30+ 개의 @n8n 스코프 패키지

현재 프로젝트에서는 이러한 내부 패키지들을 직접 구현하거나 외부 대안으로 대체해야 할 수 있습니다.

트러블슈팅

일반적인 문제 해결

1. npm 캐시 권한 오류

# 오류: EACCES: permission denied, mkdir '/Users/user/.npm/_cacache/...'
# 해결: 임시 캐시 디렉토리 사용
npm install --cache /tmp/npm-cache

2. TypeScript 컴파일 오류

오류 A: Referenced project must have setting "composite": true

# 파일: packages/workflow/tsconfig.build.esm.json
# 해결: "composite": true 추가됨 (이미 수정 완료)

오류 B: File '@n8n/typescript-config/tsconfig.common.json' not found

# 파일: packages/@n8n/api-types/tsconfig.json
# 해결: 상대 경로로 변경됨 (이미 수정 완료)

3. 포트 충돌

# 오류: Port 5678 is already in use
# 해결 1: 기존 프로세스 종료
lsof -ti:5678 | xargs kill -9

# 해결 2: 환경 변수로 다른 포트 사용
N8N_PORT=5679 npx pnpm@10.22.0 start

4. Node.js 버전 불일치

# 현재 버전 확인
node --version

# nvm 사용 시
nvm install 22.16
nvm use 22.16

# 또는 최신 LTS 버전
nvm install --lts

5. 빌드 실패

# 전체 정리 후 재빌드
npx pnpm@10.22.0 clean
npx pnpm@10.22.0 install
npx pnpm@10.22.0 build

6. 데이터베이스 마이그레이션 오류

# n8n은 첫 실행 시 자동으로 SQLite DB 생성
# 문제 발생 시 DB 파일 삭제 후 재시작
rm -rf ~/.n8n/database.sqlite
npx pnpm@10.22.0 start

환경 변수 설정 (선택사항)

n8n은 환경 변수 없이도 기본 설정으로 실행됩니다. 필요시 다음과 같이 설정할 수 있습니다:

# .env 파일 생성 예시 (선택사항)
N8N_PORT=5678
N8N_PROTOCOL=http
N8N_HOST=localhost
N8N_EDITOR_BASE_URL=http://localhost:5678
N8N_LOG_LEVEL=info

# 데이터베이스 설정 (기본값: SQLite)
DB_TYPE=sqlite
DB_SQLITE_DATABASE=~/.n8n/database.sqlite

# 보안 설정
N8N_BASIC_AUTH_ACTIVE=false
N8N_JWT_SECRET=<your-secret-key>

성능 최적화

개발 환경

# 백엔드만 개발할 때
npx pnpm@10.22.0 dev:be

# 프론트엔드만 개발할 때
npx pnpm@10.22.0 dev:fe

# AI 기능만 개발할 때
npx pnpm@10.22.0 dev:ai

프로덕션 환경

# 빌드 최적화
npx pnpm@10.22.0 build:deploy

# Docker 이미지 빌드 (선택사항)
npx pnpm@10.22.0 build:docker

로그 확인

# n8n 로그 위치
~/.n8n/logs/

# 실시간 로그 확인
tail -f ~/.n8n/logs/n8n.log

# 개발 모드 콘솔 출력
N8N_LOG_LEVEL=debug npx pnpm@10.22.0 start

데이터 백업

# n8n 데이터 디렉토리
~/.n8n/

# 백업 (워크플로우, 크레덴셜, 실행 이력 포함)
cp -r ~/.n8n ~/n8n-backup-$(date +%Y%m%d)

# 복원
cp -r ~/n8n-backup-YYYYMMDD ~/.n8n

추가 리소스

공식 문서

개발 가이드

이 프로젝트

빠른 참조 명령어 모음

# === 초기 설정 ===
git clone https://github.com/ai-exploration-25/n8n_new_project.git
cd n8n_new_project/n8n
npx pnpm@10.22.0 install
npx pnpm@10.22.0 build

# === 개발 ===
npx pnpm@10.22.0 dev           # 프론트엔드 개발 서버
npx pnpm@10.22.0 start         # 백엔드 서버

# === 테스트 ===
npx pnpm@10.22.0 test          # 전체 테스트
npx pnpm@10.22.0 lint          # 린팅
npx pnpm@10.22.0 typecheck     # 타입 체크

# === 정리 ===
npx pnpm@10.22.0 clean         # 빌드 파일 정리
rm -rf node_modules            # 의존성 정리

# === 포트 확인 ===
lsof -i:5678                   # 백엔드 포트
lsof -i:8080                   # 프론트엔드 포트

생성일: 2026-01-10
마지막 업데이트: 2026-01-10
문서 버전: 2.0
대상 독자: 신규 개발자, DevOps 엔지니어
프로젝트: Agent Builder (n8n v2.2.0 기반)

profile
AI탐사대
AI 탐사대
이전 포스트

AGI로 가는 5단계

다음 포스트

Vercel React - Agent Skill Install

0개의 댓글