La quarta pagina di una lunga discussione di supporto su ZimaOS segue i ricorrenti problemi di Jellyfin e Nginx Proxy Manager riscontrati da un utente dopo la prima configurazione riuscita dell'accesso remoto. La lezione utile non è una singola porta magica: un errore 502 può ripresentarsi ogni volta che cambiano la destinazione del reverse proxy, la mappatura delle porte di Jellyfin, la rete Docker o lo stato dell'applicazione.
Questa pagina si concentra solo sui post 61–80. Non ripete la precedente configurazione di DuckDNS e dei certificati, già trattata altrove nella stessa discussione.
Separa il messaggio dell'API di NPM dall'errore 502 di Jellyfin
L'utente ha visualizzato per la prima volta «Comunicazione con l'API non riuscita, NPM è in esecuzione correttamente?». L'analisi dei log della community ha mostrato che Nginx Proxy Manager era in esecuzione e che il rinnovo di Let's Encrypt era riuscito. Il messaggio temporaneo dell'API poteva quindi dipendere da una sessione del browser obsoleta o da una breve interruzione della comunicazione tra interfaccia e backend, mentre l'errore 502 pubblico rimaneva un problema distinto tra il proxy e Jellyfin.
Mantieni distinti i tre tipi di indirizzo
| Tipo di indirizzo | Esempio di ruolo | NPM dovrebbe inoltrare a questo indirizzo? |
|---|---|---|
| Indirizzo WAN pubblico | Indirizzo esposto su Internet aggiornato da DuckDNS | No |
| Indirizzo LAN di ZimaOS | Indirizzo stabile della rete domestica, come l'indirizzo LAN di ZimaOS 192.168.1.50
|
Sì, quando Jellyfin pubblica una porta host |
| Indirizzo o nome del container Docker | Endpoint interno come jellyfin:8096
|
Sì, solo quando NPM può raggiungere la stessa rete Docker |
La discussione passava ripetutamente dal nome di un container a un indirizzo LAN dell'host e a un indirizzo Docker interno. Non sono intercambiabili. Scegli un percorso supportato e testalo dal container NPM prima di modificare TLS o DNS.
Leggi la mappatura delle porte nella direzione corretta
Le impostazioni di Jellyfin mostravano la porta host 8097 mappata sulla porta del container 8096Quando NPM si connette tramite l'indirizzo LAN di ZimaOS, deve usare la porta host pubblicata. Quando NPM si connette direttamente tramite il nome del container su una rete Docker condivisa, normalmente usa la porta interna di Jellyfin.
Un ripristino della connessione dall'interno di NPM ha mostrato che il percorso selezionato non restituiva ancora una risposta Jellyfin valida. È un'evidenza più utile del semplice riavvio di entrambi i container.
Usa un ordine diagnostico a livelli
- Apri Jellyfin in locale e conferma la riproduzione prima di intervenire sul proxy.
- Verifica che il container di Jellyfin sia in esecuzione e leggi la mappatura salvata tra porte host e porte del container.
- Scegli l'indirizzo LAN stabile di ZimaOS insieme alla porta host pubblicata oppure un nome di container insieme alla porta interna su una rete condivisa.
- Esegui il test su quell'endpoint esatto dall'ambiente NPM.
- Solo dopo che il routing HTTP funziona, riattiva TLS e testa il dominio pubblico.
- Dopo qualsiasi modifica all'app o riavvio, ripeti i test locali e del proxy prima di modificare il DNS.
Una modifica al percorso multimediale può causare un errore diverso
In seguito, gli utenti remoti riuscivano a sfogliare Jellyfin ma non a riprodurre i contenuti multimediali. Il proprietario ha modificato le impostazioni del container di Jellyfin e il sito pubblico ha smesso di rispondere. La successiva analisi dei log della community ha mostrato che Jellyfin era in esecuzione e stava analizzando /Media/Movies, riportando l'attenzione sulla destinazione del proxy. Questo dimostra perché ogni modifica debba essere registrata e testata singolarmente.
I percorsi Linux distinguono tra maiuscole e minuscole durante il backup
Un backup della configurazione non è riuscito perché il comando faceva riferimento a /DATA/AppData/duckdns, mentre la directory reale era /DATA/AppData/DuckDNS. Linux considera questi percorsi diversi. La discussione originale proponeva un comando di archiviazione creato dalla community, ma non era stato fornito da IceWhale, quindi non viene riprodotto qui come procedura ufficiale di backup.
Prima di archiviare AppData, elenca i nomi esatti delle directory, arresta le applicazioni quando i relativi database richiedono uno snapshot coerente e verifica l'archivio ripristinando una copia in una posizione temporanea.
Accesso remoto attualmente supportato
Per l'amministrazione e l'accesso ai file, la documentazione attuale di ZimaOS indica l'accesso peer-to-peer crittografato tramite accesso remoto ZimaClient. Un reverse proxy pubblico per Jellyfin rimane una configurazione avanzata di terze parti e dovrebbe esporre solo il servizio multimediale, non il pannello di controllo di ZimaOS.
FAQ sull'errore 502 di Jellyfin
«NPM API failed» dimostra che NPM è arrestato?
No. Nella discussione, i log di NPM e il rinnovo del certificato erano normali, mentre il browser mostrava quel messaggio.
NPM deve usare la porta 8096 o 8097?
Usa la porta interna con la rete diretta del container oppure la porta host pubblicata quando inoltri all'indirizzo LAN di ZimaOS.
Perché il backup indicava che DuckDNS non esisteva?
La cartella AppData reale usava la D maiuscola e DNS; i percorsi Linux distinguono tra maiuscole e minuscole.
