Document PostgreSQL deployment and SQLite migration

2026-09-29 03:26:37 +08:00 · 2026-06-15 18:48:47 +08:00
parent 90bfeb11f2
commit 0a628a76f1
2 changed files with 138 additions and 10 deletions
@@ -41,7 +41,7 @@ MediaStationGo 是一个给个人、家庭 NAS、影音爱好者使用的媒体
 - 接入 OpenList / CloudDrive2 / WebDAV 等外部存储，支持 STRMURL 与 302 反代播放。
 - 在 NAS、小主机、VPS、Windows Docker Desktop 上用 Docker Compose 快速运行。

-> 项目还在快速迭代。重要数据都在 `data` 目录，升级前建议先备份。
+> 项目还在快速迭代。默认 PostgreSQL 部署请同时备份 `data/` 和 `postgres/`。

 ---

@@ -52,7 +52,7 @@ MediaStationGo 是一个给个人、家庭 NAS、影音爱好者使用的媒体
 - **多用户管理**：支持管理员、普通用户、账号启停、有效期、设备管理、Bot 注册/兑换码等家庭共享场景。
 - **本地媒体 + 网盘媒体统一管理**：本地硬盘、下载目录、OpenList、CloudDrive2、WebDAV 等资源可以放在同一个后台管理。
 - **下载到入库一条龙**：连接 qBittorrent 后，可做搜索、订阅、下载完成整理、刮削入库。
- **NAS 友好**：Docker Compose 部署简单，数据集中在 `data/`，适合低功耗 NAS 和小主机长期运行。
+- **NAS 友好**：Docker Compose 部署简单，主数据库在 `postgres/`，运行密钥和配置在 `data/`，适合低功耗 NAS 和小主机长期运行。

 ---

@@ -130,6 +130,59 @@ http://服务器IP:18080

 建议从轻量模式开始。Redis 和 OpenSearch 都是增强层，不是源数据库；低配 NAS 不要默认开启 OpenSearch。

+### 数据库选择与不再使用 SQLite
+
+新版 Docker Compose 默认使用 PostgreSQL，不再把 SQLite 作为主数据库。判断运行时主库只看这两个配置：
+
+```yaml
+environment:
+  MEDIASTATION_DATABASE_TYPE: postgres
+  MEDIASTATION_DATABASE_DSN: postgres://mediastation:mediastation@postgres:5432/mediastation?sslmode=disable
+```
+
+`MEDIASTATION_DATABASE_DB_PATH` 只用于旧 SQLite 数据库的一次性导入：
+
+- 新部署：直接 `docker compose up -d`，会使用 PostgreSQL，不会创建新的 SQLite 主库。
+- 旧版本升级：如果存在 `./data/mediastation.db`，首次启动新版 compose 时会自动导入到 PostgreSQL。
+- 导入只在 PostgreSQL 目标库为空时运行；PG 里已有数据时会跳过，避免覆盖现有数据。
+- Redis 是热缓存，OpenSearch 是搜索索引；它们都不是源数据库，丢失后可以重建。
+
+旧 SQLite 升级到 PostgreSQL 的建议步骤：
+
+```bash
+docker compose pull
+docker compose up -d
+docker logs -f mediastation-go
+```
+
+看到 `sqlite data migrated to postgres`，或确认网页里的用户、媒体库、设置都正常后，再处理旧 SQLite 文件。
+
+如果你确认以后不再使用 SQLite，也不希望应用再把旧 SQLite 当迁移源，可以这样做：
+
+```yaml
+environment:
+  MEDIASTATION_DATABASE_TYPE: postgres
+  MEDIASTATION_DATABASE_DSN: postgres://mediastation:mediastation@postgres:5432/mediastation?sslmode=disable
+  MEDIASTATION_DATABASE_DB_PATH: /data/disabled-sqlite-migration.db
+```
+
+然后把宿主机上的旧文件改名或移走作为离线备份：
+
+```bash
+mv data/mediastation.db data/mediastation.sqlite.bak
+```
+
+裸机或自定义 `config.yaml` 部署时同理：
+
+```yaml
+database:
+  type: postgres
+  dsn: postgres://mediastation:mediastation@127.0.0.1:5432/mediastation?sslmode=disable
+  db_path: ""
+```
+
+注意：不要删除 `./postgres`。迁移完成后真正的主数据库在 `./postgres`，`./data` 仍要保留，因为里面有 JWT 密钥和运行配置。
+
 ### 镜像地址怎么选

 两种镜像地址都可以用，选择其中一种写到 `image:` 即可：
