노드 유형 정책으로 노드 사용 가능 여부 제어
n8n v2.47요약
노드 유형 정책은 인스턴스 전체 또는 특정 프로젝트에서 사용자가 사용할 수 있는 노드를 결정하는 규칙입니다. 노드 유형 정책은 프리뷰 상태이며 향후 릴리즈에서 변경될 수 있습니다. 노드 유형 정책은 다음 플랜에서 사용할 수 있습니다.
노드 유형 정책은 인스턴스 전체 또는 특정 프로젝트에서 사용자가 사용할 수 있는 노드를 결정하는 규칙입니다.
프리뷰 상태
노드 유형 정책은 프리뷰 상태이며 향후 릴리즈에서 변경될 수 있습니다. 프로덕션 환경에서는 의존하지 않는 것이 좋습니다.
기능 사용 가능 여부
노드 유형 정책은 다음 플랜에서 사용할 수 있습니다.
- n8n Cloud: Enterprise
- 셀프 호스팅: Enterprise
노드 유형 정책은 n8n 2.45.0부터 사용할 수 있습니다.
인스턴스 소유자 또는 관리자가 인스턴스 정책을 설정합니다. 이후 프로젝트 관리자는 자신의 프로젝트를 더 제한할 수 있습니다. 정책은 n8n public API로 관리합니다.
노드 유형 정책의 작동 방식#
정책은 규칙 목록과 기본 동작(default action)으로 구성됩니다.
각 규칙에는 다음 항목이 있습니다.
id: 정책 내에서 고유한 규칙 이름입니다. 규칙이 노드를 차단하면 n8n이 이 ID를 알려 줍니다.action:allow,deny,delegate중 하나입니다.delegate는 인스턴스 정책에서만 사용할 수 있습니다.selector: 규칙이 일치시키는 노드입니다.
selector는 두 가지 방식 중 하나로 노드를 일치시킵니다.
| Selector | 일치 대상 | 예시 |
|---|---|---|
{ "kind": "name", "value": "<node-type>" } |
정확한 이름으로 지정한 노드 유형 하나입니다. | n8n-nodes-base.executeCommand |
{ "kind": "package", "value": "<package-name>" } |
패키지에 포함된 모든 노드입니다. | n8n-nodes-base, @n8n/n8n-nodes-langchain |
n8n은 규칙을 순서대로 확인하고 처음 일치하는 규칙을 사용합니다. 일치하는 규칙이 없으면 정책의 defaultAction을 사용합니다.
노드의 유형 이름을 찾으려면 캔버스에서 노드를 선택해 복사합니다. 텍스트 편집기에 붙여넣고 type 필드를 확인합니다.
name 규칙은 해당 노드의 도구(tool) 버전도 함께 일치시킵니다. 예를 들어 n8n-nodes-base.gmail에 대한 규칙은 AI 에이전트가 사용하는 Gmail Tool도 차단합니다.
인스턴스 정책과 프로젝트 정책이 결합되는 방식#
n8n은 인스턴스 정책을 먼저 평가한 다음 프로젝트 정책을 평가합니다.
| 인스턴스 판정 | 결과 |
|---|---|
deny |
노드가 차단됩니다. 프로젝트에서 다시 허용할 수 없습니다. |
allow |
프로젝트 정책이 결정합니다. 프로젝트는 더 제한하기만 할 수 있습니다. |
delegate |
프로젝트에 해당 노드에 대한 명시적 allow 규칙이 없으면 노드가 차단됩니다. 프로젝트의 defaultAction은 고려되지 않습니다. |
기본적으로 차단하되 프로젝트 관리자가 자신의 프로젝트에서 켤 수 있게 하려는 노드에는 delegate를 사용합니다. delegate는 인스턴스 정책에서만 사용할 수 있습니다.
정책이 없으면 모든 노드를 사용할 수 있습니다.
노드를 설치된 상태로 유지하면서 프로젝트별로 차단하려면 정책을 사용합니다. 셀프 호스팅 인스턴스에서 인스턴스 전체에서 노드를 제거하려면 NODES_EXCLUDE를 사용합니다.
API로 정책 설정#
인증 및 권한#
X-N8N-API-KEY 헤더로 API 키를 보냅니다. 키에는 nodeTypePolicy:manage 스코프가 필요합니다. API 키 생성을 참고합니다.
| 엔드포인트 | 호출할 수 있는 사용자 |
|---|---|
GET 및 PUT /api/v1/node-type-policies/instance |
인스턴스 소유자 및 관리자 |
GET 및 PUT /api/v1/node-type-policies/projects/<project-id> |
인스턴스 소유자 및 관리자, 해당 프로젝트의 관리자 |
프로젝트 ID를 찾으려면 n8n에서 프로젝트를 엽니다. ID는 URL에서 /projects/ 뒤에 오는 부분입니다.
정책 읽기, 변경, 쓰기#
모든 정책에는 version이 있습니다. PUT 요청은 마지막으로 읽은 버전을 보내야 합니다. 이렇게 하면 두 관리자가 서로의 변경 사항을 덮어쓰는 일을 막을 수 있습니다.
정책을 변경하려면 다음을 따릅니다.
- 인스턴스 또는 프로젝트에 대해
GET으로 현재 정책을 읽습니다. rules또는defaultAction을 변경합니다.- 인스턴스 또는 프로젝트에 대해
PUT으로 동일한version과 함께 전체 정책을 다시 보냅니다.
설정된 적 없는 정책은 version: 0을 반환하므로 첫 PUT에서는 0을 보냅니다. 읽은 이후 다른 사람이 정책을 변경했다면 n8n은 409 Conflict를 반환합니다. 정책을 다시 읽고 재시도합니다.
해당 스코프에 연결된 정책이 둘 이상이거나 스코프의 정책이 다른 스코프와 공유되는 경우에도 PUT은 409 Conflict를 반환합니다. 이 경우 공유 정책 또는 스코프의 연결(attachment)을 대신 업데이트합니다. 여러 스코프에서 정책 하나 공유를 참고합니다.
PUT은 정책의 모든 규칙을 대체합니다. 규칙 하나를 추가하려면 기존 규칙과 새 규칙을 함께 보냅니다.
예시: 인스턴스 전체에서 노드 차단#
이 인스턴스 정책은 Execute Command 노드를 차단하고, 프로젝트 관리자가 자신의 프로젝트에서 SSH 노드를 켤 수 있게 합니다. 현재 version과 함께 PUT /node-type-policies/instance로 보냅니다.
{
"version": 0,
"defaultAction": "allow",
"rules": [
{
"id": "block-execute-command",
"action": "deny",
"selector": { "kind": "name", "value": "n8n-nodes-base.executeCommand" }
},
{
"id": "ssh-on-request",
"action": "delegate",
"selector": { "kind": "name", "value": "n8n-nodes-base.ssh" }
}
]
}
응답은 저장된 정책과 새 version을 반환합니다. 앞선 규칙이 이미 포함하는 규칙을 나열한 warnings가 함께 포함될 수도 있습니다. n8n은 해당 규칙에 도달하지 않습니다. 변경 사항은 약 1초 안에 적용됩니다.
예시: 한 프로젝트에서 위임된 노드 켜기#
위 인스턴스 정책은 SSH 노드를 위임합니다. 이 프로젝트 정책은 한 프로젝트에서 해당 노드를 켭니다. 현재 version과 함께 PUT /node-type-policies/projects/<project-id>로 보냅니다.
{
"version": 0,
"defaultAction": "allow",
"rules": [
{
"id": "allow-ssh",
"action": "allow",
"selector": { "kind": "name", "value": "n8n-nodes-base.ssh" }
}
]
}
allow 규칙은 필수입니다. 프로젝트의 defaultAction: allow는 위임된 노드를 켜지 않습니다.
여러 스코프에서 정책 하나 공유#
/node-type-policies/policies 및 /node-type-policies/scopes/<scope-id>/attachments 엔드포인트를 사용하면 인스턴스 관리자가 하나의 규칙 집합을 둘 이상의 프로젝트에서 재사용할 수 있습니다. 대부분의 구성에서는 필요하지 않습니다. attachments 엔드포인트에 GET을 보내면 연결된 정책과 PUT에 필요한 version을 반환합니다. 자세한 내용은 엔드포인트 레퍼런스를 참고합니다.
에디터에서 노드가 차단되었을 때 사용자에게 보이는 화면#
프로젝트에서 노드가 차단되면 해당 프로젝트의 사용자에게 다음과 같이 표시됩니다.
- 노드 패널: 차단된 노드는 탐색할 때 나타나지 않습니다. 검색에서는 목록 끝에 잠금 표시와 함께 나타납니다. 사용자는 이 노드를 추가할 수 없습니다.
- 캔버스: 워크플로에 이미 있는 차단된 노드에는 제한됨(restricted) 라벨이 표시됩니다.
- 노드 세부 정보: 파라미터가 읽기 전용입니다. 사용자는 인스턴스 관리자에게 문의하거나 노드를 교체할 수 있습니다.
- 게시 및 실행: n8n이 해당 작업을 거부하고 차단된 각 노드를 나열한 메시지를 표시하며, 워크플로에서 노드를 찾을 수 있는 링크를 제공합니다. 저장으로 차단된 노드가 추가되는 경우에도 n8n은 같은 방식으로 저장을 거부합니다.
에이전트에서 노드가 차단되었을 때 사용자에게 보이는 화면#
- 도구 선택기: 차단된 노드는 목록 끝에 잠금 표시와 함께 나타납니다. 사용자는 이 노드를 추가할 수 없습니다. Chat Hub 도구도 같은 방식으로 작동합니다.
- 채팅: n8n이 차단된 도구에 대한 호출을 거부하고 해당 단계를 제한됨으로 표시합니다. 에이전트는 수행하지 못한 작업을 사용자에게 알려 줍니다.
- 저장 및 게시: n8n은 차단된 도구를 추가하는 에이전트의 저장을 거부하고, 차단된 도구를 사용하는 에이전트의 게시를 거부합니다.
- AI 빌더: Agent Builder가 차단된 노드를 제안할 수 있습니다. 그러면 n8n이 저장을 거부합니다. Limited enterprise readiness 상태인 n8n Assistant에도 같은 내용이 적용됩니다.
이미 차단된 노드를 사용하는 워크플로#
새 정책은 기존 워크플로를 변경하지 않지만, 사용자가 해당 워크플로로 할 수 있는 작업을 제한합니다.
| 작업 | 결과 |
|---|---|
| 열기 및 편집 | 허용됩니다. |
| 저장 | 저장으로 새 차단 노드 유형이 추가되지 않는 한 허용됩니다. |
| 게시 | 거부됩니다. |
| 트리거 또는 서브 워크플로로 실행하는 경우를 포함한 실행 | 거부됩니다. n8n은 해당 실행을 실패한 실행으로 기록합니다. |
| 다른 프로젝트로 이동 | 대상 프로젝트의 정책에 따라 확인됩니다. |
게시된 워크플로는 게시된 상태로 유지되지만, 노드를 허용하거나 워크플로에서 제거할 때까지 해당 실행은 실패합니다.
비활성화된 노드도 포함됩니다. 사용자는 차단된 노드를 비활성화된 상태로 추가한 뒤 나중에 켤 수 없습니다.
제한 사항#
- 아직 설정 페이지 없음: 정책은 public API로만 관리할 수 있습니다. 설정 페이지는 계획되어 있습니다.
- 와일드카드 없음:
name규칙은 정확히 하나의 노드 유형과 일치합니다. 여러 노드를 일치시키려면package규칙을 사용합니다. package규칙에는 설치된 패키지 필요: n8n은 설치되지 않은 패키지에 대한package규칙을 거부합니다.name규칙에는 이 제한이 없으므로 아무도 설치하기 전에 커뮤니티 노드를 차단할 수 있습니다.- 예외 노드 없음: 정책이 기본적으로 거부하면 Manual Trigger, Sticky Note 같은 노드도 차단합니다. 사용자에게 필요한 모든 노드에
allow규칙을 추가합니다. - 데이터 경계 아님: 노드를 차단해도 그 뒤의 서비스는 차단되지 않습니다. 사용자는 HTTP Request 노드 또는 Code 노드로 동일한 API에 계속 접근할 수 있습니다. 셀프 호스팅 인스턴스에서 n8n이 노드를 아예 로드하지 않게 하려면
NODES_EXCLUDE를 사용합니다. - 소스 컨트롤 풀: n8n은 차단된 노드를 사용하는 풀된 워크플로를 건너뛰고 풀 결과에 보고합니다. 노드를 허용하거나 제거할 때까지 Git의 워크플로와 n8n의 워크플로는 서로 다른 상태로 유지됩니다.
- 노드 파라미터 안의 서브 워크플로: n8n은 다른 노드의 파라미터 안에 정의된 서브 워크플로의 노드를 확인하지 않습니다.