Debug Connessione Open WebUI e Ollama su Docker per Windows: Guida Completa

Eseguire modelli linguistici in locale garantisce privacy assoluta e zero costi ricorrenti. Lo stack composto da Docker, Open WebUI e Ollama rappresenta oggi lo standard ideale su Windows 11 e 10.

Tuttavia, far dialogare un’interfaccia web containerizzata con un backend locale riserva spesso ostacoli insidiosi. Configurare la connessione tra Open WebUI e Ollama su Docker per Windows può presentare insidie legate a reti virtuali, routing e autorizzazioni.

Errori come Connection Refused, timeout continui o chiamate bloccate da policy CORS sono all’ordine del giorno. Questa guida tecnica offre una procedura passo-passo per identificare e risolvere ogni collo di bottiglia. Per comprendere a fondo il comportamento dei modelli durante l’esecuzione locale, consulta la nostra guida su come risolvere gli errori con DeepSeek e Ollama.

Architettura di rete Docker su Windows: superare il tranello di localhost

Il primo grande ostacolo riguarda la comprensione dell’ambiente di rete. Su Windows, Docker Desktop opera all’interno di una macchina virtuale WSL2 dedicata. Questa architettura isola i container dalla rete host principale.

Il tranello di localhost nei container

Quando esegui un’applicazione nel browser, localhost punta alla macchina fisica. Nei container Docker, invece, localhost fa riferimento esclusivamente al container stesso.

Spesso si riscontra un blocco totale nella connessione tra Open WebUI e Ollama impostando localhost come indirizzo target. Open WebUI cercherà Ollama dentro il proprio spazio isolato, fallendo immediatamente la richiesta HTTP.

Per raggiungere l’applicazione Ollama in esecuzione sul sistema operativo Windows, è necessario usare un bridge speciale. Docker fornisce un alias DNS interno denominato host.docker.internal.

Configurare la variabile OLLAMA_BASE_URL

L’endpoint di Ollama deve essere impostato esplicitamente durante l’avvio del container Open WebUI. Senza questa variabile, il sistema utilizzerà valori predefiniti non validi per l’ambiente Windows.

Se utilizzi Docker da riga di comando o PowerShell, avvia il container con questo comando:

docker run -d -p 3000:8080 -e OLLAMA_BASE_URL=http://host.docker.internal:11434 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

Se utilizzi Docker Compose, definisci il mapping nel file docker-compose.yml:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
    volumes:
      - open-webui:/app/backend/data
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always
La direttiva extra_hosts è fondamentale su alcuni sistemi Windows con configurazioni WSL2 personalizzate. Garantisce la risoluzione corretta dell’indirizzo IP del gateway host.

Risolvere i blocchi CORS tra interfaccia web e backend

Un altro errore frequente è causato dal meccanismo di sicurezza CORS (Cross-Origin Resource Sharing). Il browser blocca le richieste quando frontend e backend operano su porte o domini differenti.

Perché si verifica l’errore Cross-Origin Resource Sharing

Open WebUI gira solitamente sulla porta 3000. Ollama risponde invece sulla porta standard 11434.

Per impostazione predefinita, Ollama consente accessi solo da richieste provenienti dallo stesso dominio locale. Una configurazione restrittiva interrompe la connessione tra Open WebUI e Ollama durante le chiamate asincrone dal browser.

L’interfaccia mostrerà una notifica di errore generica. Aprendo gli Strumenti per Sviluppatori (tasto F12), noterai errori espliciti relativi all’header Access-Control-Allow-Origin.

Impostare OLLAMA_ORIGINS nelle variabili d’ambiente di Windows

