Dropbox Cloud-Backup konfigurieren

Diese Anleitung erklärt, wie Sie Fermentrack 2 konfigurieren, um Dropbox Cloud-Backup für Benutzer Ihrer Instanz zu aktivieren. Nach der Konfiguration können Benutzer ihre Dropbox-Konten verknüpfen und Backups direkt in ihren persönlichen Dropbox-Speicher hochladen.

observação

Jede Fermentrack 2-Instanz benötigt eigene Dropbox-App-Anmeldedaten. Wenn Sie eine selbst gehostete Instanz betreiben, müssen Sie Ihre eigene Dropbox-App im Dropbox Developer Portal erstellen.

Übersicht

Die Dropbox-Integration verwendet OAuth 2.0, um Benutzerkonten sicher zu verbinden. Wenn ein Benutzer die Verbindung initiiert:

Er wird zu Dropbox weitergeleitet, um die Verbindung zu autorisieren
Dropbox leitet mit einem Autorisierungscode zurück zu Fermentrack
Fermentrack tauscht den Code gegen Zugriffs- und Aktualisierungstoken ein
Token werden verschlüsselt in der Datenbank gespeichert
Benutzer können dann Backups in ihr Dropbox-Konto hochladen

Alle Backup-Dateien werden im dedizierten Ordner der App innerhalb von Dropbox gespeichert (/Apps/Fermentrack/ oder Ihr gewählter App-Name).

Schritt 1: Eine Dropbox-App erstellen

Gehen Sie zum Dropbox Developer Portal
Melden Sie sich mit Ihrem Dropbox-Konto an (oder erstellen Sie eines, falls nötig)
Klicken Sie auf App erstellen
Konfigurieren Sie die App mit diesen Einstellungen:

Wählen Sie eine API: Wählen Sie Scoped access

Wählen Sie den benötigten Zugriffstyp: Wählen Sie App folder

observação
"App folder"-Zugriff wird empfohlen, da er Fermentrack auf den Zugriff auf Dateien innerhalb seines eigenen dedizierten Ordners beschränkt (/Apps/IhrAppName/). Dies ist die sicherste Option und Benutzer werden sich wohler fühlen, den Zugriff zu gewähren.

Benennen Sie Ihre App: Geben Sie einen Namen für Ihre App ein (z.B. Fermentrack Backups oder MeineBrauerei Fermentrack). Dieser Name wird Benutzern während des Autorisierungsprozesses angezeigt.

aviso
App-Namen müssen über alle Dropbox-Apps hinweg eindeutig sein. Wenn Ihr bevorzugter Name vergeben ist, versuchen Sie, Ihren Brauerei-Namen oder eine eindeutige Kennung hinzuzufügen.
Klicken Sie auf App erstellen

Schritt 2: App-Berechtigungen konfigurieren

Nach dem Erstellen der App müssen Sie ihre Berechtigungen konfigurieren:

Klicken Sie auf der Einstellungsseite Ihrer App auf den Tab Permissions
Aktivieren Sie unter Files and folders die folgenden Berechtigungen:
- files.metadata.read - Informationen über Dateien und Ordner anzeigen
- files.content.write - Dateien erstellen, ändern und löschen
- files.content.read - Inhalt von Dateien anzeigen (für Verifizierung benötigt)
Klicken Sie auf Submit, um die Berechtigungsänderungen zu speichern

important
Nach dem Ändern von Berechtigungen müssen Benutzer, die ihre Konten bereits verbunden haben, möglicherweise erneut autorisieren, um die neuen Berechtigungen zu gewähren.

Schritt 3: OAuth 2-Einstellungen konfigurieren

Gehen Sie zum Tab Settings Ihrer App
Konfigurieren Sie unter OAuth 2 Folgendes:

Allow public clients (Implicit Grant & PKCE): Lassen Sie dies deaktiviert (No)

