n8n 셀프호스팅 커스텀 가이드: 한글 설정부터 버튼 튜토리얼 UI까지
이 글과 연결된 글 보기
드래그로 이동 · 휠/두 손가락으로 확대 · 방향키로 글 선택 · 0으로 맞춤. 실선: 본문 링크, 점선: 시리즈·주제의 대표 연결.표시된 글 28편 목록
n8n 써보셨다면, 한글 UI가 없어서 불편하셨던 적 있으시죠? 처음에는 워크플로우 개념도 낯선데, Credentials나 Executions 같은 영어 메뉴까지 익혀야 하니까요.
이 진입 장벽을 줄이려고 데이터팝콘 실습 서버에 한국어 UI와 버튼별 튜토리얼을 붙였습니다. 주요 메뉴는 한글로, 누를 버튼은 노란 테두리로. 실제 적용한 화면부터 보여드리겠습니다.

실제 적용 화면입니다. ‘워크플로우 만들기’ 버튼을 강조하고, 옆에서 다음 행동을 안내합니다.
워크플로우·자격 증명·실행 기록 같은 주요 메뉴도 한국어로 표시합니다.
한국어 UI는 비공식 번역 팩으로, 튜토리얼은 별도 안내 스크립트로 구현했습니다. 아래에서는 같은 결과를 만들기 위한 적용 방법과 업데이트 시 주의점을 순서대로 정리합니다.
이 글은 이런 분께 필요합니다
- Docker Compose로 n8n을 직접 운영하는 분
- 교육이나 팀 실습에서 영어 메뉴가 진입 장벽이라고 느낀 분
- 워크플로우와 데이터는 유지하고 화면 언어만 바꾸려는 분
이 글은 이미 동작하는 셀프호스팅 n8n을 전제로 합니다. 서버 설치 자체는 다루지 않습니다. n8n Cloud의 언어 설정 안내도 아닙니다. Cloud에서는 이 글처럼 서버의 편집기 파일을 바꾸지 못합니다.
데이터팝콘 서버에서는 n8n 3.0.0에 적용했고, 2026년 11월 12일 브라우저에서 한국어 주요 메뉴와 설정 메뉴의 언어 전환 항목을 다시 확인했습니다. 다른 버전은 같은 버전 번호로 빌드한 뒤 별도 검증해야 합니다.
먼저 커스텀 범위를 세 가지로 나눕니다
| 방식 | 이 글의 예시 | 필요한 작업 |
|---|---|---|
| 공식 환경설정 | 기본 시간대, 새 워크플로우 이름, 기본 온보딩 팁 표시 여부 | 해당 버전의 문서에서 옵션을 확인하고 설정합니다. |
| 편집기 번역·패치 | 한국어 메뉴와 한국어·영어 전환 | 같은 버전의 편집기를 빌드해 적용합니다. |
| 별도 안내 UI | 이용 안내 버튼, 공지 배너, 수칙 팝업, 버튼별 투어 | 스크립트·문구 피드·Worker를 별도로 구성합니다. |
아래 Step 16은 한국어 UI 적용, Step 79는 버튼 튜토리얼과 안내 UI의 실제 구현 방식입니다. 뒤쪽의 공식 환경설정 목록은 문서 참고용으로 구분했습니다.
Step 1. 공식 언어 설정과 한국어 팩을 구분합니다
n8n 공식 문서는 N8N_DEFAULT_LOCALE을 기본 언어 설정으로 안내합니다. 선택한 언어의 번역이 없으면 영어로 돌아갑니다. 이 설정은 번역기를 실행하거나 한국어 번역 파일을 설치하지 않습니다.
데이터팝콘에서 사용하는 n8n 한국어 팩은 별도의 비공식 프로젝트입니다. 영어 문구의 한국어 번역, 공통 UI 부품 번역, 한국어·영어 전환 메뉴를 추가합니다. 이 팩에서는 브라우저에 저장한 언어를 우선하고, 저장값이 없으면 한국어 브라우저에서 한국어를 선택합니다. 실제 적용 서버의 N8N_DEFAULT_LOCALE은 바꾸지 않았습니다.
번역 대상은 주로 편집기의 메뉴와 안내 문구입니다. 모든 노드의 세부 설정이나 서버 오류 메시지까지 한글로 바뀌지는 않습니다.
Step 2. 실행 중인 버전을 확인하고 백업합니다
기존 Compose 프로젝트 폴더에서 실행합니다. 아래 예시는 서비스 이름이 n8n인 구성입니다. 별도 -f 옵션이나 -p 프로젝트 이름으로 운영한다면 기존 명령의 옵션을 그대로 유지하세요.
docker compose exec n8n n8n --version
출력이 3.0.0이면 한국어 팩도 3.0.0으로 빌드합니다. 이 글의 숫자를 그대로 쓰기보다 실행 중인 서버와 빌드 버전을 일치시키세요. 한국어 적용과 n8n 버전 업그레이드를 한 번에 진행하지 않는 편이 문제를 구분하기 쉽습니다.
작업 전에 데이터베이스와 n8n 데이터 볼륨, Compose 파일, 환경 설정을 백업합니다. 자격 증명 복호화에 필요한 암호화 키도 기존 설정대로 유지하세요. 실제 적용 때도 데이터베이스와 설정을 먼저 백업했습니다. 백업 파일에는 민감한 정보가 들어가므로 공개 저장소에 올리지 않습니다.
Step 3. 같은 버전의 한국어 편집기를 빌드합니다
이 글은 공식 n8n 이미지에 한국어 화면 파일만 읽기 전용으로 마운트하는 방식을 사용합니다. Docker 빌드는 공식 n8n 소스를 받아 번역과 패치를 적용하고 editor-ui를 다시 만듭니다. JSON 파일만 실행 중인 컨테이너에 복사하는 방식과 다릅니다.
기존 Compose 프로젝트 폴더에서 실행합니다. 저장소 README는 빌드용 Docker에 메모리 8GB 이상을 권장합니다. 운영 서버 자원이 빠듯하면 별도 빌드 장비에서 만들고, 생성된 dist 폴더를 운영 서버로 옮깁니다.
V=3.0.0
docker build --target dist \
--build-arg N8N_VERSION="$V" \
--output "type=local,dest=./n8n-ko/$V" \
'https://github.com/team-datapopcorn/n8n-i18n-korean.git#main'
test -f "./n8n-ko/$V/dist/index.html"
마지막 명령이 성공하면 ./n8n-ko/3.0.0/dist/index.html이 존재합니다. 빌드가 실패하거나 이 파일이 없으면 다음 단계로 진행하지 않습니다. 새 버전에서 소스 구조가 바뀌면 패치부터 수정해야 하므로, 버전 번호만 바꾸면 항상 성공한다고 보장하지 않습니다.
공개 저장소의 빌드 검사 성공 이력에서는 편집기 파일 빌드와 Docker 이미지 빌드 검사가 통과했습니다. 이번 글 작성 중 Docker 빌드를 새로 실행하지는 않았습니다. 운영 서버에 적용한 3.0.0 화면과 공개 저장소의 빌드 검사 결과를 구분해 확인했습니다.
Step 4. 기존 Compose에 화면 파일 마운트를 추가합니다
아래는 기존 설정에 추가할 부분입니다. 전체 Compose 파일을 이 내용으로 덮어쓰지 마세요. 기존 데이터 볼륨, 데이터베이스 연결, 환경변수와 네트워크 설정은 유지합니다.
이미 compose.override.yml을 사용한다면 해당 파일의 n8n 서비스 아래에 합칩니다. 파일이 없다면 새로 만듭니다. 다음 예시는 3.0.0 기준입니다.
services:
n8n:
volumes:
- type: bind
source: ./n8n-ko/3.0.0/dist
target: /usr/local/lib/node_modules/n8n/node_modules/n8n-editor-ui/dist
read_only: true
bind:
create_host_path: false
source는 방금 빌드한 폴더이고, target은 컨테이너 내부의 편집기 경로입니다. create_host_path: false는 원본 폴더가 없을 때 빈 디렉터리를 만들어 정상 화면을 가리는 실수를 막습니다. 다른 버전이나 이미지에서는 편집기 경로도 다시 확인해야 합니다.
Compose 구문을 검사하고 n8n 서비스에만 반영합니다. 컨테이너 재생성이 필요하므로 서비스가 잠시 끊깁니다. 진행 중인 실행을 피한 점검 시간에 적용하세요.
docker compose config --quiet
docker compose up -d --no-deps n8n
config --quiet는 구문 검사이지 한국어 동작 검사나 백업 검증이 아닙니다. 일반 docker compose config 출력에는 해석된 환경 설정이 포함될 수 있으므로 공개 게시물에 통째로 붙이지 않습니다. 데이터 볼륨을 지우는 down -v는 사용하지 않습니다.
Step 5. 한국어 화면과 언어 전환을 확인합니다
브라우저를 새로고침하고 워크플로우, 자격 증명, 실행 기록, 데이터 테이블 메뉴를 확인합니다. 영어로 보이면 왼쪽 아래 설정 메뉴를 엽니다. 로그아웃 바로 위의 한국어를 선택하면 한국어로 전환됩니다. 한국어 화면에서는 같은 자리에 English가 표시됩니다.

