Baza danych

SnapOtter używa PostgreSQL 17 z Drizzle ORM (pg-core / node-postgres) do trwałego przechowywania danych. Schemat jest zdefiniowany w apps/api/src/db/schema.ts.

Połączenie konfiguruje się za pomocą zmiennej środowiskowej DATABASE_URL (domyślnie postgres://snapotter:snapotter@postgres:5432/snapotter). W Docker Compose kontener Postgres przechowuje swoje dane w nazwanym wolumenie SnapOtter-pgdata.

Tabele

users

Przechowuje konta użytkowników. Tworzone automatycznie przy pierwszym uruchomieniu na podstawie DEFAULT_USERNAME i DEFAULT_PASSWORD.

Kolumna	Typ	Uwagi
id	uuid	Klucz główny
username	varchar	Unikalna, wymagana
passwordHash	varchar	Hash scrypt
role	varchar	admin, editor lub user
mustChangePassword	boolean	Flaga wymuszonego resetu hasła
createdAt	timestamp	Czas utworzenia
updatedAt	timestamp	Czas ostatniej aktualizacji

sessions

Aktywne sesje logowania. Każdy wiersz wiąże token sesji z użytkownikiem.

Kolumna	Typ	Uwagi
id	varchar	Klucz główny (token sesji)
userId	uuid	Klucz obcy do users.id
expiresAt	timestamp	Czas wygaśnięcia
createdAt	timestamp	Czas utworzenia

teams

Grupy służące do organizowania użytkowników. Administratorzy mogą przypisywać użytkowników do zespołów.

Kolumna	Typ	Opis
id	uuid	Klucz główny
name	varchar (unikalna, maks. 50 znaków)	Nazwa zespołu
createdAt	timestamp	Czas utworzenia

api_keys

Klucze API do dostępu programowego. Surowy klucz jest pokazywany jednorazowo podczas tworzenia; przechowywany jest tylko jego hash.

Kolumna	Typ	Uwagi
id	uuid	Klucz główny
userId	uuid	Klucz obcy do users.id
keyHash	varchar	Hash scrypt klucza
name	varchar	Etykieta podana przez użytkownika
createdAt	timestamp	Czas utworzenia
lastUsedAt	timestamp	Aktualizowany przy każdym uwierzytelnionym żądaniu

Klucze mają prefiks si_, po którym następuje 96 znaków szesnastkowych (48 losowych bajtów).

pipelines

Zapisane łańcuchy narzędzi, które użytkownicy tworzą w interfejsie.

Kolumna	Typ	Uwagi
id	uuid	Klucz główny
name	varchar	Nazwa potoku
description	varchar	Opcjonalny opis
steps	jsonb	Tablica obiektów { toolId, settings }
createdAt	timestamp	Czas utworzenia

user_files

Trwała biblioteka plików. Zapisana edycja jest domyślnie wstawiana jako niezależny wiersz główny („zapisz jako nowy": version 1, parentId null, więc oryginał pozostaje na liście) albo jako wersja powiązana z rodzicem, gdy nadpisujesz oryginał (parentId ustawiony, version zwiększony, zastępując go). Kolumna toolChain zapisuje zastosowane narzędzia.

Kolumna	Typ	Opis
id	uuid	Klucz główny
userId	uuid	Klucz obcy do users (CASCADE DELETE)
originalName	varchar	Oryginalna nazwa przesłanego pliku
storedName	varchar	Nazwa pliku na dysku
mimeType	varchar	Typ MIME
size	integer	Rozmiar pliku w bajtach
width	integer	Szerokość obrazu w px
height	integer	Wysokość obrazu w px
version	integer	Numer wersji (1 = oryginał)
parentId	uuid lub null	Klucz obcy do user_files (wersja rodzica)
toolChain	jsonb	Identyfikatory narzędzi zastosowane w kolejności, aby wytworzyć tę wersję
createdAt	timestamp	Czas utworzenia

jobs

Śledzi zadania przetwarzania na potrzeby raportowania postępu i porządkowania.

Kolumna	Typ	Uwagi
id	uuid	Klucz główny
type	varchar	Identyfikator narzędzia lub potoku
status	varchar	queued, processing, completed lub failed
progress	real	Ułamek 0.0-1.0
inputFiles	jsonb	Tablica ścieżek plików wejściowych
outputPath	varchar	Ścieżka do pliku wynikowego
settings	jsonb	Użyte ustawienia narzędzia
error	varchar	Komunikat o błędzie w razie niepowodzenia
createdAt	timestamp	Czas utworzenia
completedAt	timestamp	Czas zakończenia

settings

Magazyn klucz-wartość dla ustawień obowiązujących w całym serwerze, które administratorzy mogą zmieniać z poziomu interfejsu.

Kolumna	Typ	Uwagi
key	varchar	Klucz główny
value	varchar	Wartość ustawienia
updatedAt	timestamp	Czas ostatniej aktualizacji

roles

Role niestandardowe z uprawnieniami o dużej szczegółowości.

Kolumna	Typ	Uwagi
id	uuid	Klucz główny
name	varchar	Unikalna nazwa roli
description	varchar	Opcjonalny opis
permissions	jsonb	Tablica ciągów uprawnień
createdAt	timestamp	Czas utworzenia

audit_log

Dziennik działań istotnych dla bezpieczeństwa.

Kolumna	Typ	Uwagi
id	uuid	Klucz główny
userId	uuid	Klucz obcy do users
action	varchar	Typ działania
details	jsonb	Dane specyficzne dla działania
createdAt	timestamp	Czas działania

user_preferences

Stan interfejsu dla poszczególnych użytkowników, kluczowany nazwą preferencji. Przechowuje przypięte narzędzia strony głównej, zapisywane przez PUT /api/v1/preferences.

Kolumna	Typ	Uwagi
userId	text	Klucz obcy do users, kasowanie kaskadowe. Razem z key tworzy klucz główny
key	text	Nazwa preferencji. Razem z userId tworzy klucz główny
value	jsonb	Zawartość preferencji
updatedAt	timestamp	Ostatni zapis

Migracje

Drizzle zajmuje się migracjami schematu. Pliki migracji znajdują się w apps/api/drizzle/. Podczas developmentu:

cd apps/api
npx drizzle-kit generate   # generate a migration from schema changes
npx drizzle-kit migrate    # apply pending migrations

W środowisku produkcyjnym oczekujące migracje są stosowane automatycznie przy uruchomieniu.

Utwórz kopię zapasową i przywróć

Relacyjna baza danych znajduje się w woluminie SnapOtter-pgdata kontenera Postgres, a nie w wolumenie /data aplikacji.

Logiczna kopia zapasowa z walidacją (zalecane)

# Dump into PostgreSQL's portable custom archive format
docker exec SnapOtter-postgres \
  pg_dump --format=custom --no-owner -U snapotter snapotter > snapotter.dump
test -s snapotter.dump
docker exec -i SnapOtter-postgres pg_restore --list < snapotter.dump >/dev/null

# Restore into a fresh/disposable target first and fail on the first SQL error
docker exec -i SnapOtter-postgres \
  pg_restore --exit-on-error --clean --if-exists --no-owner \
  -U snapotter -d snapotter < snapotter.dump

Ten zrzut bazy danych nie zawiera zapisanych obiektów biblioteki w /data/files ani trwałego stanu BullMQ w Redis. Utwórz kopię zapasową i przywróć te dane, stosując skoordynowaną procedurę w Bezpieczeństwo i wzmacnianie.

Migawka zimnego woluminu

# Stop every service first, then use your storage platform to snapshot the
# PostgreSQL, app-data, and Redis volumes as one crash-consistent set.
docker compose -f docker/docker-compose.yml stop

Nie kopiuj aktywnego katalogu danych PostgreSQL za pomocą tar. Twórz przedrostki nazw woluminów według projektu, więc rozpoznaj identyfikatory zamontowanych woluminów z docker inspect lub platformy pamięci masowej, zamiast przyjmować dosłowną etykietę SnapOtter-pgdata.

Migracja z 1.x (SQLite)

Aktualizacja z SnapOtter 1.x ma własny przewodnik: zobacz Aktualizacja z 1.x do 2.0. W skrócie, użyj ponownie istniejącego wolumenu /data, a 2.0 automatycznie wykryje i zaimportuje /data/snapotter.db przy pierwszym uruchomieniu (lub ustaw SQLITE_MIGRATE_PATH, aby wskazać go jawnie). Najpierw utwórz kopię zapasową całego wolumenu /data, a nie tylko snapotter.db: 1.x używa trybu SQLite WAL, więc zatrzymany kontener często pozostawia większość swoich danych w snapotter.db-wal obok niemal pustego snapotter.db.