Redirect URIs: Fügen Sie die OAuth-Callback-URL für Ihre Fermentrack-Instanz hinzu:
```
https://ihre-fermentrack-domain.de/api/cloud_storage/connections/oauth_callback/
```
observação
- Ersetzen Sie ihre-fermentrack-domain.de durch Ihre tatsächliche Domain
- Sie müssen HTTPS für Produktionsbereitstellungen verwenden
- Für lokale Entwicklung können Sie verwenden:
  http://localhost:8000/api/cloud_storage/connections/oauth_callback/
Access token expiration: Verwenden Sie die Standardeinstellung (kurzlebige Token mit Aktualisierungstoken)
Notieren Sie Ihren App key und App secret von dieser Seite - Sie benötigen diese für den nächsten Schritt

aviso
Halten Sie Ihr App secret vertraulich. Committen Sie es niemals in die Versionskontrolle oder teilen Sie es öffentlich.

Schritt 4: Fermentrack 2 konfigurieren

Fügen Sie die Dropbox-Anmeldedaten zu Ihrer Fermentrack 2-Umgebungskonfiguration hinzu:

Öffnen Sie Ihre .env-Datei (oder .envs/.local/.django für lokale Entwicklung, oder .envs/.production/.django für Produktion)
Fügen Sie die folgenden Umgebungsvariablen hinzu:
```
# Dropbox Cloud Storage Konfiguration
DROPBOX_APP_KEY=ihr_app_key_hier
DROPBOX_APP_SECRET=ihr_app_secret_hier
```
Ersetzen Sie ihr_app_key_hier und ihr_app_secret_hier durch die Werte aus Ihren Dropbox-App-Einstellungen.

Starten Sie Fermentrack 2 neu, damit die Änderungen wirksam werden:

Für Docker-Bereitstellungen:

docker-compose -f production.yml down
docker-compose -f production.yml up -d

Für lokale Entwicklung:

# Stoppen Sie den laufenden Server und starten Sie ihn erneut
uv run python manage.py runserver

Schritt 5: Konfiguration überprüfen

Um zu überprüfen, ob die Dropbox-Integration richtig konfiguriert ist:

Melden Sie sich bei Ihrer Fermentrack 2-Instanz an

Die Cloud-Storage-API sollte nun Dropbox als verfügbaren Anbieter anzeigen. Sie können dies überprüfen, indem Sie aufrufen:

https://ihre-fermentrack-domain.de/api/cloud_storage/providers/

Sie sollten eine Antwort wie diese sehen:

[
   {
      "provider_id": "dropbox",
      "display_name": "Dropbox",
      "is_enabled": true
   }
]

Wenn is_enabled false ist oder die Liste leer ist, überprüfen Sie:
- Die Umgebungsvariablen sind korrekt gesetzt
- Die Anwendung wurde nach dem Hinzufügen der Variablen neu gestartet
- Es gibt keine Tippfehler in den Variablennamen oder Werten

Benutzererfahrung

Nach der Konfiguration können Benutzer ihre Dropbox-Konten über die Fermentrack-Benutzeroberfläche (wenn die Frontend-Integration abgeschlossen ist) oder über die API verbinden:

Verbindung initiieren: Benutzer klickt auf "Dropbox verbinden", was den initiate_auth-Endpunkt aufruft
Dropbox-Autorisierung: Benutzer wird zu Dropbox weitergeleitet, um sich anzumelden und die Verbindung zu autorisieren
Rückkehr zu Fermentrack: Nach der Autorisierung wird der Benutzer zurück zu Fermentrack geleitet
Verbindung abgeschlossen: Die Verbindung wird gespeichert und der Benutzer kann nun Backups hochladen

Backups hochladen:

Nach der Verbindung können Benutzer jedes abgeschlossene Backup in ihre Dropbox hochladen. Backups werden im App-Ordner gespeichert (z.B. /Apps/Fermentrack/Fermentrack Backups/).

Fehlerbehebung

"Provider not enabled"-Fehler:

Überprüfen Sie, ob DROPBOX_APP_KEY und DROPBOX_APP_SECRET korrekt gesetzt sind
Stellen Sie sicher, dass die Anwendung nach dem Setzen der Variablen neu gestartet wurde
Überprüfen Sie auf Tippfehler in den Umgebungsvariablennamen

