먼저 결론부터 말하면, VUE_APP_URL_BASE_API는 기본 n8n Docker 이미지에 환경 변수 한 줄을 추가해 적용하는 설정이 아닙니다. 프런트엔드 패키지인 n8n-editor-ui를 직접 빌드할 때, 그 프런트엔드가 접속할 백엔드 REST API의 기준 URL을 넣는 빌드 설정입니다.
따라서 기본 Docker 이미지를 그대로 쓰는 운영이라면 이 변수를 해결책으로 선택하면 안 됩니다. 공식 문서상 기본 이미지에서는 값이 /로 고정되어 루트 도메인을 사용합니다.
30초 판단: 내 환경에서 쓸 수 있나
| 운영 방식 | VUE_APP_URL_BASE_API | 판단 |
|---|---|---|
| 기본 n8n Docker 이미지 | 사용 불가 | 이 변수를 넣어도 분리 설정이 적용되지 않음 |
| n8n-editor-ui 직접 빌드 | 사용 가능 | 빌드 전에 백엔드 REST API 기준 URL 지정 |
근거: n8n 공식 문서 — Configure the Base URL
설정 위치와 적용 시점
이 값은 프런트엔드가 백엔드 REST API를 어디에서 찾을지 정합니다. 예시는 다음과 같습니다.
export VUE_APP_URL_BASE_API=https://n8n-api.example.com/
# 그다음 n8n-editor-ui를 빌드하고 결과물을 배포핵심은 순서입니다. 실행 중인 기본 컨테이너에 나중에 변수를 추가하는 방식이 아니라, UI 빌드 전에 값을 정하고 빌드 결과물을 다시 배포해야 합니다. 프런트엔드 주소와 백엔드 REST API 주소를 서로 다르게 운영할 때만 이 복잡성을 감수할 이유가 있습니다.
이름이 비슷한 URL 변수와 혼동하지 말 것
N8N_EDITOR_BASE_URL은 사용자가 에디터에 접속하는 공개 URL입니다. n8n이 보내는 이메일과 SAML 리디렉션 URL에도 사용됩니다. 반면 VUE_APP_URL_BASE_API는 직접 빌드한 프런트엔드가 백엔드 REST API에 접속할 경로입니다. 두 변수는 대체 관계가 아닙니다.
웹훅 공개 주소는 또 별도입니다. 리버스 프록시 뒤에서 운영한다면 현재 공식 문서는 N8N_WEBHOOK_URL을 사용하도록 안내합니다. WEBHOOK_URL은 n8n 2.35.0부터 사용 중단 예정 별칭이며, 프록시가 한 단계라면 N8N_PROXY_HOPS=1과 X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto 전달도 함께 확인해야 합니다.
| 변수 | 결정하는 것 | 적용 위치 |
|---|---|---|
VUE_APP_URL_BASE_API |
프런트엔드가 접속할 백엔드 REST API 기준 URL | n8n-editor-ui 수동 빌드 |
N8N_EDITOR_BASE_URL |
사용자가 접속할 공개 에디터 URL | n8n 서버 배포 설정 |
N8N_WEBHOOK_URL |
외부에 등록·표시할 테스트/운영 웹훅 기준 URL | 리버스 프록시 뒤 서버 설정 |
N8N_PROXY_HOPS |
신뢰할 리버스 프록시 단계 수 | n8n 서버 배포 설정 |
추가 근거: Deployment 환경 변수 · Endpoints 환경 변수 · 리버스 프록시 웹훅 설정
배포 전 확인 체크리스트
- 정말 프런트엔드와 백엔드를 서로 다른 주소에서 제공해야 하는지 확인합니다.
- 기본 Docker 이미지가 아니라
n8n-editor-ui를 직접 빌드하는 배포인지 확인합니다. VUE_APP_URL_BASE_API에 브라우저에서 접근 가능한 백엔드 REST API 기준 URL을 넣습니다.- 에디터 공개 URL이 별도라면
N8N_EDITOR_BASE_URL을 따로 설정합니다. - 리버스 프록시 뒤의 웹훅이라면
N8N_WEBHOOK_URL, 프록시 홉 수, 전달 헤더를 별도로 검증합니다.
확인일: 2026-10-01