프로젝트 그룹·네이밍·외부 API
프로젝트 그룹을 만들고 네이밍 규칙을 점검·예약하며 위반 요약 이메일과 외부 API로 조직 분류를 동기화합니다.
프로젝트 그룹과 네이밍 규칙은 n8n 자산을 조직 기준으로 분류하고 점검하는 Owner/Admin용 거버넌스 기능입니다. 프로젝트 그룹은 집계 기준을 제공하고, 네이밍 규칙은 워크플로·크리덴셜 이름을 검사합니다. 외부 API를 사용하면 조직도나 운영 시스템에서 그룹 구성을 동기화할 수 있습니다.
프로젝트 그룹 만들기
- 사이드바 아래의 계정 설정을 열고 워크스페이스 → 프로젝트 그룹을 선택합니다.
- 상단에서 관리할 n8n 인스턴스를 선택합니다. 그룹은 인스턴스마다 따로 관리됩니다.
- 그룹 트리 위 입력란에 최상위 그룹 이름을 쓰고 추가를 선택하거나 Enter를 누릅니다.
- 트리에서 그룹을 선택한 뒤 이름·상위 그룹을 바꾸고 포함할 프로젝트를 여러 개 선택해 한 번에 저장합니다.
- 선택한 그룹의 하위 그룹 추가 동작으로 조직 계층을 만듭니다. 계층은 최대 4단입니다.
- 한 프로젝트는 한 그룹에만 들어가며, 다른 그룹에 할당하면 자동으로 이동합니다.
- 그룹 삭제 확인에서 하위 그룹과 할당 프로젝트 수를 검토합니다. 삭제하면 Nelper의 하위 그룹과 배정이 함께 정리되지만 n8n 프로젝트 자체는 삭제되지 않습니다.
- 프로젝트 목록을 읽지 못하면 연결 상태를 경고하며 미할당 프로젝트를 모두 배정된 것처럼 표시하지 않습니다.
- 인스턴스를 바꾸거나 트리를 새로 불러오는 동안에는 이전 상태로 그룹을 만들지 않도록 입력과 추가 동작이 잠시 비활성화됩니다.
n8n 원본과의 관계
프로젝트 그룹은 Nelper 안의 조직 분류입니다. 그룹을 만들거나 프로젝트를 옮겨도 n8n의 프로젝트, 폴더와 워크플로 이름·위치는 바뀌지 않습니다.
튜토리얼로 따라 해 보기
화면 상단의 튜토리얼을 선택하면 단계별 안내가 시작됩니다. 안내는 설명만 하는 것이 아니라 실제 화면을 따라가며 필요한 버튼과 입력란을 차례로 짚어 줍니다.
- 각 단계에서 지금 봐야 할 영역을 강조 표시하고, 왜 그 값을 정하는지 함께 설명합니다.
- 입력이 필요한 단계에서는 예시 값을 미리 채워 둡니다. 저장하기 전에는 아무것도 실제로 등록되지 않습니다.
- 진행 표시줄로 남은 단계를 확인하고, 이전으로 되돌아가거나 닫기로 언제든 중단할 수 있습니다.
그룹별 사용량 확인
- 리소스 맵 → Token Usage → 그룹별: 토큰과 추정 비용을 그룹 계층으로 확인합니다.
- 설정 → 비용·사용량 → n8n → 프로젝트별 분석 → 그룹별: 과금 실행과 배분 비용을 그룹별로 확인합니다.
- 상위 그룹 값에는 모든 하위 그룹 값이 합산됩니다.
- 그룹 미지정은 아직 그룹에 넣지 않은 프로젝트, 프로젝트 미확인은 원본 소속을 확인하지 못한 데이터를 뜻합니다.
외부 API 키 발급
- 설정 → API 키를 엽니다.
- 연동을 식별할 이름과 선택 만료일을 입력합니다.
- 프로젝트 그룹 조회 또는 프로젝트 그룹 수정 권한을 선택합니다. 수정 권한에는 조회 권한이 포함됩니다.
- 발급을 선택하고 한 번만 표시되는 키 원문을 즉시 안전한 비밀 저장소에 보관합니다.
- API 사용 가이드에서 빠른 시작, 요청·응답 예시와 7개 엔드포인트를 확인합니다.
| 권한 | 가능한 작업 |
|---|---|
| 프로젝트 그룹 조회 | 인스턴스 목록, 그룹 트리와 프로젝트 할당 현황 조회 |
| 프로젝트 그룹 수정 | 그룹 생성·이름/위치 변경·삭제, 프로젝트 전체 교체·할당 해제 |
제공 엔드포인트
| 메서드·경로 | 동작 | 필요 권한 |
|---|---|---|
GET /api/ext/v1/instances | 호출 가능한 인스턴스 ID·이름 조회 | 조회 |
GET /instances/{instanceId}/project-groups | 그룹 트리·전체 프로젝트·미할당 프로젝트 조회 | 조회 |
POST /instances/{instanceId}/project-groups | 그룹 생성과 선택 프로젝트 초기 배정 | 수정 |
PATCH /instances/{instanceId}/project-groups/{groupId} | 이름·상위·순서·프로젝트 소속 변경 | 수정 |
DELETE /instances/{instanceId}/project-groups/{groupId} | 그룹 트리와 Nelper 배정 삭제 | 수정 |
PUT /instances/{instanceId}/project-groups/{groupId}/projects | 그룹의 프로젝트 목록 전체 교체 | 수정 |
POST /instances/{instanceId}/project-groups/unassign | 프로젝트 그룹 배정 해제 | 수정 |
첫 경로를 제외한 표의 경로 앞에도 /api/ext/v1을 붙입니다.
키 원문은 발급 직후에만 표시됩니다. 문서·채팅·소스 코드에 직접 넣지 말고 환경 변수나 비밀
저장소를 사용하세요. 키를 잃어버렸거나 노출이 의심되면 즉시 폐기하고 새 키를 발급합니다.
네이밍 규칙 만들기
- 사이드바에서 정책 관리를 펼치고 네이밍 규칙을 엽니다.
- 상단에서 점검할 n8n 인스턴스를 선택하고 규칙 추가를 선택합니다.
- 규칙 이름과 자산 유형을 워크플로 또는 크리덴셜로 정합니다.
- 적용 범위를 인스턴스 전체, 개인 프로젝트 전체, 하나 이상의 프로젝트 또는 워크플로 폴더로 지정합니다.
- 구분자를
_,-,.중에서 선택합니다. - 프로젝트 그룹 1~4단계, 기존 이름, 지정값, 허용값, 임의 문자열 또는 정규식 구성요소를 원하는 순서로 놓습니다.
- 필요하면 같은 이름 중복 검사를 켜고 규칙을 저장합니다.
같은 자산에는 가장 구체적인 규칙 하나가 적용됩니다. 폴더는 가장 가까운 조상부터, 그다음
프로젝트, 마지막으로 인스턴스 전체 규칙 순서입니다. 기존 이름 구성요소는 한 번만 마지막에 둘 수 있습니다.
자동 이름 변경이 가능한 규칙
지정값, 프로젝트 그룹 값처럼 목표 이름을 하나로 결정할 수 있는 규칙만 제안 이름을 만듭니다. 복수 허용값, 임의 문자열이나 정규식이 포함되면 시스템이 값을 임의로 고르지 않고 점검·확인 요청 용도로만 사용합니다. 이름 변경에는 AI가 사용되지 않습니다.
수동 점검과 예약 점검
- 규칙을 하나 이상 저장한 뒤 지금 점검을 선택합니다.
- 워크플로·크리덴셜과 인스턴스·프로젝트·폴더 범위를 선택합니다.
- 결과에서 정상, 위반, 설정 필요와 규칙 미적용 안내를 확인합니다.
- 행을 열어 현재 이름, 적용 규칙, 구성요소별 실제값·요구조건과 자산 이력을 확인합니다.
- 점검 설정에서 일/주/월 일정, 기준 시간대와 점검 범위를 저장합니다.
- 위반 결과 요약 이메일 사용을 켜면 예약 점검에서 위반이 있을 때 관리자용 요약 한 통을 보냅니다. 수신 이메일은 최대 20명까지 추가하고, 비워 두면 활성 Owner/Admin 전체에게 보냅니다. 수동 점검에는 보내지 않으며, 자산 담당자에게 보내는 확인 요청과는 별개입니다.
- 점검이 끝나면 네이밍 규칙 점검 완료 토스트가 표시되고 결과 보기로 결과 화면에 이동합니다. 예약 점검의 완료·위반은 거버넌스 알림으로도 남습니다.
예약 점검은 결과·이력과 관리자 알림(완료 토스트, 위반 요약 이메일)만 만듭니다. 이메일 확인 요청이나
n8n 이름 변경을 자동 실행하지 않습니다.
운영자가 최신 결과를 검토하고 대상과 수신자·제안 이름을 확인한 뒤 직접 실행해야 합니다.
확인 요청과 이름 변경
- 위반 자산을 선택해 기본 수신자를 확인하고, 필요하면 추가 수신자 또는 제외 수신자를 편집한 뒤 확인 요청을 보냅니다.
- 결정 가능한 제안 이름이 있는 자산만 선택해 현재 이름과 변경 이름을 검토한 뒤 n8n 이름을 변경합니다.
- 점검 뒤 이름·소속·규칙·중복 상대가 바뀌었다면 조치를 중단하고 재점검을 요구합니다.
- 워크플로 내용과 연결은 보존하고 이름만 바꾸며, 크리덴셜 비밀값은 읽거나 전송하지 않습니다.
- 규칙 저장, 수동 점검, 확인 요청, 이름 변경과 외부 API의 그룹 변경은 Nelper 감사로그에 남습니다.
문제 해결
- 프로젝트 그룹 메뉴나 네이밍 규칙이 보이지 않습니다.
- Owner/Admin 등급과 현재 라이선스의 프로젝트 그룹·리소스 네이밍 기능 포함 여부를 확인합니다.
- 그룹별 값이 전체 값과 다릅니다.
- 그룹 미지정과 프로젝트 미확인 행을 확인합니다. 권한이 제한된 사용자는 n8n에서 허용된 프로젝트만 집계하므로 제외 프로젝트 안내도 함께 봅니다.
- 이름 변경 버튼을 사용할 수 없습니다.
- 복수 허용값·임의 문자열·정규식이 포함된 규칙은 목표 이름을 하나로 정할 수 없습니다. 지정값 또는 프로젝트 그룹 값처럼 결정 가능한 구성으로 바꾸거나 확인 요청만 사용합니다.
- 점검 뒤 바로 조치했는데 재점검 안내가 나옵니다.
- 그 사이 자산 이름·소속·규칙·그룹 경로나 중복 이름 집합이 바뀌었습니다. 최신 상태로 다시 점검한 뒤 조치합니다.
이 문서가 도움이 되었나요?