Nelper 도움말 상담 신청
문서 버전
주제 선택
가이드 02 / 20

n8n 인스턴스 설정

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

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

연동 화면 열기

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

인스턴스 추가

  1. 오른쪽 위 인스턴스 추가를 선택합니다.
  2. 인스턴스 이름을 입력합니다. 예: Production n8n
  3. n8n URL을 입력합니다. n8n 웹 UI 주소이며 리소스 맵과 감사로그의 원본 바로가기에 사용됩니다.
  4. 필수인 PostgreSQL 연결을 입력합니다.
    • 개별 입력: Host, Port(기본 5432), Username, Password, Database
    • URL 입력: postgresql://readonly_user:****@host:5432/n8n
  5. 선택 사항인 Metrics URL을 입력합니다. n8n에 N8N_METRICS=true가 필요합니다.
  6. 선택 사항인 n8n API Key를 입력합니다. Error Workflow, 노드 정책 자동 조치 등 REST API 기능에 사용하며 나중에 등록할 수 있습니다.
  7. 연결 테스트를 실행합니다.
  8. 성공 결과에서 확인된 테이블, 실행 기록과 n8n 버전을 검토한 뒤 추가를 선택합니다.
인스턴스 추가
DB·Metrics·API 연결을 입력하고 테스트하는 인스턴스 추가 패널
최소 권한 원칙 PostgreSQL은 읽기 전용 계정을 강력히 권장합니다. 신규 인스턴스는 연결 테스트를 통과해야 추가할 수 있습니다. 편집 시 DB 연결 정보가 바뀌면 다시 테스트해야 합니다.

인스턴스 카드와 상태

상태의미와 조치
연결됨DB 스캔이 완료되어 분석에 사용할 수 있습니다.
스캔 중스키마와 자산을 수집 중입니다. 완료될 때까지 기다립니다.
연결 실패네트워크, 인증, DB 이름과 방화벽을 확인합니다.
경고일부 선택 연동이나 이벤트 수신에 문제가 있는지 메시지를 확인합니다.
  • 재스캔: n8n 스키마와 리소스를 다시 읽습니다.
  • 편집: URL, DB, Metrics와 연결 옵션을 수정합니다.
  • 삭제: 확인 창을 거쳐 Nelper의 인스턴스 등록을 제거합니다.
  • 마지막 스캔, 마지막 이벤트 수신과 오류 메시지를 카드에서 확인합니다.

n8n API Key 등록과 검증

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

  1. Nelper에서 인스턴스 편집을 열고 Log Stream Webhook URL을 복사합니다.
  2. n8n의 Settings → Log Streaming으로 이동합니다.
  3. Add new destination에서 Webhook destination을 만들고 URL을 등록합니다.
  4. 워크플로 이벤트와 필요한 이벤트 그룹을 활성화합니다.
  5. n8n 감사로그를 사용하려면 Audit 이벤트 구독을 반드시 켭니다.
  6. Nelper 카드의 마지막 이벤트 수신 시각이 갱신되는지 확인합니다.
n8n Log Streaming
활성 Webhook destination을 관리하는 n8n Log Streaming 화면
등록 전에는 “이벤트 수신 대기 중” 안내가 표시됩니다. Audit 구독을 켠 이후의 이벤트만 수집되며, 구독 시작 전 감사 이벤트는 자동 소급되지 않습니다.

이벤트와 메트릭 모니터링

  • 메트릭 요약: n8n/Node 버전, 업타임, Heap, Event Loop p99, RSS 메모리와 수집 상태
  • 이벤트 통계: 일·주·월·년 기간의 수신 추세
  • 최근 이벤트: 최근 10건과 전체 이벤트 보기

이벤트 로그에서는 1시간·6시간·24시간·7일·30일 또는 직접 기간을 지정하고 이벤트명을 필터링합니다. 행을 선택해 원본 JSON payload를 확인하며 10·50·100건 페이지 크기를 선택합니다.

인스턴스 이벤트 로그
기간과 이벤트명으로 필터링하고 원본 JSON을 확인하는 이벤트 로그
Metrics의 기본 지표가 보이지 않으면 n8n에 N8N_METRICS_INCLUDE_DEFAULT_METRICS=true가 적용됐는지 확인합니다.

AI Workflow Addon 연결

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

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