Veritabanı

SnapOtter, veri kalıcılığı için Drizzle ORM (pg-core / node-postgres) ile birlikte PostgreSQL 17 kullanır. Şema apps/api/src/db/schema.ts dosyasında tanımlanır.

Bağlantı, DATABASE_URL ortam değişkeni üzerinden yapılandırılır (varsayılan postgres://snapotter:snapotter@postgres:5432/snapotter). Docker Compose'da, Postgres container'ı verilerini SnapOtter-pgdata adlı volume'da saklar.

Tablolar

users

Kullanıcı hesaplarını saklar. İlk çalıştırmada DEFAULT_USERNAME ve DEFAULT_PASSWORD değerlerinden otomatik olarak oluşturulur.

Sütun	Tür	Notlar
id	uuid	Birincil anahtar
username	varchar	Benzersiz, zorunlu
passwordHash	varchar	scrypt hash
role	varchar	admin, editor veya user
mustChangePassword	boolean	Zorunlu parola sıfırlama bayrağı
createdAt	timestamp	Oluşturulma zamanı
updatedAt	timestamp	Son güncelleme zamanı

sessions

Etkin oturum açma oturumları. Her satır, bir oturum token'ını bir kullanıcıya bağlar.

Sütun	Tür	Notlar
id	varchar	Birincil anahtar (oturum token'ı)
userId	uuid	users.id tablosuna yabancı anahtar
expiresAt	timestamp	Sona erme zamanı
createdAt	timestamp	Oluşturulma zamanı

teams

Kullanıcıları düzenlemek için gruplar. Yöneticiler kullanıcıları takımlara atayabilir.

Sütun	Tür	Açıklama
id	uuid	Birincil anahtar
name	varchar (benzersiz, en fazla 50 karakter)	Takım adı
createdAt	timestamp	Oluşturulma zamanı

api_keys

Programatik erişim için API anahtarları. Ham anahtar oluşturma sırasında bir kez gösterilir; yalnızca hash saklanır.

Sütun	Tür	Notlar
id	uuid	Birincil anahtar
userId	uuid	users.id tablosuna yabancı anahtar
keyHash	varchar	Anahtarın scrypt hash'i
name	varchar	Kullanıcının verdiği etiket
createdAt	timestamp	Oluşturulma zamanı
lastUsedAt	timestamp	Kimliği doğrulanan her istekte güncellenir

Anahtarlar, si_ ön ekiyle başlar ve ardından 96 onaltılık karakter gelir (48 rastgele bayt).

pipelines

Kullanıcıların arayüzde oluşturduğu kaydedilmiş araç zincirleri.

Sütun	Tür	Notlar
id	uuid	Birincil anahtar
name	varchar	Pipeline adı
description	varchar	İsteğe bağlı açıklama
steps	jsonb	{ toolId, settings } nesneleri dizisi
createdAt	timestamp	Oluşturulma zamanı

user_files

Kalıcı dosya kütüphanesi. Kaydedilen bir düzenleme, varsayılan olarak bağımsız bir kök satır olarak eklenir ("yeni olarak kaydet": version 1, parentId null, böylece özgün dosya listede kalır) veya özgün dosyanın üzerine yazdığınızda üst öğeye bağlı bir sürüm olarak eklenir (parentId ayarlanır, version artırılır ve onun yerini alır). toolChain sütunu, uygulanan araçları kaydeder.

Sütun	Tür	Açıklama
id	uuid	Birincil anahtar
userId	uuid	users tablosuna FK (CASCADE DELETE)
originalName	varchar	Özgün yükleme dosya adı
storedName	varchar	Diskteki dosya adı
mimeType	varchar	MIME türü
size	integer	Bayt cinsinden dosya boyutu
width	integer	Piksel cinsinden görsel genişliği
height	integer	Piksel cinsinden görsel yüksekliği
version	integer	Sürüm numarası (1 = özgün)
parentId	uuid veya null	user_files tablosuna FK (üst sürüm)
toolChain	jsonb	Bu sürümü üretmek için sırayla uygulanan araç ID'leri
createdAt	timestamp	Oluşturulma zamanı

jobs

İlerleme raporlaması ve temizlik için işleme job'larını izler.

Sütun	Tür	Notlar
id	uuid	Birincil anahtar
type	varchar	Araç ya da pipeline tanımlayıcısı
status	varchar	queued, processing, completed veya failed
progress	real	0.0-1.0 arası kesir
inputFiles	jsonb	Girdi dosya yolları dizisi
outputPath	varchar	Sonuç dosyasına giden yol
settings	jsonb	Kullanılan araç ayarları
error	varchar	Başarısız olursa hata mesajı
createdAt	timestamp	Oluşturulma zamanı
completedAt	timestamp	Tamamlanma zamanı

settings

Yöneticilerin arayüzden değiştirebileceği, sunucu geneli ayarlar için anahtar-değer deposu.

Sütun	Tür	Notlar
key	varchar	Birincil anahtar
value	varchar	Ayar değeri
updatedAt	timestamp	Son güncelleme zamanı

roles

Ayrıntılı izinlere sahip özel roller.

Sütun	Tür	Notlar
id	uuid	Birincil anahtar
name	varchar	Benzersiz rol adı
description	varchar	İsteğe bağlı açıklama
permissions	jsonb	İzin dizeleri dizisi
createdAt	timestamp	Oluşturulma zamanı

audit_log

Güvenlikle ilgili eylem günlüğü.

Sütun	Tür	Notlar
id	uuid	Birincil anahtar
userId	uuid	users tablosuna FK
action	varchar	Eylem türü
details	jsonb	Eyleme özgü veri
createdAt	timestamp	Eylem zamanı

user_preferences

Kullanıcı başına arayüz durumu, tercih adına göre anahtarlanır. Ana sayfadaki sabitlenmiş araçları saklar; bunlar PUT /api/v1/preferences üzerinden yazılır.

Sütun	Tür	Notlar
userId	text	users tablosuna FK, silmede CASCADE. key ile birlikte birincil anahtar
key	text	Tercihin adı. userId ile birlikte birincil anahtar
value	jsonb	Tercihin içeriği
updatedAt	timestamp	Son yazma zamanı

Migration'lar

Şema migration'larını Drizzle yürütür. Migration dosyaları apps/api/drizzle/ dizininde bulunur. Geliştirme sırasında:

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

Üretimde, bekleyen migration'lar başlatma sırasında otomatik olarak uygulanır.

Yedekleme ve geri yükleme

İlişkisel veritabanı, uygulamanın /data biriminde değil, Postgres kapsayıcısının SnapOtter-pgdata biriminde bulunur.

Doğrulama ile mantıksal yedekleme (önerilir)

# 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

Bu veritabanı dökümü, /data/files'de veya Redis'te dayanıklı BullMQ durumunda kaydedilmiş kitaplık nesnelerini içermiyor. Bunları Güvenlik ve Güçlendirme bölümündeki koordineli prosedürle yedekleyin ve geri yükleyin.

Soğuk hacim anlık görüntüsü

# 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

Canlı bir PostgreSQL veri dizinini tar ile kopyalamayın. Ön ek birim adlarını projeye göre oluşturun; bu nedenle, SnapOtter-pgdata değişmez etiketini varsaymak yerine, bağlı birim kimliklerini docker inspect'den veya depolama platformunuzdan çözümleyin.

1.x'ten (SQLite) geçiş

SnapOtter 1.x'ten yükseltmenin kendi kılavuzu vardır: bkz. 1.x'ten 2.0'a Yükseltme. Kısacası, mevcut /data volume'unuzu yeniden kullanın; 2.0 ilk açılışta /data/snapotter.db dosyasını otomatik olarak algılayıp içe aktarır (ya da ona açıkça işaret etmesi için SQLITE_MIGRATE_PATH değerini ayarlayın). Önce yalnızca snapotter.db dosyasını değil, tüm /data volume'unu yedekleyin: 1.x SQLite WAL modunu kullanır, bu yüzden durdurulmuş bir container genellikle verilerinin çoğunu neredeyse boş bir snapotter.db dosyasının yanındaki snapotter.db-wal dosyasında bırakır.