문제 해결

브라우저, 프런트엔드, 백엔드, Ollama, 제공자 플러그인, 배포 네트워크 중 실패하는 계층부터 확인하세요.

빠른 확인

# App branch and local changes
git status

# Backend process liveness
curl http://localhost:3001/health/live

# Backend dependency readiness (SQLite, schema, and writable data storage)
curl http://localhost:3001/health/ready

# Ollama health
curl http://localhost:11434/api/tags

# Installed Ollama models
ollama list

개발 환경에서 프런트엔드는 보통 http://localhost:5173, 백엔드는 http://localhost:3001에서 실행됩니다. 패키지 npx libre-webui 흐름은 http://localhost:8080에서 앱을 제공합니다.

Libre WebUI가 시작되지 않음

Node 및 종속성 확인

node --version
npm install
npm run dev

Node.js 22.22 이상이 필요합니다.

포트가 이미 사용 중

lsof -i :3001
lsof -i :5173
lsof -i :8080

이전 프로세스를 중지하거나 다른 포트를 설정하세요.

백엔드에서 데이터를 쓸 수 없음

백엔드는 DATA_DIR가 설정되면 해당 위치에, 아니면 backend/data에 데이터를 저장합니다. 소스 실행은 상대 DATA_DIR를 셸 현재 디렉터리가 아닌 백엔드 디렉터리에서 해석합니다. 따라서 DATA_DIR=./data는 backend/data를, 기존에 지원한 DATA_DIR=./backend/data는 backend/backend/data를 선택합니다. 선택 디렉터리에 쓰기 권한이 있는지 확인하세요. DATA_DIR 미설정 시 기존 디렉터리가 유일한 스토리지라면 Libre가 보존합니다. 두 위치 모두 데이터가 있으면 Libre를 중지하고 둘 다 백업한 뒤 의도적으로 선택 또는 마이그레이션하세요. Libre는 서로 다른 데이터베이스를 병합하거나 복사하지 않습니다.

상태 엔드포인트는 실행 중인 프로세스와 사용 가능한 애플리케이션을 의도적으로 구분합니다.

• /health와 /health/live는 백엔드 프로세스가 HTTP를 제공할 수 있으면 200을 반환합니다. 선택적 모델 제공자는 생존 여부에 영향을 주지 않습니다.
• /health/ready는 필수 데이터베이스, 스키마, 스토리지 또는 등록 플랫폼 종속성을 사용할 수 없을 때 503을 반환합니다. 선택적 모델 제공자를 기다리지 않으며 공개 응답에서 오류 메시지와 내부 세부 정보를 생략합니다.
• /health/deep은 제한된 워커에서 SQLite 무결성 및 외래 키 검사를 수행하고 Ollama 같은 선택적 서버 수준 제공자 검사를 모읍니다. 선택적 제공자 중단은 경고이며 필수 종속성을 준비되지 않은 상태로 만들지 않습니다. 현재 관리자 Bearer 토큰이 필요하고 빈번한 오케스트레이터 검사에는 적합하지 않습니다.

curl -H "Authorization: Bearer $LIBRE_ADMIN_TOKEN" \
  http://localhost:3001/health/deep

브라우저에서 백엔드에 연결할 수 없음

로컬 개발에서 프런트엔드는 VITE_API_BASE_URL이 있으면 사용하고, 없으면 개발 백엔드로 대체합니다.

프런트엔드 .env 예:

VITE_API_BASE_URL=http://localhost:3001/api
VITE_WS_BASE_URL=ws://localhost:3001

VITE_WS_BASE_URL은 선택 사항이지만 설정하면 Chat 및 Work 터미널 소켓의 공통 기본값입니다. 절대 ws: 또는 wss: URL을 사용하세요. wss://example.com/libre 같은 경로 접두사도 지원합니다. 자격 증명, 쿼리 매개변수, fragment는 포함하지 마세요. Vite 변수를 바꾼 후 프런트엔드를 다시 시작하거나 빌드합니다.

백엔드 .env 예:

CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173

휴대전화, LAN, Tailscale 접근에서는 휴대전화 브라우저에 localhost를 사용하지 마세요. 노트북의 LAN 또는 Tailscale IP를 사용하고 호스트 바인딩으로 개발 서버를 실행합니다.

npm run dev:host

이렇게 하면 프런트엔드가 포트 8080에서 제공되고, API 및 WebSocket 트래픽이 포트 3001의 로컬 백엔드로 프록시됩니다. 다른 기기에서는 포트 8080만 접근 가능하면 됩니다. frontend/.env에 VITE_API_BASE_URL 또는 VITE_WS_BASE_URL이 설정되어 있다면, 해당 URL이 다른 기기에서 접근 가능한지 확인하거나 개발 서버 프록시를 사용하도록 제거하세요.

리버스 프록시 뒤에서 채팅이 스트리밍되지 않음

일반적인 증상은 메시지는 보내지지만 응답이 표시되지 않고 브라우저 콘솔에 WebSocket 연결 실패가 나타나는 것입니다. 프록시가 WebSocket 업그레이드를 허용하고 장기 연결을 닫지 않는지 확인하세요.

둘 중 하나를 설정하면 Origin 헤더를 보내는 브라우저 업그레이드를 CORS_ORIGIN 및 BASE_URL과 비교합니다. 원격 배포에서는 하나 이상을 설정하세요. 둘 다 없으면 로컬 개발을 위해 Origin 필터가 허용적입니다. Electron 및 기타 비브라우저 클라이언트는 Origin을 생략할 수 있지만, 먼저 Authorization 헤더를 짧게 유효한 1회용 티켓으로 교환해야 합니다. HTTP API와 같은 TLS 및 네트워크 또는 리버스 프록시 접근 제어 뒤에 백엔드를 두세요.

공개 호스트 이름에서는 Libre WebUI 서비스에 해당 브라우저 출처를 허용합니다.

services:
  libre-webui:
    environment:
      CORS_ORIGIN: https://chat.example.com
      BASE_URL: https://chat.example.com

아래 nginx 및 Caddy 예제는 프록시가 Docker 호스트에서 실행되고 저장소 Compose가 Libre WebUI를 포트 8080에 공개한다고 가정합니다. 프록시가 Compose 네트워크에 참여하면 업스트림 주소로 libre-webui:3001을 사용하세요.

nginx

nginx는 업그레이드 헤더를 명시적으로 전달해야 합니다. 긴 읽기 타임아웃은 모델이 작업하는 동안 유휴 채팅 연결을 유지합니다.

