Appendix A · n8n n8n 실전 매뉴얼 0%
📘 APPENDIX A

n8n 실전 매뉴얼

노드 레퍼런스 · 표현식 치트시트 · 에러 대처법 · 운영 팁

📚 목차
1. n8n 기본 개념과 환경 2. 핵심 노드 레퍼런스 12선 3. 표현식 문법 치트시트 4. Credentials 안전한 관리 5. 디버깅 + 에러 대처 6. 운영 팁 + FAQ
Section 1

1. n8n 기본 개념과 환경

n8n이란?

Node-based workflow automation 도구. 드래그앤드롭으로 API·데이터베이스·메신저 등을 연결해 자동화를 만듭니다. Zapier·Make와 비슷하지만 오픈소스 + 무료, 고급 기능(Code 노드, 복잡한 분기) 강점.

3가지 접속 옵션

☁️ ① 강사 초청 (권장) EASY
강사가 운영하는 n8n Cloud에 초청받아 바로 시작. 설정 0, 10초 내 로그인.
URL:hyeok2.app.n8n.cloud
계정:강사 초청 이메일 수신
비용:무료 (과정 종료 시 계정 회수)
🌐 ② n8n Cloud 직접 가입 MEDIUM
본인 계정으로 자유롭게 사용. 14일 무료 후 월 $20~.
URL:n8n.io/cloud
플랜:Starter $20/mo (5,000 실행)
🐳 ③ Docker Self-Hosted ADVANCED
로컬 Docker 또는 VPS에 직접 설치. 완전 무료, 무제한, 내 서버.
# Docker Compose 한 줄 실행 docker run -it --rm \ --name n8n \ -p 5678:5678 \ -v ~/.n8n:/home/node/.n8n \ docker.n8n.io/n8nio/n8n
학습 목적은 옵션 ① 또는 ②
Docker는 서버 지식 필요. 수업 진도 방해될 수 있음. 과정 완료 후 개인 프로젝트할 때 Docker로 전환 추천.
Section 2

2. 핵심 노드 레퍼런스 12선

8주 과정에서 반복적으로 사용하는 노드 12개의 필수 설정값 모음.

