Rozwiązywanie problemów z instalacją

Większość problemów z instalacją wynika z niezgodności adresu URL, braku SMTP, zablokowanych portów lub utraty kluczy tajnych. Zacznij od widocznego adresu URL w przeglądarce i pracuj w głąb systemu.

Publiczne linki otwierają się na moim komputerze, ale nie u klientów

Sprawdź, jaki adres URL został skopiowany lub wysłany.

• http://localhost/... działa tylko na tym samym komputerze.
• http://192.168.x.x/... działa tylko w sieci LAN lub VPN. VPN może być prawidłowym rozwiązaniem dla zespołów wewnętrznych, ale nie stanowi strategii publicznych linków dla klientów.
• https://crm.example.com/... działa publicznie tylko wtedy, gdy DNS, HTTPS, proxy i firewall są skonfigurowane poprawnie.

W przypadku publicznych linków dla klientów, wdrażaj za pomocą publicznej domeny, używając publicznego serwera Ubuntu lub Coolify.

Przeglądarka wyświetla błędy CORS

CORS_ALLOWED_ORIGINS musi dokładnie zgadzać się z originem przeglądarki. Poniższe adresy to różne originy:

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

Popraw zmienną, ponownie wdroż aplikację i spróbuj ponownie w nowej sesji przeglądarki.

Wiadomości e-mail nie są dostarczane

Najpierw sprawdź:

• SMTP_HOST i SMTP_PORT są poprawne.
• SMTP_AUTH=true, gdy Twój dostawca wymaga uwierzytelniania.
• SMTP_STARTTLS=true dla portu 587.
• SMTP_USERNAME i SMTP_PASSWORD są prawidłowe.
• Dostawca zezwala na logowanie SMTP/hasło aplikacji.
• NOTIFICATIONS_EMAIL_ENABLED=true, gdy wiadomości e-mail z powiadomieniami powinny być wysyłane.

Ręczne udostępnianie linków publicznych i pobieranie PDF mogą nadal działać bez SMTP.

Linki do preferencji powiadomień są nieprawidłowe

Ustaw:

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

Nie zostawiaj go wskazującego na localhost w publicznym wdrożeniu.

Kontenery Docker są w stanie unhealthy

Uruchom:

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

Typowe przyczyny:

• PostgreSQL wciąż się uruchamia.
• DB_PASSWORD różni się między PostgreSQL a backendem.
• DB_ENCRYPTION_KEY jest brakujący lub ma nieprawidłowy format.
• Gotenberg nie jest w stanie healthy, więc generowanie PDF nie może się rozpocząć.
• Porty hosta 80/443 są już używane przez inną usługę.

Po naprawieniu konfiguracji, zrestartuj dotkniętą usługę lub cały stos:

docker compose restart backend
docker compose up -d

Moje IP jest zablokowane — nie mogę się zalogować

Są dwie typowe przyczyny: lista dozwolonych IP zablokowała dostęp lub ochrona przed brute-force zablokowała IP po zbyt wielu nieudanych próbach logowania.

Blokada przez listę dozwolonych IP

QuoteNode posiada listę dozwolonych adresów IP konfigurowalną w Ustawienia > Bezpieczeństwo > Lista dozwolonych IP (lub przez zmienną SECURITY_IP_WHITELIST). Po włączeniu obejmuje ona całą powierzchnię administracyjną — łącznie z ekranami logowania i 2FA — więc wykluczony adres dostaje 403 IP_NOT_ALLOWED i nie może się nawet zalogować. (Health-checki oraz publiczne linki do ofert klientów pozostają dostępne.)

Najpierw poczekaj dwie minuty, jeśli właśnie zmieniłeś listę w aplikacji. Włączenie lub zawężenie w aplikacji jest chronione przed blokadą: musi zostać potwierdzone przez Twoją sesję w krótkim oknie (domyślnie 120 s), a jeśli Twój bieżący adres nie jest objęty, lista automatycznie wraca do poprzedniej. Przypadkowa samoblokada z ekranu Bezpieczeństwa sama się więc naprawia — poczekaj i spróbuj ponownie. (Ta siatka bezpieczeństwa nie dotyczy zmiennej SECURITY_IP_WHITELIST, która jest egzekwowana przy starcie.)

Odzyskiwanie (override operatora): jeśli nadal nie masz dostępu — np. operatorska SECURITY_IP_WHITELIST, nieprawidłowa zapisana lista lub nie możesz czekać — dodaj tę zmienną do środowiska kontenera backend (.env lub sekcja environment: w docker-compose) i zrestartuj:

SECURITY_IP_WHITELIST_FORCE_DISABLE=true

docker compose restart backend

To wyłącza listę dozwolonych IP i pozwala się zalogować. Po zalogowaniu popraw listę w Ustawienia > Bezpieczeństwo, a następnie usuń SECURITY_IP_WHITELIST_FORCE_DISABLE i zrestartuj ponownie.

Nie zostawiaj SECURITY_IP_WHITELIST_FORCE_DISABLE=true w produkcji. Wyłącza to całą kontrolę dostępu po IP.

Blokada przez ochronę brute-force