@@ -173,7 +226,7 @@ volumes:

 | 左边 | 右边 | 说明 |
 | --- | --- | --- |
-| `./data` | 主程序 `/data` | 程序配置、JWT 密钥、旧 SQLite 迁移源；一定要备份 |
+| `./data` | 主程序 `/data` | 程序配置、JWT 密钥、旧 SQLite 迁移源；主数据库在 `./postgres` |
 | `./cache` | 主程序 `/cache` | 缓存目录；可清理 |
 | `./media` | `/media` | 媒体库目录；自动整理入库需要可写，网页里添加媒体库时填 `/media/...` |
 | `./downloads` | `/downloads` | 下载目录；文件管理和自动整理会用 |
@@ -263,6 +316,7 @@ services:
      # 轻量模式默认 PostgreSQL；旧 SQLite 会从这个路径自动迁移。
      MEDIASTATION_DATABASE_TYPE: postgres
      MEDIASTATION_DATABASE_DSN: postgres://mediastation:mediastation@postgres:5432/mediastation?sslmode=disable
+      # 确认迁移完成后，如需彻底禁用 SQLite 迁移源，可改成 /data/disabled-sqlite-migration.db。
      MEDIASTATION_DATABASE_DB_PATH: /data/mediastation.db
      MEDIASTATION_CACHE_CACHE_DIR: /cache

@@ -340,13 +394,23 @@ docker logs -f mediastation-go

 ### 备份

-重点备份：
+默认 PostgreSQL 部署重点备份：

 ```text
 data/
+postgres/
 ```

-这里面有数据库、用户、设置、部分运行状态。`cache/` 通常不用备份。
+`postgres/` 是主数据库，包含用户、媒体库、设置等核心数据；`data/` 保存 JWT 密钥、运行配置和旧 SQLite 迁移源，也要保留。
+
+如果启用了增强模式，还可以按需备份：
+
+```text
+redis/        # 热缓存，可不备份
+opensearch/   # 搜索索引，可重建；超大库可备份以减少重建时间
+```
+
+`cache/` 通常不用备份。如果你仍显式使用 `database.type=sqlite` 的旧部署，主库仍在 `data/mediastation.db`。

 ### 停止

@@ -41,7 +41,7 @@ It helps you:
 - Connect OpenList, CloudDrive2, WebDAV, and other storage backends with STRMURL or 302 redirect playback.
 - Run on NAS, mini PCs, VPS, Linux, Windows Docker Desktop, or any Docker-friendly host.

-> The project is moving fast. Keep a backup of the `data` directory before upgrades.
+> The project is moving fast. With the default PostgreSQL deployment, back up both `data/` and `postgres/`.

 ---

@@ -52,7 +52,7 @@ It helps you:
 - **Multi-user management**: supports admins, regular users, account enable/disable, expiry dates, device management, Bot registration, and redeem codes.
 - **Local + cloud media in one place**: manage local disks, download folders, OpenList, CloudDrive2, WebDAV, and other storage backends from one panel.
 - **Download-to-library workflow**: connect qBittorrent for search, subscriptions, download completion organization, and metadata matching.
- **NAS-friendly**: simple Docker Compose deployment, important data stored under `data/`, suitable for low-power NAS and mini PCs.
+- **NAS-friendly**: simple Docker Compose deployment. The primary database lives under `postgres/`, while runtime secrets and files live under `data/`.

 ---

@@ -130,6 +130,59 @@ If you already have an older `./data/mediastation.db`, the first start with the

 Start with the lightweight mode. Redis and OpenSearch are enhancement layers, not source databases. Do not enable OpenSearch by default on low-memory NAS devices.