⏰ Schedule Trigger W1~W8
워크플로를 주기적으로 자동 실행. Cron 표현식 지원.
Mode:Every Day / Custom Cron Expression
매일 아침 9시:0 9 * * *
평일 8:30:30 8 * * 1-5
4시간 간격:0 */4 * * *
Timezone:Asia/Seoul (필수 설정)
Cron 표현식 암기 법
5자리: 분 시 일 월 요일. *은 "매", */N은 "N마다". 웹사이트 crontab.guru에서 실시간 의미 확인 가능.
🌐 HTTP Request CORE
외부 API 호출. n8n의 가장 중요한 노드. 어떤 서비스든 HTTP면 연결 가능.
Method:GET / POST / PUT / DELETE / PATCH
Authentication:Generic Credential Type 선택
Send Query:Parameters 추가 버튼
Send Headers:Specify Headers Using Fields
Send Body:JSON / Form Data / Binary
Options > Timeout:10000 ms (10초 권장)
흔한 실수
KIS API처럼 Body가 JSON인 경우 반드시 Content-Type: application/json 헤더 추가. Body Content Type을 "JSON"으로 명시하고 Send Body 토글 ON.
💻 Code FLEX
JavaScript 또는 Python으로 데이터 가공. 표현식으로 해결 안 되는 복잡한 로직 담당.
Language:JavaScript (Node.js) / Python (Pyodide)
Mode:Run Once for All Items / Once for Each Item
// Run Once for All Items 모드 예시 const data = $input.all(); // 모든 item 가져오기 const prices = data.map(item => item.json.price); const avg = prices.reduce((a, b) => a + b) / prices.length; return [{ json: { average_price: avg } }]; // Run Once for Each Item 모드 const price = $input.item.json.price; $input.item.json.doubled = price * 2; return $input.item;
📝 Set / Edit Fields TRANSFORM
필드 이름 변경·추가·제거. Code보다 간단한 변환에 사용.
Mode:Manual Mapping / JSON
Include Other Input Fields:Yes (기존 필드 유지)
필드 타입:String / Number / Boolean / Array / Object
🔀 IF BRANCH
단순 true/false 분기. 두 갈래로 갈림.
Conditions:AND / OR 연결
Types:String / Number / Boolean / DateTime
Operations:Equals / Contains / Greater Than / Empty 등
🚦 Switch MULTI
3개 이상의 분기. verdict가 BUY/SELL/WATCH/HOLD 등 다중 분기일 때.
Mode:Rules / Expression
Output:최대 10개 분기 + Fallback
표현식 예:{{ $json.verdict }}
🔗 Merge JOIN
여러 브랜치의 데이터를 합침. W4에서 W1~W3 결과 통합할 때 핵심.
Mode:Append / Merge By Fields / Merge By Position
Append:두 입력을 단순 연결 (row 합치기)
Merge By Fields:공통 키(예: ticker)로 JOIN
Merge By Position:index 기준으로 대응
Merge vs Aggregate
여러 브랜치 합치기 = Merge. 한 브랜치 내 여러 item을 하나로 압축 = Aggregate. 헷갈리기 쉬움.
📊 Google Sheets STORE
결과를 스프레드시트에 저장. 학습용 DB로 최적.
Resource:Sheet Within Document
Operation:Append Row / Update / Get All Rows
Data Mode:Auto-map / Map Each Column Manually
Credentials:OAuth2 (최초 1회 Google 로그인)
컬럼 이름 = JSON 키와 일치
Auto-map 모드에서 $json.ticker를 저장하려면 스프레드시트 첫 행에 ticker 헤더 필수. 정확히 일치해야 매핑됨.
🤖 AI Agent (Tools Agent) W3+
Claude·OpenAI 등 LLM 호출 + 도구 사용. W3부터 핵심 노드.
Agent:Tools Agent (추천)
Prompt Source:Define below / From previous node
System Message:에이전트 역할 정의
Sub-nodes:Chat Model + Memory + Tools
연결 구조: AI Agent 노드는 단독으로 못 씀. 반드시 아래 서브 노드 연결:
• Chat Model (Anthropic Chat Model / OpenAI Chat Model) — 필수
• Memory (Simple Memory 권장) — 대화 맥락 유지용
• Tool (HTTP Tool / Code Tool / Vector Store 등) — 선택, 다중 가능
🗂️ Vector Store (Supabase/Qdrant) W5~W6
벡터 DB 저장/검색. RAG의 핵심.
Operation Mode:Insert / Retrieve / Load
Table Name:documents (W5에서 생성)
Query Name:match_documents (RPC 함수명)
Sub-nodes:Embeddings + Data Loader + Splitter
📨 Webhook TRIGGER
외부에서 n8n을 호출하는 트리거. Discord bot 응답 받기에 필수.
HTTP Method:POST (대부분 경우)
Path:영문 슬러그 (예: discord-ask)
Respond:Immediately / When Last Node Finishes
Test URL:개발용 (비활성화 시 404)
Production URL:Activate 후 영구 사용
Test vs Production URL
Test URL은 "Listen for Test Event" 누를 때만 살아 있음. 진짜 배포 시 Workflow Active 토글 ON → Production URL로 전환 필수.
🚨 Error Trigger W5+
다른 워크플로가 실패했을 때 자동 실행. 에러 알림 전용 워크플로에 사용.
Trigger:항상 첫 노드로 배치
Output:$json.execution.error (실패 정보)
연결 방법:대상 워크플로 Settings → Error Workflow 지정
⚠ 흔한 실수: Error Trigger 워크플로를 만들어도 대상 워크플로의 Settings에서 Error Workflow로 지정하지 않으면 작동 안 함. 양방향 연결 필수.
Section 3

3. 표현식 문법 치트시트

표현식은 {{ }} 내부에 JavaScript 코드를 쓰는 방식. 노드 간 데이터 참조의 핵심.

기본 참조

{{ $json.field }}현재 노드 입력의 필드
{{ $json['field name'] }}공백이 있는 필드명
{{ $node['노드명'].json.field }}특정 노드 참조
{{ $input.all() }}모든 입력 item 배열
{{ $input.first().json }}첫 번째 item
{{ $binary.data }}바이너리 데이터 (이미지·PDF)

자주 쓰는 변환

{{ $json.price.toFixed(2) }}소수점 2자리 반올림
{{ Number($json.qty) }}문자열 → 숫자
{{ String($json.id) }}숫자 → 문자열
{{ $json.title.slice(0, 50) }}처음 50자 자르기
{{ $json.text.toLowerCase() }}소문자 변환
{{ $json.arr.join(', ') }}배열 → 콤마 문자열

날짜·시간

{{ $now }}현재 시각 (Luxon DateTime)
{{ $now.toISO() }}ISO 8601 포맷
{{ $now.toFormat('yyyy-MM-dd') }}"2026-04-22" 형태
{{ $now.minus({ days: 7 }) }}7일 전
{{ $now.setZone('Asia/Seoul') }}한국 시간대 변환

