가이드 · 시작하기

n8n 인스턴스 설정

분석할 n8n 인스턴스를 연결하고 API Key, Log Streaming, 이벤트와 AI Addon 상태를 확인합니다.

Nelper가 분석할 n8n을 먼저 연결합니다. 워크스페이스의 인스턴스 추가·변경·삭제는 Owner/Admin만 수행할 수 있습니다.

연동 화면 열기

사이드바 아래의 프로필 아바타를 선택합니다.
설정 왼쪽의 워크스페이스 → 연동을 선택합니다.
등록된 인스턴스와 AI Workflow Addon 영역을 확인합니다.

워크스페이스 연동 설정 — n8n 인스턴스와 AI Workflow Addon을 관리하는 연동 화면

인스턴스 추가

오른쪽 위 인스턴스 추가를 선택합니다.
인스턴스 이름을 입력합니다. 예: Production n8n
n8n URL을 입력합니다. n8n 웹 UI 주소이며 리소스 맵과 감사로그의 원본 바로가기에 사용됩니다.
필수인 PostgreSQL 연결을 입력합니다.
- 개별 입력: Host, Port(기본 5432), Username, Password, Database
- URL 입력: postgresql://readonly_user:****@host:5432/n8n
선택 사항인 Metrics URL을 입력합니다. n8n에 N8N_METRICS=true가 필요합니다.
선택 사항인 n8n API Key를 입력합니다. Error Workflow, 노드 정책 자동 조치 등 REST API 기능에 사용하며 나중에 등록할 수 있습니다.
연결 테스트를 실행합니다.
성공 결과에서 확인된 테이블, 실행 기록과 n8n 버전을 검토한 뒤 추가를 선택합니다.

최소 권한 원칙 PostgreSQL은 읽기 전용 계정을 강력히 권장합니다. 신규 인스턴스는 연결 테스트를 통과해야 추가할 수 있습니다. 편집 시 DB 연결 정보가 바뀌면 다시 테스트해야 합니다.

인스턴스 카드와 상태

상태	의미와 조치
연결됨	DB 스캔이 완료되어 분석에 사용할 수 있습니다.
스캔 중	스키마와 자산을 수집 중입니다. 완료될 때까지 기다립니다.
연결 실패	네트워크, 인증, DB 이름과 방화벽을 확인합니다.
경고	일부 선택 연동이나 이벤트 수신에 문제가 있는지 메시지를 확인합니다.

재스캔: n8n 스키마와 리소스를 다시 읽습니다.
편집: URL, DB, Metrics와 연결 옵션을 수정합니다.
삭제: 확인 창을 거쳐 Nelper의 인스턴스 등록을 제거합니다.
마지막 스캔, 마지막 이벤트 수신과 오류 메시지를 카드에서 확인합니다.

n8n API Key 등록과 검증

n8n의 Settings → n8n API → Create an API Key에서 키를 만듭니다.
Nelper 연동 화면에서 인스턴스 카드의 n8n API Key 영역을 펼칩니다.
키를 붙여넣고 등록을 선택합니다.
연결 검증을 실행해 만료일과 기능별 필수 권한을 확인합니다.
교체할 때는 키 변경, 제거할 때는 삭제와 확인을 사용합니다.

Nelper n8n API Key 관리 — 키 등록 상태와 필수 scope를 검증하는 인스턴스 카드

n8n의 실제 키 목록에서는 키 값이 마스킹되어 표시됩니다.

n8n API Key 화면 — n8n Settings의 API Key 목록과 생성 진입점

기능별 대표 scope

기능	필요한 대표 권한
워크플로 조회·검증	`workflow:list`, `workflow:read`
Error Workflow 할당	워크플로 조회와 수정에 필요한 scope
노드 정책 자동 게시 해제	`workflow:read`, `workflow:deactivate`

