Vai al contenuto

Risoluzione dei problemi

Problemi comuni e come risolverli, raggruppati per area.

Problemi di database

OperationalError: Connection refused all'avvio

Causa: il servizio si è avviato prima che PostgreSQL fosse pronto.

Soluzione: Docker Compose usa gli health check — non dovrebbe accadere. Se accade: 

docker compose restart auth-service   # riprova dopo che il DB è sano

asyncpg.exceptions.InvalidAuthorizationSpecificationError

Causa: password errata nella stringa di connessione.

Soluzione: controlla DATABASE_URL nel file envs/<service>.env del servizio interessato rispetto a POSTGRES_PASSWORD nel .env radice — devono coincidere. Assicurati di non aver modificato accidentalmente il segmento della password copiandola.

La migrazione Alembic fallisce all'avvio

Sintomo: nei log del servizio vedi alembic.util.exc.CommandError o relation "xxx" already exists.

Soluzione:

  1. Controlla se è stata eseguita una migrazione parziale: docker exec -it jinbocho-postgres psql -U postgres -d jinbocho -c '\dt auth.*' (o catalog.*) e ispeziona alembic_version
  2. Se lo schema è in uno stato inconsistente, resettalo: 
    # Elimina e ricrea lo schema dentro il container jinbocho-postgres, poi riavvia
# (Alembic rieseguirà tutte le migrazioni da zero)
docker exec -it jinbocho-postgres psql -U postgres -d jinbocho -c 'DROP SCHEMA auth CASCADE;'
docker compose -f docker/docker-compose.all.yml --env-file .env restart auth-service

Problemi tra servizi

Il catalog service restituisce 401 per ogni richiesta

Causa: il JWT_SECRET_KEY del catalog-service non corrisponde all'auth-service.

Soluzione: conferma che JWT_SECRET_KEY sia esattamente la stessa stringa nelle variabili d'ambiente di auth, catalog e gateway. Gli errori di copia-incolla (spazi finali, ritorni a capo) sono comuni.

Il gateway restituisce 502 Bad Gateway

Causa: il gateway non riesce a raggiungere un servizio interno.

Controlli:

  1. L'URL del servizio interno nell'ambiente del gateway (AUTH_SERVICE_URL/CATALOG_SERVICE_URL in envs/api-gateway.env) è errato — deve essere il nome del servizio Docker Compose, es. http://auth-service:8001, non localhost
  2. Il servizio si sta ancora avviando o si è bloccato — controlla i suoi log: docker compose -f docker/docker-compose.all.yml logs auth-service

Problemi Frontend / CORS

Errore CORS nella console del browser: Access-Control-Allow-Origin mancante

Causa: il CORS_ORIGINS del gateway non include l'URL del frontend.

Soluzione:

  1. Modifica envs/api-gateway.env
  2. Imposta CORS_ORIGINS all'origin esatta del frontend: ["https://library.example.com"]
  3. Nessuna barra finale
  4. Deve essere un array JSON valido (virgolette doppie, parentesi quadre)
  5. Riavvia il gateway: docker compose -f docker/docker-compose.all.yml --env-file .env restart api-gateway

Il frontend mostra una pagina bianca dopo il deploy

Causa: API_BASE_URL nel .env radice è errato o mancante — il container frontend lo inietta in /env.js all'avvio, non al momento della build.

Soluzione: controlla API_BASE_URL nel .env, poi riavvia il container frontend: docker compose -f docker/docker-compose.all.yml --env-file .env restart frontend. Nessuna rebuild necessaria.

Il login ha successo ma tutte le chiamate API successive restituiscono 401

Causa: il token di accesso viene inviato correttamente ma il gateway o un servizio backend lo rifiuta.

Controlli:

  1. Apri DevTools del browser → scheda Network → ispeziona l'header Authorization di una richiesta che fallisce
  2. Conferma che JWT_SECRET_KEY sia identica su auth, catalog e gateway

Problemi di ricerca ISBN

La ricerca ISBN restituisce 404 per un ISBN valido

Causa: il libro non è in Open Library o Google Books, o la chiave API di Google Books è mancante/non valida.

Controlli:

  1. Testa Open Library direttamente: 
    curl "https://openlibrary.org/api/books?bibkeys=ISBN:9788845292613&format=json&jscmd=data"
  2. Se GOOGLE_BOOKS_API_KEY è mancante, la ricerca di fallback viene saltata — aggiungi la chiave a envs/catalog-service.env

La ricerca ISBN è lenta (> 2 secondi)

Causa: l'ISBN non è nella cache locale e la ricerca esterna è lenta.

Soluzione: è previsto per la prima ricerca di qualsiasi ISBN. Le ricerche successive per lo stesso ISBN sono servite dalla cache e sono veloci.

Generale

Porta già in uso

# Trova il processo che usa la porta 8000
lsof -i :8000

# Terminalo
kill -9 <PID>

# Oppure cambia la porta host nel file compose (es. "8010:8000")