문제 해결

이 페이지에는 셀프 호스팅 Nodaro에서 가장 흔한 문제가 각각의 증상과 해결 방법과 함께 정리되어 있습니다. 대부분의 문제를 한눈에 보여 주는 /setup 페이지부터 시작하세요.

/setup에서 시작

셀프 호스팅 설치는 http://<your-host>/setup에서 실시간 상태 화면을 제공합니다. 로그인이 필요 없으며, 각 구성 요소가 있고 작동하는지만 보여 주고 시크릿은 절대 보여 주지 않습니다.

• 데이터베이스, Redis, 스토리지, 암호화 키, 공급자 키의 카드가 초록색이나 빨간색으로 표시됩니다. 데이터베이스 카드에는 마이그레이션 누락 상태가 따로 있습니다.
• 실패한 카드마다 확인할 변수를 알려 주는 힌트가 있습니다.
• 실시간 업데이트: 페이지가 5초마다 다시 확인합니다.

페이지에 API에 연결할 수 없음이 표시되면 웹 서버는 실행 중이지만 API가 응답하지 않는 것입니다. docker compose -f docker-compose.community.yml logs -f로 컨테이너 로그를 읽고, 포트 3000을 막는 것이 없는지 확인하세요.

설치가 시작되지 않음

시작할 때 Missing or invalid env vars가 나타납니다. 메시지에 검증에 실패한 변수가 나열됩니다. 흔한 원인은 비어 있는 SUPABASE_SERVICE_ROLE_KEY와 32자보다 짧은 INTERNAL_ORCHESTRATOR_SECRET입니다.

docker compose up에서 port is already allocated가 나타납니다. 스택이 공개하는 호스트 포트는 두 개뿐입니다. 앱용 3000과 루프백에만 바인딩되는 MinIO 콘솔용 9001입니다. Redis와 데이터베이스는 호스트 포트를 쓰지 않습니다. docker-compose.community.yml에서 충돌하는 매핑의 호스트 쪽 포트를 바꾸세요. 예: "3001:3000". 앱 포트를 바꿨다면 PUBLIC_URL도 그에 맞게 설정하세요.

부팅할 때 마이그레이션이 실패했습니다. 앱 로그에 정확한 파일 이름이 나옵니다. API는 마이그레이션이 중간에 멈춘 데이터베이스로는 시작하지 않습니다. 원인을 해결하고 docker compose -f docker-compose.community.yml up을 다시 실행하세요. 이미 적용된 파일은 건너뜁니다.

로그인 로그에 password authentication failed for user "supabase_auth_admin"이 나타납니다. db-data 볼륨이 데이터베이스의 역할 설정보다 오래되었거나, 처음 시작한 뒤 POSTGRES_PASSWORD를 바꾼 경우입니다. 역할 비밀번호는 처음 시작할 때만 POSTGRES_PASSWORD를 따릅니다. docker compose -f docker-compose.community.yml down -v로 볼륨을 삭제하거나(데이터가 삭제됩니다), supabase_admin으로 역할 비밀번호를 직접 바꾸세요.

Docker 빌드에서 ffmpeg 아카이브를 내려받거나 검증하지 못합니다. 이미지를 직접 빌드할 때만 해당합니다. ffmpeg 버전에 따라 렌더링된 오디오와 동영상이 달라지므로, Dockerfile은 ARG FFMPEG_TARBALL_URL_*와 ARG FFMPEG_TARBALL_SHA256_*로 아키텍처마다 정확한 정적 ffmpeg 빌드를 고정합니다. 다운로드에 실패하거나 체크섬이 맞지 않으면 출력 결과를 조용히 바꾸는 대신 빌드를 멈춥니다. 고정된 빌드는 GitHub의 nodaroai/ffmpeg-static 릴리스입니다. 업스트림 ffmpeg에 스케줄러 수정 하나를 더해 소스에서 빌드한 것이며, 소스와 라이선스가 함께 공개되어 있습니다. 공개된 릴리스를 고르고, 두 아키텍처 모두의 URL과 SHA-256을 둘 다 업데이트하세요. 실제 ffmpeg 업그레이드로 취급하고, 이후 렌더링된 출력을 확인하세요.