이 항목은 한국어 팩이 추가한 메뉴이며, 기본 n8n의 공식 언어 선택 메뉴가 아닙니다. 선택값은 사용자 계정이 아니라 해당 사이트의 브라우저 저장소에 남습니다. 다른 브라우저나 다른 서버 주소로 접속하면 언어를 다시 선택해야 할 수 있습니다.
목록 화면만 확인하고 끝내지 마세요. 기존 워크플로우 하나를 열어 편집기가 정상적으로 뜨는지, 자격 증명 목록이 보이는지, 실행 기록을 조회하는지까지 확인합니다. 한국어 UI 적용은 노드 동작이나 자격 증명을 바꾸려는 작업이 아니므로 기존 자동화의 동작도 별도로 점검합니다.
Step 6. 업데이트와 원복 기준을 정합니다
n8n을 업데이트하면 한국어 편집기도 업데이트할 버전과 동일하게 다시 빌드합니다. 새 폴더의 dist/index.html을 확인한 뒤 이미지 태그와 마운트 경로를 맞춥니다. 이전 버전 편집기를 새 백엔드에 그대로 덮어쓰지 않습니다.
화면이 깨지면 이번에 추가한 한국어 dist 마운트 항목만 제거하고 n8n 서비스를 다시 생성합니다. 기존 override 파일에 다른 설정도 있다면 파일 전체를 지우지 마세요. 브라우저도 새로고침해 공식 이미지의 편집기로 돌아왔는지 확인합니다.
번들 파일에는 n8n의 라이선스가 적용됩니다. 공개 저장소는 번역과 패치를 제공하고, 빌드한 편집기나 Docker 이미지를 다운로드 파일로 배포하지 않습니다. 자신의 환경에서 빌드해 적용하는 안내이며, 수정 빌드의 재배포나 상업적 호스팅 허가까지 의미하지 않습니다. 사용 목적에 따른 권리는 n8n 라이선스를 별도로 확인하세요.
Step 7. 이용 안내 버튼과 버튼별 튜토리얼을 추가합니다
한국어 번역과 별개로, 교육용 서버에는 어디를 눌러야 하는지 알려주는 안내 UI를 덧붙였습니다. 데모 서버의 공지 배너, 이용 수칙 팝업, 화면 오른쪽 아래 이용 안내 버튼, 5단계 둘러보기가 여기에 해당합니다. 이 기능들은 n8n 기본 설정을 켠 결과가 아니라 직접 만든 확장입니다.
둘러보기는 첫 실습 템플릿 → 새 워크플로우 만들기 → 자격 증명 → 실행 기록 → 도움말 순서입니다. 현재 단계의 버튼이나 메뉴를 노란 테두리로 강조하고, 옆에 설명 카드와 이전·다음·건너뛰기를 표시합니다. 버튼 이름만 글로 설명하는 대신 실제 클릭 위치를 안내합니다.
화면 파일을 다시 빌드하지 않는 구조
한국어 팩은 편집기를 다시 빌드했지만, 안내 UI는 Cloudflare Worker에서 HTML 응답에 별도 JavaScript를 삽입했습니다. 브라우저가 n8n 화면을 받으면 이 스크립트가 배너·팝업·투어를 그립니다. n8n 본체를 수정하지 않고 안내 코드를 분리한 구조입니다.
구성할 때는 다음 네 부분을 나눕니다.
- 안내 스크립트: 버튼, 팝업, 강조 테두리와 단계 이동을 담당합니다. 데모의
onboarding.js가 이 역할입니다. - 문구 피드: 화면에 넣을 배너·수칙·투어 정보를 JSON으로 제공합니다. 데이터 조회 방법은 다음 Step에서 다룹니다.
- Worker: HTML에 스크립트를 추가하고
/__dp/onboarding.js,/__dp/notices.json요청을 처리합니다. 로그인·가입 화면은 안내 스크립트에서 건너뜁니다. - 검수: 관리자 미리보기로 안내를 열고 메뉴 위치, 언어, 완료 후 다시 열기를 확인합니다.
실제 Worker는 n8n HTML의 기존 CSP nonce를 읽어 삽입하는 스크립트에 붙입니다. CSP를 끄거나 unsafe-inline을 허용하는 방법이 아닙니다. REST API, 정적 파일, 폼, 웹훅, MCP, WebSocket 업그레이드 요청은 화면 변환 대상에서 제외합니다. 모든 응답에 일괄로 스크립트를 붙이면 JSON이나 실습 폼까지 건드리게 됩니다.
이 온보딩 코드는 현재 데이터팝콘 데모에 맞춘 자체 구현입니다. 앞의 한국어 팩 저장소에 포함된 기능이나 docker compose 옵션이 아닙니다. 같은 구성을 만들려면 안내 스크립트·Worker·문구 피드를 별도로 구현해야 합니다.
Step 8. 공지와 튜토리얼 문구는 Data table에서 관리합니다
안내 문구를 JavaScript에 전부 넣으면 공지 한 줄을 바꿀 때도 다시 배포해야 합니다. 데모에서는 n8n Data table dp_onboarding_notices에 문구를 저장하고, 별도 워크플로우가 배너·수칙·투어 목록을 반환합니다.
| 필드 | 역할 |
|---|---|
type | banner는 공지 배너, rule은 이용 수칙, tour는 둘러보기 단계입니다. |
sort | 같은 종류 안에서 표시 순서를 정합니다. |
title, body | 안내 제목과 본문입니다. |
title_en, body_en | 영어 안내에 사용할 문구입니다. |
target | 투어에서 강조할 대상을 가리킵니다. create, credentials, executions, help 등을 씁니다. |
active | 해당 안내를 표시할지 결정합니다. |
연결 순서는 Data table → 공지 피드 워크플로우 → GET 웹훅 → Worker의 JSON 경로 → 안내 스크립트입니다. 실제 공지 피드의 경로는 /webhook/dp-notices, Worker가 브라우저에 제공하는 경로는 /__dp/notices.json입니다. 응답에는 banner, rules, tour 세 목록을 넣고, 스크립트가 각각 배너·팝업·단계별 카드로 표시합니다. 확인한 피드는 배너 1개, 수칙 7개, 투어 5단계였습니다.
문구만 바꿀 때는 표를 수정합니다. Worker 쪽 피드는 60초 동안 캐시하고, 열린 페이지의 스크립트도 데이터를 메모리에 보관하므로 즉시 반영을 기대하지 마세요. 캐시 시간이 지난 뒤 페이지를 새로고침해 확인합니다. 버튼 위치를 찾는 코드나 디자인을 바꾸는 작업은 스크립트 수정·재배포가 필요합니다.
문구 피드는 인증 없이 읽히는 공개 안내입니다. 계정 정보, API 키, 내부 정책이나 비공개 공지를 넣으면 안 됩니다. 수칙 확인 기록 역시 브라우저 저장소에 남기는 UX용 기록이지, 서버에 보관하는 법적 동의나 권한 통제가 아닙니다.
Step 9. 언어·사용자별 노출과 업데이트 후 동작을 검수합니다
데모에서는 수강생에게 안내를 보이고 owner/admin에게는 기본적으로 숨깁니다. 관리자는 ?dp_preview=1로 미리보기를 켜고 ?dp_preview=0으로 끕니다. 이 주소는 데이터팝콘 자체 구현의 옵션이며 기본 n8n의 기능은 아닙니다. 프런트엔드에서 안내를 숨기는 처리는 권한 보호를 대신하지 않습니다.
수칙을 확인하거나 투어를 마치면 사용자 ID별 브라우저 저장소에 기록합니다. 수칙 문구가 바뀌면 다시 확인하도록 만들었습니다. 다른 브라우저나 저장소 초기화 후에는 다시 보일 수 있으므로, 이를 서버가 기억하는 최초 로그인 여부와 동일하게 취급하지 않습니다.
상단 배너를 닫은 뒤에는 목록 화면 오른쪽 아래에 이용 안내 버튼이 나타납니다. 이 버튼으로 수칙을 다시 열고 둘러보기를 재실행합니다. 안내 UI의 한국어·영어 선택도 별도로 구현했으며, 현재는 n8n 본체의 n8n-ui-locale과 안내의 dp_lang이 따로 저장됩니다. 본체 언어를 바꿨다고 안내 언어까지 자동 동기화된다고 가정하지 마세요.
이번 검수에서 특히 확인한 항목은 한국어 화면에서도 강조할 버튼을 찾는가였습니다. Credentials라는 영문만 찾으면 자격 증명 화면에서 테두리가 사라집니다. 실제 배포 스크립트에는 영어와 한국어 메뉴명을 모두 찾는 처리가 추가됐고, 자격 증명·실행 기록·도움말 단계의 강조 테두리를 다시 확인했습니다.
n8n을 업데이트한 뒤에는 다음 항목을 함께 점검합니다.
- 한국어·영어에서 각 투어 대상 버튼과 강조 위치가 맞는지
- 화면 전환 후에도 안내가 중복으로 쌓이지 않는지
- 작은 화면에서 설명 카드가 화면 밖으로 밀리지 않는지
- 다크 모드에서도 흰 카드의 제목과 버튼 글자가 읽히는지
- 로그인·폼·웹훅·실제 워크플로우 실행에 간섭하지 않는지
안내 스크립트는 편집기와 분리했지만 n8n의 DOM 구조와 메뉴 이름에는 의존합니다. 본체 업데이트 때 재빌드가 필요 없다는 뜻이지, 이후 버전에서도 무조건 동작한다는 뜻은 아닙니다. 장애 시에는 안내 UI를 주입하는 계층만 이전 버전으로 되돌리거나 우회하고, 한국어 팩 문제와 분리해서 확인합니다.
참고: 코드 수정 없이 바꾸는 공식 설정도 있습니다
직접 UI를 개발하기 전에 환경변수로 해결되는 항목부터 확인하세요. 공식 문서에는 다음 설정도 안내됩니다. 아래는 문서로 확인한 설정 목록이며, 이번 글 작성 중 서버 값을 바꾸거나 동작을 새로 시험하지는 않았습니다.
| 설정 | 변경 대상 |
|---|---|
GENERIC_TIMEZONE | 인스턴스의 기본 시간대입니다. 예약 실행 시각과 관계됩니다. |
WORKFLOWS_DEFAULT_NAME | 새 워크플로우의 기본 이름입니다. |
N8N_WORKFLOW_TAGS_DISABLED | 워크플로우 태그 기능의 사용 여부입니다. |
N8N_ONBOARDING_FLOW_DISABLED | 새 워크플로우를 만들 때 기본 온보딩 팁을 숨길지 정합니다. 자체 튜토리얼을 생성하는 옵션은 아닙니다. |
환경변수 설정, 한국어 편집기 빌드, 별도 안내 UI는 서로 다른 변경입니다. 로고 교체·화이트라벨링·상업적 제공도 기술적으로 수정한다는 이유만으로 허용되는 것은 아니므로 제품별 기능과 라이선스를 먼저 확인하세요.
자주 막히는 곳
| 증상 | 먼저 확인할 내용 |
|---|---|
N8N_DEFAULT_LOCALE=ko를 넣었는데 영어입니다 | 환경변수가 한국어 팩을 설치하지는 않습니다. 번역을 포함한 편집기 빌드 적용 여부를 확인합니다. |
한국어 또는 English 메뉴가 없습니다 | 기본 편집기나 오래된 파일이 제공되는지, Compose 마운트가 실제로 반영됐는지 확인합니다. |
| 적용 후 빈 화면이 나옵니다 | source에 dist/index.html이 있는지, 서버와 편집기 버전이 같은지 확인합니다. 해결 전에는 마운트를 제거해 원복합니다. |
| 일부 메뉴나 날짜가 영어로 남습니다 | 이 팩의 번역 범위 밖인 문구가 있습니다. Add new item, Open command palette, November 같은 잔여 영어를 실제 화면에서 확인했습니다. |
| 노드 세부 설정이 영어입니다 | 노드·자격 증명의 개별 번역은 기본 메뉴 번역과 별도 영역입니다. 전체 한글화를 기대하면 안 됩니다. |
| 투어 카드만 뜨고 버튼 강조가 사라집니다 | UI 언어와 n8n 버전이 바뀌며 대상 선택자가 달라졌는지 확인합니다. 영어·한국어 대상 탐색을 함께 검수합니다. |
| 공지를 고쳤는데 예전 문구가 나옵니다 | Worker의 60초 캐시와 페이지 메모리 캐시를 구분합니다. 시간이 지난 뒤 새로고침합니다. |
| 관리자에게 안내가 안 보입니다 | 데모에서는 의도적으로 숨깁니다. 자체 미리보기 옵션으로 검수하며, 모든 n8n의 기본 동작으로 보지 않습니다. |
| n8n Cloud에서 적용하려고 합니다 | 이 방식은 서버의 파일 교체 권한이 있는 셀프호스팅용입니다. Cloud에는 적용하지 않습니다. |
확인 범위와 참고 자료
2026년 11월 12일 기준으로 3.0.0 서버의 한국어 목록 메뉴와 설정 메뉴를 직접 확인했습니다. 데모 서버에서는 관리자 미리보기로 수칙 팝업, 5단계 둘러보기, 새 워크플로우 만들기 버튼과 주요 메뉴 강조, 배너를 닫은 뒤의 이용 안내 버튼을 확인했습니다. 검수 뒤 브라우저의 미리보기·확인 기록은 원상복구했습니다. 새 수강생 계정을 생성해 전체 가입 절차를 시험한 결과는 아닙니다. 11월 4일 적용 기록에서는 한국어·영어 전환과 워크플로우 편집기 열기를 확인했습니다. 새 버전으로 자동 업데이트한 뒤 한국어 팩까지 이어지는 전 과정은 검증하지 않았습니다. 번역 키 검사 통과나 CI 빌드 성공을 모든 화면의 번역 품질 보증으로 해석하지 않습니다.
