Перейти к основному содержимому

Устранение неполадок

Начните со слоя: браузер, frontend, backend, Ollama, plugin или сеть.

Быстрые проверки​

# 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 не запускается​

node --version
npm install
npm run dev

Node.js 22.22+.

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

Остановите процесс или смените порт.

Backend использует DATA_DIR или backend/data. Source: DATA_DIR=./data → backend/data, DATA_DIR=./backend/data → backend/backend/data. Проверьте запись. Два состояния требуют осознанного выбора, без merge.

/health и /health/live — liveness; /health/ready даёт 503 для обязательных зависимостей; /health/deep проверяет SQLite и optional providers, требует admin Bearer.

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

Браузер не подключается​

Frontend .env, backend .env:

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

VITE_API_BASE_URL используется при настройке. VITE_WS_BASE_URL абсолютный ws:/wss:, может быть wss://example.com/libre, без credentials/query/fragment.

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

Это раздаёт frontend на порту 8080 и проксирует API- и WebSocket-трафик на локальный backend на порту 3001. С другого устройства должен быть доступен только порт 8080. Если в frontend/.env заданы VITE_API_BASE_URL или VITE_WS_BASE_URL, убедитесь, что эти URL доступны с другого устройства, либо удалите их, чтобы использовать прокси dev-сервера.

Нет streaming за reverse proxy​

Проверьте WebSocket upgrade и timeout. Origin должен совпадать с CORS_ORIGIN/BASE_URL; клиенты без Origin всё равно требуют ticket и TLS. Proxy на хосте использует 8080, в Compose — libre-webui:3001.

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 поддерживает 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'

Проверьте idle timeout и transport.respondingTimeouts.

Ollama не обнаружена​

Backend .env:

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

В Docker используйте внешний Compose или доступный OLLAMA_BASE_URL.

Проблемы модели​

ollama pull gemma4:12b

Ошибка terminal вне Libre. Cloud через фильтр, без ручного :cloud. Admin может запретить скачивание.

Chat медленный​

Меньшая модель, ollama ps, короче context/tokens, RAM/VRAM, key/quota.

Изображения OpenAI недоступны​

Активируйте OpenAI, key пользователя или OPENAI_API_KEY; включите изображения и GPT Image; предпочитайте gpt-image-2; оставьте image_endpoint пустым; /responses//chat/completions не Image API; проверьте организацию.

Проблемы endpoint поставщика​

В Настройки → Плагины: Chat Completions для /chat/completions, Responses для /responses; root https://provider.example/v1, optional path. Custom full endpoint имеет приоритет; suffix определяет формат.

JSON поддерживает OpenAI Chat Completions/Responses, Anthropic, Gemini; иное требует adapter. HTTP без шифрования. Без query/fragment/traversal. Discovery меняет suffix на /models, работает на пользователя и сохраняет ID per user; fallback model_map. Redirects не следуются.

В container localhost — container; используйте http://ai-gateway:8080/v1 или http://host.docker.internal:8080/v1.

Только admin меняет routing; endpoint/api_url полный https://provider.example/v1/chat/completions, root base_url, api_mode, api_path. Environment key только trusted manifest; custom требует account. Переимпортируйте старые определения и сохраните credentials после смены. models_endpoint для списка. Activation per account и ждёт discovery. Обновить модели не healthcheck. Требуется array data. Reset удаляет старые route/catalog.

Chat использует неверного поставщика​

ID может быть в Ollama и plugins. Текущие сессии сохраняют provider. Активируйте точный plugin или выберите новый; без перенаправления к одноимённому. Legacy без metadata работает по имени и показывает "provider not recorded". Persona persona:<id>.

Проблемы Work​

Work отсутствует или runtime недоступен​

docker info
docker version

npx не устанавливает Docker. Compose монтирует socket; Kubernetes использует work.enabled=true.

СообщениеИсправление
The "docker" CLI is not installed…docker-cli или WORK_DOCKER_COMMAND
No Docker daemon is reachable…socket/daemon
The Docker socket is mounted but…cannot openDOCKER_GID в .env
Экран или аудио Work закрывается с WebSocket 1006 и логом screen is unreachableBackend в контейнере обращается к собственному loopback. Docker Desktop: штатный WORK_DOCKER_PUBLISHED_HOST=host.docker.internal; нативный Docker Engine: дополнительно WORK_PREVIEW_BIND на непубличный шлюз моста Docker, затем пересоздайте 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.

Модель без tools​

Ollama с tools; plugin active, model, admin key, tools support. Без fallback.

HTTP 429​

Лимит task/runtime. По умолчанию два глобально, один per user; preview считается. Измените WORK_MAX_ACTIVE_RUNTIMES_*, WORK_MAX_TASKS_*.

Сеть и пакеты​

Проверьте DNS, proxy, registry и Активность. Нет host SSH/cloud/profile/socket в задаче.

Preview не запускается​

0.0.0.0, WORK_PREVIEW_PORT 4173; пустой command обнаруживает package.json dev/index.html; для вложенного cd <app-directory> && ...; детали и stop старого preview. Custom commands начинаются в /workspace, готовый сервис отвечает 200. Loopback требует ту же машину, HTTPS может блокировать mixed content.

Файл не открывается​

UTF-8 до 2 MB, reload при конфликте, format до 100 000/4000, browser draft не сохранение.

Задача остановлена​

Stop/restart сохраняет том; Delete удаляет навсегда.

Проблемы входа и регистрации​

Первый аккаунт новой базы — admin. Стабильный JWT_SECRET; смена аннулирует. Turnstile требует оба:

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

OAuth в 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

Проблемы документов​

До 10 MB. Установите/включите/пересоздайте nomic-embed-text:

ollama pull nomic-embed-text

Ключевые слова работают без embedding.

Проблемы артефактов​

Попросите один автономный HTML с inline CSS/JS. Щёлкните предпросмотр, откройте отдельную вкладку, не используйте отсутствующие локальные файлы.

Проблемы Docker​

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

Постоянный том и DATA_DIR.

Сброс локальных данных​

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

Сначала остановите, затем запустите и создайте аккаунт.

Проблема остаётся​

Укажите версию/commit, метод, OS, Node.js, Ollama, Docker+docker info, логи, console, точную модель/provider и Активность.