n8n 버전과 API 권한 모델에 따라 표시 명칭이 달라질 수 있으므로 Nelper의 연결 검증 결과를 기준으로 보완합니다.

Log Streaming Webhook 등록

실행 상태, 워크플로 오류, n8n 감사 이벤트와 LLM 토큰 이벤트는 n8n Log Streaming을 통해 Nelper로 전달됩니다.

Nelper에서 인스턴스 편집을 열고 Log Stream Webhook URL을 복사합니다.
n8n의 Settings → Log Streaming으로 이동합니다.
Add new destination에서 Webhook destination을 만들고 URL을 등록합니다. 별도 인증 헤더나 비밀값은 필요하지 않습니다.
Live Runs와 라이선스 사용량을 실시간으로 갱신하려면 Workflow Events의 Started, Success, Failed를 모두 선택합니다. 완료 이벤트가 없으면 두 화면은 n8n DB를 5초마다 확인하는 방식으로 동작합니다.
현재 실행 중인 노드까지 표시하려면 Node Executions의 Started도 선택합니다.
n8n 감사로그를 사용하려면 Audit 이벤트 구독을 반드시 켭니다.
Nelper 카드의 마지막 이벤트 수신 시각이 갱신되는지 확인합니다.

Resource Map의 Live Runs는 현재 n8n 설정을 읽어 Log Streaming 미설정·비활성화, Workflow 이벤트 미선택, Node 이벤트 미선택 상태를 구분해 필요한 조치를 안내합니다. Workflow 이벤트만 선택돼 있으면 실행 시작과 성공·실패는 실시간이지만 현재 노드는 표시되지 않습니다. Audit 구독을 켠 이후의 이벤트만 수집되며, 구독 시작 전 감사 이벤트는 자동 소급되지 않습니다.

이벤트와 메트릭 모니터링

시스템 메트릭: n8n/Node 버전, 업타임, Heap, Event Loop p99, RSS 메모리와 수집 상태
수신 이벤트: 마지막 수신 시각과 최근 수신 추세

인스턴스 카드의 전체 이벤트를 선택하면 이벤트 탐색 화면이 열립니다. 조회 기간을 1시간·6시간·24시간·7일·30일·1년 또는 직접 선택으로 지정하고, 이벤트 종류로 목록을 좁힙니다. 표에서 이벤트와 내용, 실행 ID, 수신 시각(KST)과 경과 시간을 함께 확인하고 행을 선택해 원본 payload를 봅니다. 페이지당 10·50·100건을 선택할 수 있습니다.

기간·종류 필터와 실행 ID·수신 시각을 제공하는 n8n 이벤트 탐색 화면 — 기간과 종류로 좁혀 수신 이벤트를 추적하는 이벤트 탐색 화면

Metrics의 기본 지표가 보이지 않으면 n8n에 N8N_METRICS_INCLUDE_DEFAULT_METRICS=true가 적용됐는지 확인합니다.

AI Workflow Addon 연결

연동 화면 아래의 AI Workflow Addon 영역으로 이동합니다.
AI Addon URL을 입력합니다.
Addon 서버의 M4N_API_SECRET과 같은 API Secret을 입력합니다.
Health Check를 실행해 연결 성공을 확인합니다.
성공한 뒤 활성화 토글을 켭니다.

상태는 확인 중, 비활성, 정상, 연결 끊김으로 표시됩니다. 저장된 Secret 원문은 다시 표시되지 않습니다.

n8n 버전 변경 감지

연결된 n8n 버전이 바뀌면 Nelper가 스키마를 자동으로 다시 읽고 결과를 알림으로 남깁니다. 알림에는 이전 버전과 새 버전이 함께 표시되며, 재스캔이 실패하면 필수 알림으로 분류해 오래된 정보로 조회되는 상황을 알려 줍니다. 실패 알림을 받으면 연동 화면에서 재스캔을 다시 실행하고 연결 상태를 확인합니다.

이 문서가 도움이 되었나요?