location /ws {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

nginx -t로 설정을 검증한 뒤 nginx를 다시 불러옵니다.

Caddy

Caddy의 reverse_proxy는 WebSocket을 기본 지원하므로 업그레이드 헤더가 필요하지 않습니다.

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

Traefik도 WebSocket 업그레이드를 기본 처리합니다. Docker 제공자가 Libre WebUI 네트워크를 공유하면 다음과 같은 일반 라우터 및 서비스 라벨만 필요합니다.

labels:
  - 'traefik.enable=true'
  - 'traefik.http.routers.libre-webui.rule=Host(`chat.example.com`)'
  - 'traefik.http.routers.libre-webui.entrypoints=websecure'
  - 'traefik.http.routers.libre-webui.tls=true'
  - 'traefik.http.services.libre-webui.loadbalancer.server.port=3001'

스트림이 연결되지만 나중에 끊어지면 Traefik 앞의 프록시 또는 로드 밸런서 유휴 타임아웃을 확인하세요. Traefik 자체에서 제한하면 엔트리 포인트의 transport.respondingTimeouts 설정을 조정합니다.

Ollama가 감지되지 않음

Ollama 실행 확인

curl http://localhost:11434/api/tags

사용자 지정 Ollama URL 설정

백엔드 .env:

OLLAMA_BASE_URL=http://localhost:11434

Libre WebUI는 Docker에서, Ollama는 호스트에서 실행되면 외부 Ollama Compose 파일을 사용하거나 컨테이너에서 도달 가능한 호스트 주소로 OLLAMA_BASE_URL을 지정하세요.

모델 가져오기 문제

먼저 터미널에서 가져오기

ollama pull gemma4:12b

터미널에서 실패하면 Libre WebUI 외부의 문제입니다.

클라우드 모델

Ollama Cloud 모델은 모델 관리자의 클라우드 필터를 사용하세요. Libre WebUI가 흐름에서 필요한 클라우드 접미사를 정규화하므로 지원되는 클라우드 항목에 사용자가 :cloud를 직접 붙일 필요가 없습니다.

사용자가 모델을 가져올 수 없음

관리자는 일반 사용자의 모델 가져오기를 비활성화할 수 있습니다. 관리자가 아닌 사용자가 모델은 볼 수 있지만 설치하지 못하면 관리자 설정을 확인하세요.

채팅이 느리거나 실패함

• 더 작은 모델을 사용합니다.
• ollama ps로 로드된 모델을 확인합니다.
• 문맥 길이를 줄입니다.
• 매우 긴 응답의 최대 토큰을 줄입니다.
• 모델이 RAM/VRAM에 맞는지 확인합니다.
• 제공자 플러그인은 API 키와 제공자 할당량을 확인합니다.

OpenAI 이미지 생성을 사용할 수 없음

• 번들 OpenAI 제공자를 활성화합니다. 현재 사용자용 API 키를 저장하거나 신뢰된 번들 제공자의 OPENAI_API_KEY 환경 대체값을 설정합니다.
• 이미지 생성 설정을 열고 이미지 생성을 활성화한 뒤 표시된 GPT Image 모델 중 하나를 선택합니다.
• gpt-image-2를 우선하세요. 이전 GPT Image ID는 기존 설정 호환성을 위해서만 남아 있고 업스트림에서 더 이상 권장하지 않습니다.
• 호환 이미지 엔드포인트를 운영하지 않는 한 OpenAI image_endpoint 재정의를 비워 둡니다. Chat /responses 또는 /chat/completions 엔드포인트는 Image API 요청을 처리할 수 없습니다.
• 유효한 키와 할당량에도 OpenAI가 GPT Image 요청을 거부하면 API 조직이 GPT Image 모델 사용 자격이 있는지 확인합니다.

이미지 가용성은 현재 사용자가 저장한 자격 증명 또는 신뢰된 번들 제공자의 환경 대체값으로 평가됩니다. 다른 사용자의 설정에만 저장된 키는 이미지 모델을 공개하지 않습니다.

제공자 엔드포인트 문제

OpenAI 호환 제공자가 잘못된 경로에서 요청을 받으면 설정 → 플러그인에서 설정을 확인하세요.

• /chat/completions 페이로드에는 Chat Completions, /responses 페이로드에는 Responses를 선택합니다.
• API 루트(예: https://provider.example/v1)를 Base URL로 입력합니다.
• 모드 기본값에는 API 경로를 비우고, 제공자가 별도 경로를 제공하면 슬래시로 시작하는 경로를 입력합니다.
• 실제 사용자 지정 기존 전체 엔드포인트는 의도적으로 최우선입니다. Base URL과 API 경로로 돌아갈 때 지우세요. 번들 매니페스트의 이전 기본값과 같은 저장 값은 업그레이드 후 자동으로 무시됩니다. 사용자 지정 엔드포인트가 /chat/completions 또는 /responses로 끝나면 접미사가 요청 형식도 결정하므로 잘못된 페이로드를 받을 수 없습니다.

가져온 플러그인 JSON은 OpenAI Chat Completions, OpenAI Responses, Anthropic 또는 Gemini 호환 통신 형식의 제공자를 지원합니다. 독점 페이로드, 스트리밍 이벤트, 도구 호출 또는 응답 형식을 사용하면 백엔드 어댑터가 필요합니다. 엔드포인트만 바꿔서는 변환할 수 없습니다.

제공자 URL은 HTTP 또는 HTTPS를 사용할 수 있습니다. HTTP는 자격 증명과 제공자 트래픽을 전송 중 암호화하지 않으므로 신뢰된 네트워크의 셀프 호스팅 게이트웨이에만 사용하고 TLS가 있으면 HTTPS를 우선하세요. Base URL에는 쿼리 문자열 또는 fragment를 포함할 수 없습니다. 상대 API 경로에는 리터럴 또는 반복 인코딩된 traversal 구간, 쿼리 문자열, fragment를 포함할 수 없습니다. 검증 제한 안에서 안정되지 않는 과도한 인코딩도 거부됩니다.

모델 새로 고침은 /responses를 포함한 알려진 작업 접미사를 /models로 바꿉니다. 활성화, 명시적 새로 고침, 저장한 연결 재정의는 현재 사용자의 엔드포인트와 API 키를 사용합니다. 사용자 API 키 저장/제거 및 연결 재정의 초기화도 목록을 새로 고치지만 무관한 생성 매개변수는 그렇지 않습니다. 검색 ID는 사용자별로 저장되고 공유 플러그인 JSON을 덮어쓰지 않습니다. 파생 경로를 제공자가 지원하지 않으면 플러그인의 model_map에 모델 ID를 직접 설정합니다.

모델 검색, Chat, Work, 이미지 생성, 임베딩, 음성 합성을 포함한 제공자 요청은 의도적으로 HTTP 리디렉션을 따르지 않습니다. 리디렉션 URL 대신 최종 목적지 URL을 설정하세요. 이 안전한 실패 동작은 Authorization 헤더가 검증되지 않은 목적지로 넘어가지 않게 합니다.

Work가 실행 중 제공자 라우팅 변경을 보고하면 설정 업데이트를 마친 뒤 새 실행을 시작하세요. 이전 도구 상태가 다른 모드, 엔드포인트 또는 API 키 인증 경계로 재생되지 않도록 다음 제공자 요청 전에 의도적으로 중지합니다.

요청은 백엔드에서 시작하므로 컨테이너에서 실행할 때 localhost는 호스트가 아니라 Libre WebUI 컨테이너를 가리킵니다. Compose 또는 Kubernetes에서는 http://ai-gateway:8080/v1 같은 게이트웨이 서비스 DNS 이름을 사용합니다. 컨테이너 런타임이 호스트 별칭을 제공할 때만 http://host.docker.internal:8080/v1을 사용하세요. 이름이 사설로 해석되어도 HTTP 트래픽은 평문입니다.

이미지 모델 가용성, 엔드포인트 재정의, API 키도 현재 사용자에 대해 해석됩니다. 이미지 요청이 다른 계정의 설정을 사용하는 것처럼 보이면 예상 사용자로 인증되었는지 확인하세요.

다음 보안 및 소유권 규칙도 적용됩니다.

• 제공자 라우팅을 바꾸려면 관리자로 로그인합니다. 플러그인 정의와 연결 필드는 인스턴스 관리 설정입니다. 일반 사용자도 생성 설정, 자격 증명, 자신의 활성화 상태를 저장할 수 있습니다.
• 기존 endpoint 또는 api_url 재정의를 사용할 때는 작업 경로를 포함한 전체 API URL(예: https://provider.example/v1/chat/completions)을 입력합니다. API 루트는 base_url에만 입력하고 api_mode 및 선택적 api_path와 함께 사용합니다.
• 절대 HTTP 및 HTTPS URL만 허용됩니다. HTTP는 API 키, 프롬프트, 응답을 전송 중 암호화하지 않으므로 신뢰된 네트워크의 셀프 호스팅 게이트웨이에만 사용합니다.
• 빈 재정의는 플러그인 정의의 번들 엔드포인트를 사용합니다. 명시적으로 잘못되거나 안전하지 않은 재정의는 거부되며 번들 제공자 엔드포인트로 조용히 보내지 않습니다.
• 배포 환경 키는 shadow되지 않은 번들 정의가 신뢰된 루트 엔드포인트, 인증 필드, 기능 엔드포인트와 선택기, 라우팅 변수 기본값을 유지할 때만 사용됩니다. 가져온 정의, 번들 ID를 재사용하는 쓰기 가능 정의, 관리자가 저장한 사용자 지정 경로에는 같은 계정이 저장한 자격 증명이 필요합니다. 환경 키만 있으면 Libre WebUI가 제공자를 사용 불가로 보고하고 검색을 건너뜁니다.
• 이전 릴리스는 관리자 출처를 기록하지 않았으므로 업그레이드 전 사용자 지정 정의는 격리됩니다. 관리자로 JSON을 다시 가져오고 각 사용자가 다시 활성화하게 합니다. 승인된 플러그인 JSON을 직접 편집하면 다시 격리됩니다. 소스 경로와 정의 해시가 기록되도록 관리자 설치 또는 업데이트 흐름을 사용하세요.
• 저장 자격 증명은 입력 당시의 경로, 인증 계약, 정의, 소스에 묶입니다. 엔드포인트 또는 정의를 바꾸면 해당 계정의 자격 증명을 다시 저장합니다. 바인딩 없는 이전 자격 증명은 정확히 앵커된 번들 경로에서만 자동 마이그레이션됩니다.
• 가져온 플러그인은 api_url을 기존 전체 작업 URL 별칭으로 사용할 수 있습니다. 둘 다 설정되면 endpoint가 우선합니다. 모델 검색이 다른 곳에 있으면 완전한 모델 목록 URL을 models_endpoint에 설정합니다. 검증되며 리디렉션은 따르지 않습니다.
• 엔드포인트와 자격 증명을 저장한 후 플러그인을 활성화합니다. 활성화는 저장된 전체 엔드포인트에서 /models URL을 파생하고, models_endpoint가 없으면 활성화한 사용자의 자격 증명을 사용합니다. 연결 필드를 저장하거나 초기화해도 검색을 새로 고칩니다. UI가 플러그인 목록을 다시 불러오기 전에 검색을 기다립니다. 활성화는 계정별이므로 다른 사용자도 같은 공유 플러그인을 따로 활성화해야 합니다.
• 설정 → 플러그인에서 제공자를 선택하고 모델 새로 고침으로 카탈로그를 명시적으로 확인합니다. 모델 표는 읽기 전용이며 현재 계정의 설정 또는 검색 ID를 표시합니다. 일시적 검색 실패는 이전 카탈로그를 유지하고 이전 결과가 없으면 플러그인의 model_map을 사용하므로 완료된 검사만으로 원격 엔드포인트 상태가 증명되지는 않습니다.
• 자동 검색은 모델 ID가 담긴 OpenAI 호환 data 배열이 필요합니다. 성공 카탈로그는 공유 JSON을 바꾸지 않고 사용자별로 저장됩니다. 일반 활성화는 검색 불가 시 이전 카탈로그를 유지합니다. 연결 필드 변경/초기화는 오래된 카탈로그를 먼저 지워 실패한 새로 고침이 기존 model_map을 사용하게 합니다. 필요하면 플러그인 JSON에 대체 모델 ID를 설정하세요.
• 이미지 모델 가용성, 엔드포인트 재정의, API 키도 현재 사용자에 대해 해석됩니다. 다른 계정 설정을 쓰는 것처럼 보이면 인증 사용자를 확인합니다.
• 업그레이드된 비관리자 계정이 이전에 라우팅 값을 저장했다면 해당 플러그인의 초기화를 사용하세요. 무시된 이전 값이 제거되어 이후 역할 변경으로 활성화되지 않습니다. 라우팅 저장 또는 초기화는 오래된 카탈로그가 이전 경로를 따르지 않도록 계정의 검색 모델도 지웁니다.
• 요청은 백엔드에서 시작합니다. 컨테이너의 localhost는 호스트가 아니라 해당 컨테이너를 가리킵니다.
• 제공자 요청은 리디렉션을 따르지 않습니다. 최종 검증 작업 URL을 직접 설정하세요.

Chat이 잘못된 제공자를 사용하거나 제공자가 사용 불가로 표시됨

같은 모델 ID가 Ollama와 여러 플러그인에 존재할 수 있습니다. 현재 Chat 세션 및 기본 모델 환경 설정은 원시 모델 ID와 선택 제공자를 함께 저장하므로 같은 이름의 항목은 독립된 선택입니다.

• 선택기에 제공자를 사용할 수 없다고 표시되면 정확한 플러그인을 다시 활성화 또는 설치하고 모델 맵에 저장 모델 ID가 있는지 확인합니다.
• 제공자 또는 모델을 의도적으로 제거했다면 대체 항목을 명시적으로 선택합니다. Libre WebUI는 정확히 저장된 선택을 같은 이름의 다른 제공자로 돌리지 않습니다.
• 이전 세션 및 환경 설정에는 제공자 메타데이터가 없을 수 있습니다. 원래 제공자를 추론할 수 없으므로 기존 이름 전용 라우팅을 계속 사용하며 선택기에 "제공자 기록 없음"으로 나타납니다. 원하는 Ollama 또는 플러그인 항목을 다시 선택해 이후 요청을 고정합니다.
• 페르소나 항목은 persona:<id> 라벨을 유지합니다. 새로 선택한 페르소나는 Ollama를 기반 제공자로 기록하며 제공자 메타데이터가 없는 이전 페르소나 세션은 기존 라우팅과 호환됩니다.

Work 문제

Work가 없거나 런타임을 사용할 수 없다고 보고함

Work에는 현재 인증되고 Work 접근 권한이 있는 계정이 필요합니다. 관리자 또는 관리자가 설정의 사용자 관리 탭에서 모든 사용자에게 Work를 연 뒤의 활성 사용자입니다. 컨테이너 런타임은 Libre WebUI 백엔드에서 사용할 수 있어야 합니다.

docker info
docker version

기본 Docker 백엔드에서는 Docker가 실행 중이고 Libre WebUI를 실행하는 OS 사용자가 설정된 WORK_DOCKER_COMMAND를 호출할 수 있는지 확인하세요. npx로 Libre WebUI를 설치해도 Docker는 설치되지 않습니다. 런타임이 없어도 Libre WebUI는 나머지 애플리케이션을 사용할 수 있게 유지하고 모델 명령을 호스트에서 직접 실행하도록 대체하지 않습니다.

저장소 Compose 파일은 호스트 Docker 소켓을 마운트해 Work를 활성화합니다. Kubernetes에서는 Helm 값 work.enabled=true로 네이티브 Pod/PVC 런타임을 활성화하고 노드 런타임 소켓을 마운트하지 마세요. Compose 배포에서 런타임 사용 불가가 계속 표시되면 Work 페이지가 다음 중 원인을 알려 줍니다.

메시지	원인 및 해결
The "docker" CLI is not installed…	docker-cli가 없는 사용자 지정 이미지. 공식 이미지를 쓰거나 WORK_DOCKER_COMMAND로 CLI를 지정합니다.
No Docker daemon is reachable…	소켓 마운트가 제거되었거나 호스트 데몬이 중지됨. Compose 파일의 마운트를 복원하고 Docker를 시작합니다.
The Docker socket is mounted but…cannot open	소켓 그룹과 컨테이너 그룹이 다름. .env에 DOCKER_GID를 설정하고(아래 참조) 컨테이너를 다시 만듭니다.
Work 화면/오디오가 WebSocket 1006으로 닫히고 screen is unreachable 로그가 남음	컨테이너로 실행되는 백엔드가 자기 자신의 루프백으로 접속하는 경우입니다. Docker Desktop에서는 기본 제공되는 WORK_DOCKER_PUBLISHED_HOST=host.docker.internal을 사용하고, 네이티브 Docker Engine에서는 WORK_PREVIEW_BIND도 공개되지 않은 Docker 브리지 게이트웨이로 설정한 뒤 Libre WebUI를 다시 만듭니다.

macOS 호스트가 컨테이너에서 보는 값과 다른 값을 보고하므로 컨테이너를 통해 소켓 그룹을 읽습니다.

echo "DOCKER_GID=$(docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  alpine stat -c '%g' /var/run/docker.sock)" >> .env
docker compose up -d --force-recreate

이 소켓은 Docker 호스트의 root와 동등한 제어권을 줍니다. 배포에 미치는 영향은 Work: 격리된 워크스페이스를 검토하세요.

모델에 도구 지원이 없음

Work에는 도구를 지원하는 채팅 모델이 필요합니다. Ollama에서는 보고된 기능에 tools가 포함된 설치 모델을 선택합니다. 플러그인 기반 모델에서는 다음을 확인하세요.

• 채팅 또는 완성 플러그인이 활성 상태.
• 선택 모델이 플러그인의 설정 모델 목록에 있음.
• 현재 관리자용 API 키를 사용할 수 있음.
• 제공자가 정확한 모델의 도구 호출을 지원.

Libre WebUI는 실패한 Work 실행을 다른 제공자로 조용히 라우팅하지 않습니다.

Work 요청이 HTTP 429를 반환함

인스턴스가 작업 또는 활성 런타임 수용 한도에 도달했습니다. 기본적으로 Libre WebUI는 인스턴스 전체에 활성 컨테이너 기반 작업 두 개, 사용자당 하나를 허용합니다. 실행 중인 미리보기도 런타임 용량을 사용합니다. 다른 작업이 끝날 때까지 기다리거나 사용하지 않는 미리보기를 중지하거나, 운영자가 WORK_MAX_ACTIVE_RUNTIMES_* 및 WORK_MAX_TASKS_* 설정을 검토하게 하세요.

패키지 설치 또는 네트워크 접근 실패

새 Work 작업은 생성된 프로젝트가 패키지를 다운로드하고 미리보기를 시작할 수 있도록 Docker 브리지 네트워킹을 사용합니다. Docker DNS, 프록시 설정, 레지스트리 가용성, 활동의 명령 출력을 확인하세요. Libre WebUI는 호스트 SSH 키, 클라우드 자격 증명, 브라우저 프로필, Docker 소켓을 작업 컨테이너에 마운트하지 않습니다.

Work 미리보기가 시작되지 않음

• 서버가 0.0.0.0의 WORK_PREVIEW_PORT(기본값 4173)에 바인드하는지 확인합니다.
• 선택적 명령을 비워 package.json dev 스크립트 또는 단순 index.html을 자동 감지합니다. 중첩 앱 하나도 포함됩니다.
• 여러 앱 또는 지원 엔트리 포인트 없음이 보고되면 선택적 명령 필드에 프로젝트의 명시적 개발 명령을 입력합니다. 명령은 /workspace에서 시작하므로 중첩 앱에는 cd <app-directory> && ...를 사용합니다.
• 반환된 오류 세부 정보를 펼쳐 시작 출력을 확인합니다.
• 컨테이너가 필요한 다른 명령을 시작하기 전에 기존 미리보기를 중지합니다.

미리보기 URL은 동적으로 할당된 루프백 포트를 사용합니다. 따라서 브라우저와 Libre WebUI 백엔드가 같은 컴퓨터에서 실행되어야 합니다. 원격 백엔드에 연결된 브라우저는 백엔드 루프백 미리보기에 도달할 수 없고 HTTPS 페이지가 평문 HTTP 미리보기를 mixed content로 차단할 수 있습니다.

워크스페이스 파일을 열거나 저장할 수 없음

Work 파일 API는 최대 2 MB의 UTF-8 텍스트 파일을 허용합니다. 파일을 연 뒤 변경되었다면 더 최신 버전을 덮어쓰지 않도록 저장 전에 다시 불러옵니다. 포맷은 100,000자 및 4,000줄 아래의 지원 파일 유형으로 제한되고 큰 파일에서는 편집 반응성을 위해 구문 강조가 일시 중지됩니다.

저장되지 않은 편집은 현재 브라우저의 초안으로 보관됩니다. 영구 워크스페이스에 저장하는 것을 대신하지 않습니다.

작업 또는 미리보기가 중지됨

실행 중지, 미리보기 중지, Libre WebUI 재시작은 일회용 컨테이너 프로세스를 멈추지만 작업의 이름 있는 워크스페이스 볼륨을 보존합니다. 작업을 다시 열고 미리보기를 시작하세요. 작업 삭제는 다릅니다. 확인 후 작업과 워크스페이스를 영구 삭제합니다.

로그인 및 가입 문제

첫 사용자가 관리자가 아님

새 데이터베이스에서 만든 첫 계정만 관리자가 됩니다. 기존 데이터베이스는 현재 사용자와 역할을 유지합니다.

JWT 오류

프로덕션에서는 안정된 시크릿을 설정합니다.

JWT_SECRET=replace-with-a-long-random-secret

JWT_SECRET을 바꾸면 기존 세션이 무효화됩니다.

Turnstile이 가입을 차단함

두 키가 모두 있을 때만 Turnstile이 활성화됩니다.

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

가입이 갑자기 실패하면 사이트 키가 도메인과 일치하고 시크릿 키가 유효한지 확인합니다.

OAuth 리디렉션 실패

제공자 대시보드와 백엔드 .env에 콜백 URL을 모두 설정합니다.

BASE_URL=https://your-domain.example
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback

문서 채팅 문제

Libre WebUI는 최대 10 MB의 PDF, Office(DOCX/PPTX/XLSX), Markdown, HTML, 코드, CSV 파일을 받습니다.

검색은 작동하지만 의미 검색이 작동하지 않으면:

1. nomic-embed-text 같은 임베딩 모델을 설치합니다.
2. 설정에서 임베딩을 활성화합니다.
3. 문서 설정 또는 API에서 임베딩을 다시 생성합니다.

ollama pull nomic-embed-text

임베딩이 비활성화되어도 키워드 검색은 계속 작동합니다.

아티팩트 미리보기 문제

게임 또는 대화형 HTML에는 인라인 CSS와 JavaScript를 포함한 완전하고 독립적인 HTML 파일 하나를 모델에 요청하세요.

아티팩트에 키보드 입력이 필요하면:

• 먼저 미리보기 안을 클릭합니다.
• 열기 버튼으로 자체 브라우저 탭에서 실행합니다.
• 응답에 포함되지 않은 로컬 파일에 의존하지 않습니다.

Libre WebUI는 일반적인 index.html + CSS + JavaScript 코드 블록을 묶을 수 있지만, 독립형 HTML이 가장 신뢰할 수 있는 출력입니다.

Docker 문제

컨테이너에서 Ollama에 연결할 수 없음

Ollama가 같은 Compose 스택에 없으면 외부 Ollama Compose 파일을 사용합니다.

docker compose -f docker-compose.external-ollama.yml up -d

데이터가 유지되지 않음

영구 데이터 볼륨을 마운트하고 필요하면 DATA_DIR를 설정합니다. DATA_DIR 또는 Docker 모드를 사용하면 암호화 키가 영구 스토리지에 저장됩니다.

로컬 데이터 초기화

먼저 앱을 중지합니다. 사용 중인 데이터 디렉터리를 백업한 뒤 제거합니다. 기본 개발 데이터는 backend/data에 있습니다.

cp -R backend/data backend/data.backup
rm -rf backend/data

백엔드를 재시작하고 새 계정을 만듭니다.

그래도 해결되지 않음

다음 정보를 포함해 이슈를 등록하세요.

• Libre WebUI 버전 및 커밋
• 설치 방법
• 운영 체제
• Node.js 버전
• Ollama 버전
• Work 문제의 Docker 버전 및 docker info 결과
• 실패 전후의 백엔드 로그
• 브라우저 콘솔 오류
• 사용한 정확한 모델 또는 제공자
• 작업 또는 미리보기 실패 시 Work 활동 출력