+### Database Choice And Disabling SQLite
+
+The current Docker Compose setup uses PostgreSQL by default. SQLite is no longer the primary database in the recommended Docker deployment. The runtime database is controlled by:
+
+```yaml
+environment:
+  MEDIASTATION_DATABASE_TYPE: postgres
+  MEDIASTATION_DATABASE_DSN: postgres://mediastation:mediastation@postgres:5432/mediastation?sslmode=disable
+```
+
+`MEDIASTATION_DATABASE_DB_PATH` is only used as a one-time migration source for old SQLite data:
+
+- Fresh installs: `docker compose up -d` uses PostgreSQL and does not create a new SQLite primary database.
+- Upgrades: if `./data/mediastation.db` exists, the first start with the new compose file imports it into PostgreSQL.
+- Migration only runs when the PostgreSQL target tables are empty. If PostgreSQL already has data, the SQLite import is skipped.
+- Redis is a hot cache and OpenSearch is a search index; neither is a source database.
+
+Recommended SQLite to PostgreSQL upgrade flow:
+
+```bash
+docker compose pull
+docker compose up -d
+docker logs -f mediastation-go
+```
+
+After you see `sqlite data migrated to postgres`, or after the web UI shows your users, libraries, and settings correctly, you can stop using the old SQLite file as a migration source.
+
+To make the deployment PostgreSQL-only after migration, keep PostgreSQL selected and point the old SQLite migration path at a non-existent file:
+
+```yaml
+environment:
+  MEDIASTATION_DATABASE_TYPE: postgres
+  MEDIASTATION_DATABASE_DSN: postgres://mediastation:mediastation@postgres:5432/mediastation?sslmode=disable
+  MEDIASTATION_DATABASE_DB_PATH: /data/disabled-sqlite-migration.db
+```
+
+Then rename or move the old host-side SQLite file as an offline backup:
+
+```bash
+mv data/mediastation.db data/mediastation.sqlite.bak
+```
+
+For bare-metal or custom `config.yaml` deployments, use the same idea:
+
+```yaml
+database:
+  type: postgres
+  dsn: postgres://mediastation:mediastation@127.0.0.1:5432/mediastation?sslmode=disable
+  db_path: ""
+```
+
+Do not delete `./postgres`. After migration, it is the real primary database. Keep `./data` too, because it stores the JWT secret and runtime files.
+
 ### Choose an image source

 Both image sources are supported. Pick one and put it in `image:`:
@@ -173,7 +226,7 @@ Meaning:

 | Host path | Container path | Purpose |
 | --- | --- | --- |
-| `./data` | app `/data` | Settings, JWT secret, old SQLite migration source; back this up |
+| `./data` | app `/data` | Settings, JWT secret, old SQLite migration source; the primary DB is under `./postgres` |
 | `./cache` | app `/cache` | Cache; safe to clean when needed |
 | `./media` | `/media` | Media libraries; use `/media/...` in the web UI |
 | `./downloads` | `/downloads` | Download directory and organization source |
@@ -264,6 +317,7 @@ services:
      # Old SQLite data migrates from this path on first start.
      MEDIASTATION_DATABASE_TYPE: postgres
      MEDIASTATION_DATABASE_DSN: postgres://mediastation:mediastation@postgres:5432/mediastation?sslmode=disable
+      # After migration, change this to /data/disabled-sqlite-migration.db to disable the SQLite migration source.
      MEDIASTATION_DATABASE_DB_PATH: /data/mediastation.db
      MEDIASTATION_CACHE_CACHE_DIR: /cache

@@ -341,13 +395,23 @@ docker logs -f mediastation-go

 ### Backup

-Back up:
+For the default PostgreSQL deployment, back up:

 ```text
 data/
+postgres/
 ```

-It contains the database, users, settings, and runtime state. `cache/` is usually not important.
+`postgres/` is the primary database and contains users, libraries, settings, and media metadata. `data/` stores the JWT secret, runtime files, and optional old SQLite migration source.
+
+If you enabled the extended modes, these are optional:
+
+```text
+redis/        # hot cache, safe to rebuild
+opensearch/   # search index, rebuildable; backing it up can save reindex time on huge libraries
+```
+
+`cache/` is usually not important. If you explicitly still use `database.type=sqlite`, the primary database remains `data/mediastation.db`.

 ### Stop