Per autorizzare Open WebUI a comunicare con Ollama, bisogna configurare la variabile d’ambiente OLLAMA_ORIGINS sul sistema host.

  1. Chiudi completamente l’applicazione Ollama dall’area di notifica (system tray).
  2. Premi Win + S, digita Variabili di ambiente e premi Invio.
  3. Clicca sul pulsante Variabili d’ambiente… in basso a destra.
  4. Nella sezione Variabili utente, fai clic su Nuova….
  5. Imposta come nome variabile: OLLAMA_ORIGINS.
  6. Imposta come valore variabile: * (oppure l’URL specifico http://localhost:3000).
  7. Salva le modifiche premendo OK su tutte le finestre aperte.
  8. Riavvia Ollama dal menu Start o tramite PowerShell.

Con il valore jolly *, Ollama accetterà chiamate da qualsiasi origine locale. Questa modifica elimina istantaneamente i fallimenti API dovuti a restrizioni di sicurezza del browser.

Gestione dei timeout e latenza con modelli pesanti

I modelli di grandi dimensioni possono richiedere molti secondi prima di generare il primo token. Se il server interrompe la connessione prematuramente, la chat risulterà inutilizzabile.

Timeout di inferenza e allocazione VRAM

Quando invii un prompt complesso, Ollama carica i pesi del modello nella VRAM della scheda video. Se la memoria video è insufficiente, parte del modello viene scaricata sulla RAM di sistema.

Questo processo rallenta vistosamente la risposta iniziale del backend. Durante l’inferenza di DeepSeek o Llama 3, la connessione tra Open WebUI e Ollama può cadere per superamento dei tempi limite.

Open WebUI interpreta l’attesa prolungata come un crash del server, mostrando l’errore 504 Gateway Timeout o un messaggio di disconnessione.

Modificare i parametri di keep-alive e timeout in Open WebUI

Puoi estendere le finestre temporali di attesa agendo sulle impostazioni avanzate di Open WebUI o tramite variabili d’ambiente aggiuntive nel container.

  • Aumenta il timeout HTTP: imposta la variabile AIOHTTP_CLIENT_TIMEOUT=300 per concedere fino a 5 minuti di attesa per ogni risposta.
  • Mantieni i modelli in memoria: imposta la variabile d’ambiente OLLAMA_KEEP_ALIVE=24h su Windows. In questo modo il modello non verrà rimosso dalla VRAM dopo 5 minuti di inattività.
  • Disabilita lo scaricamento automatico: ridurrai a zero la latenza iniziale per i prompt successivi.

Checklist pratica di debug e comandi utili

Quando la comunicazione non funziona, procedi con un’analisi metodica dei singoli componenti dello stack.

Test della rete con curl da dentro il container

Verifica se il container di Open WebUI riesce effettivamente a raggiungere l’host Windows. Esegui un comando interattivo all’interno del container tramite terminale:

docker exec -it open-webui curl http://host.docker.internal:11434/api/tags

Se il comando restituisce un array JSON contenente l’elenco dei tuoi modelli scaricati, la rete funziona. In caso di errore di risoluzione o mancata risposta, il problema risiede nel firewall di Windows o in Docker Desktop.

Regole del Firewall di Windows

Il Firewall di Windows Defender può bloccare le connessioni in entrata provenienti dalla subnet virtuale di WSL2. Apri PowerShell con privilegi di amministratore ed esegui:

New-NetFirewallRule -DisplayName "Ollama Port 11434" -Direction Inbound -LocalPort 11434 -Protocol TCP -Action Allow

Questa regola consente il transito dei pacchetti provenienti dal container verso l’istanza nativa di Ollama. Questo script assicura la corretta connessione tra Open WebUI e Ollama dopo ogni riavvio di Windows.

Domande Frequenti (FAQ)

Perché ricevo l’errore ‘WebUI: Server Connection Failed’ all’avvio?

Questo messaggio indica che Open WebUI non riceve risposta all’endpoint configurato. Controlla che Ollama sia attivo nella barra delle applicazioni di Windows. Assicurati inoltre che la variabile OLLAMA_BASE_URL utilizzi host.docker.internal anziché localhost.

Posso eseguire sia Ollama che Open WebUI all’interno di Docker?

Sì, è possibile containerizzare entrambi i servizi usando una rete Docker condivisa. Tuttavia, su Windows l’esecuzione nativa di Ollama garantisce prestazioni di inferenza superiori e un migliore supporto all’accelerazione GPU Nvidia CUDA.

Cosa fare se le variabili d’ambiente di Ollama non vengono caricate?

Le variabili impostate a livello utente richiedono il riavvio completo del processo. Se Ollama viene eseguito come servizio all’avvio, devi impostare le variabili nella sezione ‘Variabili di sistema’ e riavviare il PC.

Articoli simili