Installations-Fehlerbehebung

Die meisten Installationsprobleme entstehen durch URL-Missmatch, fehlendes SMTP, blockierte Ports oder verlorene Secrets. Beginnen Sie mit der sichtbaren URL in Ihrem Browser und arbeiten Sie nach innen.

Öffentliche Links öffnen auf meinem Computer, aber nicht für Kunden

Überprüfen Sie, welche URL kopiert oder gesendet wurde.

• http://localhost/... funktioniert nur auf demselben Gerät.
• http://192.168.x.x/... funktioniert nur im LAN oder VPN. VPN kann eine valide Brücke für interne Teams sein, aber keine öffentliche Kundenlink-Strategie.
• https://crm.example.com/... funktioniert öffentlich nur, wenn DNS, HTTPS, Proxy und Firewall korrekt sind.

Für öffentliche Kundenlinks stellen Sie mit einer öffentlichen Domain unter Verwendung von Ubuntu-Oeffentlichserver oder Coolify bereit.

Browser zeigt CORS-Fehler

CORS_ALLOWED_ORIGINS muss exakt mit dem Browser-Ursprung übereinstimmen. Dies sind unterschiedliche Ursprünge:

https://crm.example.com
https://www.crm.example.com
http://crm.example.com
https://crm.example.com:8443

Korrigieren Sie die Variable, stellen Sie erneut bereit und versuchen Sie es in einer frischen Browser-Sitzung.

E-Mail wird nicht zugestellt

Überprüfen Sie zuerst diese Punkte:

• SMTP_HOST und SMTP_PORT sind korrekt.
• SMTP_AUTH=true, wenn Ihr Provider Authentifizierung erfordert.
• SMTP_STARTTLS=true für Port 587.
• SMTP_USERNAME und SMTP_PASSWORD sind gültig.
• Der Provider erlaubt SMTP/App-Passwort-Login.
• NOTIFICATIONS_EMAIL_ENABLED=true, wenn Benachrichtigungs-E-Mails gesendet werden sollen.

Manuelles öffentliches-Link-Teilen und PDF-Download können auch ohne SMTP funktionieren.

Benachrichtigungs-Einstellungslinks sind falsch

Setzen Sie:

NOTIFICATIONS_PUBLIC_PREFERENCES_URL=https://<frontend-domain>/notifications/preferences

Lassen Sie es nicht in einer öffentlichen Bereitstellung auf localhost zeigen.

Docker-Container sind nicht gesund

Führen Sie aus:

docker compose ps
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f gotenberg

Häufige Ursachen:

• PostgreSQL startet noch.
• DB_PASSWORD unterscheidet sich zwischen PostgreSQL und Backend.
• DB_ENCRYPTION_KEY fehlt oder ist fehlerhaft.
• Gotenberg ist nicht gesund, daher kann die PDF-Generierung nicht starten.
• Host-Ports 80/443 werden bereits von einem anderen Dienst verwendet.

Nach der Korrektur der Konfiguration starten Sie den betroffenen Dienst oder den Stack neu:

docker compose restart backend
docker compose up -d

Meine IP ist blockiert — Anmeldung nicht möglich

Es gibt zwei häufige Ursachen: Die IP-Allowlist hat den Zugang gesperrt oder der Brute-Force-Schutz hat Ihre IP nach zu vielen fehlgeschlagenen Anmeldeversuchen blockiert.

Sperrung durch IP-Allowlist

QuoteNode verfügt über eine IP-Allowlist, die unter Einstellungen > Sicherheit > IP-Allowlist konfiguriert wird (oder über die Umgebungsvariable SECURITY_IP_WHITELIST). Wenn aktiviert, schützt sie die gesamte Admin-Oberfläche — einschließlich der Login- und 2FA-Bildschirme — sodass eine ausgeschlossene Adresse 403 IP_NOT_ALLOWED erhält und sich nicht einmal anmelden kann. (Health-Checks und kundenseitige öffentliche Angebotslinks bleiben erreichbar.)

Warten Sie zunächst zwei Minuten, wenn Sie die Liste gerade in der App geändert haben. Ein Aktivieren oder Einschränken in der App ist sperrgeschützt: Es muss von Ihrer Sitzung innerhalb eines kurzen Fensters (Standard 120 s) erneut bestätigt werden, und wenn Ihre aktuelle Adresse nicht abgedeckt ist, wird die Liste automatisch auf die vorherige zurückgesetzt. Eine versehentliche Selbstsperre über den Sicherheitsbildschirm heilt sich also selbst — warten Sie und versuchen Sie es erneut. (Dieses Sicherheitsnetz gilt nicht für die Variable SECURITY_IP_WHITELIST, die beim Start durchgesetzt wird.)

Wiederherstellung (Operator-Override): Wenn Sie weiterhin ausgesperrt sind — z. B. durch ein Operator-SECURITY_IP_WHITELIST, eine ungültige gespeicherte Liste oder weil Sie nicht warten können — fügen Sie diese Variable zur Backend-Container-Umgebung hinzu (.env oder environment:-Abschnitt in docker-compose) und starten Sie neu:

SECURITY_IP_WHITELIST_FORCE_DISABLE=true

docker compose restart backend

Dies umgeht die Allowlist vollständig und ermöglicht die Anmeldung. Korrigieren Sie nach der Anmeldung die Allowlist unter Einstellungen > Sicherheit, entfernen Sie dann SECURITY_IP_WHITELIST_FORCE_DISABLE und starten Sie erneut.

Lassen Sie SECURITY_IP_WHITELIST_FORCE_DISABLE=true nicht in der Produktion aktiviert. Es deaktiviert die gesamte IP-Zugriffskontrolle.

