공식 문서 기반으로 이해하는 n8n 핵심 개념

 

n8n

🐙 n8n이란?

n8n은 다양한 서비스와 시스템을 서로 연결해 주는 워크플로우 자동화 툴입니다.
쉽게 말해, “특정 이벤트가 발생하면 정해둔 작업들을 순서대로 실행해 주는 자동화 엔진”이에요.

대표적인 SaaS 자동화 툴로는 Zapier가 있지만, n8n은 몇 가지 큰 차별점을 가지고 있습니다.

👉 개발자 친화적인 노코드/로우코드 자동화 플랫폼

 

🔑 n8n의 특징

1. 오픈소스 & 셀프호스팅
   • Zapier, Make 같은 툴은 클라우드 서비스 기반이라 사용량이 늘어나면 요금이 빠르게 올라갑니다.
   • n8n은 완전히 오픈소스이고, 직접 서버(Docker, Kubernetes 등)에 설치해서 운영할 수 있어 비용과 보안 측면에서 자유도가 높습니다.
2. Node.js 기반 아키텍처
   • n8n은 Node.js 위에서 돌아가며, JavaScript/TypeScript 친화적인 확장성을 제공합니다.
   • 필요하다면 직접 커스텀 노드(Node)를 만들어 기능을 추가할 수도 있습니다.
3. 풍부한 통합 지원 (300+ 노드)
   • Slack, Discord, Telegram 같은 메신저
   • PostgreSQL, MySQL, MongoDB 같은 DB
   • AWS, GCP, GitHub, Jira, Sentry 등 다양한 SaaS/DevOps 툴
     → 이미 준비된 노드만 연결하면 바로 자동화 워크플로우를 만들 수 있습니다.
4. 노코드/로우코드 방식
   • UI에서 노드를 끌어다 놓고 연결하면 워크플로우가 완성됩니다.
   • 필요할 때는 Expression(자바스크립트 문법)이나 Function Node를 활용해서 직접 로직을 추가할 수도 있습니다.
   • 즉, 비개발자도 쉽게 쓰되, 개발자가 쓰면 훨씬 강력해지는 툴이에요.

 

🔑 n8n 핵심 개념

1. Workflow  - https://docs.n8n.io/workflows/
   • 정의: n8n에서 가장 기본 단위. 여러 Node들이 연결되어 만들어진 자동화 프로세스.
   • 역할: 특정 이벤트를 트리거로 시작해서, 조건 분기 → 데이터 가공 → 외부 서비스 호출 → 결과 저장 같은 단계들을 순서대로 실행.
   • 특징:
     • GUI 기반으로 시각적으로 구성 가능
     • 재사용 가능 (Export/Import)
     • 실행 이력 관리 가능
2. Node - https://docs.n8n.io/integrations/builtin/core-nodes/
   • 정의: Workflow를 구성하는 “작업 단위”.
   • 종류:
     • Action Node: 실제 작업 실행 (DB 쿼리, HTTP 요청, Slack 전송 등)
     • Trigger Node: Workflow 시작 조건 담당
     • Function Node: JavaScript로 데이터 가공
   • 특징:
     • 입력 → 처리 → 출력 구조
     • 서로 연결되어 데이터가 흐름
3. Trigger Node
   • 정의: Workflow를 실행하게 만드는 시작점.
   • 예시:
     • Manual Trigger – 수동 실행, 개발/디버깅에 자주 사용
     • Schedule Trigger – 시간 기반 자동 실행; cron 표현식도 지원 
     • Form Trigger – n8n이 제공하는 간단한 웹 폼 제출을 통해 워크플로우 실행
     • Local File Trigger – 파일 시스템 변화를 감지해 자동 실행 (자체 호스팅에서 유용)
   • 특징:
     • Workflow는 반드시 Trigger Node에서 시작
     • 여러 Trigger Node를 한 Workflow에 둘 수도 있음
4. Expression - https://docs.n8n.io/code/expressions/
   • 정의: Node 간 데이터 전달 시 동적으로 값을 생성하는 방식.
   • 사용법: {{ $json["fieldName"] }} 같은 JavaScript 문법을 활용.
   • 예시:
     • API 응답의 특정 필드만 다음 Node에 넘기기
     • "Hello {{ $json["username"] }}" → Hello 세연
   • 특징:
     • 단순 변수 치환부터, JS 코드로 가공까지 가능
     • Function Node를 쓰지 않아도 간단한 로직은 Expression으로 처리 가능
5. Credentials - https://docs.n8n.io/credentials/
   • 정의: 외부 서비스(API, DB 등)와 연결할 때 필요한 인증 정보를 안전하게 저장하는 기능.
   • 예시:
     • Slack OAuth Token
     • PostgreSQL DB 계정 정보
     • GitHub Personal Access Token
   • 특징:
     • 암호화되어 저장
     • 여러 Workflow에서 재사용 가능
     • 보안상 노드에 직접 입력하지 않고 Credentials에 등록 후 선택
