Sorun Giderme

Önce başarısız katmanı belirleyin: tarayıcı, frontend, backend, Ollama, sağlayıcı eklentisi veya dağıtım ağı.

Hızlı Kontroller

# 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

Geliştirmede frontend genellikle http://localhost:5173, backend http://localhost:3001; paketli npx libre-webui ise http://localhost:8080 kullanır.

Libre WebUI Başlamıyor

node --version
npm install
npm run dev

Node.js 22.22 veya sonrası gerekir.

Port kullanımda

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

Eski süreci durdurun veya portu değiştirin.

Backend veri yazamıyor

Veriler ayarlıysa DATA_DIR, değilse backend/data altındadır. Kaynaktan başlatma göreli DATA_DIR değerini kabuktan değil backend dizininden çözer: DATA_DIR=./data → backend/data, eski DATA_DIR=./backend/data → backend/backend/data. Dizin yazılabilir olmalıdır. Değişken yokken yalnız eski depo varsa korunur. İki konumda veri varsa Libre’yi durdurun, ikisini yedekleyin ve bilinçli seçin veya taşıyın; Libre farklı veritabanlarını birleştirmez.

Sağlık uçları canlı süreci hazır uygulamadan ayırır:

• /health ve /health/live, HTTP sunulabiliyorsa 200; isteğe bağlı sağlayıcılar etkilemez.
• /health/ready, gerekli veritabanı, şema, depolama veya platform bağımlılığı yoksa 503; isteğe bağlı sağlayıcıları beklemez ve iç ayrıntıyı göstermez.
• /health/deep, sınırlı worker’da SQLite bütünlüğü/yabancı anahtarları ve Ollama gibi isteğe bağlı sunucu kontrollerini toplar. Sağlayıcı kesintisi uyarıdır. Geçerli yönetici bearer tokenı ister ve sık orkestratör yoklaması için değildir.

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

Tarayıcı Backend’e Ulaşamıyor

Frontend ayarlıysa VITE_API_BASE_URL, değilse geliştirme backend’ini kullanır:

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

VITE_WS_BASE_URL isteğe bağlıdır ancak Chat ve Work terminal socket’lerinin ortak temelidir. Mutlak ws:/wss: URL kullanın; wss://example.com/libre gibi yol öneki desteklenir. Kimlik bilgisi, query veya fragment eklemeyin. Vite değişkeninden sonra frontend’i yeniden başlatın/derleyin.

Backend .env:

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

Telefon/LAN/Tailscale için telefonda localhost değil dizüstünün IP’sini kullanın ve:

npm run dev:host

Bu komut, ön yüzü 8080 portunda sunar ve API ile WebSocket trafiğini yerel arka uca (3001 portu) yönlendirir. Diğer cihazdan yalnızca 8080 portunun erişilebilir olması gerekir. frontend/.env içinde VITE_API_BASE_URL veya VITE_WS_BASE_URL ayarlıysa, bu URL'lerin diğer cihazdan erişilebilir olduğundan emin olun ya da geliştirme sunucusu proxy'sini kullanmak için bunları kaldırın.

Chat Reverse Proxy Arkasında Akmıyor

Mesaj gider ama yanıt görünmez ve WebSocket hatası varsa proxy upgrade’e ve uzun bağlantılara izin vermelidir.

CORS_ORIGIN veya BASE_URL ayarlıysa tarayıcının Origin başlığı doğrulanır. Uzak dağıtımda en az birini ayarlayın; ikisi yoksa yerel geliştirme izinlidir. Electron gibi istemciler Origin göndermese de Authorization’ı kısa tek kullanımlık bilete çevirmelidir. Backend’i TLS ve HTTP API ile aynı ağ kontrolleri arkasında tutun.

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

Proxy Docker ana bilgisayarındaysa Compose 8080 portunu yayımlar; Compose ağına katılıyorsa upstream libre-webui:3001 kullanın.

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 sonrası yeniden yükleyin.

Caddy

reverse_proxy WebSocket’i varsayılan destekler:

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'

Akış sonradan düşerse öndeki proxy/balancer boşta kalma süresini ve Traefik transport.respondingTimeouts ayarını kontrol edin.

