Databas

SnapOtter använder PostgreSQL 17 med Drizzle ORM (pg-core / node-postgres) för datapersistens. Schemat definieras i apps/api/src/db/schema.ts.

Anslutningen konfigureras via miljövariabeln DATABASE_URL (standard postgres://snapotter:snapotter@postgres:5432/snapotter). I Docker Compose lagrar Postgres-containern sina data i den namngivna volymen SnapOtter-pgdata.

Tabeller

users

Lagrar användarkonton. Skapas automatiskt vid första körningen från DEFAULT_USERNAME och DEFAULT_PASSWORD.

Kolumn	Typ	Anmärkningar
id	uuid	Primärnyckel
username	varchar	Unik, obligatorisk
passwordHash	varchar	scrypt-hash
role	varchar	admin, editor eller user
mustChangePassword	boolean	Flagga för framtvingad lösenordsåterställning
createdAt	timestamp	Skapandetidpunkt
updatedAt	timestamp	Senaste uppdateringstidpunkt

sessions

Aktiva inloggningssessioner. Varje rad knyter en sessionstoken till en användare.

Kolumn	Typ	Anmärkningar
id	varchar	Primärnyckel (sessionstoken)
userId	uuid	Främmande nyckel till users.id
expiresAt	timestamp	Utgångstidpunkt
createdAt	timestamp	Skapandetidpunkt

teams

Grupper för att organisera användare. Administratörer kan tilldela användare till team.

Kolumn	Typ	Beskrivning
id	uuid	Primärnyckel
name	varchar (unik, max 50 tecken)	Teamnamn
createdAt	timestamp	Skapandetidpunkt

api_keys

API-nycklar för programmatisk åtkomst. Den råa nyckeln visas en gång vid skapandet; endast hashen lagras.

Kolumn	Typ	Anmärkningar
id	uuid	Primärnyckel
userId	uuid	Främmande nyckel till users.id
keyHash	varchar	scrypt-hash av nyckeln
name	varchar	Användarangiven etikett
createdAt	timestamp	Skapandetidpunkt
lastUsedAt	timestamp	Uppdateras vid varje autentiserad begäran

Nycklar prefixas med si_ följt av 96 hex-tecken (48 slumpmässiga byte).

pipelines

Sparade verktygskedjor som användare skapar i användargränssnittet.

Kolumn	Typ	Anmärkningar
id	uuid	Primärnyckel
name	varchar	Pipeline-namn
description	varchar	Valfri beskrivning
steps	jsonb	Array av { toolId, settings }-objekt
createdAt	timestamp	Skapandetidpunkt

user_files

Beständigt filbibliotek. En sparad ändring infogas som standard som en oberoende rotrad ("spara som ny": version 1, parentId null, så originalet ligger kvar i listan), eller som en förälderlänkad version när du skriver över originalet (parentId satt, version uppräknad, vilket ersätter det). Kolumnen toolChain registrerar vilka verktyg som tillämpades.

Kolumn	Typ	Beskrivning
id	uuid	Primärnyckel
userId	uuid	FK till users (CASCADE DELETE)
originalName	varchar	Ursprungligt uppladdningsfilnamn
storedName	varchar	Filnamn på disk
mimeType	varchar	MIME-typ
size	integer	Filstorlek i byte
width	integer	Bildbredd i px
height	integer	Bildhöjd i px
version	integer	Versionsnummer (1 = original)
parentId	uuid eller null	FK till user_files (förälderversion)
toolChain	jsonb	Verktygs-ID:n tillämpade i ordning för att producera den här versionen
createdAt	timestamp	Skapandetidpunkt

jobs

Spårar bearbetningsjobb för framstegsrapportering och rensning.

Kolumn	Typ	Anmärkningar
id	uuid	Primärnyckel
type	varchar	Identifierare för verktyg eller pipeline
status	varchar	queued, processing, completed eller failed
progress	real	0.0-1.0 andel
inputFiles	jsonb	Array av sökvägar till indatafiler
outputPath	varchar	Sökväg till resultatfilen
settings	jsonb	Använda verktygsinställningar
error	varchar	Felmeddelande om det misslyckades
createdAt	timestamp	Skapandetidpunkt
completedAt	timestamp	Slutförandetidpunkt

settings

Nyckel-värde-lager för serveromfattande inställningar som administratörer kan ändra från användargränssnittet.

Kolumn	Typ	Anmärkningar
key	varchar	Primärnyckel
value	varchar	Inställningsvärde
updatedAt	timestamp	Senaste uppdateringstidpunkt

roles

Anpassade roller med granulära behörigheter.

Kolumn	Typ	Anmärkningar
id	uuid	Primärnyckel
name	varchar	Unikt rollnamn
description	varchar	Valfri beskrivning
permissions	jsonb	Array av behörighetssträngar
createdAt	timestamp	Skapandetidpunkt

audit_log

Logg över säkerhetsrelevanta åtgärder.

Kolumn	Typ	Anmärkningar
id	uuid	Primärnyckel
userId	uuid	FK till users
action	varchar	Åtgärdstyp
details	jsonb	Åtgärdsspecifika data
createdAt	timestamp	Åtgärdstidpunkt

user_preferences

Gränssnittstillstånd per användare, nycklat på inställningens namn. Lagrar startsidans fästa verktyg, som skrivs via PUT /api/v1/preferences.

Kolumn	Typ	Anmärkningar
userId	text	FK till users, kaskaderande borttagning. Primärnyckel tillsammans med key
key	text	Inställningens namn. Primärnyckel tillsammans med userId
value	jsonb	Inställningens innehåll
updatedAt	timestamp	Senaste skrivning

Migrationer

Drizzle sköter schemamigrationer. Migrationsfiler ligger i apps/api/drizzle/. Under utveckling:

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

I produktion tillämpas väntande migrationer automatiskt vid uppstart.

Säkerhetskopiera och återställa

Relationsdatabasen finns i Postgres-behållarens SnapOtter-pgdata-volym, inte appens /data-volym.

Logisk säkerhetskopiering med validering (rekommenderas)

# 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

Denna databasdump innehåller inte sparade biblioteksobjekt i /data/files eller hållbart BullMQ-tillstånd i Redis. Säkerhetskopiera och återställ dem med den samordnade proceduren i Säkerhet och härdning.

Önblicksbild av kall volym

# 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

Kopiera inte en live PostgreSQL-datakatalog med tar. Komponera prefix volymnamn efter projekt, så lös de monterade volym-ID:n från docker inspect eller din lagringsplattform istället för att anta den bokstavliga etiketten SnapOtter-pgdata.

Migrera från 1.x (SQLite)

Uppgradering från SnapOtter 1.x har sin egen guide: se Uppgradera från 1.x till 2.0. Kort sagt, återanvänd din befintliga /data-volym så upptäcker och importerar 2.0 automatiskt /data/snapotter.db vid första uppstarten (eller ställ in SQLITE_MIGRATE_PATH för att peka på den explicit). Säkerhetskopiera hela /data-volymen först, inte bara snapotter.db: 1.x använder SQLite WAL-läge, så en stoppad container lämnar ofta det mesta av sina data i snapotter.db-wal bredvid en nästan tom snapotter.db.