Document PostgreSQL deployment and SQLite migration

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`。
 
 ### 停止