이미지에는 /usr/local/share/doc/ffmpeg-static/에 ffmpeg 바이너리의 라이선스가 들어 있습니다. LICENSE, SOURCE, LINK-TRACE.txt, 그리고 정적으로 링크된 각 라이브러리의 라이선스 텍스트가 담긴 LICENSES/ 폴더입니다. ffmpeg 바이너리는 GPL-3.0-or-later이며, 소스는 같은 릴리스의 에셋으로 공개되어 있습니다.

브라우저 오류

편집기가 렌더링되지만 빈 화면으로 남거나 “불러오는 중…”이 계속 표시됩니다. 브라우저 콘솔을 여세요.

• CORS 오류: 다음 항목을 참조하세요.
• 로그인 오류: 내 설치의 /config.js를 여세요. 브라우저가 접근할 수 있는 Supabase URL(번들된 스택에서는 PUBLIC_URL/supabase)과 anon 키가 들어 있어야 합니다. 컨테이너는 부팅할 때 PUBLIC_URL, FRONTEND_SUPABASE_URL, SUPABASE_ANON_KEY로 이 파일을 씁니다. 이 값들을 고치고 재시작하세요.

브라우저에 CORS 오류가 나타납니다. http://localhost:3000과 PUBLIC_URL은 항상 허용되므로, LAN 주소나 다른 포트 같은 다른 출처에서 앱을 연 것입니다. PUBLIC_URL을 그 출처로 설정하거나, CORS_ORIGIN에 추가 출처를 쉼표로 구분해 나열하세요. 예: CORS_ORIGIN=http://192.168.1.20:3000. 그런 다음 docker compose -f docker-compose.community.yml up -d를 실행하세요.

NodarCut에서 편집, 또는 앱의 동영상 결과에서 편집을 누르면 편집기 대신 패널이 표시됩니다. 호스팅된 동영상 편집기는 http://localhost:3000에서만 임베딩을 허용합니다. 다른 출처에서는 직접 편집기를 실행하고 FREECUT_URL을 설정하세요. 동영상 및 오디오 편집기를 참조하세요.

오디오 결과에서 편집을 눌러도 아무 일도 일어나지 않거나, 편집기 대신 패널이 표시됩니다. 호스팅된 오디오 편집기는 없습니다. 직접 AudioMass를 실행하고 AUDIOMASS_URL을 설정하세요.

데이터베이스

마이그레이션이 “relation … does not exist”로 실패합니다. 마이그레이션이 순서에 맞지 않게 실행되었습니다. supabase/migrations/의 파일을 파일 이름 순서대로 적용하세요. 예를 들어 Supabase SQL 편집기에서 적용할 수 있습니다. 각 파일은 이미 적용된 데이터베이스에서 다시 실행해도 됩니다.

OAuth 콜백이 500을 반환합니다. 마이그레이션 하나가 적용되지 않아서 OAuth 앱용 테이블이 없습니다. 모든 마이그레이션을 파일 이름 순서대로 적용하세요. 데이터베이스를 참조하세요.

API가 계속 재시작됩니다. Postgres에 연결할 수 없습니다. 데이터베이스가 내려가 있는 동안에는 정상입니다. Postgres가 돌아오면 docker compose -f docker-compose.community.yml restart nodaro를 실행하세요.

스토리지

번들된 스택에서 업로드가 실패합니다. http://localhost:9001에서 MinIO 콘솔을 여세요. 기본 자격 증명은 Compose 파일에 있습니다.

Cloudflare R2로의 업로드가 401 또는 403으로 응답합니다. API 토큰에 버킷에 대한 Object Read & Write 권한이 있는지 확인하세요. R2 앞에 커스텀 도메인을 두었다면 버킷의 공개 접근 설정도 확인하세요. Nodaro는 브라우저에 공개 미디어 URL을 주므로, 인증 없이 읽을 수 있어야 합니다.

모든 스토리지 요청이 인증 오류나 엔드포인트 오류로 실패합니다. R2_REGION을 스토리지의 리전으로 설정하세요. AWS, DigitalOcean Spaces, 로컬 Supabase는 기본값 auto를 거부하며, 그 오류에는 리전이 언급되지 않습니다.

STORAGE_OBJECT_ACL을 설정한 뒤 모든 업로드가 실패합니다. 스토리지 키에 객체 ACL을 설정할 권한이 없습니다. 스토리지가 버킷 정책을 거부하는 경우가 아니라면 이 변수를 비워 두세요.

