Przejdź do głównej zawartości

Rozwiązywanie problemów

Zacznij od warstwy: przeglądarka, frontend, backend, Ollama, plugin lub sieć.

Szybkie kontrole​

# 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

Frontend http://localhost:5173, backend http://localhost:3001, npx libre-webui http://localhost:8080.

Libre WebUI nie startuje​

node --version
npm install
npm run dev

Node.js 22.22+.

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

Zatrzymaj proces lub zmień port.

Backend używa DATA_DIR lub backend/data. Source: DATA_DIR=./data → backend/data, DATA_DIR=./backend/data → backend/backend/data. Sprawdź zapis. Dwa stany wymagają świadomego wyboru, bez merge.

/health i /health/live = liveness; /health/ready daje 503 dla wymaganych zależności; /health/deep sprawdza SQLite i opcjonalnych providerów, wymaga admin Bearer.

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

Przeglądarka nie łączy się​

Frontend .env, backend .env:

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

VITE_API_BASE_URL używane gdy ustawione. VITE_WS_BASE_URL absolutne ws:/wss:, może wss://example.com/libre, bez credentials/query/fragment.

CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173
npm run dev:host

Uruchamia to frontend na porcie 8080 i przekierowuje ruch API oraz WebSocket do lokalnego backendu na porcie 3001. Tylko port 8080 musi być osiągalny z drugiego urządzenia. Jeśli w frontend/.env ustawiono VITE_API_BASE_URL lub VITE_WS_BASE_URL, upewnij się, że te adresy URL są osiągalne z drugiego urządzenia, albo usuń je, aby korzystać z proxy serwera deweloperskiego.

Brak streamingu za proxy​

Proxy na hoście używa portu 8080, a w sieci Compose adresu libre-webui:3001.

Sprawdź WebSocket upgrade i timeout. Origin musi pasować do CORS_ORIGIN/BASE_URL; klienci bez Origin nadal wymagają biletu i TLS.

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

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.

Caddy​

reverse_proxy obsługuje WebSocket:

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik​

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'

Sprawdź idle timeout i transport.respondingTimeouts.

Ollama niewykryta​

Backend .env:

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

W Dockerze użyj zewnętrznego Compose lub dostępnego OLLAMA_BASE_URL.

Problemy z modelem​

ollama pull gemma4:12b

Błąd terminala jest poza Libre. Cloud przez filtr, bez ręcznego :cloud. Admin może blokować pobieranie.

Chat wolny​

Mniejszy model, ollama ps, krótszy kontekst/tokeny, RAM/VRAM, klucz/quota.

Obrazy OpenAI niedostępne​

Aktywuj OpenAI, klucz użytkownika lub OPENAI_API_KEY; włącz obrazy i wybierz GPT Image; preferuj gpt-image-2; zostaw image_endpoint pusty; /responses//chat/completions nie obsługują Image API; sprawdź organizację.

Problemy endpointu dostawcy​

W Ustawienia → Pluginy wybierz Chat Completions dla /chat/completions, Responses dla /responses; root np. https://provider.example/v1, opcjonalny path. Własny pełny endpoint ma priorytet; suffix określa format.

JSON wspiera OpenAI Chat Completions/Responses, Anthropic, Gemini; inne protokoły wymagają adaptera. HTTP bez szyfrowania. Brak query/fragment/traversal. Discovery zmienia suffix na /models, działa per użytkownik i zapisuje ID per użytkownik; fallback model_map. Brak redirectów.

Backend w kontenerze: localhost to kontener; użyj http://ai-gateway:8080/v1 lub http://host.docker.internal:8080/v1.

Tylko admin routing; endpoint/api_url pełny https://provider.example/v1/chat/completions, root base_url, api_mode, api_path. Klucz środowiskowy tylko trusted manifest; custom wymaga konta. Reimportuj stare definicje, zapisz poświadczenia po zmianie. models_endpoint dla listy. Aktywacja per konto i czeka na discovery. Odśwież modele nie jest healthcheck. Array data wymagany. Reset usuwa stare routing/katalog.

Chat używa złego dostawcy​

ID może być w Ollama i pluginach. Obecne sesje zapisują dostawcę. Reaktywuj dokładny plugin albo wybierz nowy; nie ma przekierowania do imiennika. Legacy bez metadata działa po nazwie i pokazuje "provider not recorded". Persona persona:<id>.

Problemy Work​

Work brak/runtime niedostępny​

Konto z dostępem i Docker:

docker info
docker version

npx nie instaluje Docker. Compose montuje socket; Kubernetes work.enabled=true.

KomunikatNaprawa
The "docker" CLI is not installed…docker-cli lub WORK_DOCKER_COMMAND
No Docker daemon is reachable…socket/daemon
The Docker socket is mounted but…cannot openDOCKER_GID w .env
Ekran lub audio Work zamyka się z WebSocket 1006 i logiem screen is unreachableBackend w kontenerze łączy się z własnym loopbackiem. Docker Desktop: dołączone WORK_DOCKER_PUBLISHED_HOST=host.docker.internal; natywny Docker Engine: dodatkowo WORK_PREVIEW_BIND na niepubliczną bramę mostka Docker, potem odtwórz Libre WebUI
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

Socket root-equivalent. Work.

Model bez tools​

Ollama z tools; plugin aktywny, model, klucz admina, obsługa tools. Bez fallbacku.

HTTP 429​

Limit task/runtime. Domyślnie dwa globalnie, jeden per użytkownik; preview liczy się. Zmień WORK_MAX_ACTIVE_RUNTIMES_*, WORK_MAX_TASKS_*.

Sieć/pakiety​

Sprawdź DNS, proxy, registry i Aktywność. Brak host SSH/cloud/profile/socket w zadaniu.

Preview nie startuje​

0.0.0.0, WORK_PREVIEW_PORT 4173; pusty command wykrywa package.json dev/index.html; przy zagnieżdżeniu cd <app-directory> && ...; szczegóły i stop starej preview. Loopback wymaga tej samej maszyny, HTTPS może blokować mixed content.

Plik nie otwiera/zapisuje​

Niestandardowe polecenia zaczynają się w /workspace, a gotowa usługa odpowiada kodem 200.

UTF-8 do 2 MB, reload przy konflikcie, format do 100 000/4000, szkic przeglądarki nie jest zapisem.

Zadanie zatrzymane​

Stop/restart zachowuje wolumen; Delete usuwa trwale.

Problemy login/rejestracja​

Pierwsze konto nowej bazy admin. Produkcyjny stabilny JWT_SECRET; zmiana unieważnia. Turnstile wymaga obu:

JWT_SECRET=replace-with-a-long-random-secret
TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

OAuth w backend .env:

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

Problemy dokumentów​

Do 10 MB. Zainstaluj/aktywuj/regeneruj nomic-embed-text:

ollama pull nomic-embed-text

Słowa działają bez embeddingów.

Problemy artefaktów​

Poproś jeden samodzielny HTML z inline CSS/JS. Kliknij podgląd, otwórz w osobnej karcie, bez brakujących lokalnych plików.

Problemy Docker​

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

Trwały wolumen i DATA_DIR.

Reset lokalnych danych​

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

Zatrzymaj przed, potem uruchom i utwórz konto.

Nadal problem​

Podaj wersję/commit, metodę, OS, Node.js, Ollama, Docker+docker info, logi, console, model/provider i Aktywność.