Backup i Recovery

QuoteNode ma wbudowany system backupow, ktory chroni dane handlowe przed awariami sprzetu, przypadkowym usunieciem i incydentami operacyjnymi.

Co obejmuje backup

Kazdy backup zawiera trzy komponenty:

1. Dump bazy danych — pelny dump PostgreSQL w formacie custom (pg_dump --format=custom), obejmujacy wszystkie tabele, sekwencje i ograniczenia.
2. Storage plikow — wszystkie wyslane pliki (obrazy produktow, logotypy firmy) oraz wygenerowane PDF-y, spakowane jako files.tar.gz.
3. Manifest integralnosci — plik checksums.sha256 zawierajacy sumy SHA-256 zarowno dumpa bazy, jak i archiwum plikow, co pozwala sprawdzic, czy backup nie zostal uszkodzony ani zmodyfikowany.

Backup online

Backup online dziala wtedy, gdy aplikacja normalnie obsluguje ruch. Nie ma przestoju.

Jak to dziala:

• pg_dump w formacie custom tworzy transakcyjnie spojny snapshot bazy bez blokowania tabel i bez zatrzymywania zapytan.
• Storage plikow jest archiwizowany rownolegle — poniewaz uploady i PDF-y sa niezmienne po utworzeniu, archiwum pozostaje spojne.
• Oba artefakty sa sumowane kontrolnie i opcjonalnie szyfrowane przed zapisem.

Ograniczenia:

• Jezeli dokladnie w chwili wykonywania dumpa trwa transakcja, jej niezatwierdzone dane nie wejda do backupu. To poprawne zachowanie — dump reprezentuje spojny stan w konkretnym momencie.
• Dla wiekszosci organizacji to w pelni wystarczajace. Backup online jest rekomendowanym trybem pracy.

Backup offline

Dla maksymalnej gwarancji spojnosci, na przyklad przed wiekszym upgradem lub migracja:

1. Zatrzymaj kontenery aplikacyjne (docker compose stop backend backup-worker).
2. Uruchom pg_dump bezposrednio na dzialajacym kontenerze PostgreSQL.
3. Zarchiwizuj wolumeny ze storage plikow.
4. Ponownie uruchom aplikacje.

Takie podejscie eliminuje ryzyko transakcji “w locie”, ale wymaga krotkiego okna serwisowego, zwykle 1-5 minut w zaleznosci od rozmiaru bazy.

Harmonogram

Backupami zarzadza kontener backup-worker, czyli dedykowana instancja backendu pracujaca w trybie backup-only:

• Domyslny harmonogram: codziennie o 2:00 (0 0 2 * * *, konfigurowane przez BACKUP_CRON)
• Wlaczanie i wylaczanie: BACKUP_ENABLED=true|false
• Reczny trigger: administrator moze uruchomic backup natychmiast z panelu admina albo przez API (POST /api/v1/admin/backup/trigger)
• Ochrona przed rownoleglym uruchomieniem: wzorzec SKIP LOCKED gwarantuje, ze jednoczesnie wykona sie tylko jeden backup, nawet gdy istnieje kilka workerow

Opcje storage

Lokalny storage

Backupy sa zapisywane w katalogu BACKUP_LOCAL_DIR (domyslnie /app/data/backups), zamapowanym do wolumenu Dockera. To wystarcza dla developmentu i malych wdrozen.

W produkcji lokalny backup powinien byc uzupelniony kopia zdalna — backup zapisany na tym samym dysku co baza nie chroni przed awaria dysku.

Storage zdalny przez rclone

Jesli ustawisz BACKUP_RCLONE_REMOTE, backup po zapisaniu lokalnym zostanie automatycznie wyslany do zewnetrznego celu. rclone obsluguje ponad 70 dostawcow storage, miedzy innymi:

• Systemy zgodne z S3 — AWS S3, MinIO, DigitalOcean Spaces, Backblaze B2
• Google Cloud Storage
• Azure Blob Storage
• SFTP — dowolny serwer z dostepem SSH
• WebDAV — Nextcloud, ownCloud i podobne

Jesli upload zdalny sie nie powiedzie, backup lokalny pozostaje zachowany, a blad jest logowany.

Szyfrowanie

Backupy moga byc szyfrowane w storage przez GPG:

• Ustaw BACKUP_GPG_RECIPIENT na identyfikator klucza GPG albo adres email.
• Skrypt backupu szyfruje zarowno dump bazy, jak i archiwum plikow przed zapisem.
• Zaszyfrowane pliki otrzymuja rozszerzenie .gpg.
• Odszyfrowanie wymaga odpowiedniego klucza prywatnego — bez niego backup jest nieczytelny.

To jest szczegolnie wazne dla organizacji, ktore przechowuja backupy u zewnetrznego dostawcy chmury i nie chca, aby storage provider mial dostep do tresci backupu.

Metadane i audyt

Kazdy backup, udany lub nieudany, trafia do tabeli backup_logs:

Pole	Opis
Status	PENDING, RUNNING, COMPLETED, FAILED
Zainicjowany przez	SCHEDULER (automatycznie) lub ADMIN (reczny trigger)
Czas startu	Chwila rozpoczecia backupu
Czas zakonczenia	Chwila zakonczenia backupu
Rozmiar (bytes)	Laczny rozmiar archiwum backupu
Cel	Lokalna sciezka albo zdalny URL
Checksum SHA-256	Hash integralnosci archiwum
Komunikat bledu	Przyczyna niepowodzenia (jesli wystapila)

50 ostatnich wpisow backupowych jest dostepnych w panelu admina albo przez API.

Odtwarzanie

Pelne odtworzenie

