SnapOtter/apps/docs/zh-TW/guide/database.md

description, i18n_source_hash, i18n_provenance, i18n_output_hash

description	i18n_source_hash	i18n_provenance	i18n_output_hash
SnapOtter 的 PostgreSQL 資料庫結構、資料表、遷移，以及備份程序。	50d5d4f220cf	human	34debcc24c5a

資料庫

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

使用者在 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 的外鍵（CASCADE DELETE）
originalName	varchar	原始上傳檔名
storedName	varchar	磁碟上的檔名
mimeType	varchar	MIME 類型
size	integer	檔案大小（位元組）
width	integer	影像寬度（px）
height	integer	影像高度（px）
version	integer	版本編號（1 = 原始）
parentId	uuid 或 null	指向 user_files 的外鍵（父版本）
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 的外鍵
action	varchar	動作類型
details	jsonb	動作特定的資料
createdAt	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

在生產環境中，待處理的遷移會在啟動時自動套用。

備份與還原

關聯式資料庫位於 Postgres 容器的 SnapOtter-pgdata 磁碟區，而非應用程式的 /data 磁碟區。

選項 1：pg_dump（建議）

# Dump the database while the stack is running
docker exec SnapOtter-postgres pg_dump -U snapotter snapotter > backup.sql

# Restore into a fresh database
cat backup.sql | docker exec -i SnapOtter-postgres psql -U snapotter snapotter

選項 2：磁碟區快照

# Stop the stack, then snapshot the pgdata volume
docker compose down
docker run --rm -v SnapOtter-pgdata:/data -v $(pwd)/backup:/backup \
  alpine tar czf /backup/snapotter-pgdata.tar.gz -C /data .

從 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。