6. Execution - https://docs.n8n.io/workflows/executions/
   • 정의: Workflow가 실행된 기록. 어떤 Trigger로 시작되었고, 각 Node가 어떤 입력/출력을 가졌는지 확인 가능.
   • 특징:
     • 성공/실패 여부 확인
     • 실패 시 Error Workflow 연결 가능
     • Debug 모드에서 단계별 데이터 확인 가능
   • 예시:
     • Cron Trigger → DB Query → Slack 메시지 → 성공 로그
     • Webhook Trigger → API 오류 발생 → 실패 로그

 

⚙️ 설치 (Self-host 기준)

Docker를 이용하면 가장 쉽게 설치할 수 있습니다.

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e N8N_BASIC_AUTH_USER=user \
  -e N8N_BASIC_AUTH_PASSWORD=pass \
  n8nio/n8n

👉 실행 후 http://localhost:5678 로 접속하면 n8n 에디터를 사용할 수 있습니다.
👉 N8N_BASIC_AUTH_USER / N8N_BASIC_AUTH_PASSWORD 를 설정해 두면 기본 인증 로그인 화면이 뜹니다. (보안상 권장)

 

🐳 Docker 실행 시 주요 환경변수

n8n은 다양한 환경변수 설정을 지원합니다. 실무에서는 최소한 아래 정도는 지정해두면 좋아요.

1. 기본 보안

-e N8N_BASIC_AUTH_USER=user \
-e N8N_BASIC_AUTH_PASSWORD=pass

 

• 관리자 로그인 계정/비밀번호 설정
• 기본 인증을 켜지 않으면 누구나 접속 가능하므로 꼭 설정 권장

2. 실행 환경(Workflow 저장 위치)

-v ~/.n8n:/home/node/.n8n

 

• 워크플로우와 설정을 호스트 볼륨에 저장
• --rm 옵션으로 실행하면 컨테이너 종료 시 데이터가 사라지므로, 실제 운영에서는 반드시 볼륨을 마운트해야 합니다.

3. 외부 접속용 설정

-e N8N_HOST=example.com \
-e N8N_PORT=5678 \
-e N8N_PROTOCOL=https

• `N8N_HOST`: 서비스 도메인/호스트명
• `N8N_PORT`: 포트 (기본 5678)
• `N8N_PROTOCOL`: http 또는 https

👉 프록시/리버스 프록시(Nginx, Traefik)와 함께 HTTPS 설정 시 필요합니다.

 

4. Webhook 관련

-e WEBHOOK_URL=https://example.com/

 

• 외부 서비스에서 n8n Webhook Node를 호출할 때 사용할 URL
• 클라우드 환경이나 도메인 기반 서비스에 필수

 

5. 실행/큐 모드 (고급)

-e EXECUTIONS_PROCESS=main

• `main`: 단일 프로세스 (기본)
• `queue`: BullMQ 기반 큐 모드 (여러 워커에서 병렬 실행 가능)
• 대량 데이터/고성능 환경에서는 queue 모드와 Redis 연동을 사용

6. 실행 이력 보관

-e EXECUTIONS_DATA_SAVE_ON_SUCCESS=none \ -e EXECUTIONS_DATA_SAVE_ON_ERROR=all

• 성공한 실행은 기록하지 않고, 실패한 실행만 기록하도록 설정
• DB 공간 절약에 유용

7. SQLite 대신 Postgres 쓰기(운영/협업 권장)

  -e DB_POSTGRESDB_HOST=localhost \
  -e DB_POSTGRESDB_PORT=5432 \
  -e DB_POSTGRESDB_DATABASE=n8n \
  -e DB_POSTGRESDB_USER=n8n \
  -e DB_POSTGRESDB_PASSWORD=비밀번호 \

• 기본 DB는 SQLite지만, PostgreSQL을 공식 지원합니다( MySQL/MariaDB는 v1.0에서 deprecated ).
• 스키마, SSL 등도 환경변수로 세밀하게 설정 가능합니다.
  `DB_POSTGRESDB_SCHEMA`(기본 public), `DB_POSTGRESDB_SSL_ENABLED`, ..._CA/CERT/KEY 등.
• “기본은 SQLite, Postgres 지원, MySQL/MariaDB deprecated”도 공식 문서에 명시되어 있습니다.
  https://docs.n8n.io/hosting/configuration/environment-variables/database/

 

🧩 주요 기능 (실무에서 많이 쓰는 것)

1. Webhook Node → 외부 이벤트 받아서 워크플로우 실행

 

• 역할: 외부 서비스가 n8n의 엔드포인트를 호출하면 워크플로우를 시작합니다. 테스트/운영 2개의 URL을 제공하고, 응답 타이밍(즉시/마지막 노드 완료/Respond to Webhook 노드 사용)도 선택 가능.
  인증 방식(Basic/Header/JWT)과 CORS, IP 화이트리스트, 바이너리 수신도 지원합니다. 최대 페이로드는 기본 16MB(환경변수 `N8N_PAYLOAD_SIZE_MAX`로 조정)