조건 표현식 (삼항연산자)

{{ $json.score > 0 ? 'up' : 'down' }}조건부 값
{{ $json.val || 'default' }}null/undefined 대체값
{{ $json?.nested?.field }}옵셔널 체이닝 (안전 접근)

배열 처리

{{ $json.items.length }}배열 길이
{{ $json.items.map(i => i.price) }}가격만 추출
{{ $json.items.filter(i => i.qty > 0) }}조건 필터
{{ $json.items.reduce((a,b)=>a+b.v,0) }}합계
표현식 디버깅 꿀팁
표현식 입력 필드 우측 상단 "Expression Editor" 아이콘 클릭 → 실시간 결과 미리보기 모달. 타입까지 표시됨. 실행 없이 검증 가능.
Section 4

4. Credentials 안전한 관리

Credential이란?

API 키·비밀번호를 워크플로와 분리해 저장하는 n8n 기능. 암호화되어 DB에 저장되고, 워크플로에서는 이름만 참조합니다.

3가지 Credential 타입

🔑 ① Generic Credential Type
가장 유연. Header Auth, Query Auth, Basic Auth, OAuth2 선택.

KIS API 예시 (Header Auth)

Credential Name:kis_paper_credentials
Name:appkey
Value:(36자리 키)
⚠ Header Auth는 하나의 헤더만 설정 가능. KIS처럼 여러 헤더(appkey + appsecret + tr_id)가 필요하면 Send Headers를 Manual로 하고 각 필드에 {{ $credentials.fieldName }} 표현식 사용.
🤝 ② 서비스 전용 Credential
Google Sheets, Slack, Discord, OpenAI 등 공식 지원 서비스. 대부분 OAuth2.
  • Google Sheets: "Sign in with Google" 팝업 → 권한 승인 → 자동 저장
  • Discord Webhook: Webhook URL 전체 붙여넣기
  • OpenAI / Anthropic: API Key 한 줄
📁 ③ Environment Variables
Self-hosted에서만 사용. .env에 N8N_ENCRYPTION_KEY, 민감한 키 저장.
# ~/.n8n/.env N8N_ENCRYPTION_KEY=your_random_32_char_key ANTHROPIC_API_KEY=sk-ant-... FRED_API_KEY=abc123... # 워크플로에서 참조 {{ $env.ANTHROPIC_API_KEY }}

안전한 관리 원칙

🚨 금기 사항:
1. 워크플로 JSON export 시 Credential 포함 금지 — 실수로 GitHub에 올리면 재앙
2. 스크린샷에 Credential 노출 금지 — 강의 자료 배포 시 반드시 모자이크
3. Credential 이름에 "실전/모의" 명시 — 섞이면 실계좌 사고
4. 주기적 재발급 — 최소 3개월에 한 번
Section 5

5. 디버깅 + 에러 대처

빈번한 에러 Top 10

에러 메시지원인 + 해결
Request failed with status code 401 인증 실패. Credentials 키가 유효한지 확인. KIS는 토큰 만료 체크.
Request failed with status code 403 권한 부족 or 계정 차단. API 플랜 확인. KIS 모의투자에 실전 TR_ID 사용했는지 확인.
Request failed with status code 429 Rate limit 초과. Wait 노드 추가 or API 호출 간격 늘리기.
timeout of 10000ms exceeded API 응답 느림. HTTP Request Options → Timeout 30000으로 증가.
Cannot read properties of undefined 표현식에서 존재하지 않는 필드 참조. ?. 옵셔널 체이닝 사용: {{ $json?.result?.data }}
JSON at position X JSON 파싱 실패. Claude가 ```json\n ... \n``` 감싸서 반환. Code 노드에서 정리 후 파싱.
Payload too large Body 1MB 초과. 긴 PDF는 청킹 후 전송.
Workflow execution timeout 워크플로 전체 10분 초과. Execute Workflow로 분할 or 비동기 처리.
SSL certificate error KIS 일부 환경에서 발생. Options → SSL: Ignore SSL Issues 토글 (자체 서명 CA 대응).
No item to process 이전 노드 출력 비어있음. 테스트 데이터로 각 노드 확인. Merge 노드의 mode 확인.

디버깅 체크리스트