"Invalid redirect URI"-Fehler von Dropbox:

Stellen Sie sicher, dass die Redirect-URI in Ihren Dropbox-App-Einstellungen genau mit Ihrer Fermentrack-URL übereinstimmt
Stellen Sie sicher, dass Sie HTTPS für Produktion verwenden
Überprüfen Sie auf abschließende Schrägstriche - sie müssen genau übereinstimmen

"Invalid state parameter"-Fehler:

Die OAuth-Sitzung ist möglicherweise abgelaufen (10-Minuten-Timeout)
Versuchen Sie, den Verbindungsprozess erneut zu starten
Stellen Sie sicher, dass Cookies im Browser des Benutzers aktiviert sind

Token-Aktualisierungsfehler:

Der Benutzer muss möglicherweise die Verbindung erneut autorisieren
Überprüfen Sie, ob die Dropbox-App-Berechtigungen nach der ersten Verbindung geändert wurden
Stellen Sie sicher, dass die App noch im Dropbox Developer Portal aktiv ist

Upload-Fehler:

Überprüfen Sie, ob das Dropbox-Konto des Benutzers ausreichend Speicherplatz hat
Stellen Sie sicher, dass die Backup-Datei unter 150MB ist (größere Dateien erfordern Chunked Upload, noch nicht implementiert)
Überprüfen Sie die Celery-Worker-Logs auf detaillierte Fehlermeldungen

Sicherheitsüberlegungen

Token-Speicherung: OAuth-Token werden im Ruhezustand mit Fernet symmetrischer Verschlüsselung verschlüsselt (via django-fernet-encrypted-fields)
Token-Aktualisierung: Zugriffs-Token sind kurzlebig und werden bei Bedarf automatisch mit Aktualisierungs-Token erneuert
App-Ordner-Zugriff: Die Verwendung des "App folder"-Zugriffstyps stellt sicher, dass Fermentrack nur auf seinen eigenen Ordner innerhalb der Dropbox-Konten der Benutzer zugreifen kann
CSRF-Schutz: OAuth-State-Token werden verwendet, um Cross-Site-Request-Forgery-Angriffe während des Autorisierungsablaufs zu verhindern
Multi-Tenant-Isolation: Die Verbindungen jedes Brauhauses sind isoliert; Benutzer können nur auf ihre eigenen Verbindungen und Backups zugreifen

API-Referenz

Für Entwickler, die die Cloud-Storage-API integrieren:

Anbieter auflisten:

GET /api/cloud_storage/providers/

Verbindungen auflisten:

GET /api/cloud_storage/connections/

OAuth initiieren:

POST /api/cloud_storage/connections/initiate_auth/

Request-Body:

{"provider": "dropbox"}

OAuth abschließen:

POST /api/cloud_storage/connections/complete_auth/

Request-Body:

{
   "provider": "dropbox",
   "code": "authorization_code",
   "state": "state_token"
}

Upload auslösen:

POST /api/cloud_storage/uploads/upload/

Request-Body:

{
   "connection_id": "uuid",
   "backup_request_id": "uuid"
}

Uploads auflisten:

GET /api/cloud_storage/uploads/

Übersicht​

Schritt 1: Eine Dropbox-App erstellen​

Schritt 2: App-Berechtigungen konfigurieren​

Schritt 3: OAuth 2-Einstellungen konfigurieren​

Schritt 4: Fermentrack 2 konfigurieren​

Schritt 5: Konfiguration überprüfen​

Benutzererfahrung​

Fehlerbehebung​

Sicherheitsüberlegungen​

API-Referenz​

Übersicht

Schritt 1: Eine Dropbox-App erstellen

Schritt 2: App-Berechtigungen konfigurieren

Schritt 3: OAuth 2-Einstellungen konfigurieren

Schritt 4: Fermentrack 2 konfigurieren

Schritt 5: Konfiguration überprüfen

Benutzererfahrung

Fehlerbehebung

Sicherheitsüberlegungen

API-Referenz