Sperrung durch Brute-Force-Schutz

QuoteNode blockiert IP-Adressen nach zu vielen fehlgeschlagenen Anmeldeversuchen innerhalb einer Stunde:

Schwelle	Fehlversuche in 1 h	Auswirkung
Soft	10	Progressive Verzögerung (1 s pro Versuch über Schwelle, max. 30 s)
Temporäre Sperre	20	Gesperrt für 5 Minuten
Dauerhafte Sperre	50	Gesperrt bis zur manuellen Freigabe

Entsperren:

1. Admin-Panel — ein anderer Administrator öffnet Einstellungen > Sicherheits-Dashboard > Blockierte IPs und klickt Entsperren.
2. Warten — temporäre Sperren laufen nach SECURITY_TEMP_LOCK_MINUTES (Standard 5 Minuten) ab. Dauerhafte Sperren laufen nicht von selbst ab.
3. Schwellenwerte temporär erhöhen, wenn Sie gesperrt sind und kein anderer Admin helfen kann. Zur .env hinzufügen, neu starten, anmelden, dann entfernen:

SECURITY_MAX_FAILED_LOGINS_SOFT=9999
SECURITY_MAX_FAILED_LOGINS_TEMP_LOCK=9999
SECURITY_MAX_FAILED_LOGINS_HARD_LOCK=9999

Setzen Sie diese Werte nach Wiedererlangung des Zugangs auf die Standardwerte zurück.

IP-Sperren für öffentliche Links

Der Rate-Limiter für öffentliche Links blockiert IP-Adressen, die Probe- oder Fehlerlimits überschreiten. Diese Sperren sind im Arbeitsspeicher und laufen nach PUBLIC_RATE_LIMIT_IP_BLOCK_MINUTES (Standard 60 Minuten) oder nach einem Backend-Neustart ab.

HTTPS-Zertifikat wird nicht ausgestellt

Für öffentliche Bereitstellungen:

• DNS muss auf den Bereitstellungsserver zeigen.
• Ports 80 und 443 müssen aus dem Internet erreichbar sein.
• Nur ein Proxy sollte HTTPS für dieselbe Domain terminieren.
• In Coolify weisen Sie die Domain dem frontend-Dienst zu.

Ich habe .env verloren

Wenn Sie .env verloren haben, stoppen Sie und bewerten Sie, bevor Sie Werte rotieren.

• DB_PASSWORD kann normalerweise mit PostgreSQL-Admin-Zugang zurückgesetzt werden.
• TIMING_TOKEN_SECRET und PUBLIC_LINK_PASSWORD_SESSION_SECRET können neu generiert werden, aber bestehende Sitzungen/Tokens können ablaufen.
• DB_ENCRYPTION_KEY ist kritisch. Ohne den ursprünglichen Schlüssel können verschlüsselte Werte nicht entschlüsselt werden.
• Wenn PII-Verschlüsselung aktiviert ist, hängen verschlüsselte Kunden-/Kontaktfelder von DB_ENCRYPTION_KEY ab.

Stellen Sie .env wann immer möglich aus einem Backup wieder her.

Wiederherstellung bei Verlust von .env mit vorhandenem Datenbank-Backup

1. Erstellen Sie eine neue .env mit neuen Secrets.
2. Stellen Sie die Datenbank aus Ihrem Backup wieder her (pg_dump / pg_restore).
3. Alle Geschäftsdaten (Kunden, Angebote, Produkte, Benutzer) sind vollständig zugänglich.
4. Nur wenige Felder gehen verloren: MFA-Codes (Benutzer registrieren sich erneut), SMTP-Passwort (in den Einstellungen neu eingeben), FX-API-Schlüssel (neu eingeben). Wenn ENCRYPT_PII=true aktiviert war, gehen auch verschlüsselte Kundendaten verloren.

Wenn Ihre Backups mit age verschlüsselt sind (Standardeinstellung), benötigen Sie die age-Identitätsdatei aus Ihrem Wiederherstellungs-Kit, um sie zu entschlüsseln. Siehe die Anleitung Backup und Wiederherstellung.

Admin-Passwort vergessen

Verwenden Sie einen nicht-destruktiven Wiederherstellungspfad:

1. Wenn SMTP konfiguriert ist, nutzen Sie die Login-Seite: Passwort vergessen?
2. Wenn ein anderer Administrator sich noch anmelden kann, öffnen Sie Benutzer im Admin-Panel und setzen Sie das Passwort zurück.
3. Wenn kein Administrator sich anmelden kann und der E-Mail-Reset-Ablauf nicht verfügbar ist, stellen Sie den Zugang aus einem bekannten guten Backup wieder her oder verwenden Sie Ihre interne Wartungsprozedur.

docker compose down -v ist kein Passwort-Reset-Verfahren. Es löscht alle Daten — Benutzer, Angebote, Kunden, Einstellungen und Backups. Verwenden Sie es nur für einwegige Testumgebungen.

Lizenzverifizierung schlägt fehl

Für echte Bereitstellungen halten Sie:

LICENSE_SKIP_SIGNATURE_CHECK=false

Wenn eine gültige Lizenz trotzdem fehlschlägt, überprüfen Sie, ob die Bereitstellung die erwartete App-Version und eine NTP-synchronisierte Systemuhr hat. Bestätigen Sie, dass die Lizenz zur bereitgestellten Edition/Version passt, dann kontaktieren Sie den Support oder ersetzen Sie die Lizenzdatei über den dokumentierten Betreiberpfad. Setzen Sie die Signatur-Umgehung nicht als Produktions-Workaround auf true.