QuoteNode blokuje adresy IP po zbyt wielu nieudanych próbach logowania w ciągu godziny:

Próg	Niepowodzenia w 1 h	Efekt
Soft	10	Postępujące opóźnienie (1 s na każdą dodatkową próbę, maks. 30 s)
Tymczasowa blokada	20	Zablokowany na 5 minut
Trwała blokada	50	Zablokowany do ręcznego odblokowania

Jak odblokować:

1. Panel admina — inny administrator otwiera Ustawienia > Panel bezpieczeństwa > Zablokowane IP i klika Odblokuj.
2. Czekanie — tymczasowe blokady wygasają po SECURITY_TEMP_LOCK_MINUTES (domyślnie 5 minut). Trwałe blokady nie wygasają samoistnie.
3. Tymczasowe podniesienie progów jeśli jesteś zablokowany i żaden inny admin nie może pomóc. Dodaj do .env, zrestartuj, zaloguj się, a potem usuń:

SECURITY_MAX_FAILED_LOGINS_SOFT=9999
SECURITY_MAX_FAILED_LOGINS_TEMP_LOCK=9999
SECURITY_MAX_FAILED_LOGINS_HARD_LOCK=9999

Przywróć domyślne wartości po odzyskaniu dostępu.

Blokady IP linków publicznych

Rate limiter linków publicznych blokuje adresy IP po przekroczeniu limitów prób. Te blokady są przechowywane w pamięci i wygasają po PUBLIC_RATE_LIMIT_IP_BLOCK_MINUTES (domyślnie 60 minut) lub po restarcie backendu.

Certyfikat HTTPS nie zostaje wystawiony

W przypadku publicznych wdrożeń:

• DNS musi wskazywać na serwer wdrożeniowy.
• Porty 80 i 443 muszą być osiągalne z internetu.
• Tylko jeden proxy powinien zakończyć HTTPS dla tej samej domeny.
• W Coolify, przypisz domenę do usługi frontend.

Zgubiłem plik .env

Jeśli zgubiłeś plik .env, zatrzymaj się i oceń sytuację przed rotacją wartości.

• DB_PASSWORD zazwyczaj można zresetować z dostępem administratora PostgreSQL.
• TIMING_TOKEN_SECRET i PUBLIC_LINK_PASSWORD_SESSION_SECRET mogą zostać zregenerowane, ale istniejące sesje/tokeny mogą wygasnąć.
• DB_ENCRYPTION_KEY jest krytyczny. Bez oryginalnego klucza zaszyfrowane wartości nie mogą zostać odszyfrowane.
• Jeśli szyfrowanie PII jest włączone, zaszyfrowane pola klienta/kontaktu zależą od DB_ENCRYPTION_KEY.

Przywróć plik .env z kopii zapasowej, gdy tylko to możliwe.

Odzyskiwanie po utracie .env przy posiadaniu kopii zapasowej bazy danych

1. Utwórz nowy .env z nowymi sekretami.
2. Przywróć bazę danych z kopii zapasowej (pg_dump / pg_restore).
3. Wszystkie dane biznesowe (klienci, oferty, produkty, użytkownicy) będą w pełni dostępne.
4. Utracone zostaną tylko nieliczne pola: kody MFA (użytkownicy ponownie się rejestrują), hasło SMTP (wpisz ponownie w ustawieniach), klucz FX API (wpisz ponownie). Jeśli ENCRYPT_PII=true było włączone, zaszyfrowane dane klientów również przepadają.

Jeśli kopie zapasowe są szyfrowane age (ustawienie domyślne), potrzebujesz pliku tożsamości age z zestawu odzyskiwania, aby je odszyfrować. Zapoznaj się z przewodnikiem Kopie zapasowe i odzyskiwanie.

Zapomniałem hasła administratora

Użyj niedestrukcyjnej ścieżki odzyskiwania:

1. Jeśli SMTP jest skonfigurowany, skorzystaj ze strony logowania: Zapomniałeś hasła?
2. Jeśli inny administrator może się zalogować, otwórz Użytkownicy w panelu administratora i zresetuj hasło.
3. Jeśli żaden administrator nie może się zalogować, a procedura resetowania przez e-mail jest niedostępna, przywróć dostęp z dobrze działającej kopii zapasowej lub zastosuj wewnętrzną procedurę konserwacyjną.

docker compose down -v nie jest procedurą resetowania hasła. Usuwa wszystkie dane — użytkowników, oferty, klientów, ustawienia i kopie zapasowe. Używaj tylko dla jednorazowych środowisk testowych.

Weryfikacja licencji nie powiodła się

W przypadku rzeczywistych wdrożeń, zachowaj:

LICENSE_SKIP_SIGNATURE_CHECK=false

Jeśli prawidłowa licencja nadal nie działa, sprawdź czy wdrożenie ma oczekiwaną wersję aplikacji i zsynchronizowany z NTP zegar systemowy. Potwierdź, że licencja odpowiada wdrożonej edycji/wersji, a następnie skontaktuj się z pomocą techniczną lub zastąp plik licencji poprzez udokumentowaną ścieżkę operatora. Nie ustawiaj pomijania podpisu na true jako obejścia produkcyjnego.