Search K
データベース
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 桁の 16 進数（48 バイトのランダム値）が続きます。
pipelines
ユーザーが UI で作成する、保存されたツールチェーン。
| カラム | 型 | 備考 |
|---|---|---|
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 への FK（CASCADE DELETE） |
originalName | varchar | アップロード時の元のファイル名 |
storedName | varchar | ディスク上のファイル名 |
mimeType | varchar | MIME タイプ |
size | integer | ファイルサイズ（バイト） |
width | integer | 画像の幅（ピクセル） |
height | integer | 画像の高さ（ピクセル） |
version | integer | バージョン番号（1 = オリジナル） |
parentId | uuid または null | user_files への FK（親バージョン） |
toolChain | jsonb | このバージョンを生成するために順に適用されたツール ID |
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
管理者が UI から変更できる、サーバー全体の設定のためのキーバリューストア。
| カラム | 型 | 備考 |
|---|---|---|
key | varchar | 主キー |
value | varchar | 設定値 |
updatedAt | timestamp | 最終更新日時 |
roles
きめ細かな権限を持つカスタムロール。
| カラム | 型 | 備考 |
|---|---|---|
id | uuid | 主キー |
name | varchar | 一意のロール名 |
description | varchar | 任意の説明 |
permissions | jsonb | 権限文字列の配列 |
createdAt | timestamp | 作成日時 |
audit_log
セキュリティに関わるアクションのログ。
| カラム | 型 | 備考 |
|---|---|---|
id | uuid | 主キー |
userId | uuid | users への FK |
action | varchar | アクションの種類 |
details | jsonb | アクション固有のデータ |
createdAt | timestamp | アクション日時 |
user_preferences
ユーザーごとの UI 状態を、設定名をキーとして保持します。ホームページのピン留めしたツールは PUT /api/v1/preferences 経由でここに書き込まれます。
| カラム | 型 | 備考 |
|---|---|---|
userId | text | users への FK、削除時にカスケード。key と合わせて主キー |
key | text | 設定の名前。userId と合わせて主キー |
value | jsonb | 設定の内容 |
updatedAt | timestamp | 最終書き込み日時 |
マイグレーション
Drizzle がスキーマのマイグレーションを処理します。マイグレーションファイルは apps/api/drizzle/ にあります。開発中は次のとおりです。
bash
cd apps/api
npx drizzle-kit generate # generate a migration from schema changes
npx drizzle-kit migrate # apply pending migrations本番環境では、保留中のマイグレーションが起動時に自動的に適用されます。
{#backup-and-restore} のバックアップと復元
リレーショナル データベースは、アプリの /data ボリュームではなく、Postgres コンテナーの SnapOtter-pgdata ボリュームに存在します。
検証付きの論理バックアップ (推奨)
bash
# 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 で保存されたライブラリ オブジェクトや、Redis の永続的な BullMQ 状態は含まれません。 セキュリティと強化 の連携手順でバックアップと復元を行ってください。
コールド ボリューム スナップショット
bash
# 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 stoptar を使用してライブ PostgreSQL データ ディレクトリをコピーしないでください。ボリューム名はプロジェクトごとにプレフィックスを作成するため、リテラル ラベル SnapOtter-pgdata を想定するのではなく、docker inspect またはストレージ プラットフォームからマウントされたボリューム ID を解決します。
1.x（SQLite）からの移行
SnapOtter 1.x からのアップグレードには専用のガイドがあります。1.x から 2.0 へのアップグレード を参照してください。要点としては、既存の /data ボリュームを再利用すれば、2.0 が初回起動時に /data/snapotter.db を自動検出してインポートします（または SQLITE_MIGRATE_PATH を設定して明示的に指定します）。まず snapotter.db だけでなく /data ボリューム全体をバックアップしてください。1.x は SQLite の WAL モードを使うため、停止したコンテナはデータの大半を、ほぼ空の snapotter.db のそばにある snapotter.db-wal に残していることがよくあります。