Architettura e stack tecnologico di SSH Everywhere

> Questo documento spiega in modo comprensibile l'architettura complessiva di SSH Everywhere, i protocolli e lo stack tecnologico utilizzati. È pensato per chi vuole capire «come funziona davvero»: non serve alcuna competenza tecnica per seguirlo.

---

Il progetto in una frase

SSH Everywhere è un pannello tutto-in-uno per l'operations remoto di server e dispositivi, all'altezza di 1Panel / BT Panel. La sua capacità principale è: ovunque si trovi il tuo dispositivo — con IP pubblico, senza IP pubblico (dietro NAT) o su uno smartphone Android — puoi gestirlo da questo unico pannello come se usassi SSH.

Il pannello stesso è installato su un server con IP pubblico (in ascolto su 0.0.0.0:5501). Accedi al pannello dal browser e il pannello raggiunge ogni dispositivo di destinazione tramite diversi «metodi di connessione».

---

Architettura complessiva (tutto in una figura)

┌───────────────────────────────────────────────────────────────┐
│  Frontend del browser (single-page app, simula un OS desktop) │
│  Finestre desktop · Barra attività · Menu Start · Schede      │
│  · Terminale reale · Icone · JS puro (senza framework)        │
└──────────────────────────┬────────────────────────────────────┘
                           │ HTTP REST + SocketIO
┌──────────────────────────┴────────────────────────────────────┐
│  Backend del pannello (Flask + Flask-SocketIO, Python)        │
│  Programma principale · Tunnel inverso · SocketIO · File      │
│  Protezione dai crash · Gestione siti · Backup · SQLite       │
└───┬───────────────┬──────────────────┬────────────────────────┘
    │ SSH           │ Tunnel inverso   │ SocketIO
    │ diretto/tunnel│ (0.0.0.0:4433)   │ (su HTTP)
    ▼               ▼                  ▼
┌─────────────┐    ┌────────────────┐    ┌────────────┐
│ Server con  │    │ Linux senza IP │    │ Smartphone │
│ IP pubblico │    │ pubblico / NAS │    │ Android    │
│             │    │ / Raspberry Pi │    │ (Termux)   │
└─────────────┘    └────────────────┘    └────────────┘

---

I quattro metodi di connessione (protocolli)

All'interno SSH Everywhere usa 4 protocolli, ciascuno con un compito preciso per tipo di dispositivo:

1. SSH —— Il canale principale

Uso: gestire le funzionalità principali di tutti i «server Linux normali».

Gestione di sistema (panoramica, processi, attività pianificate, firewall, Docker, siti, mirror, protezione dai crash)
Terminale (shell interattiva)
Gestione file (upload/download/modifica/compressione)
Controllo di integrità (CPU/memoria/disco/temperatura)
Esecuzione di comandi

Metodo di connessione:

Con IP pubblico: il pannello si collega direttamente a host:port
Senza IP pubblico: il pannello crea prima una porta proxy locale tramite il tunnel inverso, poi si collega in SSH

> In altre parole, il tunnel inverso non è altro che «portare SSH sui dispositivi senza IP pubblico», quindi SSH resta il protocollo finale di destinazione.

2. Protocollo del tunnel inverso —— Il canale di tunnel

Uso: permettere al pannello di raggiungere i «dispositivi senza IP pubblico». Il dispositivo si connette attivamente verso l'esterno al pannello, stabilendo una connessione TCP inversa persistente; il pannello usa questo tunnel per inviare comandi e inoltrare porte.

Caratteristiche: connessione TCP persistente + cifratura (AES-256-GCM), il server è in ascolto su 0.0.0.0:4433.

Scenari tipici:

Operations tramite tunnel via SSH su server Linux senza IP pubblico (dentro il tunnel gira di nuovo SSH)
Tunnel di porta: mappare una porta di servizio del dispositivo (ad es. 8090) su una porta pubblica del pannello

> Concetti facilmente confondibili: inoltro di porta vs tunnel di porta

> | | Inoltro di porta | Tunnel di porta |

> |---|---|---|

> | Dispositivi adatti | Server con IP pubblico | Dispositivi in tunnel senza IP pubblico |

> | Come funziona | DNAT del firewall di sistema, eseguito sulla macchina di destinazione | Passa dal tunnel inverso |

> | Flusso dei dati | Visitatore → IP pubblico di destinazione → porta di destinazione | Visitatore → porta pubblica del pannello → tunnel inverso → porta del dispositivo |

> | Dipende dal dispositivo online | No | Sì (il dispositivo deve mantenere l'Agent online) |

> In una frase: l'«inoltro» si usa per i server con IP pubblico; il «tunnel» per i dispositivi senza IP pubblico.

3. SocketIO —— Il canale dedicato agli smartphone Android

Uso: gestire Termux su uno smartphone Android. La rete mobile del telefono cambia NAT di frequente e SSH è instabile, quindi si usa un canale stabile a long polling SocketIO (soluzione matura, verificata su dispositivi reali).

L'Agent in esecuzione sul telefono offre via SocketIO:

Gestione di sistema (panoramica/processi/attività pianificate)
Terminale (bridge PTY)
Gestione file
Monitoraggio di integrità (report ogni 30 secondi: carico/memoria/disco/batteria/temperatura)

> È l'unico canale del progetto che «non passa da SSH» — perché gli smartphone Android non usano sshd, ma una connessione SocketIO persistente.

4. HTTP REST —— Tra frontend e backend

Il frontend nel browser chiama il backend del pannello tramite API REST e allo stesso tempo usa SocketIO per la comunicazione bidirezionale in tempo reale, come nel terminale.

---

Panoramica dei percorsi di raggiungimento dei tre tipi di dispositivo

Tipo di dispositivo	Metodo di connessione	Protocollo finale	Note
Server Linux con IP pubblico	Connessione diretta dal pannello	SSH	Lo scenario più diretto
Server Linux senza IP pubblico (NAS/Raspberry Pi ecc.)	Il tunnel inverso crea un proxy → SSH	SSH (trasportato dal tunnel)	Il tunnel è il «corriere» di SSH
Smartphone Android (Termux)	Long polling SocketIO	SocketIO (l'unico che non usa SSH)	Canale stabile dedicato ai telefoni

---

Archiviazione dei dati

Database SQLite (data/ssheverywhere.db): schede server, inoltro di porta, record dei tunnel, utenti, attività e altro.
File system: file di backup, chiavi del tunnel, risorse statiche.

---

Forma di distribuzione

Pannello: servizio systemd ssh-everywhere.service, in ascolto su 0.0.0.0:5501.
Tunnel inverso: in ascolto su 0.0.0.0:4433.
L'Agent sul dispositivo di destinazione resta attivo come servizio (systemd su Linux / termux-services su Termux).

---

Sul nome del progetto «SSH Everywhere»

Il progetto si chiama SSH Everywhere, che significa «gestibile ovunque, come SSH». SSH è il metodo di connessione assolutamente principale dell'intero progetto: a parte il solo caso degli smartphone Android, tutte le altre funzionalità (gestione di server Linux, operations tramite tunnel, trasferimento file, controllo di integrità) finiscono su SSH. E il tunnel inverso non è altro che «portare SSH ovunque». Il nome «SSH Everywhere» esprime quindi con precisione la capacità principale del progetto.

Documentazione