Einführung

Dieses Dokument beschreibt die Einrichtung und Konfiguration eines automatisierten Dienstes zur Übertragung von Export Job Dateien auf einen FTP/SFTP-Server. Die Dateien werden durch den werner-backend Prozess generiert und lokal im Dateisystem abgelegt. Mit Hilfe des bereitgestellten Skripts sftp_pusher.sh können diese Dateien in regelmässigen Abständen automatisch auf einen FTP-Server hochgeladen werden.

Das Skript unterstützt folgende Protokolle:

SFTP (SSH File Transfer Protocol) - Standard
FTP (File Transfer Protocol) - unverschlüsselt
FTPS (FTP mit SSL/TLS) - für Server wie Hetzner Storage Box

Funktionsweise

Das Skript überwacht ein lokales Verzeichnis auf neue Dateien eines bestimmten Musters (z.B. *.json oder *.csv) und überträgt diese auf den konfigurierten SFTP-Server. Nach erfolgreicher Übertragung werden die lokalen Dateien gelöscht.

Übertragungsmodi

Das Skript unterstützt zwei Übertragungsmodi:

Atomarer Transfer (ohne Control-Verzeichnis): Die Datei wird zunächst mit der Endung .tmp auf den Server übertragen und anschliessend in den finalen Dateinamen umbenannt. Dies stellt sicher, dass empfangende Systeme nur vollständig übertragene Dateien verarbeiten.
Mit Control-Verzeichnis: Eine Datei wird nur übertragen, wenn sie sowohl im lokalen Daten-Verzeichnis (--data-dir) als auch im lokalen Control-Verzeichnis (--control-dir) vorhanden ist. Die Control-Datei dient als "Ready"-Signal, dass die Datenerzeugung abgeschlossen ist. Nach erfolgreicher Übertragung werden beide lokalen Dateien (Daten- und Control-Datei) gelöscht.
Der Ablauf ist:
- Prüfen ob die Datei in beiden lokalen Verzeichnissen existiert
- Datei aus dem Daten-Verzeichnis auf den Server in --target-dir hochladen
- Falls --target-control-dir angegeben: dieselbe Datei zusätzlich in das Control-Verzeichnis auf dem Server hochladen
- Bei Erfolg: Falls --save-dir angegeben, Datei ins Archiv kopieren
- Lokale Datei aus --data-dir und --control-dir löschen

Voraussetzungen

lftp Installation

Das Skript verwendet lftp für die SFTP-Kommunikation. Installieren Sie lftp auf Ihrem System:

Debian/Ubuntu:

sudo apt-get update
sudo apt-get install lftp

RHEL/CentOS:

sudo yum install lftp

Verzeichnisstruktur

Stellen Sie sicher, dass die lokalen Verzeichnisse für Export Jobs existieren und vom ausführenden Benutzer beschrieben werden können. Diese Verzeichnisse werden in der export_job_definition als path_to_save und optional path_to_copy_to konfiguriert.

Skript-Parameter

Das Skript sftp_pusher.sh akzeptiert die folgenden benannten Parameter:

Parameter	Erforderlich	Beschreibung
`--host`	Ja	Hostname des FTP/SFTP-Servers
`--user`	Ja	FTP/SFTP-Benutzername
`--password`	Ja	FTP/SFTP-Passwort
`--protocol`	Nein	Übertragungsprotokoll: `sftp`, `ftp` oder `ftps` (Standard: `sftp`). Verwenden Sie `ftps` für FTP mit SSL/TLS.
`--data-dir`	Ja	Lokales Verzeichnis mit den zu übertragenden Dateien (entspricht `path_to_save`)
`--target-dir`	Ja	Zielverzeichnis auf dem SFTP-Server
`--file-pattern`	Ja	Dateimuster für die Übertragung (z.B. `".json"`, `".csv"`). Wichtig: Das Muster muss in Anführungszeichen gesetzt werden!
`--control-dir`	Nein	Lokales Control-Verzeichnis (entspricht `path_to_copy_to`). Wenn angegeben, muss eine Datei in beiden Verzeichnissen vorhanden sein, um übertragen zu werden.
`--target-control-dir`	Nein	Ziel-Control-Verzeichnis auf dem SFTP-Server für Signal-Dateien
`--save-dir`	Nein	Lokales Archiv-Verzeichnis. Erfolgreich übertragene Dateien werden hierhin kopiert, bevor sie aus data-dir/control-dir gelöscht werden.

Mapping zu export_job_definition

Die Konfiguration der export_job_definition in der Datenbank definiert, wo die Export-Dateien lokal gespeichert werden:

export_job_definition Spalte	Skript-Parameter
`path_to_save`	`--data-dir`
`path_to_copy_to`	`--control-dir`
`export_job_definition_target_type`	`--file-pattern` (z.B. `json` → `*.json`)

Einrichten des Cronjobs