Ollama Algılanmıyor

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

OLLAMA_BASE_URL=http://localhost:11434

Libre Docker’da, Ollama ana bilgisayardaysa harici Compose veya kapsayıcıdan ulaşılabilir OLLAMA_BASE_URL kullanın.

Model İndirme Sorunları

ollama pull gemma4:12b

Terminal başarısızsa sorun Libre dışındadır. Ollama Cloud için Model Yöneticisi bulut filtresini kullanın; Libre gerekli sonekleri düzeltir, :cloud elle gerekmez. Yönetici normal kullanıcıların indirmesini kapatmış olabilir.

Chat Yavaş veya Hatalı

• Küçük model kullanın.
• ollama ps ile yüklenenleri görün.
• Bağlamı ve maksimum tokenı azaltın.
• RAM/VRAM’e sığdığını doğrulayın.
• Eklenti anahtarını ve kotayı kontrol edin.

OpenAI Görüntü Üretimi Yok

• OpenAI eklentisini etkinleştirin; kullanıcı anahtarını veya güvenilir OPENAI_API_KEY yedeğini ayarlayın.
• Görüntü üretimini açıp duyurulan GPT Image modelini seçin.
• gpt-image-2 tercih edin; eskiler yalnız uyumluluk içindir.
• Uyumlu özel Image API yoksa image_endpoint boş kalsın. Chat /responses veya /chat/completions görüntü işleyemez.
• Geçerli anahtar ve kota reddediliyorsa kuruluşun GPT Image erişimini doğrulayın.

Başka kullanıcının anahtarı görüntü modellerini açmaz.

Sağlayıcı Uç Sorunları

• /chat/completions için Chat Completions, /responses için Responses seçin.
• API kökünü https://provider.example/v1 olarak Base URL’ye girin.
• Varsayılan yol için API path boş, özel için / ile başlayan yol.
• Eski özel tam uç en yüksek önceliktedir; Base URL/API Path’e dönerken temizleyin. /chat/completions veya /responses soneki istek biçimini de belirler.

JSON yalnız OpenAI Chat Completions, Responses, Anthropic veya Gemini protokollerini yapılandırır; özel yük/akış/araç biçimi backend bağdaştırıcısı ister.

HTTP kimlik bilgilerini şifresiz yollar; yalnız güvenilir ağda kullanın. Base URL query/fragment içeremez; göreli yol traversal, query veya fragment içeremez. Aşırı kodlama reddedilir.

Model yenileme bilinen sonekleri /models ile değiştirir. Etkinleştirme, yenileme, bağlantı, anahtar ve sıfırlama güncel kullanıcının ucu/anahtarını kullanır. ID’ler kullanıcı başına saklanır; desteklenmeyen rotada model_map ayarlayın.

Sağlayıcı istekleri keşif, Chat, Work, görüntü, embedding ve TTS dâhil HTTP yönlendirmelerini izlemez. Son hedefi doğrudan yapılandırın.

Work çalışma sırasında yönlendirme değişti derse ayar bitince yeni çalışma başlatın; önceki araç durumu başka moda, uca veya anahtara gitmeden durur.

İstekler backend’den çıkar; kapsayıcıdaki localhost kapsayıcıdır. Compose/Kubernetes’te http://ai-gateway:8080/v1, yalnız desteklenirse http://host.docker.internal:8080/v1 kullanın. HTTP özel ad çözse de düz metindir.

Ek güvenlik kuralları:

• Yönlendirmeyi yalnız yönetici değiştirir; normal kullanıcı üretim ayarı, kimlik bilgisi ve etkinliğini kaydeder.
• endpoint/api_url tam işlem URL’sidir, ör. https://provider.example/v1/chat/completions; kök base_url içine api_mode ve api_path ile girilir.
• Mutlak HTTP/HTTPS kabul edilir; HTTP yalnız güvenilir özel ağda.
• Boş geçersiz kılma paketli ucu kullanır; hatalı açık değer reddedilir.
• Ortam anahtarı yalnız gölgelenmemiş güvenilir paketli rota için kullanılır. İçe aktarılan, yazılabilir aynı ID veya yönetici özel rotası aynı hesabın anahtarını ister.
• Eski özel tanımlar karantinadadır; yönetici JSON’u yeniden içe aktarmalı, kullanıcılar yeniden etkinleştirmelidir. Dosyayı doğrudan değiştirmek yeniden karantinaya alır.
• Kaydedilen kimlik bilgisi rota, sözleşme, tanım ve kaynağa bağlıdır; değişiklikten sonra yeniden kaydedin.
• api_url eski tam işlem takma adıdır; endpoint önceliklidir. Ayrı keşif için tam models_endpoint kullanın.
• Etkinleştirme kaydedilen uçtan /models türetir ve etkinleştiren kullanıcının anahtarını kullanır. Bağlantı alanlarını kaydetmek/sıfırlamak keşfi yeniler; diğer kullanıcı ayrıca etkinleştirir.
• Modelleri yenile katalogu açıkça kontrol eder. Tablo salt okunurdur; geçici hata eski katalogu veya model_map değerini korur.
• Keşif OpenAI uyumlu data dizisi ister ve kullanıcı başına saklanır. Bağlantı değişikliği eski katalogu önce temizler.
• Eski yönetici olmayan rota değeri için Sıfırla kullanın; göz ardı edilen değer ve katalog temizlenir.
• İstekler backend’den çıkar ve yönlendirmeleri izlemez.

Chat Yanlış Sağlayıcıyı Kullanıyor veya Kullanılamaz Diyor

Aynı ID Ollama ve eklentilerde olabilir. Güncel oturumlar sağlayıcıyı ham ID ile kaydeder.

• Kullanılamazsa tam eklentiyi yeniden etkinleştirip model haritasını doğrulayın.
• Bilerek kaldırıldıysa açıkça yenisini seçin; Libre aynı adlı diğerine yönlendirmez.
• Eski oturumlarda sağlayıcı meta verisi olmayabilir ve ada göre eski yönlendirmeyi kullanır; “sağlayıcı kaydedilmedi” görünür. Yeniden seçin.
• Persona girdileri persona:<id> etiketini korur; yenileri Ollama’yı arka sağlayıcı olarak kaydeder.

Work Sorunları

Work Yok veya Çalışma Zamanı Kullanılamıyor

Güncel erişimli hesap ve backend’in eriştiği runtime gerekir:

docker info
docker version

Docker’ın çalıştığını ve kullanıcı WORK_DOCKER_COMMAND çağırabildiğini doğrulayın. npx Docker kurmaz; runtime yoksa diğer uygulama çalışır ve ana bilgisayarda komut yürütülmez.

Compose socket bağlar; Kubernetes’te work.enabled=true kullanın ve node socket’i bağlamayın. Mesajlar:

Mesaj	Neden ve çözüm
The "docker" CLI is not installed…	Özel image’da docker-cli yok; resmi image veya WORK_DOCKER_COMMAND.
No Docker daemon is reachable…	Socket yok ya da daemon kapalı; bağlantıyı ve Docker’ı geri getirin.
The Docker socket is mounted but…cannot open	Grup farklı; .env içinde DOCKER_GID ayarlayıp yeniden oluşturun.
Work ekranı/sesi WebSocket 1006 ile kapanıyor ve günlükte screen is unreachable görünüyor	Kapsayıcıdaki arka uç kendi loopback adresini arıyor. Docker Desktop’ta ürünle gelen WORK_DOCKER_PUBLISHED_HOST=host.docker.internal değerini kullanın; yerel Docker Engine’de ayrıca WORK_PREVIEW_BIND değerini herkese açık olmayan Docker köprü ağ geçidine ayarlayıp Libre WebUI’yi yeniden oluşturun.

macOS farklı değer bildirdiğinden grubu kapsayıcı içinden okuyun:

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 düzeyi denetim verir; ayrıntılar Work.

Model Araçları Desteklemiyor

Ollama için tools bildirilen model; eklenti için etkin chat/completion, listede model, yönetici API anahtarı ve o modelde araç çağrısı gerekir. Libre başka sağlayıcıya geçmez.

Work İsteği HTTP 429 Döndürüyor

