External/SnapOtter
1
0
Fork 0
mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
d10d0f544f2a093d2adb13cbd69d54a31c0cbf7a
SnapOtter/apps/docs/ko/guide/database.md
T
SnapOtterandGitHub d10d0f544f fix: release QA hardening across processing, media, security, and CI gates (#649) 
A release-readiness QA pass over the whole product. The commits split into
defects a user would hit and gates that were reporting green while measuring
nothing.

## Fixes that change behaviour

Rate limiting was bypassable on every install: TRUST_PROXY defaulted to true, so
request.ip came from a client-set header and a forged X-Forwarded-For got past
the login limiter. The default is now a private-network trust list.

A transient Postgres outage stranded in-flight jobs, leaving finished output on
disk with no row pointing at it. A reconciler now resolves those rows and adopts
the bytes rather than dropping the work.

A Redis connection that moved to a new address wedged every read-blocked
consumer, so completions stopped signalling while health still answered 200.
Socket timeouts plus subscriber pings recover it.

Installing more than one AI bundle left the shared venv multi-versioned and
silently broke three tools. The installer now reconciles distributions to one
version each.

Converting an image to JXL at quality 1 through 4 returned a 500, because
libjxl 0.7 rejects the distance those values compute. The quality is floored at
what the encoder honours. A missing ffmpeg was also reported to the user as a
corrupt upload; it now says the engine is unavailable.

RAW uploads reached an unpatched LibRaw on arm64, so it is built from source at
0.22.2, and the release scan was split so it can fail on an unfixed critical
instead of hiding it behind ignore-unfixed.

## Gates that could not fail

Two mutation lanes ran zero mutants because Stryker crawled the gitignored docs
build; coverage discarded its whole report on any failing test; the lint gate
skipped root tests, scripts, and two workspaces; and several generated matrices
counted a host missing ffmpeg as a passing tool. Each now measures what it
claims.

Full evidence and the outstanding release items are tracked locally and are not
part of this branch.
2026-07-27 15:37:30 +08:00

206 lines
8.7 KiB
Markdown
Raw Blame History

---
description: "SnapOtter의 PostgreSQL 데이터베이스 스키마, 테이블, 마이그레이션, 백업 절차."
i18n_source_hash: a68264552836
i18n_provenance: machine
i18n_output_hash: 469f8d270e1f
i18n_hash_version: 2
---
# 데이터베이스 {#database}
SnapOtter는 데이터 영속성을 위해 PostgreSQL 17과 [Drizzle ORM](https://orm.drizzle.team/)(pg-core / node-postgres)을 사용합니다. 스키마는 `apps/api/src/db/schema.ts`에 정의되어 있습니다.
연결은 `DATABASE_URL` 환경 변수로 구성됩니다(기본값 `postgres://snapotter:snapotter@postgres:5432/snapotter`). Docker Compose에서는 Postgres 컨테이너가 데이터를 `SnapOtter-pgdata` 명명된 볼륨에 저장합니다.
## 테이블 {#tables}
### users {#users}
사용자 계정을 저장합니다. 첫 실행 시 `DEFAULT_USERNAME`과 `DEFAULT_PASSWORD`에서 자동으로 생성됩니다.
| 컬럼 | 타입 | 비고 |
|---|---|---|
| `id` | uuid | 기본 키 |
| `username` | varchar | 고유, 필수 |
| `passwordHash` | varchar | scrypt 해시 |
| `role` | varchar | `admin`, `editor`, 또는 `user` |
| `mustChangePassword` | boolean | 비밀번호 강제 재설정 플래그 |
| `createdAt` | timestamp | 생성 시각 |
| `updatedAt` | timestamp | 마지막 업데이트 시각 |
### sessions {#sessions}
활성 로그인 세션. 각 행은 세션 토큰을 사용자와 연결합니다.
| 컬럼 | 타입 | 비고 |
|---|---|---|
| `id` | varchar | 기본 키 (세션 토큰) |
| `userId` | uuid | `users.id`에 대한 외래 키 |
| `expiresAt` | timestamp | 만료 시각 |
| `createdAt` | timestamp | 생성 시각 |
### teams {#teams}
사용자를 조직화하기 위한 그룹. 관리자는 사용자를 팀에 할당할 수 있습니다.
| 컬럼 | 타입 | 설명 |
|--------|------|-------------|
| `id` | uuid | 기본 키 |
| `name` | varchar (고유, 최대 50자) | 팀 이름 |
| `createdAt` | timestamp | 생성 시각 |
### api_keys {#api-keys}
프로그래밍 방식 접근을 위한 API 키. 원본 키는 생성 시 한 번만 표시되며, 해시만 저장됩니다.
| 컬럼 | 타입 | 비고 |
|---|---|---|
| `id` | uuid | 기본 키 |
| `userId` | uuid | `users.id`에 대한 외래 키 |
| `keyHash` | varchar | 키의 scrypt 해시 |
| `name` | varchar | 사용자가 지정한 레이블 |
| `createdAt` | timestamp | 생성 시각 |
| `lastUsedAt` | timestamp | 인증된 요청마다 업데이트됨 |
키는 `si_` 접두어 뒤에 96개의 16진수 문자(48개의 임의 바이트)가 붙습니다.
### pipelines {#pipelines}
사용자가 UI에서 만드는 저장된 도구 체인.
| 컬럼 | 타입 | 비고 |
|---|---|---|
| `id` | uuid | 기본 키 |
| `name` | varchar | 파이프라인 이름 |
| `description` | varchar | 선택적 설명 |
| `steps` | jsonb | `{ toolId, settings }` 객체의 배열 |
| `createdAt` | timestamp | 생성 시각 |
### user_files {#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 | 이미지 너비(px) |
| `height` | integer | 이미지 높이(px) |
| `version` | integer | 버전 번호 (1 = 원본) |
| `parentId` | uuid 또는 null | user_files에 대한 FK (부모 버전) |
| `toolChain` | jsonb | 이 버전을 생성하기 위해 순서대로 적용된 도구 ID |
| `createdAt` | timestamp | 생성 시각 |
### jobs {#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 {#settings}
관리자가 UI에서 변경할 수 있는 서버 전역 설정을 위한 키-값 저장소.
| 컬럼 | 타입 | 비고 |
|---|---|---|
| `key` | varchar | 기본 키 |
| `value` | varchar | 설정 값 |
| `updatedAt` | timestamp | 마지막 업데이트 시각 |
### roles {#roles}
세분화된 권한을 가진 커스텀 역할.
| 컬럼 | 타입 | 비고 |
|---|---|---|
| `id` | uuid | 기본 키 |
| `name` | varchar | 고유 역할 이름 |
| `description` | varchar | 선택적 설명 |
| `permissions` | jsonb | 권한 문자열의 배열 |
| `createdAt` | timestamp | 생성 시각 |
### audit_log {#audit-log}
보안 관련 작업 로그.
| 컬럼 | 타입 | 비고 |
|---|---|---|
| `id` | uuid | 기본 키 |
| `userId` | uuid | users에 대한 FK |
| `action` | varchar | 작업 유형 |
| `details` | jsonb | 작업별 데이터 |
| `createdAt` | timestamp | 작업 시각 |
### user_preferences {#user-preferences}
사용자별 UI 상태를 환경설정 이름으로 키를 잡아 저장합니다. 홈페이지에 고정된 도구는 `PUT /api/v1/preferences`를 통해 여기에 기록됩니다.
| 컬럼 | 타입 | 비고 |
|---|---|---|
| `userId` | text | users에 대한 FK, 삭제 시 연쇄 적용. `key`와 함께 기본 키 |
| `key` | text | 환경설정 이름. `userId`와 함께 기본 키 |
| `value` | jsonb | 환경설정 내용 |
| `updatedAt` | timestamp | 마지막 쓰기 시각 |
## 마이그레이션 {#migrations}
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
```
이 데이터베이스 덤프에는 Redis의 `/data/files` 또는 내구성 있는 BullMQ 상태에 저장된 라이브러리 개체가 포함되어 있지 않습니다. [보안 및 강화](/ko/guide/security#backup-and-recovery)의 조정된 절차에 따라 백업 및 복원하세요.
**콜드 볼륨 스냅샷**
```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 stop
```
`tar`를 사용하여 라이브 PostgreSQL 데이터 디렉터리를 복사하지 마세요. 프로젝트별로 접두사 볼륨 이름을 구성하므로 리터럴 레이블 `SnapOtter-pgdata`를 가정하는 대신 `docker inspect` 또는 스토리지 플랫폼에서 마운트된 볼륨 ID를 확인합니다.
### 1.x(SQLite)에서 마이그레이션 {#migrating-from-1-x-sqlite}
SnapOtter 1.x에서 업그레이드하는 방법은 별도의 가이드가 있습니다. [1.x에서 2.0으로 업그레이드](./upgrading)를 참고하세요. 간단히 말하면, 기존 `/data` 볼륨을 재사용하면 2.0이 첫 부팅 시 `/data/snapotter.db`를 자동으로 감지하고 가져옵니다(또는 `SQLITE_MIGRATE_PATH`를 설정해 명시적으로 지정할 수 있습니다). 먼저 `snapotter.db`만이 아니라 전체 `/data` 볼륨을 백업하세요. 1.x는 SQLite WAL 모드를 사용하므로, 중지된 컨테이너는 거의 비어 있는 `snapotter.db` 옆에 있는 `snapotter.db-wal`에 대부분의 데이터를 남겨두는 경우가 많습니다.
Reference in New Issue View Git Blame Copy Permalink