Für die automatisierte Übertragung empfehlen wir die Verwendung eines Cronjobs. Der folgende Abschnitt zeigt ein konkretes Beispiel basierend auf einer existierenden export_job_definition.

Beispiel: ABACUS Artikelinventur Export

Gegeben ist folgende Export Job Definition:

export_job_definition (id=2):
  name:                 ABACUS Artikelinventur
  export_job_type:      article_inventory
  target_type:          json
  path_to_save:         /tmp/werner/interface/out/abacus-article-inventory/data
  path_to_copy_to:      /tmp/werner/interface/out/abacus-article-inventory/control
  encoding:             UTF-8
  locale:               de-CH

Manueller Aufruf

/path/to/werner-backend/scripts/sftp_pusher.sh \
  --host ftp.abacus.example.com \
  --user export_user \
  --password "geheimes_passwort" \
  --data-dir /tmp/werner/interface/out/abacus-article-inventory/data \
  --control-dir /tmp/werner/interface/out/abacus-article-inventory/control \
  --save-dir /tmp/werner/interface/out/abacus-article-inventory/archive \
  --target-dir /in/artikel-inventur \
  --target-control-dir /in/artikel-inventur/control \
  --file-pattern "*.json"

Cronjob einrichten

Öffnen Sie die Crontab des Benutzers, unter dem das Skript ausgeführt werden soll:

crontab -e

Fügen Sie folgende Zeile hinzu, um das Skript alle 5 Minuten auszuführen:

*/5 * * * * /home/werner/werner-backend/scripts/sftp_pusher.sh \
  --host ftp.abacus.example.com \
  --user export_user \
  --password "geheimes_passwort" \
  --data-dir /tmp/werner/interface/out/abacus-article-inventory/data \
  --control-dir /tmp/werner/interface/out/abacus-article-inventory/control \
  --save-dir /tmp/werner/interface/out/abacus-article-inventory/archive \
  --target-dir /in/artikel-inventur \
  --target-control-dir /in/artikel-inventur/control \
  --file-pattern "*.json" >> /var/log/sftp_pusher_abacus.log 2>&1

Der --save-dir Parameter ist optional. Wenn angegeben, werden erfolgreich übertragene Dateien in dieses Verzeichnis kopiert, bevor sie aus dem data-dir und control-dir gelöscht werden. Das Archiv-Verzeichnis wird automatisch erstellt, falls es nicht existiert.

Cronjob ohne Control-Verzeichnis

Falls kein Control-Verzeichnis benötigt wird (z.B. wenn die export_job_definition kein path_to_copy_to definiert), verwenden Sie den atomaren Übertragungsmodus:

*/5 * * * * /home/werner/werner-backend/scripts/sftp_pusher.sh \
  --host ftp.abacus.example.com \
  --user export_user \
  --password "geheimes_passwort" \
  --data-dir /tmp/werner/interface/out/abacus-article-inventory/data \
  --target-dir /in/artikel-inventur \
  --file-pattern "*.json" >> /var/log/sftp_pusher_abacus.log 2>&1

In diesem Modus werden Dateien zunächst mit der Endung .tmp übertragen und anschliessend auf dem Server in den finalen Namen umbenannt. Dies garantiert, dass das empfangende System nur vollständig übertragene Dateien sieht.

Fehlerbehebung

"no matches found" Fehler (zsh)

Wenn Sie den Fehler zsh: no matches found: *.json erhalten, haben Sie vergessen, das Dateimuster in Anführungszeichen zu setzen:

# Falsch - Shell expandiert *.json im aktuellen Verzeichnis
--file-pattern *.json

# Richtig - Muster wird als String an das Skript übergeben
--file-pattern "*.json"

Wenn Sie den Fehler "Login incorrect" erhalten, obwohl die Anmeldedaten korrekt sind, verwenden Sie wahrscheinlich das falsche Protokoll. Hetzner Storage Boxes und ähnliche Dienste erfordern FTPS (FTP mit SSL):

# Falsch - SFTP funktioniert nicht bei allen Servern
--protocol sftp

# Richtig - FTPS für Server mit SSL/TLS
--protocol ftps

Verbindungsprobleme

Testen Sie die Verbindung manuell:

# SFTP
lftp -u <user>,<password> sftp://<host>

# FTPS (z.B. Hetzner Storage Box)
lftp -e "set ftp:ssl-force true; set ftp:ssl-protect-data true; set ssl:verify-certificate false" \
  -u <user>,<password> ftp://<host>

Berechtigungsfehler

Stellen Sie sicher, dass:

Das lokale Daten-Verzeichnis existiert und lesbar ist
Der ausführende Benutzer Schreibrechte auf das Log-Verzeichnis hat
Der SFTP-Benutzer Schreibrechte auf das Zielverzeichnis hat

Log-Analyse

Überprüfen Sie die Log-Datei auf Fehler:

tail -f /var/log/sftp_pusher_abacus.log

Das Skript gibt detaillierte Informationen über jede Dateiübertragung aus, inklusive Erfolgs- und Fehlermeldungen.