서버 모드Postgres + 중앙 인증
다중 팀 지원, JWKS를 통해 JWT 인증. 웹앱은 인증 서버의 정보를 기준으로 토큰을 오프라인에서 검증합니다. /api/auth/.well-known/jwks.json.
Docker 빠른 시작 가이드
공식 이미지 arnaudprioul/i18n-dashboard두 가지 모두에 대해 Docker Hub에 배포됩니다 linux/amd64그리고 linux/arm64. 팀 규모에 따라 세 가지 방식으로 진행할 수 있습니다.
로컬 모드SQLite, 인증 없음
단일 사용자, 단일 팀. 번역 데이터는 Docker 볼륨에 저장됩니다. 최대 약 10만 개의 키를 자체 호스팅하는 데 가장 적합합니다. 이 파일을 다음 위치에 저장하세요. docker-compose.yml그리고 실행 docker compose up -d:
기본적으로
127.0.0.1에만 바인딩됩니다. 이 머신에서만 접근할 수 있으며 네트워크상의 다른 기기에서는 접근할 수 없습니다. 로컬 모드에는 로그인 화면이 없으므로, 포트에 접근할 수 있는 사람은 누구나 모든 프로젝트에 완전히 접근할 수 있습니다 — 신뢰할 수 있는 방화벽이나 VPN 뒤에서만 이 바인딩을 확장하세요.자세한 퀵스타트 가이드, 환경 변수 및 문제 해결 방법은 Docker Hub 개요.
데스크톱 모드타우리, 지역 데이터
Nitro 서버와 SQLite가 내장된 macOS/Windows/Linux 전용 빌드입니다. Docker도, 별도로 설정해야 할 데이터베이스도 필요 없습니다. 로그인은 온라인 계정을 통해 이루어집니다.
- macOS
- Windows
- 리눅스
하려는 작업으로 찾기
8개 그룹: 시작하기, 프레임워크 가이드, 배포, 관리, 품질, 참조, 결제, 지원.
시작하기
프레임워크 가이드
배포
행정
품질 및 협업
참고 문헌
청구 및 요금
지원
환경 변수
모든 runtimeConfig이 값은 런타임에 다음을 통해 재정의할 수 있습니다. NUXT_*접두사 — Nitro의 표준 규칙. 다음과 같은 단순 이름은 I18N_DB_HOST와이어 프로토콜 변수로 명시적으로 나열되지 않는 한 묵시적으로 무시됩니다.
전체 인용 정보 (모든 변수, 기본값, 범위 및 마이그레이션 참고 사항)은 Docker Hub 페이지에 게시되어 해당 이미지와 함께 확인할 수 있습니다:
Docker Hub에서 전체 환경 변수 참조를 열어보세요 →가장 흔히 볼 수 있는 손잡이
I18N_APP_MODE—local/server/desktop. 서버 모드를 사용하려면 실제 데이터베이스와 중앙 인증 시스템이 필요합니다.NUXT_DB_CLIENT+NUXT_DB_HOST+NUXT_DB_NAME+NUXT_DB_USER+NUXT_DB_PASSWORD— Postgres / SQLite / MySQL 연결.NUXT_SESSION_SECRET— 프로덕션 환경에서 필수입니다. 다음을 사용하여 생성하십시오.openssl rand -hex 32.NUXT_CENTRAL_AUTH_URL+NUXT_PUBLIC_CENTRAL_AUTH_URL— 인증 발급자의 서버 측 및 브라우저 측 URL(JWKS와 호환되어야 함).NUXT_AUTH_JWT_ISSUER+NUXT_AUTH_JWT_AUDIENCE— 예상된iss/aud액세스 토큰에 대한 청구권.NUXT_INTERNAL_API_SECRET— 웹 애플리케이션과 중앙 인증 서버 간의 호출에 사용되는 공유 HMAC. 양측에서 동일해야 합니다.NUXT_SMTP_HOST+NUXT_SMTP_PORT+NUXT_SMTP_USER+NUXT_SMTP_PASS+NUXT_SMTP_FROM— 워크플로 알림. 이메일 알림을 비활성화하려면 ‘호스트’ 필드를 비워 두십시오.NUXT_DASHBOARD_URL— 이 웹앱 인스턴스의 공개 URL로, 거래 관련 이메일 링크에 사용됩니다.
30초 만에 SMTP 설정하기
임의의 SMTP 중계 서버를 선택하고 아래 네 가지 값을 입력하세요. 그러면 모든 워크플로 이벤트 발생 시 해당 서버를 통해 이메일이 전송됩니다.
로컬 개발 및 스모크 테스트를 위해서는 번들로 제공된 파일을 지정하십시오. 메일핏서비스: NUXT_SMTP_HOST=mailpit, NUXT_SMTP_PORT=1025.
역할과 권한
역할은 인스턴스 전체가 아니라 프로젝트별로 부여됩니다 — 세 단계가 있으며, 각 단계는 해당 프로젝트에서 허용되는 범위를 넓혀줍니다.
translator | moderator | admin | super_admin | |
|---|---|---|---|---|
| 번역 수정 | 가능 | 가능 | 가능 | 가능 |
| 번역 승인 | 불가 | 가능 | 가능 | 가능 |
| 프로젝트 관리(설정, 스캔, 동기화) | 불가 | 불가 | 가능 | 가능 |
| 프로젝트 멤버 관리 | 불가 | 불가 | 가능 | 가능 |
프로젝트의 Users 페이지에서 역할을 지정하세요 — 멤버를 선택한 뒤 translator, moderator, admin 중 하나를 고릅니다. 한 프로젝트의 admin은 다른 프로젝트에도, 그 프로젝트를 소유한 계정에도 아무런 권한이 없습니다.
super_admin 플래그
super_admin은 어떤 프로젝트 역할과도 별개입니다 — 위의 모든 검사를 모든 프로젝트에서 무시하는 계정 수준의 플래그입니다. 로컬 설치 마법사를 통해서든 서버 모드에서의 첫 로그인을 통해서든, 인스턴스에서 처음 생성된 계정에 자동으로 부여되며, 현재 대시보드 내에서 다른 계정을 super_admin으로 승격시킬 방법은 없습니다.
웹훅
Admin → Integrations(super_admin 전용)에서 프로젝트별로 설정합니다. 구독한 이벤트가 해당 프로젝트에서 발생할 때마다 웹훅이 엔드포인트로 전송됩니다.
이벤트
웹훅은 다음 이벤트 중 하나 이상을 구독할 수 있습니다.
key.deleted— 번역 키가 하나 이상 삭제됨translation.saved— 번역 값이 저장됨scan.completed— 새로 추가되거나 변경된 키에 대한 소스 코드 스캔이 완료됨sync.completed— 설정된 번역 제공업체와의 동기화가 완료됨
전달 검증하기
일반 HTTP 엔드포인트로의 모든 전달에는 X-Webhook-Signature(웹훅 생성 시 한 번만 표시되는 시크릿을 사용한 JSON 본문의 HMAC-SHA256)와 X-Webhook-Event가 포함됩니다. Slack과 Discord URL은 자동으로 감지되어 각 플랫폼 고유의 메시지 형식으로 대신 전송됩니다. 이 두 가지는 URL 자체로 인증하므로 서명 헤더를 전혀 포함하지 않습니다.
발신 URL 요구 사항
- 공인 주소로 해석되어야 합니다 — loopback, private(RFC1918/unique-local), link-local 대상은 URL을 저장할 때와 전달을 시도할 때마다(각 리다이렉트 홉 포함) 모두 거부됩니다. 이는 호스트 이름이 두 시점 사이에 다르게 해석되는 허점을 막기 위한 것입니다.
- 프로덕션 환경에서는 엔드포인트가
https:를 사용해야 합니다 — 순수 HTTP는 프로덕션 환경 밖에서만 허용됩니다. - URL에 포함된 자격 증명(
https://user:pass@host)은 거부됩니다. - 전달은 10초 후 시간 초과되며, 최대 5회의 리다이렉트를 따릅니다.
웹훅 옆의 ▶ 버튼을 사용하면 실제 이벤트를 기다리지 않고도 서명된 ping 이벤트를 즉시 보낼 수 있습니다.
백업과 복원
super_admin 전용이며, Admin → Backup 또는 CLI에서 실행합니다. 백업은 모든 프로젝트, 번역, 사용자, 설정을 포괄하는 단일 JSON 내보내기입니다.
항상 제외되는 항목: refresh_tokens, password_reset_tokens, otp_tokens, webhook_deliveries, 그리고 각 계정의 비밀번호 해시.
대시보드에서
"Download backup"을 누르면 날짜가 포함된 JSON 파일(예: i18n-dashboard-backup-2026-07-31.json)이 저장됩니다.
복원은 해당 파일을 다시 업로드하고 모드를 선택하는 방식으로 진행됩니다.
- merge(기본값)는 기존 행을 유지하고 없는 항목만 삽입합니다
- replace는 각 테이블의 기존 데이터를 먼저 삭제한 뒤 가져옵니다 — 되돌릴 수 없습니다
결과에는 복원된 행 수, 건너뛴 중복 항목, 실패한 행이 표시됩니다. 부분적으로 복원되었는데도 조용히 성공으로 보고하지 않습니다.
CLI에서
두 명령 모두 상위 권한의 관리자 토큰이 필요합니다 — NUXT_CLI_ADMIN_TOKEN(대체 값은 NUXT_CLI_TOKEN) — --token로 전달하거나 CLI 설정에서 확인합니다.
문제 해결
셀프 호스팅 사용자가 가장 자주 겪는 문제들로, Docker 이미지 자체의 문제 해결 가이드에서 그대로 가져왔습니다.
Refusing to start: NUXT_DB_HOST is still the build-time default 'localhost'— 환경 변수가 아직 NUXT_* 접두사 이전 이름을 사용하고 있습니다. 데이터베이스 환경 변수(NUXT_DB_HOST, NUXT_DB_USER 등)에 NUXT_ 접두사를 추가하세요.Webapp returns 401 on every API call— JWKS 엔드포인트에 접근할 수 없습니다. 동일한 compose에서 두 서비스가 함께 실행 중이라면 Docker 네트워크 호스트 이름을 사용해 NUXT_CENTRAL_AUTH_URL이 컨테이너 내부에서 해석되는지 확인하세요.JWT verification fails right after a key rotation— JWKS 캐시는 1시간 동안 유지되며, 키 ID 불일치 후 30초 뒤에 갱신됩니다. 짧은 유예 기간을 두거나, 키 교체 직후 웹앱을 재시작하세요.Health check shows "0 keys" despite a non-empty database— 잘못된 데이터베이스에 연결되어 있을 가능성이 높습니다. 남아 있는 SQLite 파일로 대체되지 않고 NUXT_DB_HOST가 실제로 설정되어 있는지 확인하세요.Container starts on port 3000 instead of 6001— Nitro는 PORT를 직접 읽습니다. 이미지는 I18N_PORT=6001을 설정하지만, PORT를 재정의하면 바인딩 위치가 바뀝니다 — ports: 매핑과 일치시키세요.Can't reach the dashboard from another machine— 기본 Compose 설정에서는 예상된 동작입니다 — 포트가 의도적으로 127.0.0.1에 바인딩되어 있습니다. 의도적으로 노출하려면 라우팅 가능한 주소에 바인딩하거나 앞단에 리버스 프록시를 두세요.