Görev veya runtime kabul sınırına ulaşıldı. Varsayılan iki etkin görev ve kullanıcı başına birdir; önizleme de kapasite tutar. Bekleyin, önizlemeyi durdurun veya WORK_MAX_ACTIVE_RUNTIMES_*, WORK_MAX_TASKS_* ayarlarını inceleyin.

Paket veya Ağ Çalışmıyor

Yeni görevler paket ve önizleme için Docker köprü ağı kullanır. DNS, proxy, kayıt ve Etkinlik çıktısını kontrol edin. Libre ana bilgisayar SSH anahtarı, bulut kimliği, tarayıcı profili veya Docker socket’ini göreve bağlamaz.

Work Önizlemesi Başlamıyor

• Sunucu 0.0.0.0 üzerinde WORK_PREVIEW_PORT (varsayılan 4173) dinlemeli.
• Boş komut package.json dev, index.html veya tek iç içe uygulamayı algılar.
• Birden çok/hiç yoksa açık geliştirme komutu girin; /workspace içinde başlar, iç içe için cd <app-directory> && ....
• Başlangıç çıktısı için hata ayrıntılarını açın.
• Aynı kapsayıcı gereken başka komuttan önce önizlemeyi durdurun.

Önizleme dinamik loopback portu kullanır; tarayıcı ve backend aynı makinede olmalıdır. Uzak tarayıcı backend loopback’ine ulaşamaz ve HTTPS düz HTTP’yi karma içerik olarak engelleyebilir.

Çalışma Alanı Dosyası Açılmıyor/Kaydedilmiyor

API 2 MB’a kadar UTF-8 kabul eder. Açıldıktan sonra değiştiyse kaydetmeden yenileyin. Biçimlendirme 100,000 karakter ve 4,000 satır altındaki destekli türlerle sınırlıdır; büyük dosyalarda vurgulama durur. Kaydedilmemiş taslak kalıcı çalışma alanına yazmanın yerine geçmez.

Görev veya Önizleme Durduruldu

Çalıştırmayı/önizlemeyi durdurmak veya Libre’yi yeniden başlatmak tek kullanımlık süreçleri durdurur fakat adlandırılmış birimi korur. Yeniden açıp başlatın. Görevi silmek birimi kalıcı kaldırır.

Giriş ve Kayıt Sorunları

İlk yönetici yalnız yeni veritabanındaki ilk hesaptır; mevcut roller korunur.

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

JWT_SECRET değişikliği oturumları iptal eder.

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Turnstile yalnız iki anahtarla açıktır; etki alanını ve sırrı doğrulayın.

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

Callback URL’lerini sağlayıcı paneli ve backend .env içinde aynı ayarlayın.

Belge Sohbeti Sorunları

PDF, DOCX/PPTX/XLSX, Markdown, HTML, kod ve CSV 10 MB’a kadar kabul edilir. Anlamsal arama çalışmıyorsa nomic-embed-text kurun, gömmeleri açın ve yeniden üretin:

ollama pull nomic-embed-text

Anahtar sözcük araması gömmesiz çalışır.

Yapıt Önizleme Sorunları

Tek, kendi kendine yeterli, gömülü CSS/JavaScript içeren HTML isteyin. Klavye için önce önizlemeye tıklayın, ayrı sekmede açın ve yanıtta olmayan yerel dosyalara güvenmeyin. Libre index.html + CSS + JavaScript’i birleştirebilir ama tek dosya daha güvenilirdir.

Docker Sorunları

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

Ollama aynı stack’te değilse harici Compose kullanın. Veri kalıcı değilse kalıcı birim ve gerekirse DATA_DIR ayarlayın.

Yerel Verileri Sıfırlama

Uygulamayı durdurun, kullanılan dizini yedekleyip silin; varsayılan backend/data:

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

Backend’i başlatıp yeni hesap oluşturun.

Hâlâ Çözülmediyse

Issue içinde sürüm/commit, kurulum yöntemi, işletim sistemi, Node.js/Ollama/Docker sürümü, Work için docker info, backend günlükleri, tarayıcı konsolu, model/sağlayıcı ve Work Etkinlik çıktısını ekleyin.