✅ 에러 발생 시 순서대로 확인:
1. 실패 노드 클릭 → 상단 "Error" 탭에서 정확한 메시지 읽기
2. 이전 노드의 출력 데이터 확인 (테이블 뷰 / JSON 뷰 전환)
3. Credentials이 올바른지 재확인 (특히 실전/모의 구분)
4. 문제 노드만 "Execute Node" 버튼으로 단독 실행해 격리 테스트
5. Code 노드에서 console.log() → Executions 탭에서 로그 확인
6. 해결 안 되면 해당 노드 삭제 후 재생성 (드문 캐싱 버그)

테스트 vs 실행 구분

❌ 흔한 실수
"Execute Workflow" 누르고 결과가 안 오는데 기다림 → 트리거가 Schedule인데 시간 안 됨.
✓ 올바른 방법
테스트 시 트리거 노드 "Execute Node" → 즉시 실행. 전체 워크플로 확인하려면 "Execute Workflow" 상단 버튼.
Section 6

6. 운영 팁 + FAQ

🌟 프로페셔널 운영 팁 10가지

  1. Sticky Note 적극 사용 — 워크플로 에디터 우클릭 → "Add Sticky Note". 섹션 구분·설명 남기기. 한 달 뒤에 보면 감사함.
  2. 워크플로 명명 규칙 — [카테고리]_[용도]. 예: [Price]_Daily_Snapshot, [Agent]_News_Processor.
  3. Execute Workflow 노드로 모듈화 — 같은 로직 반복되면 서브 워크플로로 분리. 재사용 + 유지보수 용이.
  4. Error Trigger 연결 필수 — 배포된 워크플로마다 Settings → Error Workflow 지정. 조용한 실패 방지.
  5. Execution Log 주기적 확인 — 좌측 메뉴 "Executions" → 실패율·평균 실행시간 체크. 이상 징후 조기 발견.
  6. Wait 노드로 Rate Limit 방어 — CoinGecko Free는 30/분 제한. 루프에서 Wait 2초 추가.
  7. Max Iterations 설정 — Code 노드의 while 루프는 반드시 카운터 + 최대 반복 수 안전장치.
  8. 버전 관리 — 주요 변경 전 Workflow Duplicate → 이름 뒤 _v2 붙여 백업.
  9. 비활성화 후 편집 — 운영 중 워크플로 편집하면 예기치 않은 실행. 편집 전 Active 토글 OFF.
  10. Manual Trigger 보존 — 배포 후에도 Manual Trigger 노드 남겨두기. 테스트용으로 유용.

❓ FAQ

워크플로가 실행 안 됨 — 스케줄 시간 됐는데도
Active 토글이 ON인지 확인. Test URL이 아닌 Production URL을 쓰는지. Timezone이 Asia/Seoul로 설정됐는지.
HTTP Request의 Body를 JSON으로 보냈는데 400 에러
Send Body 토글 ON + Body Content Type = "JSON" + Send Headers에 Content-Type: application/json. 3개 모두 필요.
Code 노드에서 npm 라이브러리 쓸 수 있나?
n8n Cloud는 제한됨 (Lodash 등 일부만). Self-hosted Docker면 NODE_FUNCTION_ALLOW_EXTERNAL 환경변수로 허용 가능. 학습 단계에서는 기본 JS만으로 충분.
AI Agent가 계속 같은 실수를 반복함
System Message 프롬프트를 더 구체화. "반드시 JSON만 출력", "설명 금지" 같은 명시적 제약 추가. Memory가 이전 실수를 기억하고 있다면 Memory 비우기.
Vector Store Retrieve가 엉뚱한 문서 반환
(1) match_documents RPC가 제대로 만들어졌는지, (2) 임베딩 차원(1536)이 맞는지, (3) 데이터가 충분히 저장됐는지 확인. W6 Reranker로 보정 가능.
Discord 메시지가 안 보내짐
(1) Webhook URL 정확한지, (2) Discord 채널 접근 권한, (3) 메시지 길이 2000자 초과 여부. embed 대신 content만 테스트해보기.
실행 비용이 폭발적으로 증가함
Chat Model이 Claude Opus면 즉시 Sonnet 또는 Haiku로 교체. Tool Use가 무한 루프에 빠지지 않는지 Max Iterations 확인. Cohere Rerank는 매우 저렴하므로 문제 아닐 가능성 큼.
n8n Cloud vs Self-hosted 전환 시기는?
월 실행 5,000회 이상이거나, 개인정보/보안이 중요한 데이터를 다룰 때 Self-hosted 고려. 초기 학습·개인 프로젝트는 Cloud가 압도적으로 편함.
📘 APPENDIX A COMPLETE
n8n 실전 매뉴얼
12 nodes · 50+ expressions · Top 10 errors
2026 · ZeroOneAI Education