Cơ sở dữ liệu

SnapOtter sử dụng PostgreSQL 17 với Drizzle ORM (pg-core / node-postgres) để lưu trữ dữ liệu bền vững. Lược đồ được định nghĩa trong apps/api/src/db/schema.ts.

Kết nối được cấu hình qua biến môi trường DATABASE_URL (mặc định postgres://snapotter:snapotter@postgres:5432/snapotter). Trong Docker Compose, container Postgres lưu dữ liệu của nó trong volume có tên SnapOtter-pgdata.

Bảng

users

Lưu trữ các tài khoản người dùng. Được tạo tự động ở lần chạy đầu tiên từ DEFAULT_USERNAME và DEFAULT_PASSWORD.

Cột	Kiểu	Ghi chú
id	uuid	Khóa chính
username	varchar	Duy nhất, bắt buộc
passwordHash	varchar	Băm scrypt
role	varchar	admin, editor, hoặc user
mustChangePassword	boolean	Cờ buộc đặt lại mật khẩu
createdAt	timestamp	Thời điểm tạo
updatedAt	timestamp	Thời điểm cập nhật gần nhất

sessions

Các phiên đăng nhập đang hoạt động. Mỗi hàng liên kết một token phiên với một người dùng.

Cột	Kiểu	Ghi chú
id	varchar	Khóa chính (token phiên)
userId	uuid	Khóa ngoại tới users.id
expiresAt	timestamp	Thời điểm hết hạn
createdAt	timestamp	Thời điểm tạo

teams

Các nhóm để tổ chức người dùng. Quản trị viên có thể gán người dùng vào các nhóm.

Cột	Kiểu	Mô tả
id	uuid	Khóa chính
name	varchar (duy nhất, tối đa 50 ký tự)	Tên nhóm
createdAt	timestamp	Thời điểm tạo

api_keys

Các khóa API để truy cập lập trình. Khóa thô chỉ được hiển thị một lần khi tạo; chỉ giá trị băm được lưu trữ.

Cột	Kiểu	Ghi chú
id	uuid	Khóa chính
userId	uuid	Khóa ngoại tới users.id
keyHash	varchar	Băm scrypt của khóa
name	varchar	Nhãn do người dùng cung cấp
createdAt	timestamp	Thời điểm tạo
lastUsedAt	timestamp	Được cập nhật ở mỗi yêu cầu đã xác thực

Các khóa có tiền tố si_ theo sau bởi 96 ký tự hex (48 byte ngẫu nhiên).

pipelines

Các chuỗi công cụ đã lưu mà người dùng tạo trong giao diện.

Cột	Kiểu	Ghi chú
id	uuid	Khóa chính
name	varchar	Tên pipeline
description	varchar	Mô tả tùy chọn
steps	jsonb	Mảng các đối tượng { toolId, settings }
createdAt	timestamp	Thời điểm tạo

user_files

Thư viện tệp bền vững. Theo mặc định, một chỉnh sửa đã lưu được chèn vào như một hàng gốc độc lập («lưu thành tệp mới»: version 1, parentId null, nên tệp gốc vẫn được liệt kê), hoặc như một phiên bản liên kết với tệp cha khi bạn ghi đè lên tệp gốc (parentId được đặt, version tăng lên, thay thế nó). Cột toolChain ghi lại các công cụ đã áp dụng.

Cột	Kiểu	Mô tả
id	uuid	Khóa chính
userId	uuid	FK tới users (CASCADE DELETE)
originalName	varchar	Tên tệp tải lên gốc
storedName	varchar	Tên tệp trên đĩa
mimeType	varchar	Kiểu MIME
size	integer	Kích thước tệp tính bằng byte
width	integer	Chiều rộng ảnh tính bằng px
height	integer	Chiều cao ảnh tính bằng px
version	integer	Số phiên bản (1 = bản gốc)
parentId	uuid hoặc null	FK tới user_files (phiên bản cha)
toolChain	jsonb	Các ID công cụ được áp dụng theo thứ tự để tạo ra phiên bản này
createdAt	timestamp	Thời điểm tạo

jobs

Theo dõi các tác vụ xử lý để báo cáo tiến độ và dọn dẹp.

Cột	Kiểu	Ghi chú
id	uuid	Khóa chính
type	varchar	Định danh công cụ hoặc pipeline
status	varchar	queued, processing, completed, hoặc failed
progress	real	Phân số 0.0-1.0
inputFiles	jsonb	Mảng các đường dẫn tệp đầu vào
outputPath	varchar	Đường dẫn tới tệp kết quả
settings	jsonb	Các thiết lập công cụ đã sử dụng
error	varchar	Thông báo lỗi nếu thất bại
createdAt	timestamp	Thời điểm tạo
completedAt	timestamp	Thời điểm hoàn thành

settings

Kho lưu trữ khóa-giá trị cho các thiết lập phạm vi toàn máy chủ mà quản trị viên có thể thay đổi từ giao diện.

Cột	Kiểu	Ghi chú
key	varchar	Khóa chính
value	varchar	Giá trị thiết lập
updatedAt	timestamp	Thời điểm cập nhật gần nhất

roles

Các vai trò tùy chỉnh với quyền chi tiết.

Cột	Kiểu	Ghi chú
id	uuid	Khóa chính
name	varchar	Tên vai trò duy nhất
description	varchar	Mô tả tùy chọn
permissions	jsonb	Mảng các chuỗi quyền
createdAt	timestamp	Thời điểm tạo

audit_log

Nhật ký các hành động liên quan đến bảo mật.

Cột	Kiểu	Ghi chú
id	uuid	Khóa chính
userId	uuid	FK tới users
action	varchar	Loại hành động
details	jsonb	Dữ liệu riêng cho hành động
createdAt	timestamp	Thời điểm hành động

user_preferences

Trạng thái giao diện của từng người dùng, lấy tên thiết lập làm khóa. Lưu các công cụ đã ghim trên trang chủ, được ghi qua PUT /api/v1/preferences.

Cột	Kiểu	Ghi chú
userId	text	FK tới users, xóa theo tầng. Khóa chính cùng với key
key	text	Tên thiết lập. Khóa chính cùng với userId
value	jsonb	Nội dung thiết lập
updatedAt	timestamp	Lần ghi gần nhất

Di trú

Drizzle xử lý việc di trú lược đồ. Các tệp di trú nằm trong apps/api/drizzle/. Trong quá trình phát triển:

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

Trong môi trường sản xuất, các di trú đang chờ được áp dụng tự động khi khởi động.

Sao lưu và khôi phục

Cơ sở dữ liệu quan hệ nằm trong ổ SnapOtter-pgdata của vùng chứa Postgres chứ không phải ổ /data của ứng dụng.

Sao lưu hợp lý có xác thực (được khuyến nghị)

# 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

Kết xuất cơ sở dữ liệu này không chứa các đối tượng thư viện đã lưu ở /data/files hoặc trạng thái BullMQ bền vững trong Redis. Sao lưu và khôi phục chúng bằng quy trình phối hợp trong Bảo mật & tăng cường.

Ảnh chụp nhanh khối lượng lạnh

# 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

Không sao chép thư mục dữ liệu PostgreSQL trực tiếp bằng tar. Soạn tiền tố tên tập đĩa theo dự án, do đó hãy phân giải ID tập đĩa được gắn từ docker inspect hoặc nền tảng lưu trữ của bạn thay vì giả định nhãn bằng chữ SnapOtter-pgdata.

Di trú từ 1.x (SQLite)

Nâng cấp từ SnapOtter 1.x có hướng dẫn riêng: xem Nâng cấp từ 1.x lên 2.0. Nói ngắn gọn, hãy tái sử dụng volume /data hiện có của bạn và 2.0 sẽ tự động phát hiện và nhập /data/snapotter.db ở lần khởi động đầu tiên (hoặc đặt SQLITE_MIGRATE_PATH để trỏ tới nó một cách tường minh). Hãy sao lưu toàn bộ volume /data trước, không chỉ snapotter.db: 1.x dùng chế độ SQLite WAL, nên một container đã dừng thường để lại phần lớn dữ liệu của nó trong snapotter.db-wal bên cạnh một snapotter.db gần như rỗng.