1. Zatrzymaj wszystkie kontenery aplikacyjne: docker compose down
2. Odtworz baze:

   pg_restore --clean --if-exists -d quotenode backup.dump

3. Wypakuj storage plikow:

   tar xzf files.tar.gz -C /app/data/

4. Uruchom wszystkie kontenery: docker compose up -d
5. Sprawdz, czy checksum zgadza sie z manifestem backupu.

Odtwarzanie czesciowe

Custom dump PostgreSQL pozwala odtwarzac pojedyncze tabele albo podzbiory danych za pomoca pg_restore z flagami dla konkretnych tabel. To przydaje sie przy odzyskiwaniu pojedynczych rekordow bez pelnego restore.

Odtwarzanie backupow zaszyfrowanych

Dla backupow zaszyfrowanych GPG:

gpg --decrypt backup.dump.gpg > backup.dump
gpg --decrypt files.tar.gz.gpg > files.tar.gz

Po tym wykonujesz standardowa procedure restore.

Timeout backupu

Kazda operacja backupu ma 30 minut limitu czasu. Jesli backup nie zakonczy sie w tym oknie, jest przerywany i zapisywany jako FAILED. Dla bardzo duzych baz (10+ GB) limit moze zostac zwiekszony konfiguracyjnie.

Pobieranie backupow

Administratorzy moga pobierac archiwa backupow bezposrednio z panelu admina:

1. Przejdz do Settings > Backup.
2. Znajdz backup, ktory chcesz pobrac (status musi byc Success).
3. Kliknij przycisk Download przy wybranym wpisie.

Plik backupu to archiwum .tar.gz zawierajace dump bazy, storage plikow oraz manifest integralnosci. Trzeba przechowywac je bezpiecznie — zawiera komplet danych biznesowych.

Pobrane backupy moga posluzyc do disaster recovery na nowym serwerze albo do migracji do innego srodowiska hostingowego.

Uwaga: backupow przechowywanych tylko w storage zdalnym (S3, SFTP itp.) nie pobierzesz przez panel admina. Trzeba je pobrac bezposrednio od dostawcy storage.

Retencja backupow

Stare lokalne backupy sa automatycznie czyszczone po kazdym udanym backupie. Polityke retencji ustawia BACKUP_RETENTION_DAILY (domyslnie: 7). System zachowuje N ostatnich udanych backupow i usuwa starsze pliki lokalne.

Backupy zdalne (wyslane przez rclone) nie sa usuwane przez QuoteNode — tam polityke retencji trzeba ustawic po stronie storage providera.

Disaster recovery od zera

Serwer przestal istniec. Masz plik backupu (.tar.gz pobrany z panelu admina albo zapisany w storage zdalnym). Masz nowy serwer z Dockerem. Tak odtworzysz calosc.

Krok 1 — przygotuj nowy serwer

Utworz katalog projektu i przygotuj konfiguracje dokladnie tak, jak opisano w Instalacji:

mkdir quotenode && cd quotenode

Potrzebujesz dwoch plikow:

• docker-compose.yml — skopiowanego z instrukcji instalacji
• .env — odtworzonego z Twojej kopii backupowej

Krytyczne: uzyj tego samego DB_ENCRYPTION_KEY, co w oryginalnej instalacji. Bez niego zaszyfrowane dane (kody MFA, dane SMTP oraz PII, jesli ENCRYPT_PII=true) stana sie trwale nieczytelne.

Krok 2 — skopiuj plik backupu na serwer

Przenies backup za pomoca scp, rsync albo dowolnego narzedzia transferowego:

scp quotenode-backup-20260320.tar.gz user@new-server:~/quotenode/

Krok 3 — pobierz skrypt restore

cp /path/to/your/quotenode-repository/scripts/restore.sh .
chmod +x restore.sh

Jesli repozytorium QuoteNode znajduje sie na innym komputerze, najpierw skopiuj ten sam plik na serwer:

scp /path/to/your/quotenode-repository/scripts/restore.sh user@new-server:~/quotenode/

Krok 4 — uruchom restore

./restore.sh --fresh-install ~/quotenode/quotenode-backup-20260320.tar.gz

Skrypt:

1. uruchomi kontener bazy danych
2. poczeka na jego gotowosc
3. odtworzy baze z dumpa backupowego
4. uruchomi caly stack aplikacyjny
5. przywroci uploady i wygenerowane PDF-y
6. wykona health check potwierdzajacy, ze wszystko dziala

Krok 5 — weryfikacja

Otworz domene w przegladarce i zaloguj sie starymi danymi. Klienci, oferty, produkty i ustawienia powinny wygladac dokladnie tak, jak w momencie wykonania backupu.

Dry run

Aby zweryfikowac backup bez modyfikowania systemu:

RESTORE_DRY_RUN=true ./restore.sh --fresh-install backup-file.tar.gz

Polecenie wypakuje i zweryfikuje archiwum, sprawdzi checksums i pokaze plan restore — bez dotykania bazy i storage plikow.

Zalecana strategia backupu

Dla produkcji:

1. Wlacz codzienne backupy automatyczne razem ze storage zdalnym (S3, SFTP lub podobnym).
2. Wlacz szyfrowanie GPG dla backupow przechowywanych poza Twoja infrastruktura.
3. Regularnie testuj procedure restore — backup, ktory nigdy nie byl odtworzony, nie jest zaufanym backupem.
4. Pobieraj backup na lokalna maszyne co najmniej raz w miesiacu — storage zdalny nie zastapi kopii offline.
5. Monitoruj logi backupow w panelu admina. Panel pokazuje ostrzezenie, jesli w ostatnich 48 godzinach nie bylo zadnego udanego backupu.
6. Trzymaj co najmniej 7 dni historii backupow (BACKUP_RETENTION_DAILY=7, domyslnie).