n8n Cheat Sheet

 

n8n을 처음 접하는 분들이  자동화 구축 실무 적용시  표현식 활용 → 내장 노드 이해 → Docker 운영 → AI Agent 구성 → 단축키 활용 → 에러 핸들링을 정리해 놓은 n8n Cheat Sheet 가 있어서 다시  정리해 보았습니다. (source : data popcorn)  

---

1. 기본 개념

• 트리거(Trigger): 워크플로우 실행 시작점.
• 노드(Node): 입력(Input) → 함수(Function) → 출력(Output) 흐름으로 구성.
• 데이터 처리: 아이템 수, 데이터 타입, 표현식(Expression)을 통해 제어.

트리거 노드 이해하기

[Trigger Node] → [Node] → [Output]
   (Start)    (Input>Function>Output)

• Items Count: 처리할 데이터 아이템 개수
• Data Type: 데이터 타입 정의
• Data Transfer: 노드 간 데이터 전달 방식

 

 

---

2. 표현식 (Expressions)  타입별 문법

 

타입 표현식 

• {{ $json["key"] }} → 현재 노드 데이터 값
• {{ $node["nodeName"].json["value"] }} → 특정 노드의 값 참조
• {{ $now.format('yyyy-MM-dd') }} → 현재 날짜 포맷
• 조건문 : {{ $json["price"] > 100 ? "expensive" : "cheap" }}

기본	{{ $json["key"] }}	현재 아이템의 JSON 데이터 접근
노드 참조	{{ $node["nodeName"].json["value"] }}	다른 노드의 데이터 참조
날짜 포맷	{{ $now.format('yyyy-MM-dd') }}	현재 시간 포맷팅
조건문	{{ $json["price"] > 100 }}	조건 평가
삼항 연산자	{{ $json["price"] > 100 ? "expensive" : "cheap" }}	조건부 값 반환

 

내장 메서드 

$jmespath(), $max(), $min(), $fromAI() 등 사용 가능.

• $jmespath(): JSON 경로 표현식
• $fromAI(): AI 결과 파싱
• $max(), $min(): 최대/최소값
• 메타데이터: $execution, $itemIndex, $input, $parameter, $prevNode, $runIndex, $today, $vars, $workflow

 

---

3. 주요 내장 노드 (Built-in Nodes)

Built-in Nodes (내장 노드)

카테고리별 주요 노드

Trigger Nodes (트리거 노드)

• 트리거(Trigger): Manual, Schedule, Webhook, Chat, Workflow Call

노드 설명 사용 케이스

Manual	수동 실행 트리거	테스트, 일회성 작업
Schedule	시간 기반 자동 실행	정기 보고서, 백업
Form	폼 제출 시 트리거	신청서, 설문조사
Chat	채팅 메시지 트리거	챗봇, 고객 지원
Webhook	외부 HTTP 요청 트리거	API 연동, 외부 이벤트
Workflow	다른 워크플로우에서 호출	모듈화, 재사용

 Core Nodes (핵심 노드)

• 데이터 처리(Core):
  • Set (필드값 편집)
  • IF (조건 분기)
  • Aggregate (집계)
  • Split Out (배열 분리)
  • Merge (데이터 스트림 합치기)
  • Sort, Limit, Loop, Wait 등
• 파일 관련: Convert to File, Extract from File, Compression
• 에러/종료: Stop and Error
• API 연동: HTTP Request.

노드 설명 활용 예시

Edit Fields (Set)	필드 값 설정/수정	데이터 변환, 필드 추가
Remove Duplicate	중복 데이터 제거	데이터 정제
IF	조건 분기	상태별 처리 분기
Aggregate	데이터 그룹화/집계	통계, 요약
Split Out	세트를 개별 요소로 분리	배열 처리
Filter	조건 충족 데이터만 필터링	데이터 선별
Code	JavaScript 코드 실행	복잡한 로직 구현
Merge	두 데이터 스트림 병합	데이터 통합
Loop	반복 실행	배치 처리
HTTP Request	외부 API 호출	REST API 연동

 

---

4. Docker 기반 설치/운영

• 실행 명령 예시
• sudo docker run -it \ --restart unless-stopped \ --name n8n \ -p 5678:5678 \ -v n8n_data:/home/node/.n8n \ -e WEBHOOK_URL="https://n8n.example.com/" \ -e GENERIC_TIMEZONE="Asia/Seoul" \ -d docker.n8n.io/n8nio/n8n:latest
• SMTP, Timezone, Encryption Key, Custom Node 경로 등 환경변수 설정 가능.
• 업데이트: docker pull, stop, rm, run 순서로 버전 관리.

Docker 실행 명령어 (전체 옵션)

sudo docker run -it \
  --restart unless-stopped \                    # 자동 재시작
  --name n8n \                                   # 컨테이너 이름
  -p 5678:5678 \                                # 포트 매핑
  -v n8n_data:/home/node/.n8n \                 # 데이터 영구 저장
  -e WEBHOOK_URL="https://n8n.example.com/" \   # 공개 웹훅 URL
  -e N8N_SMTP_HOST="smtp.gmail.com" \           # SMTP 서버
  -e N8N_SMTP_PORT=465 \                        # SMTP 포트
  -e N8N_SMTP_USER="YOUR_EMAIL" \               # 이메일 계정
  -e N8N_SMTP_PASS="app_password" \             # 앱 비밀번호
  -e GENERIC_TIMEZONE="Asia/Seoul" \            # 시간대 설정
  -e N8N_ENCRYPTION_KEY="" \     # 암호화 키
  -e EXECUTIONS_TIMEOUT=3600 \                  # 실행 타임아웃(초)
  -e NODE_FUNCTION_ALLOW_BUILTIN=* \            # 내장 모듈 허용
  -d docker.n8n.io/n8nio/n8n:latest            # 최신 버전 실행