• Tip
  • 테스트 중엔 Test URL로 “Listen for Test Event”, 운영 전환 시 Production URL.
  • HTML을 응답으로 보낼 때는 n8n이 보안을 위해 <iframe>로 감쌀 수 있어요(1.103.0+)
    
    

2. If / Switch / Function(Code) Node — 분기와 가공의 3종 세트

If Node

• 역할: 단일 조건으로 true/false 두 갈래 분기. v1.0 이후 실행 순서가 바뀌면서(레거시 v0와 다름) If+Merge 조합의 동작이 정리되었습니다(레거시 주의 섹션 참고).
  https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.if/
  
• 예시(표현식): {{$json.total > 100}}

Switch Node

• 역할: 여러 케이스로 라우팅(If의 멀티버전). Rules 모드(출력별 규칙) 또는 Expression 모드(인덱스 반환) 지원.
  https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.switch/
• 예시: 상태값이 pending/shipped/cancelled일 때 1·2·3번 출력으로 분기

Function / Code Node

• 역할: JS/파이썬으로 자유로운 가공. v0.198.0+부터는 Code Node가 Function/Function Item을 대체.
• 모드: “Run once for all items”(배치 처리) vs “Run once for each item”(아이템별).
• 외부 모듈: Self-host에선 외부 npm 모듈 사용 가능(설정 필요). Cloud에선 crypto, moment만 제공. 파일시스템/직접 HTTP 접근은 불가(전용 노드 사용). 데이터 구조/아이템 링크 규칙도 문서에 정리돼 있습니다.
  https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.code/
• 자주 쓰는 패턴(JS)

// 모든 입력 아이템을 가져와 가공 후 반환
const items = $input.all();
return items.map(item => ({ json: { ...item.json, ok: true }}));

 

3. Wait Node  → 승인/이벤트/시간까지 “잠시 멈춤

 

• 역할: 실행을 DB로 오프로딩하고 조건을 기다린 뒤 재개. 대기 조건은 시간 간격, 특정 시각, 웹훅 호출, 폼 제출 4가지. On Webhook Call에서는 실행마다 고유한 $execution.resumeUrl 이 생성돼 외부에 전달해 재개를 트리거합니다.
  65초 미만 대기는 오프로딩 없이 같은 프로세스에서 이어집니다(서버 시간 기준).
  https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.wait/
  
• 실무 예시:
  • “검토 대기” 이메일 발송 → 승인자가 resumeUrl 클릭 시 이어서 진행
  • “내일 09:00에 다시 실행” 스케줄링

4. Error Workflow → 실패 시 알림/Slack 연동

• 역할: 워크플로우 실패 시 Error Trigger 노드가 있는 별도 워크플로우를 실행해 슬랙/메일 알림, 롤백, 재시도 큐 적재 등을 수행. Workflow Settings에서 Error Workflow를 지정하면 됩니다.
  https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.errortrigger/
• 구성 팁: 실패 로그를 Executions에서 열람하고, Error Workflow에서 `{{$json.error.message}}`, `{{$json.workflow.id}}` 같은 정보를 슬랙 메시지에 포함.
  https://docs.n8n.io/flow-logic/error-handling/
  

5. Looping — 대용량/페이지네이션/레이트리밋

• 기본 철학: 대부분의 노드는 리스트 입력을 자동으로 순회하므로 별도 루프가 필요 없습니다. 그래도 페이지네이션, 레이트 리밋 회피, 특정 예외 노드 처리에는 Loop Over Items(Split in Batches) 노드를 씁니다. Reset 옵션으로 반복 시 입력을 새로 초기화하며 종료 조건(If)과 함께 사용 
  https://docs.n8n.io/flow-logic/looping
• 패턴: “다음 페이지가 있으면 If로 루프 계속 → 없으면 종료”, “API 100건씩 배치 전송”

6. Version Control(이력/롤백) — 안전한 변경 관리

• Workflow History: Enterprise(Cloud Pro는 제한적)에서 이전 버전 열람/로딩이 가능합니다.
  https://docs.n8n.io/release-notes
  
• Git 기반 환경 분리(소스 컨트롤): 엔터프라이즈에서 Git 리포지토리와 연결해 브랜치별 환경(dev/stage/prod)과 Diff 비교를 제공합니다. 권한 요건과 사용법은 문서 참고.
  https://docs.n8n.io/source-control-environments/
• 커뮤니티/셀프호스트 백업 팁: CLI로 워크플로우/자격증명 Export/Import 자동화(예: n8n export:workflow --all). 정기 백업 + Git에 JSON 저장을 추천합니다.
  https://docs.n8n.io/hosting/cli-commands

 

 

n8n은 단순히 자동화를 넘어, 팀 생산성을 높여주는 오픈소스 플랫폼입니다.
이번 글에서 정리한 기본 개념을 바탕으로, 이후에는 실제 예제와 함께 더 깊이 다뤄보겠습니다. 🙌