Zum Hauptinhalt springen

Fehlerbehebung beim Self-Hosting

Beginnen Sie mit den Logs: docker compose logs --tail=200 app. Mehr Details erhalten Sie mit LOG_LEVEL=debug (setzen Sie den Wert danach wieder zurück).

Die App startet nicht​

  • Das Log nennt eine Umgebungsvariable: Eine Pflichtvariable fehlt oder ist zu kurz: APP_URL (eine vollständige URL), DATABASE_URL, AUTH_SECRET (16+ Zeichen), APP_ENCRYPTION_KEY (32+ Zeichen). Siehe Konfiguration.
  • Datenbank nicht erreichbar: Prüfen Sie docker compose ps (der Service db muss healthy sein) und ob sich POSTGRES_PASSWORD seit dem Anlegen der Datenbank geändert hat (das Passwort wird nur beim ersten Start mit einem leeren Volume gesetzt).
  • Eine Migration schlägt fehl: Bearbeiten Sie die Datenbank nicht von Hand. Stellen Sie das Backup von vor dem Upgrade wieder her und melden Sie den Fehler mit den Log-Zeilen.

Die Betriebsbereitschaft prüfen Sie mit curl -fsS http://127.0.0.1:3000/api/ready.

Probleme bei der Anmeldung​

  • Weiterleitung an die falsche Adresse, oder Cookies bleiben nicht erhalten: APP_URL muss exakt die öffentliche HTTPS-Adresse sein, und der Proxy muss X-Forwarded-Proto weitergeben (Reverse-Proxy und TLS).
  • „Zu viele Versuche“ für alle: Alle Anfragen scheinen von einer Adresse zu kommen. Korrigieren Sie die Behandlung von X-Forwarded-For im Proxy und TRUST_PROXY_HOPS (Client-IP-Adressen).
  • Single Sign-on scheitert nach der Seite des Providers: Die beim Provider registrierte Redirect-URI muss exakt der unter Admin → Authentifizierung entsprechen; prüfen Sie den Issuer mit Verbindung testen.
  • Passkeys funktionieren nicht mehr: Die Domain in APP_URL hat sich geändert. Die Personen fügen ihre Passkeys neu hinzu.
  • Aus allen Admin-Konten ausgesperrt: Legen Sie über die Kommandozeile einen Owner an oder befördern Sie ein Konto dazu (Installation).

E-Mails kommen nicht an​

  • MAIL_DRIVER muss smtp sein; mit log erscheinen Nachrichten nur im App-Log.
  • Suchen Sie im Log nach Mail-Fehlern (Authentifizierung fehlgeschlagen, Verbindung abgelehnt, TLS-Fehler). Port 465 braucht SMTP_SECURE=true, Port 587 braucht false.
  • Zugestellt, aber im Spam: Richten Sie SPF, DKIM und DMARC für die Absenderdomain ein (E-Mail).
  • Neue Konten hängen bei Prüfen Sie Ihre E-Mails fest: Sie brauchen die Bestätigungs-E-Mail. Beheben Sie den Versand oder schalten Sie E-Mail-Bestätigung verlangen unter Admin → Authentifizierung aus (E-Mail-Bestätigung).

Uploads schlagen fehl​

  • Scheitern bei größeren Dateien sofort: Das Body-Limit des Proxys liegt unter der Chunk-Größe (bei nginx standardmäßig 1 MB). Siehe Reverse-Proxy und TLS.
  • „Diese Datei ist größer als die Grenze von …“: Erhöhen Sie die maximale Dateigröße unter Admin → Allgemein → Uploads. Ein Workspace-Admin kann für seinen Workspace ein niedrigeres Limit festlegen.
  • S3: Uploads funktionieren, Downloads nicht: Browser müssen die Adresse des Buckets erreichen; setzen Sie S3_PUBLIC_ENDPOINT (Speicher).
  • S3: Chunk-Größe abgelehnt: S3 braucht Chunks von mindestens 5 MB.

Webhooks werden nicht zugestellt​

  • Die Instanz oder der Workspace hat Webhooks ausgeschaltet (Admin → Allgemein → API oder die Einstellungen des Workspaces).
  • Das Ziel liegt in einem privaten Netzwerk: nur erlaubt mit Webhooks an private Netzwerkadressen erlauben.
  • Ein Webhook, der 20-mal hintereinander fehlgeschlagen ist, schaltet sich selbst ab; schalten Sie ihn wieder ein, nachdem Sie den Empfänger repariert haben. Siehe Webhooks.

Kommen Sie nicht weiter?​

Sammeln Sie die Version (SOL2FLOW_VERSION), die relevanten Log-Zeilen (ohne Secrets und personenbezogene Daten) und die Schritte zum Reproduzieren, und wenden Sie sich an Ihren sol2flow-Supportkanal.