암호화 키 교체를 사용하면 인스턴스의 마스터 암호화 키를 변경하지 않고도, 자격 증명, OAuth 토큰 및 기타 민감한 콘텐츠와 같은 n8n 데이터를 암호화하는 키를 주기적으로 교체할 수 있습니다.

암호화 키 교체 동작 방식#

n8n은 2계층 키 모델을 사용합니다:

• 인스턴스 암호화 키 (N8N_ENCRYPTION_KEY): 배포 시 설정되는 마스터 키입니다. 이 키는 변경되지 않습니다. n8n은 데이터 암호화 키를 보호하는 용도로만 이 키를 사용합니다.
• 데이터 암호화 키: 자격 증명 데이터를 직접 암호화하는 키입니다. 교체 대상이 되는 키입니다. n8n은 이 키를 인스턴스 키로 암호화하여 데이터베이스에 저장합니다.

교체가 이루어지면 n8n은 새 데이터 암호화 키를 생성하고 이후의 모든 쓰기에 사용합니다. 이전 키로 암호화된 기존 데이터는 계속 읽을 수 있습니다. n8n은 각 레코드를 다음에 업데이트할 때 자동으로 새 키로 재암호화합니다.

시작하기 전에#

또한 다음 사항을 확인해야 합니다:

• 모든 n8n 인스턴스(메인 및 모든 워커)가 동일한 N8N_ENCRYPTION_KEY 값을 공유해야 합니다.
• 환경 변수와 n8n 데이터베이스를 직접 제어할 수 있어야 합니다. 이는 셀프 호스팅 배포에서만 가능합니다.

암호화 키 교체 활성화#

1. 모든 n8n 인스턴스(메인 및 워커 모두)에 다음 환경 변수를 설정합니다:

   N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true
   

2. 모든 인스턴스를 재시작합니다. 시작 시 n8n은 자동으로 초기 데이터 암호화 키를 생성하고 암호화하여 데이터베이스에 저장합니다.

3. 기능이 활성화되었는지 확인하려면 Settings > Data Encryption Keys로 이동합니다. 활성 키가 목록에 표시되어야 합니다.

활성 키 교체#

기능이 활성화된 후에는 언제든지 새 데이터 암호화 키로 교체할 수 있습니다.

UI 사용#

Settings > Data Encryption Keys로 이동하여 Rotate key를 선택합니다.

API 사용#

/encryption/keys 엔드포인트에 POST 요청을 보냅니다. 해당 요청에는 encryptionKey:manage 글로벌 스코프가 필요합니다. n8n은 API 응답에서 키 자체를 반환하지 않으며, ID, 알고리즘, 상태, 타임스탬프와 같은 메타데이터만 반환합니다.

교체 후 n8n은 모든 새 쓰기에 새 활성 키를 사용합니다. 이전 키로 암호화된 레코드는 계속 읽을 수 있습니다. n8n은 각 레코드를 다음에 업데이트할 때 새 키로 재암호화합니다.

하위 호환성 및 롤백#

암호화 키 교체를 활성화하면 n8n은 키 식별자가 포함된 새 형식으로 자격 증명 및 기타 민감한 데이터를 작성하기 시작합니다. 이전 버전의 n8n과 기능 플래그 없이 실행 중인 인스턴스는 이 형식을 읽을 수 없습니다.

• 기능 플래그를 비활성화하지 마세요. 새 형식으로 데이터가 작성된 후 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION을 제거하거나 false로 설정하면 기능을 활성화한 이후에 암호화된 모든 데이터에 영구적으로 접근할 수 없게 됩니다.
• 활성화 후 n8n 버전을 다운그레이드하지 마세요. 이전 버전은 새 형식을 복호화할 수 없습니다.

새 형식으로 암호화된 데이터를 레거시 형식으로 변환하는 자동화된 도구는 없습니다. 유일한 복구 경로는 기능을 활성화하기 전에 만든 데이터베이스 백업에서 복원하는 것입니다.

권장 단계#

1. 데이터베이스를 백업하세요. 변경하기 전에 전체 스냅샷을 찍으세요.
2. 먼저 스테이징 환경에서 활성화하세요. 프로덕션이 아닌 환경에서 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true를 설정하고 재시작한 후 자격 증명이 여전히 올바르게 복호화되는지 확인하세요.
3. 프로덕션에서 활성화하세요. 스테이징 동작을 검증한 후에만 이 작업을 수행하세요.
4. 비활성화하거나 다운그레이드하지 마세요. 프로덕션 데이터가 새 형식으로 작성된 후에는 플래그를 활성화 상태로 유지하고 동일하거나 더 새로운 n8n 버전을 유지하세요.

관련 리소스#

• 사용자 지정 암호화 키 설정: 인스턴스 수준의 N8N_ENCRYPTION_KEY 값을 설정합니다.
• 배포 환경 변수: N8N_ENCRYPTION_KEY 및 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION에 대한 참조입니다.
• 큐 모드 구성: 모든 워커가 동일한 인스턴스 암호화 키를 공유하도록 합니다.