README_PL.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](README_IT.md) · [Türkçe](README_TR.md) · [Українська](README_UK.md) · **Polski**
[](https://github.com/alexlnos/dsm-mini/actions/workflows/ci.yml)
[](LICENSE)
Bot Telegrama z Mini App do zarządzania domowym NAS-em Synology: pobierania
Download Station i pliki File Station prosto z komunikatora, bez VPN-a i bez
interfejsu webowego DSM.
Wrzucasz link magnet na czat — bot pyta przyciskami, gdzie pobrać, i wstawia do
kolejki. Otwierasz aplikację — widać, co się pobiera, ile zostało, co leży na
dyskach i jak się miewa NAS.
<p align="center">
<img src="docs/screenshots/pl-home.webp" width="19%" alt="Przegląd NAS-a">
<img src="docs/screenshots/pl-downloads.webp" width="19%" alt="Pobierania">
<img src="docs/screenshots/pl-task.webp" width="19%" alt="Zadanie">
<img src="docs/screenshots/pl-files.webp" width="19%" alt="Pliki">
<img src="docs/screenshots/pl-storage.webp" width="19%" alt="Magazyn">
</p>
> Działa: bot, Mini App i powiadomienia. Potrzebny jest DSM 7 albo nowszy — na
> DSM 6 pakiet się nie zainstaluje i nikt go tam nie sprawdzał. Sprawdzone na
> DSM 7.2.2 z Download Station 4.1.2 i File Station 1.4.4.
## Co to potrafi
**Pobierania**
- Lista zadań: postęp, prędkość, pozostały czas, seedy i peery
- Wstrzymanie, wznowienie, usunięcie
- Dodawanie linkiem magnet, linkiem bezpośrednim i plikiem `.torrent`
- Wybór folderu docelowego, z konfigurowalną listą szybkiego dostępu
- Wybór plików wewnątrz torrenta i ich priorytetu
- Wiadomość na czacie, gdy zadanie się skończy albo padnie
**Pliki**
- Przeglądanie folderów, podgląd, wysyłanie na NAS
- Zmiana nazwy, kopiowanie, przenoszenie, usuwanie
**Stan NAS-a**
- Obciążenie procesora i pamięci, czas pracy, sieć
- Dyski, pule i woluminy: temperatura, zajęte miejsce, kondycja
- Maszyny wirtualne i kontenery: uruchamianie i zatrzymywanie
- Dziennik zdarzeń DSM
**Powiadomienia i ustawienia**
- To, co zgłasza sam DSM — doradca bezpieczeństwa, dyski, aktualizacje — trafia na czat
- Wybór, co bot może wysyłać: nic, tylko pobierania, wszystko
- Własny ekran w menu głównym DSM: tam pakiet konfiguruje się po instalacji i tam później zmienia się każde ustawienie, bez restartu
**Język**
Aplikacja i bot mówią w języku wybranym w Telegramie: angielski, rosyjski,
hiszpański, portugalski, niemiecki, francuski, włoski, turecki, ukraiński,
polski. Nieznany język dostaje angielski.
---
## Instalacja
Pół godziny, z czego większość pochłania certyfikat, a nie sama usługa.
Potrzebny jest NAS Synology z DSM 7 i Download Station; niczego więcej nie
trzeba instalować wcześniej.
> **Publiczny adres jest potrzebny tylko dla Mini App.** Telegram otwiera Mini
> App tylko po `https://` z prawdziwym certyfikatem: lokalny `192.168.…` ani
> samopodpisany się nie otworzą. Bez adresu bot działa sam — linki, pliki
> `.torrent`, `/status` i powiadomienia — a NAS nie musi być dostępny z
> zewnątrz. Trzy sposoby zdobycia adresu są w kroku 4, dwa z nich bez
> przekierowania portów na routerze.
**1. Utworzyć bota.** [@BotFather](https://t.me/BotFather) → `/newbot` → nazwa
i login kończący się na `bot`. W odpowiedzi przyjdzie token; zachowaj go, to
hasło do twojego bota.
**2. Poznać swój numer.** [@userinfobot](https://t.me/userinfobot) → Start.
Odpowie linią `Id`.
**3. Założyć użytkownika DSM dla usługi.** Panel sterowania → Użytkownik i grupa
→ Utwórz. Dostęp tylko do Download Station i File Station, bez weryfikacji
dwuetapowej: kod jednorazowy nie ma jak trafić z pliku konfiguracyjnego. Nie
dawaj administratora: usługa potrafi kasować pliki. Czy konto wystarczy, pokaże
przycisk **Sprawdź konto** w oknie DSM mini (krok 6): loguje się jako ten
użytkownik i wylicza, na co DSM mu pozwala.
**4. Zdobyć adres dla Mini App** — albo pomiń ten krok i korzystaj z samego
bota. Adres musi się otwierać po `https://` na telefonie, na którym masz
Telegram. Sposoby są trzy. Pierwszy idzie przez DSM i wymaga przekierowania
portów na routerze; pomiń go, jeśli NAS ma już domenę z ważnym certyfikatem:
- Panel sterowania → Dostęp zewnętrzny → DDNS → Dodaj, usługodawca `Synology`:
wyjdzie coś w rodzaju `alex-nas.synology.me`.
- Na routerze przekieruj na NAS porty **80** i **443**. Bez 80 nie wystawi się
certyfikat, bez 443 nie otworzy się aplikacja.
- Panel sterowania → Zabezpieczenia → Certyfikat → Dodaj → z Let's Encrypt, na
tę samą nazwę.
Sprawdź z telefonu przez internet mobilny:
`https://alex-nas.synology.me:5001` powinien otworzyć DSM bez ostrzeżeń.
Drugi to **Cloudflare Tunnel**, bez otwierania portów; potrzebna jest domena z
DNS w Cloudflare. Utwórz tunel w panelu Cloudflare, zainstaluj pakiet
**Cloudflare Tunnel** z [SynoCommunity](https://synocommunity.com) z tokenem
tunelu i nadaj tunelowi publiczną nazwę hosta — na przykład `mini.example.com` —
z usługą `http://localhost:58080`.
Trzeci to **Tailscale**, tylko dla własnych urządzeń. Zainstaluj Tailscale na
NAS-ie i na telefonie, włącz certyfikaty HTTPS w ustawieniach DNS swojego
tailnetu i uruchom na NAS-ie `sudo tailscale serve --bg 58080`: wypisze adres w
rodzaju `https://nas.tail1234.ts.net`. Aplikacja otwiera się wtedy, dopóki
telefon jest połączony z Tailscale.
**5. Zainstalować pakiet.** Centrum pakietów → Ustawienia → Źródła pakietów →
Dodaj, nazwa `dsm-mini` i adres według twojej architektury:
- Intel i AMD, większość modeli: `https://alexlnos.github.io/dsm-mini/amd64.json`
- ARM, modele budżetowe: `https://alexlnos.github.io/dsm-mini/arm64.json`
Dalej Ustawienia → Ogólne → Poziom zaufania → **Dowolny wydawca**, i
zainstaluj **DSM mini — Telegram Mini App** z sekcji **Społeczność**. Nie masz
pewności co do architektury? Spróbuj `amd64`: niepasujący pakiet po prostu
zostanie odrzucony.
Instalacja o nic nie pyta. Albo zainstaluj `.spk` z
[wydań](https://github.com/alexlnos/dsm-mini/releases) ręcznie, przez Centrum
pakietów → Instalacja ręczna.
**6. Skonfigurować.** Otwórz **DSM mini** z menu głównego DSM albo naciśnij
**Otwórz** w Centrum pakietów — samo o tym przypomni po instalacji. Wypełnij
wartości zebrane w krokach powyżej — okno objaśnia każdą — a w sekcji
**Dostęp do Mini App** wybierz sposób z kroku 4 albo
**Tylko bot, bez Mini App**. Naciśnij **Zapisz**, a potem **Uruchom** u góry
okna. Stan tam pokaże, kiedy DSM i bot odpowiedziały, a jeśli nie — co jest nie
tak.
Dla pierwszego sposobu regułę zwrotnego serwera proxy okno tworzy samo: wpisz
nazwę w polu **Skieruj nazwę do usługi**. Ręcznie to Panel sterowania → Portal
logowania → Zaawansowane → Zwrotny serwer proxy → Utwórz. Źródło: `HTTPS`, twoja
nazwa, port `443`. Miejsce docelowe: `HTTP`, `localhost`, port `58080`. Przy
tunelu lub Tailscale wybierz **Inny sposób** i wpisz adres, który od nich
dostałeś.
> Portu **80** dla tej nazwy nie przepuszczaj przez proxy: przez niego DSM
> odnawia certyfikat, a przechwycenie zepsuje odnowienie trzy miesiące później.
**7. Sprawdzić.** Jeśli jest adres, `https://twoj-adres/healthz` w przeglądarce
powinno odpowiedzieć `{"status":"ok"}`. Bez podpisu Telegrama nic nie jest
wydawane.
**8. Otworzyć aplikację.** Znajdź bota po loginie, naciśnij Start — obok pola
wpisywania pojawi się przycisk **Pobierania**. Wyślij mu dowolny link magnet,
zaproponuje foldery przyciskami. Bez adresu przycisku nie będzie: linki po
prostu wysyłaj botowi na czacie.
## Jeśli coś poszło nie tak
| Co widzisz | O co chodzi | Co zrobić |
|---|---|---|
| Bot milczy na `/start` | Bot jest wyłączony lub nieskonfigurowany albo token jest zły | Otwórz **DSM mini** w menu głównym DSM: stan u góry powie, które z nich, a **Uruchom** włączy bota |
| „Dostęp do tego bota jest zamknięty” | Twojego ID nie ma na liście | Wpisz liczbę z kroku 2 do dozwolonych identyfikatorów w oknie **DSM mini** |
| Nie ma przycisku aplikacji | Publiczny adres jest pusty — wtedy działa sam bot — albo nie jest `https://` | Okno **DSM mini**, sekcja **Dostęp do Mini App** |
| Przycisk jest, aplikacja się nie otwiera | Nie działa zwrotny serwer proxy albo certyfikat | Otwórz `https://twoj-adres/healthz` w przeglądarce |
| „Otwórz aplikację przez bota” | Aplikację otwarto bezpośrednim linkiem w przeglądarce | Tak ma być: otwieraj z bota |
| „Dostęp zamknięty: twoje Telegram ID…” | Usługa cię nie rozpoznała | W dozwolonych identyfikatorach tylko cyfry, po przecinku |
| Okno pisze, że DSM odrzucił logowanie | Hasło, 2FA albo uprawnienia użytkownika | Krok 3: hasło bez literówek, 2FA wyłączona, aplikacje dozwolone |
| Okno pisze, że Download Station nie działa | Nie jest zainstalowany albo jest zabroniony użytkownikowi | Centrum pakietów i uprawnienia z kroku 3 |
| Pakiet zatrzymuje się zaraz po starcie | Jego port zajmuje coś innego — dziennik to powie | Zmień `LISTEN_ADDR` w `config.env` przez SSH (patrz niżej) |
Pierwsze miejsce, gdzie warto spojrzeć, to wiersz stanu u góry okna **DSM
mini**: mówi, czy DSM i Telegram odpowiedziały, a jeśli nie — dlaczego.
Szczegóły są w dzienniku pakietu, `/var/packages/dsm-mini/var/dsm-mini.log`,
który otwiera się też z Centrum pakietów. Dziennik prowadzony jest po angielsku,
okno, interfejs i wiadomości bota — w twoim języku.
### Zmienić ustawienia
**Otwórz DSM mini w menu głównym DSM** — są tam wszystkie ustawienia. Hasło i
token są tylko do zapisu: puste pole zachowuje poprzednią wartość. Zapis działa
od razu: usługa sama restartuje się z nowymi ustawieniami, pakietu nie trzeba
uruchamiać ponownie.
Ustawienia leżą na NAS-ie w jednym pliku `/var/packages/dsm-mini/var/config.env`
z uprawnieniami `600`. Można go też poprawić przez SSH (Panel sterowania →
Terminal i SNMP → włącz SSH), a potem zrestartować pakiet:
```bash
sudo sed -i "s|^TELEGRAM_BOT_TOKEN=.*|TELEGRAM_BOT_TOKEN='twoj-nowy-token'|" /var/packages/dsm-mini/var/config.env
sudo synopkg restart dsm-mini
```
Aktualizacja nie rusza tego pliku, dlatego ustawienia ją przeżywają.
## Aktualizacja
Jeśli źródło pakietów jest dodane, Centrum pakietów samo pokaże aktualizację. Bez
źródła — pobierz świeży `.spk` z
[wydań](https://github.com/alexlnos/dsm-mini/releases) i zainstaluj na wierzchu.
Ustawienia i baza w obu przypadkach zostaną: leżą w katalogu `var` pakietu, a
aktualizacja go nie rusza.
## Gdzie trzymane są dane
Wszystko w `/var/packages/dsm-mini/var/`:
- `config.env` — ustawienia z okna DSM mini, uprawnienia `600`;
- `dsm-mini.db` — baza SQLite: przypięte foldery, język i ostatnie znane statusy
zadań, po których usługa wie, o czym już powiadomiła;
- `dsm-mini.log` — dziennik.
Aktualizacja pakietu zachowuje wszystkie trzy. Odinstalowanie je kasuje.
## Bezpieczeństwo
Usługa jest wystawiona do internetu i potrafi kasować pliki na NAS-ie, dlatego:
- **Osobny użytkownik DSM**, a nie administrator (krok 3).
- **Bez weryfikacji dwuetapowej** na tym koncie: kod jednorazowy nie ma prawa
zadziałać z pliku konfiguracyjnego.
- **Dozwolone identyfikatory to biała lista.** Pusta lista zamyka dostęp
wszystkim, a nie otwiera.
- Każde żądanie do `/api/` sprawdzane jest dwa razy: podpis `initData` kluczem z
tokenu bota i identyfikator wobec listy dozwolonych. Podpis dowodzi tylko
tego, że ktoś otworzył bota — a otworzyć go może każdy.
- Na zewnątrz idzie ogólne zdanie, szczegóły do dziennika: komunikat mówiący, co
dokładnie nie zgadzało się w podpisie, podpowiadałby, jak go podrobić.
- Token bota i hasło DSM żyją wyłącznie w `config.env` na samym NAS-ie z
uprawnieniami `600` i nigdy nie trafiają do dziennika: przy odmowie zapisywana
jest przyczyna, nigdy wartość.
- Usługa słucha tylko na `127.0.0.1` — czyli z samego NAS-a. Wszystko z zewnątrz
idzie przez to, co obsługuje adres publiczny — zwrotny serwer proxy DSM, tunel
albo Tailscale — i to ono kończy też TLS. Bez adresu z zewnątrz nie dociera do
niej nic.
## Rozwój
```bash
cd web && npm install && npm run build # Mini App trafi do internal/web/dist
cd .. && go build ./cmd/dsm-mini # jeden plik binarny z wbudowaną aplikacją
go test ./...
```
Frontend osobno, z automatycznym przeładowaniem:
```bash
cd web && npm run dev # rozmawia z backendem na localhost:58080
```
Lokalne uruchomienie backendu czyta `config.env` ze `STATE_DIR`, tak jak pakiet,
a zmienne środowiskowe uzupełniają to, czego w pliku nie ma. Wygodnie trzymać je
w pliku:
```bash
cp .env.example .env # wypełnij
set -a; . ./.env; set +a
go run ./cmd/dsm-mini
```
Zbudowany interfejs leży w repozytorium (`internal/web/dist`) — stamtąd bierze go
`go:embed`. Po zmianach we frontendzie przebuduj i zacommituj wynik, bo inaczej
kontrole nie przejdą.
Testy integracyjne działają na prawdziwym NAS-ie i domyślnie są pomijane:
```bash
DSM_URL=https://192.168.1.10:5001 DSM_USER=... DSM_PASSWORD=... \
DSM_INSECURE_TLS=true go test -tags=integration ./...
```
Testy zmieniające stan NAS-a wymagają osobnej zgody: `DSM_TEST_MUTATIONS=1`, a
do operacji na plikach jeszcze `DSM_TEST_FOLDER` — folderu, wewnątrz którego
wolno tworzyć pliki tymczasowe. Wszystko, co utworzą, sprzątają po sobie.
Nowy język interfejsu to jeden plik słownika po każdej stronie:
`web/src/i18n/<kod>.ts` i `internal/i18n/<kod>.go`. Pominąć linii się nie da: na
froncie pilnuje tego typ, na serwerze — test.
Kod, komentarze i dziennik w projekcie są po angielsku; pozostałe języki żyją
tylko w słownikach. Szczegóły w [CLAUDE.md](CLAUDE.md).
## Osobliwości API Synology
Web API Synology miejscami zachowuje się inaczej, niż napisano w dokumentacji: ta
sama akcja odpowiada w trzech różnych formatach, `limit = -1` kładzie File
Station, a `_sid` przy wysyłaniu pliku trzeba przekazać inaczej niż wszędzie.
Wszystko, co ustalono na żywym NAS-ie, zebrano w
[docs/synology-api.md](docs/synology-api.md).
## Licencja
[MIT](LICENSE)