SFTPGo Smart-Home-Integration, kostenlos und Open Source
Dein SFTPGo-Dateiserver in Gladys: Verbindungen, Kontingente und eine Szene bei jedem Upload.
Veröffentlicht von guim31
- Geräte
- Version 1.0.0
- Erfordert Gladys >=5.1.0
- ★ 0
SFTPGo ist ein freier Dateiserver (SFTP, FTP/S, WebDAV und Web), den viele zu Hause betreiben: Ein Scanner schickt seine PDFs dorthin, eine Kamera ihre Bilder, ein Handy seine Fotos. Diese Integration bringt einen SFTPGo-Server in Gladys: die offenen Verbindungen, die Benutzer und ihre Kontingente, und vor allem einen Szenen-Auslöser, wenn eine Datei hochgeladen wird, mit Benutzer, Pfad, Größe und Protokoll. Außerdem warnt die Integration, wenn ein Kontingent eine Schwelle überschreitet oder eine Anmeldung abgelehnt wird, und ein Dashboard-Widget listet die zuletzt hochgeladenen Dateien.
Getestet mit einem echten SFTPGo 2.7 (Docker-Images drakkan/sftpgo und
drakkan/sftpgo:plugins mit PostgreSQL): Uploads über SFTP und WebDAV,
Kontingente, abgelehnte Anmeldungen, API-Schlüssel und Admin-Passwort, mit und
ohne Ereignisprotokoll. Noch nicht mit einem echten Gladys getestet: Rückmeldungen
gern in den Issues.
Was du brauchst
- Gladys Assistant 5.1.0 oder neuer.
- SFTPGo 2.x mit seinem Webserver (standardmäßig Port 8080), vom Gladys-Rechner
aus erreichbar: Die Integration nutzt seine REST-API (
/api/v2). - Einen SFTPGo-Admin (keinen Benutzer des Dateiservers) mit den
Berechtigungen
view_users,view_connsundview_events: am besten einen eigenen Admin für Gladys. Entweder seinen API-Schlüssel oder seinen Benutzernamen und sein Passwort. - Für Uploads und abgelehnte Anmeldungen: das Ereignisprotokoll von
SFTPGo, also seine Plugins
eventstoreundeventsearch(siehe unten). Ohne es funktionieren Verbindungen, Benutzer und Kontingente, aber keine Uploads.
Die Integration liest SFTPGo standardmäßig alle 30 Sekunden: ein paar leichte Anfragen in deinem eigenen Netz.
Erste Schritte
1. Einen Admin für Gladys anlegen
In der Web-Administration von SFTPGo, Admins → Add: ein Benutzername, ein
Passwort und nur die Berechtigungen view_users, view_conns und
view_events. Für einen API-Schlüssel stattdessen „API key authentication“ im
Profil dieses Admins anhaken und dann unter API keys einen Schlüssel
anlegen (Bereich „Admin“).
2. Das Ereignisprotokoll einschalten (für die Uploads)
Die Uploads kommen aus dem Ereignisprotokoll von SFTPGo, geschrieben und
gelesen von zwei Plugins aus dem Image drakkan/sftpgo:plugins. Diese brauchen
eine PostgreSQL- oder MySQL-Datenbank (SQLite unterstützen die Plugins nicht).
Mit Docker Compose ergänzt du das environment von SFTPGo:
SFTPGO_PLUGINS__0__TYPE: notifier
SFTPGO_PLUGINS__0__NOTIFIER_OPTIONS__FS_EVENTS: upload
SFTPGO_PLUGINS__0__NOTIFIER_OPTIONS__LOG_EVENTS: 1,2
SFTPGO_PLUGINS__0__CMD: /usr/local/bin/sftpgo-plugin-eventstore
SFTPGO_PLUGINS__0__ARGS: serve
SFTPGO_PLUGINS__0__AUTO_MTLS: "1"
SFTPGO_PLUGIN_EVENTSTORE_DRIVER: postgres
SFTPGO_PLUGIN_EVENTSTORE_DSN: "host=db user=sftpgo password=… dbname=sftpgo_events sslmode=disable"
SFTPGO_PLUGIN_EVENTSTORE_RETENTION: "720"
SFTPGO_PLUGINS__1__TYPE: eventsearcher
SFTPGO_PLUGINS__1__CMD: /usr/local/bin/sftpgo-plugin-eventsearch
SFTPGO_PLUGINS__1__ARGS: serve
SFTPGO_PLUGINS__1__AUTO_MTLS: "1"
SFTPGO_PLUGIN_EVENTSEARCH_DRIVER: postgres
SFTPGO_PLUGIN_EVENTSEARCH_DSN: "host=db user=sftpgo password=… dbname=sftpgo_events sslmode=disable"
FS_EVENTS: upload speichert die Uploads, LOG_EVENTS: 1,2 die abgelehnten
Anmeldungen (falsches Passwort, unbekannter Benutzer); RETENTION behält 30
Tage. Ohne diese Plugins antwortet SFTPGo „no events searcher plugin defined“,
und die Integration zeigt das in ihrem Status und Widget; sie fragt jede Stunde
erneut.
3. Die Integration konfigurieren
Unter Integrationen → SFTPGo → Konfiguration:
- SFTPGo-Adresse: die Adresse der Weboberfläche, z. B.
http://192.168.1.2:8080(eine aus dem Browser kopierte Adresse geht auch). - Admin-API-Schlüssel oder Admin-Benutzername und Admin-Passwort.
- Aktualisierungsintervall: 10 Sekunden bis 5 Minuten. Es ist auch die Verzögerung der Szene bei einer hochgeladenen Datei.
- Kontingent-Warnschwelle: 70 bis 95 %.
- Sprache der Namen: die Sprache der Funktionsnamen und der Texte der Integration (standardmäßig Französisch).
Verbindung testen antwortet zum Beispiel „SFTPGo: verbunden (2.7.6), 3 Benutzer, 1 Verbindung(en), Uploads werden verfolgt“.
4. Die Geräte anlegen
Lege im Tab Entdecken den Server und die Benutzer an, die du verfolgen willst. Die Szenen-Auslöser funktionieren für alle Benutzer, angelegt oder nicht.
Die Geräte
SFTPGo (der Server):
| Funktion | Bedeutung |
|---|---|
| Online | 1, solange SFTPGo antwortet |
| Uploads verfolgt | 1, wenn das Ereignisprotokoll antwortet |
| Verbindungen | offene Verbindungen (SFTP, FTP, WebDAV, Web) |
| Laufende Übertragungen | laufende Uploads und Downloads |
| Benutzer | Benutzer des Servers |
| Heute hochgeladene Dateien | seit Mitternacht hochgeladene Dateien (Protokoll) |
| Heute abgelehnte Anmeldungen | seit Mitternacht abgelehnte Anmeldungen (Protokoll) |
SFTPGo <Benutzer> (einer pro Benutzer):
| Funktion | Bedeutung |
|---|---|
| Belegtes Größenkontingent | % seines Größenkontingents, 0 ohne Größenkontingent |
| Belegtes Dateikontingent | % seines Dateikontingents, 0 ohne Dateikontingent |
| Belegter Speicher | MB, wenn SFTPGo das Kontingent des Benutzers verfolgt |
| Dateien | Dateien, gleiche Bedingung |
| Verbindungen | seine offenen Verbindungen |
| Heute hochgeladene Dateien | seine Uploads seit Mitternacht (Protokoll) |
| Zuletzt hochgeladene Datei | Pfad seiner zuletzt hochgeladenen Datei (Protokoll) |
| Zeit des letzten Uploads | Tag/Monat Stunden:Minuten dieses Uploads (Protokoll) |
Standardmäßig verfolgt SFTPGo Speicher und Dateien nur bei Benutzern mit
Kontingent (track_quota 2): Die anderen haben weder Belegter Speicher
noch Dateien.
Dashboard
Das Widget SFTPGo-Uploads zeigt drei Kacheln (heute hochgeladene Dateien, Verbindungen, abgelehnte Anmeldungen des Tages) und dann die acht zuletzt hochgeladenen Dateien, die neueste zuerst, mit Benutzer und Uhrzeit. In seinen Einstellungen wählst du die gezeigten Benutzer (leer: alle). Der Button Aktualisieren liest SFTPGo neu.
Szenen
Auslöser
- Eine Datei wird hochgeladen: Ein Benutzer lädt eine Datei hoch, über
jedes Protokoll. Filter: Benutzer, Ordner (genau, z. B.
/scans), Endung (pdf). Variablen: Benutzer, Pfad, Ordner, Dateiname, Endung, Größe, Größe in Bytes, Protokoll, Client-Adresse. Höchstens zwanzig Uploads werden pro Lesen gemeldet: Ein Ordner mit 500 Fotos startet nicht 500 Szenen. - Ein Kontingent überschreitet die Schwelle: Ein Benutzer überschreitet die Schwelle der Konfiguration (Größen- oder Dateikontingent). Einmal, dann erst wieder, wenn die Nutzung 5 Punkte unter die Schwelle gesunken ist.
- Eine Anmeldung wird abgelehnt: falsches Passwort oder unbekannter Benutzer. Ein Ereignis pro Benutzer und Adresse bei jedem Lesen, mit der Zahl der Versuche.
Aktionen
- Zustand eines Benutzers: liest Kontingent, belegten Speicher, Verbindungen, heute hochgeladene Dateien und die letzte Datei eines Benutzers, und einen fertigen Satz: „scanner: Kontingent zu 42 % belegt, letzte Datei /scans/rechnung.pdf am 22.10., 08:12.“
Szenen-Ideen
- Eine Datei wird hochgeladen, Ordner
/scans, Endungpdf→ „Neuer Scan: {{triggerEvent.data.file_name}}“ per Telegram senden. - Eine Datei wird vom Benutzer „camera“ hochgeladen → das Licht im Flur einschalten und eine Nachricht senden.
- Eine Anmeldung wird abgelehnt → mit Adresse und Zahl der Versuche benachrichtigen.
- Jeden Sonntag Zustand eines Benutzers → den Satz senden.
Fehlerbehebung
- „SFTPGo antwortet nicht“: Prüfe Adresse und Port der Weboberfläche (standardmäßig 8080), vom Gladys-Rechner aus.
- „API-Schlüssel, Benutzername oder Passwort von SFTPGo abgelehnt“: Es braucht die Zugangsdaten eines Admins, nicht eines Benutzers. Ein API-Schlüssel braucht „API key authentication“ im Admin-Profil.
- „der Admin braucht die Berechtigungen view_users und view_conns“: Gib sie dem Admin der Integration.
- Kein Upload zu sehen: Starte Verbindung testen. „kein Ereignisprotokoll“ heißt, dass die Plugins fehlen (Schritt 2); „view_events“, dass dem Admin diese Berechtigung fehlt. Uploads von vor dem Start der Integration werden nicht gemeldet, nur gezählt.
- Kein Belegter Speicher bei einem Benutzer: SFTPGo verfolgt sein
Kontingent nicht; gib ihm ein Kontingent oder setze
SFTPGO_DATA_PROVIDER__TRACK_QUOTA=1. - Protokolle:
LOG_LEVEL=debugzeigt jedes Lesen und jeden Upload.
Grenzen
- Ohne die Plugins des Ereignisprotokolls ist kein Upload zu sehen. Die Integration kann die HTTP-Aktionen der Ereignisregeln von SFTPGo nicht empfangen: Es gibt keinen offenen Port.
- Ein Upload wird beim nächsten Lesen gemeldet (standardmäßig 30 Sekunden).
- Nur lesend: Die Integration ändert nichts in SFTPGo.
- Ein SFTPGo-Server pro Integration; bis zu 2.500 Benutzer.
- Entwickelt und getestet mit einem echten SFTPGo in Docker, noch nicht mit jeder Installation: Rückmeldungen willkommen.
Konfigurationseinstellungen
Diese Einstellungen fragt SFTPGo in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Dein SFTPGo-Server | section | Nein | Gib die Adresse der SFTPGo-Weboberfläche und einen Admin-API-Schlüssel ein, oder Benutzername und Passwort eines Admins mit den Berechtigungen view_users, view_conns und view_events. Lege dann Server und Benutzer im Tab „Entdecken“ an. |
| SFTPGo-Adresse | string | Ja | Die Adresse der Weboberfläche, standardmäßig Port 8080. |
| Admin-API-Schlüssel | secret | Nein | Optional: ein API-Schlüssel eines Admins, der ihn nutzen darf. Sonst fülle die zwei Felder darunter aus. |
| Admin-Benutzername | string | Nein | Ein SFTPGo-Admin, kein Benutzer des Dateiservers. |
| Admin-Passwort | secret | Nein | |
| Uploads und abgelehnte Anmeldungen | section | Nein | Dafür braucht es das Ereignisprotokoll von SFTPGo: seine Plugins eventstore und eventsearch (Image drakkan/sftpgo:plugins, mit PostgreSQL oder MySQL). Ohne diese Plugins funktioniert der Rest. |
| Aktualisierungsintervall | select | Nein | Auch die Verzögerung der Szene bei einer hochgeladenen Datei. |
| Kontingent-Warnschwelle | select | Nein | Der Szenen-Auslöser startet, wenn ein Benutzer sie überschreitet. |
| Sprache der Namen | select | Nein | Namen der Funktionen und Texte der Integration. |
So installierst du SFTPGo in Gladys
- Öffne in Gladys Integrationen: SFTPGo erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/guim31/gladys-sftpgo:1.0.0) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-sftpgo.
SFTPGo benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
SFTPGo ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von guim31 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation