# what is n8n
## n8n 이란?
nodemation을 줄인 표현입니다.
#### 왜 node가 핵심 설계 단위인가?
워크 플로우를 노드 그래프(DAG에 가까운 형태)로 모델링합니다. \
이로써 조합/재사용/확장(커스텀 노드)이 쉬워집니다.
#### 코드 기반 파이프라인에 비해 갖는 구조적 트레이드 오프는?
* 장점: 가시성/운영편의/비개발자 협업
* 단점:
* 복잡한 조건/추상화는 코드(컴스텀 함수/스크립트 노드)로 다시 내려가야합니다.
* 그래프가 커질수록 텟그트/버전관리/리뷰 전략이 중요
## 많은 자동화 도구 중 n8n의 장점은?
* 셀프호스팅/배포 유연성: 데이터/크리덴셜을 내부에 두고 운영하기 쉽고, 필요하면 확장도 가능합니다.
* 큐 기반 확장: 메인 프로세스와 워크플로 실행을 분리해, 워커를 여러 대 붙여 처리량을 늘릴 수 있습니다.
* 노드 생태계 + 커스텀: 트리거/액션/로직 노드 조합으로 "통합 파이프라인"을 빠르게 만들고, 부족하면 커스텀 노드/코드로 보완하는 방향이 일반적입니다.
* 웹훅을 API 엔드포인트처럼: Webhook 노드는 외부 요청으로 워크플로를 시작하는 트리거이고, 응답 반환 방식도 제공해 "간단한 백엔드 엔드포인트" 처럼 쓸 수 있습니다.
#### Zapier/Make 같은 SaaS 자동화와 비교해 n8n의 본질적 차이는?
* 셀프호스트
* 확장성(큐/워커)
* 커스터마이징(코드/노드 개발)
* 운영(모니터링/장애대응)까지 사용자의 책임
#### 큐 모드로 스케일할 때 생기는 운영 이슈(중복 실행, 순서 보장, 재시도, 멱등성)을 어떻게 다루고 있나요?
* 워크플로 설계를 "멱등"하게
* 외부 API 호출은 재시도/백오프/서킷브레이커 관점
* 순서가 필요한 작업은 키 기반 직렬화/락/단일 워커 전략 고민
## n8n은 기존 백엔드 서버와 비교해 아키텍처 관점에서 뭐가 다른가요?
**전통 백엔드 서버:**
* 요청 라우팅(HTTP)
* 비즈니스 로직
* 데이터 저장
* 비동기 작업 큐
* 스케줄러 등 개발자가 직접 조립.
n8n:
* 서버 프레임워크가 아닌 워크플로 실행/오케스트레이션 플랫폼에 가깝습니다
* 로직이 코드 팔일이 아니라 워크플로(노드 그래프)로 저장/실행됩니다.
* 트리거(웹훅/스케줄/이벤트)로 시작된 실행이 실행 기록/상태와 함께 관리되는 쪽에 초점이 있습니다.
특히 큐 모드에서는 구성요소가 더 "분산 시스템"처럼 나뉩니다.
* 메인(UI/API, 트리거/스케줄) <-> Redis 큐 <-> 워커(실행) <-> DB(상태 기록)
#### n8n을 백엔드 대체로 쓰면 안되는/조심해야하는 경계는 어디인가요?
복잡한 도메인 로직/트랜잭션/고성능 API는 전통 백엔드가 유리합니다.\
n8n은 통합/자동화/오케스트레이션에 강합니다.
#### Webhook 노드로 API처럼 쓸 때, 성능/보안/버전관리 이슈를 어떻게 설계하나요?
핵심 포인트:
* 인증(서명검증/토큰), rate limit, 입력 검증
* 테스트 URL/프로덕션 URL 분리 운영
* 워크플로 변경이 곧 API 변경 -> 버전 분기(워크플로 버전/별도 엔드포인트) 전략 필요
## n8n은 어떤 "엔진"으로 구성되고 각 역할은?
1. Main(웹 앱/오케스트레이션): UI(에디터) + API + 트리거 등록/스케줄 관리, 실행을 직접 하거나(단일 모드) 큐에(큐 모드) 넣습니다.
2. Worker(실행 엔진): 큐에서 Job을 가져와 노드들을 순서대로 실행하고 결과/상태를 저장.
3. Webhook 처리(웹훅 엔드포인트): Webhook 트리거 요청을 받아 워크플로 실행을 시작하거나, 워크플로 결과를 HTTP 응답으로 반환.
4. DB(상태/메타데이터 저장): 워크플로 정의, 크리덴셜 메타, 실행 이력/상태 등을 영속화. (DB+Redis 조합을 전제로 설명)
5. Redis(큐/브로커): 큐 모드에서 실행을 분산하기 위한 브로커.
6. Task Runner(작업 실행 격리): n8n 작업을 내부/외부 러너로 실행할 수 있게 하는 구성. 운영 환경에서는 격리를 보장(보안/안정성 관점)
#### 단일 모드 vs 큐 모드 차이와, 언제 큐 모드로 가야하나?
동시 실행/처리량/장애 격리/스케일 아웃 필요 시 큐 모드.
#### 워커를 늘렸을 떄도 "같은 워크플로가 중복으로 실행"될 수 있는 조건과 방지 전략
트리거 중복(웹훅 재전송, 스케줄 겹침), 재시도를\
멱등키/디듀프 저장소/락/외부 시스템의 idempotency key 활
## workflows, trigger, node는 무엇이고 어떤 역할인가요?
* workflow: 자동화의 "설계도". 노드들의 연결 그래프
* trigger node: 워크플로의 시작점. 이벤트 조건이 만족되면 실행을 시작
* 예: webhook 노드는 외부 HTTP 요청으로 시작
* 예: manual trigger는 테스트용 수동 실행 시작점
* (참고: 예전 workflow trigger는 deprecated 되고 기능이 n8n trigger로 옮겨짐)
* node: 한 단계의 작업 단위(외부 API호출, 데이터 변환, 조건 분기, DB 쓰기 등). 입력 데이터를 받아 처리하고 다음 노드로 넘김
#### 트리거가 "상시 대기(listen)하는 방식과 폴링(polling) 방식의 차이는?
* 웹훅 = 푸시/이벤트 기반
* 폴링 = 주시적으로 조회(지연/비용/부하 trade-off)
#### 노드 간 데이터 전달에서 스키마/형식 문제를 어떻게 관리하나?
노드 출력 형태(JSON/바이너리), 변환 노드로 정규화, 필드 누락 방어, 에러 분기(try/catch 패턴), 테스트 데이터 고정
#### 실행/장애/재시도 설계
* 자동화는 성공보다는 실패 경로가 더 중요합니다. 재시도 정책, 중복 실행 대비, 부분 실패 처리, DLQ 유사 운영, 알림/모니터링
* 큐 모드에서의 분산 실행 흐름을 말로 그릴 수 있어야 함.
#### 실패한 실행을 재처리할 때 데이터 일관성은 어떻게 보장하나?
**재처리는 중복 실행을 전체로 하므로, 이벤트 ID 기반 멱등키 + 상태머신(단계별 커밋) + 필요시 보상 트랜잭션**
핵심은 “재처리는 결국 **중복 실행**을 전제로 하므로, 시스템을 **멱등(idempotent)** 하게 설계”하는 겁니다.
1. **멱등 키(디듀프 키)로 ‘같은 작업’ 재실행을 흡수**
* 외부에서 들어오는 이벤트에 고유 ID(예: webhook event\_id, message\_id)가 있으면 그걸 **idempotency key**로 씁니다.
* 처리 전에 DB/캐시에 `processed_events(event_id)` 같은 테이블/키를 조회하고, 이미 있으면 **바로 종료(또는 이전 결과 반환)**.
* 없다면 **먼저 “처리 시작 기록”을 저장**(가능하면 유니크 제약) → 그 다음 실제 side-effect(결제, 발송, 티켓 생성 등)를 실행.
2. **side-effect를 “원자적 커밋”처럼 다루기 (Outbox / Saga 관점)**
* “DB 업데이트 + 외부 API 호출” 같이 **2개의 시스템**이 엮이면 트랜잭션이 끊깁니다.
* 그래서 현실적 해법은:
* DB에 상태를 먼저 기록(예: `PENDING`) → 외부 호출 성공 시 `DONE`으로 전이
* 또는 Outbox 패턴처럼 “보낼 메시지/요청”을 DB에 먼저 적재하고, 별도 흐름이 전송 후 `SENT`로 마킹
3. **부분 실패(Partial failure)를 상태 머신으로 모델링**
* 실행은 한 번에 “올 성공”이 아니라 단계별 실패가 납니다.
* 각 단계(예: “주문 생성 → 결제 승인 → 영수증 발송”)를 상태로 나누고,
* 재시도는 **마지막 성공 단계 이후부터** 재개하도록(= 재처리 범위를 최소화)
* 실패 시에는 **보상(취소/롤백 API)** 또는 **수동 검증 큐(사람이 보는 큐)** 로 보냄
4. **n8n 큐 모드에서 특히 중요한 포인트**
* 큐 모드는 메인/워커가 분리되고(메인은 오케스트레이션, 워커는 실행), Redis 큐를 통해 작업이 분산됩니다. 즉, **재시도/재전송/워커 장애**로 “같은 입력이 다시 실행”될 수 있다는 전제가 강해집니다.\
→ 그래서 위의 멱등/상태기반 설계가 사실상 필수입니다.
#### 외부 API rate limit/timeout이 잦을 때, 워크플로 레벨에서 어떤 패턴을 쓰나요?
실무에서는 “**호출을 줄이고(최적화)**, **망가져도 버티고(회복탄력성)**, **다시 돌려도 안전(멱등)**” 3축으로 갑니다.
1. **백오프 + 지터(jitter)**
* 429(Too Many Requests), 5xx, timeout은 즉시 재시도하면 더 악화됩니다.
* **지수 백오프(예: 1s→2s→4s…) + 랜덤 지터**로 “동시 재시도 폭주”를 피합니다.
2. **레이트리밋 친화적 설계(스로틀/동시성 제한)**
* 한 번에 병렬로 많이 때리면 rate limit에 바로 걸립니다.
* 워크플로에서 **동시 호출 수를 제한**하거나, 큐에 넣고 **워커 수/동시 실행량**을 조절합니다(큐 모드 자체가 운영적 스로틀 도구가 됨).
3. **벌크화(Batching)**
* “N번 호출”을 “1번 벌크 호출”로 바꿀 수 있으면 가장 강력합니다.
* 예: CRM 레코드 200개 업데이트 → 개별 PATCH 200번 대신 batch endpoint 1\~2번.
4. **캐시 / 조건부 요청**
* 동일한 조회를 반복하면 rate limit을 소모합니다.
* 캐시(짧은 TTL이라도) + ETag/If-Modified-Since 같은 조건부 요청이 가능하면 적극 사용.
5. **서킷 브레이커 + 폴백**
* timeout이 연속으로 나면 **일정 시간 호출을 끊고(open)**, 빠르게 실패시키거나 대체 경로(캐시 값, “나중에 처리”)로 폴백합니다.
* 자동화는 “지금 실패해도 나중에 처리”가 가능한 일이 많아서, **DLQ 유사 큐로 보내고 알림**이 잘 맞습니다.
#### 자동화 플랫폼에서 권한분리를 어떻게 설계하나요?
원칙은 “**편집 권한**과 **비밀(크리덴셜) 접근 권한**을 분리”하고, 자동화 실행은 “최소권한”으로 제한하는 겁니다.
1. **RBAC(역할 기반)로 최소권한**
* 역할 예시:
* Viewer: 실행 결과만 보기
* Editor: 워크플로 편집 가능
* Operator: 재실행/중지/롤백 운영 권한
* Admin/Security: 크리덴셜/환경변수 관리
* 특히 “Editor가 크리덴셜을 평문으로 볼 수 있다”면 내부자 위협이 커집니다.
2. **크리덴셜은 ‘참조’만 하게**
* 워크플로는 크리덴셜을 “선택/참조”만 하고, 값 자체는 숨김.
* 교체/회전(rotate)은 보안 담당자가 하고, 워크플로는 동일 참조를 유지.
3. **실행 격리(코드 실행이 특히 위험)**
* n8n은 Code node에서 사용자 JS/Python 실행이 가능하고, 이를 안전/성능 목적으로 task runner로 분리할 수 있습니다.
* 공식 문서도 내부 모드는 프로덕션에서 보안 리스크가 될 수 있어 **외부 모드로 격리**를 권장합니다.\
→ 즉, “워크플로 편집 가능자”가 곧 “서버 내부에서 코드 실행 가능자”가 될 수 있으니, **격리 + 권한 통제**가 같이 가야 합니다.
#### 공통 로직을 어떻게 재사용하나요? (서브워크플로, 템플릿화)
n8n에서는 큰 워크플로를 쪼개서 **서브워크플로로 호출**하는 패턴이 대표적입니다. 공식 문서도 “다른 워크플로를 호출해 재사용하고 큰 워크플로를 작은 구성요소로 분해”하라고 안내합니다.
실무 패턴:
1. **서브워크플로(공통 함수처럼)**
* 공통 로직(예: “고객 정규화”, “권한 체크”, “Slack 알림 포맷”)을 별도 워크플로로 분리
* 시작 노드는 **Execute Sub-workflow Trigger**(다른 워크플로가 호출할 때 시작)
* 호출 측은 “execute workflow/서브워크플로 실행” 노드로 호출
2. **입력/출력 계약(Contract) 정의**
* 서브워크플로는 입력 필드/출력 형태를 명확히 고정(= 함수 시그니처)
* “호출자마다 조금씩 다른 데이터”는 앞단에서 정규화해서 넣고, 서브워크플로 내부는 단순/일관 유지
3. **템플릿/표준 스캐폴딩**
* 신규 자동화가 생길 때 공통 뼈대(로깅/알림/에러 라우팅)를 템플릿처럼 복제해 시작
#### 재사용이 많아질 때 버전 호환성/변경 영향도는 어떻게 통제하나요?
재사용이 늘면 “한 번 고치면 전부 깨지는” 상황이 옵니다. 그래서 아래 4가지를 같이 합니다.
1. **버전 분리(깨는 변경은 새 워크플로로)**
* Breaking change가 있으면 기존 서브워크플로를 덮어쓰지 말고 `subwf_v2`처럼 새 버전으로 만들고,
* 호출자들을 단계적으로 마이그레이션(= 단계적 배포).
2. **계약 테스트(Contract test)**
* 서브워크플로의 입력/출력 샘플을 고정해, 변경 시에도 동일 계약을 만족하는지 테스트.
* 특히 “필드명/타입/빈 값 처리”가 자주 깨짐 포인트라 여기부터 테스트합니다.
3. **점진 롤아웃(카나리)**
* 일부 호출자만 v2로 전환해 관측하고(에러율/지연/외부 API 실패율),
* 안정화되면 확장.
4. **관측성(Observability)으로 변경 영향 추적**
* 서브워크플로 호출을 공통 로깅/메트릭으로 남기면, 버전별 에러율 비교가 쉬워집니다.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://wonjoon.gitbook.io/joons-til/automation/why-fetchresults-is-deprecated.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.