R2를 쓸 때 부팅 로그에 [storage] failed to create bucket이 나타납니다. 무해합니다. R2 토큰은 버킷을 만들 수 없고, 내 버킷은 이미 있기 때문입니다.

실행과 노드

워크플로가 대기열에 들어가지만 시작되지 않습니다. docker compose -f docker-compose.community.yml logs nodaro로 로그를 읽으세요. 오케스트레이터는 Redis에서 작업을 가져오므로, Redis에 연결할 수 없으면 아무것도 실행되지 않습니다. REDIS_URL을 확인하고 docker compose -f docker-compose.community.yml exec redis redis-cli ping을 실행하세요. PONG으로 응답해야 합니다.

노드가 Missing API key로 실패합니다. 노드가 키가 없는 공급자를 호출하고 있습니다. /setup이나 .env에 키를 추가하세요. 공급자 키를 참조하세요.

이미지와 동영상은 작동하지만 모든 텍스트 기능이 실패합니다. KIE_API_BASE_URL이 미디어 경로만 전달하는 프록시를 가리키고 있습니다. 내 프록시로 공급자 트래픽 보내기를 참조하세요.

키를 붙여 넣거나 Nodaro Cloud에 연결할 때 EncryptionKeyMissingError로 실패합니다. 설치에 암호화 키가 없습니다. 관리형 Supabase 프로젝트를 쓴다면 NODARO_ENCRYPTION_KEY를 openssl rand -hex 32로 만든 64자 16진수 값으로 설정하세요.

복원 후 공급자 키가 누락됨으로 표시됩니다. 데이터베이스가 짝이 맞는 암호화 키 없이 복원되었습니다. 백업과 복원을 참조하세요.

노드가 503 nodaro_connection_required로 실패합니다. Nodaro Cloud 연결이 필요한 Nodaro 전용 노드입니다. Nodaro Cloud에 연결을 참조하세요.

Cloud 실행이 Token expired로 실패합니다. 연결의 90일짜리 토큰이 만료되었습니다. 연결 해제를 클릭한 다음 연결을 클릭하세요.

Cloud 실행이 402 instance_cap_reached로 실패합니다. 설치가 월간 지출 한도에 도달했습니다. app.nodaro.ai의 결제 › 연결된 인스턴스에서 한도를 올리세요.

정상인 실행이 Execution orphaned로 표시됩니다. 두 설치가 데이터베이스 하나를 공유하면서 서로 다른 Redis를 쓰고 있습니다. 설치마다 고유한 RUNTIME_ENV를 지정하세요. 확장을 참조하세요.

3D 렌더링 Pro가 503 SCENE_CAPABILITY_UNAVAILABLE로 응답합니다. 3D 렌더링 Pro는 호스팅된 빌드 서비스에서 실행되며, 셀프 호스팅 에디션에는 포함되지 않습니다. 다른 렌더러로 조용히 대체되는 일은 없습니다. 내 서버에서 실행되는 3D 장면 생성과 동영상 렌더링을 쓰세요.

로그인과 MCP

SSO 경로가 404 unknown_provider로 응답합니다. 구성된 공급자가 없습니다. EXTERNAL_SSO_PROVIDERS를 확인하고, Compose 스택에서는 nodaro 서비스의 environment: 아래에 추가하세요. 싱글 사인온을 참조하세요.

모든 API 호출이 403 sso_required로 응답합니다. 서피스 프로필이 SSO만 허용하는데, 계정이 SSO를 통해 만들어지거나 연결되지 않았습니다. 로그인 방법을 참조하세요.

MCP 클라이언트가 405 wrong_mcp_host를 받습니다. 클라이언트가 앱의 기본 주소를 쓰고 있습니다. 대신 MCP 호스트의 주소를 지정하세요. MCP를 참조하세요.

업데이트

버전 레이블에 내장 버전만 표시되고 릴리스 노트가 비어 있습니다. 업데이트 확인이 GitHub를 읽지 못합니다. 로그 줄 [update-check] … read failed: HTTP 403 (rate limit: 0 of 60 left…)은 내 외부 주소가 GitHub의 익명 할당량을 모두 썼다는 뜻입니다. NODARO_UPDATE_CHECK_TOKEN을 설정하세요. 업데이트를 참조하세요.

도움 받기

그래도 해결되지 않으면 앱 컨테이너의 Docker 로그와 함께 GitHub에 이슈를 여세요.