Docker 관리 명령어

# 최신 버전 업데이트
sudo docker pull docker.n8n.io/n8nio/n8n

# 컨테이너 중지
sudo docker stop n8n

# 컨테이너 제거
sudo docker rm n8n

# AI Starter Kit 설치
git clone https://github.com/n8n-io/self-hosted-ai-starter-kit.git
cd self-hosted-ai-starter-kit

 

 

---

5. AI Agent 구조

• Persona (역할), Task (할 일), Context (목적), Format (출력 형식) 지정
• AI Model 필수 (예: OpenAI, Anthropic 등)
• Memory(1:N), Tool(1:N) 구조 지원 → 예: HTTP Request API 호출, One-click 자동 채움.

AI Agent 아키텍처

[AI Agent]
    ├── Persona (역할 정의)
    ├── Task (수행할 작업)
    ├── Context (목적/맥락)
    └── Format (출력 형식)
    
연결 구성:
- AI Model (1:1) *필수
- Memory (1:N) 
- Tool (1:N)

사용자 입력 처리 흐름

사용자 입력 → AI Agent → Memory/Tool 활용 → 응답 생성

 

HTTP Request (API)

HTTP Request 노드 구조

// 요청 설정 예시
{
  url: "https://api.example.com/data",
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
  },
  body: {
    "param": "value"
  }
}

One Click Auto-fill 기능

API 문서의 cURL 명령어를 붙여넣으면 자동으로 설정이 채워짐 

 

 

6.  Keyboard Shortcuts

주요 단축키 카테고리

워크플로우 제어

기능 단축키 설명

새 워크플로우	Ctrl + Alt + N	새 워크플로우 생성
워크플로우 열기	Ctrl + O	기존 워크플로우 열기
저장	Ctrl + S	현재 워크플로우 저장
실행	Ctrl + Enter	워크플로우 실행
실행 취소	Ctrl + Z	마지막 작업 취소
다시 실행	Ctrl + Shift + Z	취소한 작업 복원

 캔버스 네비게이션

기능 단축키/제스처 설명

이동	Ctrl + 드래그	캔버스 이동
확대	= 또는 +	화면 확대
축소	- 또는 _	화면 축소
초기화	0	줌 레벨 초기화
화면 맞춤	1	전체 워크플로우 보기

노드 작업

기능 단축키 설명

모든 노드 선택	Ctrl + A	전체 노드 선택
복사	Ctrl + C	선택한 노드 복사
붙여넣기	Ctrl + V	노드 붙여넣기
삭제	Delete	선택한 노드 삭제
비활성화	D	노드 비활성화
노트 추가	Shift + S	노트 추가
데이터 고정	P	노드 데이터 고정

 

7. 노드 설정 (에러 핸들링)

 

• Always Output Data: 데이터 없을 때도 빈 값 반환 (주의: 무한 루프 가능)
• Execute Once: 첫 아이템만 처리
• Retry On Fail: 실패 시 재시도

Always Output Data	데이터가 없어도 빈 아이템 반환	IF 노드 무한 루프 주의
Execute Once	첫 번째 아이템만 처리	단일 실행 필요 시
Retry On Fail	실패 시 재시도	네트워크 오류 대응

⚠️ 에러 처리

옵션 동작 활용

Stop Workflow	에러 시 워크플로우 중단	중요 작업
Continue	에러 무시하고 계속	선택적 작업
Continue (using error output)	에러 정보를 다음 노드로 전달	에러 로깅

 

 

• 워크플로우
  • 새로 만들기: Ctrl + Alt + N
  • 저장: Ctrl + S
  • 실행: Ctrl + Enter
• 화면 이동/확대 축소
  • Ctrl + Mouse Wheel → 확대/축소
  • 0 → 줌 리셋
  • 1 → 화면에 맞춤
• 노드 조작
  • 복사: Ctrl + C
  • 붙여넣기: Ctrl + V
  • 삭제: Delete
  • 주석 추가: Shift + S.

• On Error 옵션
  • Stop Workflow
  • Continue
  • Continue (error output 활용).

---

8. 커뮤니티 & 리소스

• 공식 문서: docs.n8n.io
• 포럼: community.n8n.io
• GitHub: n8n-io/n8n
• Discord: discord.gg/n8n

---

성능 최적화 포인트

• Execute Once 설정으로 불필요한 반복 방지
• Split Out 대신 Loop 사용으로 메모리 효율 개선
• Error Workflow 설정으로 에러 모니터링
• Webhook 응답 시간 최적화

디버깅 팁

• 각 노드의 출력 데이터 확인 (Pin Data 활용)
• Expression Editor에서 실시간 결과 확인
• Error Workflow로 에러 로그 수집
• 노드별 Notes로 로직 문서화