База даних

SnapOtter використовує PostgreSQL 17 з Drizzle ORM (pg-core / node-postgres) для збереження даних. Схему визначено у apps/api/src/db/schema.ts.

З'єднання налаштовується через змінну середовища DATABASE_URL (за замовчуванням postgres://snapotter:snapotter@postgres:5432/snapotter). У Docker Compose контейнер Postgres зберігає свої дані в іменованому томі SnapOtter-pgdata.

Таблиці

users

Зберігає облікові записи користувачів. Створюється автоматично під час першого запуску з DEFAULT_USERNAME та DEFAULT_PASSWORD.

Стовпець	Тип	Примітки
id	uuid	Первинний ключ
username	varchar	Унікальний, обов'язковий
passwordHash	varchar	scrypt-хеш
role	varchar	admin, editor або user
mustChangePassword	boolean	Прапорець примусового скидання пароля
createdAt	timestamp	Час створення
updatedAt	timestamp	Час останнього оновлення

sessions

Активні сесії входу. Кожен рядок пов'язує токен сесії з користувачем.

Стовпець	Тип	Примітки
id	varchar	Первинний ключ (токен сесії)
userId	uuid	Зовнішній ключ на users.id
expiresAt	timestamp	Час закінчення терміну дії
createdAt	timestamp	Час створення

teams

Групи для організації користувачів. Адміністратори можуть призначати користувачів до команд.

Стовпець	Тип	Опис
id	uuid	Первинний ключ
name	varchar (унікальний, макс. 50 символів)	Назва команди
createdAt	timestamp	Час створення

api_keys

API-ключі для програмного доступу. Необроблений ключ показується один раз під час створення; зберігається лише хеш.

Стовпець	Тип	Примітки
id	uuid	Первинний ключ
userId	uuid	Зовнішній ключ на users.id
keyHash	varchar	scrypt-хеш ключа
name	varchar	Мітка, надана користувачем
createdAt	timestamp	Час створення
lastUsedAt	timestamp	Оновлюється під час кожного автентифікованого запиту

Ключі мають префікс si_, за яким слідують 96 шістнадцяткових символів (48 випадкових байтів).

pipelines

Збережені ланцюжки інструментів, які користувачі створюють в інтерфейсі.

Стовпець	Тип	Примітки
id	uuid	Первинний ключ
name	varchar	Назва конвеєра
description	varchar	Необов'язковий опис
steps	jsonb	Масив об'єктів { toolId, settings }
createdAt	timestamp	Час створення

user_files

Постійна бібліотека файлів. За замовчуванням збережене редагування додається як незалежний кореневий рядок («зберегти як новий»: version 1, parentId null, тож оригінал лишається у списку) або як пов'язана з батьківською версія, коли ви перезаписуєте оригінал (parentId встановлено, version збільшено, замінюючи його). Стовпець toolChain записує застосовані інструменти.

Стовпець	Тип	Опис
id	uuid	Первинний ключ
userId	uuid	Зовнішній ключ на users (CASCADE DELETE)
originalName	varchar	Оригінальна назва завантаженого файлу
storedName	varchar	Назва файлу на диску
mimeType	varchar	MIME-тип
size	integer	Розмір файлу в байтах
width	integer	Ширина зображення в пікселях
height	integer	Висота зображення в пікселях
version	integer	Номер версії (1 = оригінал)
parentId	uuid або null	Зовнішній ключ на user_files (батьківська версія)
toolChain	jsonb	Ідентифікатори інструментів, застосовані по порядку для створення цієї версії
createdAt	timestamp	Час створення

jobs

Відстежує завдання обробки для звітування про прогрес та очищення.

Стовпець	Тип	Примітки
id	uuid	Первинний ключ
type	varchar	Ідентифікатор інструмента чи конвеєра
status	varchar	queued, processing, completed або failed
progress	real	Частка 0.0-1.0
inputFiles	jsonb	Масив шляхів до вхідних файлів
outputPath	varchar	Шлях до файлу результату
settings	jsonb	Використані налаштування інструмента
error	varchar	Повідомлення про помилку у разі невдачі
createdAt	timestamp	Час створення
completedAt	timestamp	Час завершення

settings

Сховище ключ-значення для загальносерверних налаштувань, які адміністратори можуть змінювати з інтерфейсу.

Стовпець	Тип	Примітки
key	varchar	Первинний ключ
value	varchar	Значення налаштування
updatedAt	timestamp	Час останнього оновлення

roles

Кастомні ролі з деталізованими дозволами.

Стовпець	Тип	Примітки
id	uuid	Первинний ключ
name	varchar	Унікальна назва ролі
description	varchar	Необов'язковий опис
permissions	jsonb	Масив рядків дозволів
createdAt	timestamp	Час створення

audit_log

Журнал дій, релевантних для безпеки.

Стовпець	Тип	Примітки
id	uuid	Первинний ключ
userId	uuid	Зовнішній ключ на users
action	varchar	Тип дії
details	jsonb	Дані, специфічні для дії
createdAt	timestamp	Час дії

user_preferences

Стан інтерфейсу для кожного користувача з ключем за назвою налаштування. Зберігає закріплені інструменти головної сторінки, які записуються через PUT /api/v1/preferences.

Стовпець	Тип	Примітки
userId	text	Зовнішній ключ на users, каскадне видалення. Первинний ключ разом із key
key	text	Назва налаштування. Первинний ключ разом із userId
value	jsonb	Вміст налаштування
updatedAt	timestamp	Час останнього запису

Міграції

Drizzle відповідає за міграції схеми. Файли міграцій знаходяться у apps/api/drizzle/. Під час розробки:

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

У продакшені відкладені міграції застосовуються автоматично під час запуску.

Резервне копіювання та відновлення

Реляційна база даних знаходиться в томі SnapOtter-pgdata контейнера Postgres, а не в томі /data програми.

Логічна резервна копія з перевіркою (рекомендовано)

# 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

Цей дамп бази даних не містить збережених об’єктів бібліотеки в /data/files або тривалому стані BullMQ у Redis. Створюйте резервні копії та відновлюйте їх за допомогою скоординованої процедури в Безпека та посилення.

Знімок холодного обсягу

# 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

Не копіюйте живий каталог даних PostgreSQL за допомогою tar. Створюйте префікси імен томів за проектом, тому вирішуйте ідентифікатори змонтованих томів із docker inspect або вашої платформи зберігання, а не припускайте буквальну мітку SnapOtter-pgdata.

Міграція з 1.x (SQLite)

Оновлення з SnapOtter 1.x має власний посібник: див. Оновлення з 1.x до 2.0. Коротко: повторно використайте свій наявний том /data, і 2.0 автоматично виявить та імпортує /data/snapotter.db під час першого запуску (або встановіть SQLITE_MIGRATE_PATH, щоб явно вказати на нього). Спершу зробіть резервну копію всього тому /data, а не лише snapotter.db: 1.x використовує режим SQLite WAL, тож зупинений контейнер часто залишає більшість своїх даних у snapotter.db-wal поруч із майже порожнім snapotter.db.