From 0a628a76f17e570f60836b0cd3fe11b1ba5b65fc Mon Sep 17 00:00:00 2001 From: ShukeBta <272197458+ShukeBta@users.noreply.github.com> Date: Mon, 15 Jun 2026 18:48:47 +0800 Subject: [PATCH] Document PostgreSQL deployment and SQLite migration --- README.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++---- README_EN.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 138 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5c99ab7..807c7fd 100644 --- a/README.md +++ b/README.md @@ -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`。 ### 停止 diff --git a/README_EN.md b/README_EN.md index b8727c0..90f09c1 100644 --- a/README_EN.md +++ b/README_EN.md @@ -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