README_IT.md
Rama main · réplica de lectura del repositorio original.
<img src="docs/icon.png" width="88" alt="">
# dsm-mini
[English](README.md) · [Русский](README_RU.md) · [Español](README_ES.md) · [Português](README_PT.md) · [Deutsch](README_DE.md) · [Français](README_FR.md) · **Italiano** · [Türkçe](README_TR.md) · [Українська](README_UK.md) · [Polski](README_PL.md)
[](https://github.com/alexlnos/dsm-mini/actions/workflows/ci.yml)
[](LICENSE)
Un bot Telegram con Mini App per governare un NAS Synology di casa: i download di
Download Station e i file di File Station direttamente dalla messaggistica, senza
VPN e senza l'interfaccia web di DSM.
Butti un link magnet in chat — il bot chiede con dei pulsanti dove metterlo e lo
mette in coda. Apri l'applicazione — e vedi cosa sta scaricando, quanto manca,
cosa c'è sui dischi e come sta il NAS.
<p align="center">
<img src="docs/screenshots/it-home.webp" width="19%" alt="Panoramica del NAS">
<img src="docs/screenshots/it-downloads.webp" width="19%" alt="Download">
<img src="docs/screenshots/it-task.webp" width="19%" alt="Un'attività">
<img src="docs/screenshots/it-files.webp" width="19%" alt="File">
<img src="docs/screenshots/it-storage.webp" width="19%" alt="Archiviazione">
</p>
> Funzionano: il bot, la Mini App e le notifiche. Serve DSM 7 o più recente: su
> DSM 6 il pacchetto non si installa e lì non l'ha provato nessuno. Verificato
> su DSM 7.2.2 con Download Station 4.1.2 e File Station 1.4.4.
## Cosa sa fare
**Download**
- L'elenco delle attività: avanzamento, velocità, tempo rimasto, seed e peer
- Mettere in pausa, riprendere, eliminare
- Aggiunta con link magnet, con link diretto e con file `.torrent`
- Scelta della cartella di destinazione, con un elenco di accesso rapido
configurabile
- Scelta dei file dentro un torrent e della loro priorità
- Un messaggio in chat quando un'attività finisce o fallisce
**File**
- Sfogliare le cartelle, anteprime, caricamento sul NAS
- Rinominare, copiare, spostare, eliminare
**Stato del NAS**
- Carico di processore e memoria, tempo di attività, rete
- Dischi, pool e volumi: temperatura, spazio occupato, salute
- Macchine virtuali e contenitori: avvio e arresto
- Il registro eventi di DSM
**Notifiche e impostazioni**
- Ciò che annuncia il DSM stesso — consulente di sicurezza, dischi, aggiornamenti — arriva in chat
- La scelta di cosa il bot può mandare: niente, solo download, tutto
- Una schermata propria nel menu principale di DSM: lì il pacchetto si configura dopo l'installazione e lì si cambia poi qualsiasi impostazione, senza riavvio
**Lingua**
L'applicazione e il bot parlano la lingua scelta in Telegram: inglese, russo,
spagnolo, portoghese, tedesco, francese, italiano, turco, ucraino, polacco. Una
lingua sconosciuta riceve l'inglese.
---
## Installazione
Mezz'ora, e il grosso se ne va nel certificato, non nel servizio. Serve un NAS
Synology con DSM 7 e Download Station; nient'altro va installato prima.
> **L'indirizzo pubblico serve solo alla Mini App.** Telegram apre una Mini App
> solo via `https://` con un certificato vero: un `192.168.…` locale o uno
> autofirmato non si apriranno. Senza indirizzo il bot funziona da solo — link,
> file `.torrent`, `/status` e notifiche — e il NAS non deve essere
> raggiungibile dall'esterno. Il passo 4 dà tre modi per ottenerne uno, due dei
> quali senza aprire porte sul router.
**1. Creare il bot.** [@BotFather](https://t.me/BotFather) → `/newbot` → un
nome e un nome utente che finisca in `bot`. Risponde con un token: conservalo,
è la password del tuo bot.
**2. Scoprire il proprio numero.** [@userinfobot](https://t.me/userinfobot) →
Start. Risponde con la riga `Id`.
**3. Creare un utente DSM per il servizio.** Pannello di controllo → Utente e
gruppo → Crea. Accesso solo a Download Station e File Station, senza verifica in
due passaggi: un codice usa e getta non può arrivare da un file di
configurazione. Niente amministratore: il servizio sa cancellare file. Se
l'account basta lo dice il pulsante **Verifica l'account** nella finestra DSM
mini (passo 6): accede come questo utente ed elenca quello che DSM gli permette.
**4. Ottenere un indirizzo per la Mini App** — oppure salta questo passo e usa
il bot da solo. L'indirizzo deve aprirsi via `https://` sul telefono dove usi
Telegram. I modi sono tre. Il primo passa da DSM e richiede di inoltrare porte
sul router; saltalo se il NAS ha già un dominio con certificato valido:
- Pannello di controllo → Accesso esterno → DDNS → Aggiungi, fornitore
`Synology`: viene fuori qualcosa come `alex-nas.synology.me`.
- Sul router inoltra al NAS le porte **80** e **443**. Senza la 80 il
certificato non verrà emesso, senza la 443 l'applicazione non si apre.
- Pannello di controllo → Sicurezza → Certificato → Aggiungi → da Let's
Encrypt, per quello stesso nome.
Controlla dal telefono con la rete mobile: `https://alex-nas.synology.me:5001`
deve aprire DSM senza avvisi.
Il secondo è **Cloudflare Tunnel**, senza aprire porte; serve un dominio il cui
DNS sia su Cloudflare. Crea un tunnel nel pannello di Cloudflare, installa il
pacchetto **Cloudflare Tunnel** di [SynoCommunity](https://synocommunity.com)
con il token del tunnel e dai al tunnel un nome host pubblico — ad esempio
`mini.example.com` — con il servizio `http://localhost:58080`.
Il terzo è **Tailscale**, solo per i tuoi dispositivi. Installa Tailscale sul
NAS e sul telefono, attiva i certificati HTTPS nelle impostazioni DNS della tua
tailnet ed esegui `sudo tailscale serve --bg 58080` sul NAS: stampa un indirizzo
come `https://nas.tail1234.ts.net`. L'applicazione si apre finché il telefono è
connesso a Tailscale.
**5. Installare il pacchetto.** Centro pacchetti → Impostazioni → Origini
pacchetti → Aggiungi, nome `dsm-mini` e l'indirizzo della tua architettura:
- Intel e AMD, la maggior parte dei modelli: `https://alexlnos.github.io/dsm-mini/amd64.json`
- ARM, modelli economici: `https://alexlnos.github.io/dsm-mini/arm64.json`
Poi Impostazioni → Generale → Livello di attendibilità → **Qualsiasi editore**,
e installa **DSM mini — Telegram Mini App** dalla sezione **Community**. Dubbi
sull'architettura? Prova `amd64`: un pacchetto che non va bene viene
semplicemente rifiutato.
L'installazione non chiede nulla. Oppure installa lo `.spk` dalle
[versioni](https://github.com/alexlnos/dsm-mini/releases) a mano, da Centro
pacchetti → Installazione manuale.
**6. Configurare.** Apri **DSM mini** dal menu principale di DSM, oppure premi
**Apri** in Centro pacchetti — lo ricorda lui stesso a fine installazione.
Compila i valori raccolti nei passi qui sopra — la finestra spiega ognuno — e in
**Accesso alla Mini App** scegli il modo del passo 4, o
**Solo il bot, senza Mini App**. Premi **Salva** e poi **Avvia** in cima alla
finestra. Lo stato lì dice quando DSM e il bot hanno risposto, e cosa non va se
non l'hanno fatto.
Per il primo modo, la regola di proxy inverso la crea la finestra stessa: scrivi
il tuo nome in **Puntare un nome al servizio**. A mano è Pannello di controllo →
Portale di accesso → Avanzate → Proxy inverso → Crea. Origine: `HTTPS`, il tuo
nome, porta `443`. Destinazione: `HTTP`, `localhost`, porta `58080`. Con un
tunnel o Tailscale, scegli **Un altro modo** e inserisci l'indirizzo che ti
hanno dato.
> Non passare per il proxy la porta **80** di questo nome: è da lì che DSM
> rinnova il certificato, e intercettarla rompe il rinnovo tre mesi dopo.
**7. Verificare.** Con un indirizzo, `https://tuo-indirizzo/healthz` in un
browser deve rispondere `{"status":"ok"}`. Senza firma di Telegram non viene
dato niente.
**8. Aprire l'applicazione.** Trova il bot dal nome utente, premi Start e
accanto al campo di scrittura compare un pulsante **Download**. Mandagli un link
magnet qualsiasi: ti propone le cartelle con dei pulsanti. Senza indirizzo il
pulsante non c'è: manda i link al bot nella chat.
## Se qualcosa è andato storto
| Cosa vedi | Di cosa si tratta | Cosa fare |
|---|---|---|
| Il bot tace su `/start` | Il bot è spento o non configurato, oppure il token è sbagliato | Apri **DSM mini** nel menu principale di DSM: lo stato in cima dice quale, e **Avvia** accende il bot |
| «L'accesso a questo bot è chiuso» | Il tuo ID non è nell'elenco | Aggiungi il numero del passo 2 agli ID consentiti nella finestra **DSM mini** |
| Non c'è il pulsante dell'applicazione | L'indirizzo pubblico è vuoto — allora c'è solo il bot — o non è `https://` | La finestra **DSM mini**, **Accesso alla Mini App** |
| Il pulsante c'è, l'applicazione non si apre | Il proxy inverso o il certificato non funzionano | Apri `https://tuo-indirizzo/healthz` in un browser |
| «Apri l'applicazione dal bot» | L'applicazione è stata aperta con un link diretto nel browser | È voluto: aprila dal bot |
| «Accesso negato: il tuo ID Telegram…» | Il servizio non ti ha riconosciuto | Negli ID consentiti solo cifre, separate da virgole |
| La finestra dice che DSM ha rifiutato l'accesso | La password, la 2FA o i diritti dell'utente | Passo 3: password senza errori di battitura, 2FA spenta, applicazioni consentite |
| La finestra dice che Download Station non è avviato | Non è installato, o è negato all'utente | Centro pacchetti e i diritti del passo 3 |
| Il pacchetto si ferma subito dopo l'avvio | La sua porta è occupata da altro — il registro lo dice | Cambia `LISTEN_ADDR` in `config.env` via SSH (vedi sotto) |
Il primo posto dove guardare è la riga di stato in cima alla finestra **DSM
mini**: dice se DSM e Telegram hanno risposto e, se no, perché. I dettagli sono
nel registro del pacchetto, `/var/packages/dsm-mini/var/dsm-mini.log`, che si
apre anche dal Centro pacchetti. Il registro è in inglese; la finestra,
l'interfaccia e i messaggi del bot nella tua lingua.
### Cambiare le impostazioni
**Apri DSM mini nel menu principale di DSM**: lì ci sono tutte le impostazioni.
Password e token sono solo in scrittura: un campo lasciato vuoto mantiene quello
di prima. Il salvataggio vale subito: il servizio si riavvia da solo con le
nuove impostazioni, e il pacchetto non va riavviato.
Le impostazioni stanno in un file sul NAS,
`/var/packages/dsm-mini/var/config.env`, permessi `600`. Si può modificare anche
via SSH (Pannello di controllo → Terminale e SNMP → attivare SSH) e poi
riavviare il pacchetto:
```bash
sudo sed -i "s|^TELEGRAM_BOT_TOKEN=.*|TELEGRAM_BOT_TOKEN='il-tuo-nuovo-token'|" /var/packages/dsm-mini/var/config.env
sudo synopkg restart dsm-mini
```
Un aggiornamento non tocca il file, ed è per questo che le impostazioni
sopravvivono.
## Aggiornare
Se l'origine pacchetti è stata aggiunta, il Centro pacchetti mostra
l'aggiornamento da solo. Senza origine, scarica lo `.spk` fresco dalle
[versioni](https://github.com/alexlnos/dsm-mini/releases) e installalo sopra.
Le impostazioni e il database restano in entrambi i casi: stanno nella cartella
`var` del pacchetto, che un aggiornamento non tocca.
## Dove sono tenuti i dati
Tutto sta in `/var/packages/dsm-mini/var/`:
- `config.env` — le impostazioni della finestra DSM mini, permessi `600`;
- `dsm-mini.db` — un database SQLite: le cartelle fissate, la lingua e gli ultimi
stati noti delle attività, da cui il servizio capisce di cosa ha già riferito;
- `dsm-mini.log` — il registro.
Un aggiornamento del pacchetto li mantiene tutti e tre. La disinstallazione li
cancella.
## Sicurezza
Il servizio è esposto a internet e sa cancellare file sul NAS, perciò:
- **Un utente DSM a parte**, non un amministratore (passo 3).
- **Senza verifica in due passaggi** su quell'account: un codice usa e getta non
può funzionare da un file di configurazione.
- **Gli ID consentiti sono una lista di ammessi.** Una lista vuota chiude
l'accesso a tutti, non lo apre.
- Ogni richiesta a `/api/` viene controllata due volte: la firma `initData` con
una chiave ricavata dal token del bot, e l'identificatore contro l'elenco. La
firma dimostra soltanto che qualcuno ha aperto il bot — e aprirlo può chiunque.
- Verso l'esterno va una frase generica, i dettagli nel registro: un messaggio
che dicesse cosa esattamente non tornava nella firma sarebbe un suggerimento su
come falsificarla.
- Il token del bot e la password DSM vivono solo in `config.env` sul NAS stesso,
permessi `600`, e non finiscono mai nel registro: in un rifiuto si scrive il
motivo, mai il valore.
- Il servizio ascolta solo su `127.0.0.1`, cioè dal NAS stesso. Tutto quello che
arriva da fuori passa da ciò che serve l'indirizzo pubblico — il proxy inverso
di DSM, un tunnel o Tailscale — che chiude anche il TLS. Senza indirizzo, da
fuori non gli arriva niente.
## Sviluppo
```bash
cd web && npm install && npm run build # la Mini App finisce in internal/web/dist
cd .. && go build ./cmd/dsm-mini # un binario con l'applicazione incorporata
go test ./...
```
Il frontend da solo, con ricaricamento automatico:
```bash
cd web && npm run dev # parla col backend su localhost:58080
```
Avviare il backend in locale legge `config.env` in `STATE_DIR`, come fa il
pacchetto, e le variabili d'ambiente completano quello che il file non dice. È
comodo tenerle in un file:
```bash
cp .env.example .env # compilalo
set -a; . ./.env; set +a
go run ./cmd/dsm-mini
```
L'interfaccia compilata sta nel repository (`internal/web/dist`) — è da lì che la
prende `go:embed`. Dopo aver toccato il frontend, ricompila e fai il commit del
risultato, altrimenti i controlli non passano.
I test di integrazione girano contro un NAS vero e di default vengono saltati:
```bash
DSM_URL=https://192.168.1.10:5001 DSM_USER=... DSM_PASSWORD=... \
DSM_INSECURE_TLS=true go test -tags=integration ./...
```
I test che cambiano lo stato del NAS richiedono un permesso a parte:
`DSM_TEST_MUTATIONS=1`, e per le operazioni sui file anche `DSM_TEST_FOLDER` — la
cartella dentro cui si possono creare file temporanei. Cancellano tutto quello
che creano.
Una nuova lingua dell'interfaccia è un file di dizionario per parte:
`web/src/i18n/<codice>.ts` e `internal/i18n/<codice>.go`. Saltare una stringa non
si può: sul frontend ci pensa il tipo, sul server un test.
Codice, commenti e registro nel progetto sono in inglese; le altre lingue vivono
solo nei dizionari. I dettagli sono in [CLAUDE.md](CLAUDE.md).
## Particolarità dell'API Synology
La Web API di Synology a tratti si comporta diversamente da come sta scritto
nella documentazione: la stessa azione risponde in tre formati diversi,
`limit = -1` stende File Station, e il `_sid` durante il caricamento di un file va
passato in modo diverso che altrove. Tutto quello che è emerso su un NAS vero è
raccolto in [docs/synology-api.md](docs/synology-api.md).
## Licenza
[MIT](LICENSE)