mirror of
https://github.com/jxxghp/MoviePilot.git
synced 2026-08-14 10:14:36 +08:00
309 lines
11 KiB
Markdown
309 lines
11 KiB
Markdown
# PostgreSQL 数据库配置指南
|
||
|
||
MoviePilot 现在支持 PostgreSQL 数据库，您可以根据需要选择使用 SQLite 或 PostgreSQL。
|
||
|
||
## 配置选项
|
||
|
||
### 1. 数据库类型选择
|
||
|
||
在 `config/app.env` 文件中设置：
|
||
|
||
```bash
|
||
# 使用 SQLite（默认）
|
||
DB_TYPE=sqlite
|
||
|
||
# 使用 PostgreSQL
|
||
DB_TYPE=postgresql
|
||
```
|
||
|
||
### 2. PostgreSQL 配置参数
|
||
|
||
当 `DB_TYPE=postgresql` 时，以下配置生效：
|
||
|
||
```bash
|
||
# PostgreSQL 主机地址
|
||
DB_POSTGRESQL_HOST=localhost
|
||
|
||
# PostgreSQL 端口；使用 Unix Socket 时可留空
|
||
DB_POSTGRESQL_PORT=5432
|
||
|
||
# PostgreSQL 数据库名
|
||
DB_POSTGRESQL_DATABASE=moviepilot
|
||
|
||
# PostgreSQL 用户名
|
||
DB_POSTGRESQL_USERNAME=moviepilot
|
||
|
||
# PostgreSQL 密码
|
||
DB_POSTGRESQL_PASSWORD=moviepilot
|
||
|
||
# PostgreSQL 连接池大小
|
||
DB_POSTGRESQL_POOL_SIZE=20
|
||
|
||
# PostgreSQL 连接池溢出数量
|
||
DB_POSTGRESQL_MAX_OVERFLOW=30
|
||
```
|
||
|
||
### 3. Unix Socket 连接
|
||
|
||
如果 PostgreSQL 通过 Unix Socket 暴露，可以把 `DB_POSTGRESQL_HOST` 设置为套接字目录。
|
||
|
||
```bash
|
||
DB_TYPE=postgresql
|
||
DB_POSTGRESQL_HOST=/var/run/postgresql
|
||
DB_POSTGRESQL_PORT=
|
||
DB_POSTGRESQL_DATABASE=moviepilot
|
||
DB_POSTGRESQL_USERNAME=moviepilot
|
||
DB_POSTGRESQL_PASSWORD=moviepilot
|
||
```
|
||
|
||
如需显式指定 socket 端口，也可以保留 `DB_POSTGRESQL_PORT`，程序会生成带 `host=/path/to/socket` 查询参数的 PostgreSQL URL。
|
||
|
||
## Docker 部署
|
||
|
||
### 使用外部 PostgreSQL
|
||
|
||
如果您想使用外部的 PostgreSQL 服务：
|
||
|
||
1. 确保外部 PostgreSQL 服务已启动并可访问
|
||
2. 设置环境变量指向外部服务：
|
||
```bash
|
||
DB_TYPE=postgresql
|
||
DB_POSTGRESQL_HOST=your-postgresql-host
|
||
DB_POSTGRESQL_PORT=5432
|
||
DB_POSTGRESQL_DATABASE=moviepilot
|
||
DB_POSTGRESQL_USERNAME=your-username
|
||
DB_POSTGRESQL_PASSWORD=your-password
|
||
```
|
||
|
||
## 数据迁移
|
||
|
||
### 从 SQLite 迁移到 PostgreSQL（以在 Windows 下操作为例）
|
||
|
||
1. 关闭 SQLite 的 WAL 模式（如果此前已经开启），并关闭 MoviePilot
|
||
2. 备份现有的 SQLite 数据库文件（`config/user.db`）
|
||
3. 按照上述要求修改配置为 PostgreSQL
|
||
4. 注意，由于 SQLite 与 PostgreSQL 对部分字段的类型（例如`json`类型）定义不同，请勿通过`user.db`在迁移阶段直接在空数据库的基础上创建表结构，而应按照下一条要求通过 MoviePilot 的初始化自动创建正确的表结构，只有在这种情况下迁移工具才能正确处理数据类型
|
||
5. 启动应用，让 MoviePilot 自动创建表结构，确认创建完成后关闭 MoviePilot
|
||
6. 使用如下 SQL 语句清理所有初始化完成的表数据，只保留表结构，避免默认的初始化数据干扰迁移
|
||
```sql
|
||
TRUNCATE TABLE agentchat, agenttask, alembic_version, downloadfailure, downloadfiles, downloadhistory, mediaserveritem, message, passkey, plugindata, site, siteicon, sitestatistic, siteuserdata, subscribe, subscribehistory, systemconfig, transferhistory, "user", userconfig, workflow RESTART IDENTITY CASCADE;
|
||
```
|
||
6. 安装 Java 21 或更新的版本，并下载 dimitri/pgloader 中的 v4 版本 jar 包，即`pgloader.jar`
|
||
7. 创建`migrate.load`文件，并编辑如下内容，注意：Windows 下本地`.db`文件路径引用需要有 3 个斜线；`userrequest`表已经废弃，是 v1 阶段的残留物，下列配置文件将会自动去除
|
||
```
|
||
LOAD DATABASE
|
||
FROM sqlite:///X:/path/to/user.db
|
||
INTO postgresql://moviepilot:your-password@host:5432/moviepilot
|
||
|
||
WITH
|
||
data only,
|
||
reset sequences
|
||
|
||
EXCLUDING TABLE NAMES LIKE 'userrequest'
|
||
|
||
SET work_mem TO '16MB',
|
||
maintenance_work_mem TO '512MB'
|
||
|
||
CAST
|
||
type integer to boolean when (= precision 1)
|
||
;
|
||
```
|
||
8. 使用`java --enable-native-access=ALL-UNNAMED -jar .\pgloader.jar .\migrate.load`启动迁移。迁移过程中可能产生大量警告和报错，主要与孤儿索引`idx__PRIMARY`相关，形如`WARN [main] pgloader.core - Primary Keys failed (skipping): ERROR: index "idx__PRIMARY" does not belong to table "plugindata" 浣嶇疆锛?9`
|
||
9. 清理孤儿索引：`DROP INDEX IF EXISTS "idx__PRIMARY";`
|
||
10. 修正 Alembic 版本号：`UPDATE alembic_version SET version_num = 'd58298a0879f';`
|
||
11. 由于 SQLite 与 PostgreSQL 的自增序列原理不同，直接导入会出现冲突，需手动更新自增序列，执行：
|
||
```sql
|
||
-- MoviePilot PostgreSQL 自增序列修复脚本
|
||
-- 用途：修复从 SQLite 迁移到 PostgreSQL 后的自增 ID 冲突
|
||
-- 问题背景：
|
||
-- SQLite 的 AUTOINCREMENT 不依赖独立序列对象，数据行带着具体 id 值进入 PostgreSQL。
|
||
-- 但 PostgreSQL 使用独立的 Sequence（如 plugindata_id_seq）生成新 ID。
|
||
-- 迁移后 Sequence 仍停留在初始值（如 1），而表中已有 id=10186 的数据，
|
||
-- 导致新插入时报 "duplicate key value violates unique constraint"。
|
||
-- 执行时机：
|
||
-- 1. 迁移完成后、应用启动前（必做）
|
||
-- 2. 运行中报主键冲突时（应急）
|
||
-- 3. 从备份恢复数据后（建议做）
|
||
-- 安全说明：
|
||
-- 本脚本只读表内最大 id 并调整序列，不修改任何数据行，可重复执行。
|
||
|
||
DO $$
|
||
DECLARE
|
||
rec RECORD;
|
||
seq_name TEXT;
|
||
max_id BIGINT;
|
||
tbl_full TEXT;
|
||
fix_count INT := 0;
|
||
err_count INT := 0;
|
||
BEGIN
|
||
RAISE NOTICE '开始扫描 public schema 下的自增序列...';
|
||
|
||
-- 遍历 public schema 下所有带自增序列的列
|
||
-- 通过 pg_get_serial_sequence() 直接获取序列名，不依赖 pg_depend，兼容性好
|
||
FOR rec IN
|
||
SELECT
|
||
n.nspname AS schema_name,
|
||
c.relname AS table_name,
|
||
a.attname AS column_name
|
||
FROM pg_class c
|
||
JOIN pg_namespace n ON c.relnamespace = n.oid
|
||
JOIN pg_attribute a ON a.attrelid = c.oid
|
||
WHERE n.nspname = 'public'
|
||
AND c.relkind = 'r' -- 只处理普通表，排除视图/系统表
|
||
AND a.attnum > 0 -- attnum <= 0 是系统隐藏列
|
||
AND NOT a.attisdropped -- 排除已删除但未清理的列
|
||
AND c.relname NOT LIKE 'pg_%' -- 排除 PostgreSQL 系统表
|
||
AND c.relname NOT LIKE 'sql_%'
|
||
AND pg_get_serial_sequence(
|
||
quote_ident(n.nspname) || '.' || quote_ident(c.relname),
|
||
a.attname
|
||
) IS NOT NULL -- 只保留确实有自增序列关联的列
|
||
ORDER BY c.relname, a.attname
|
||
LOOP
|
||
BEGIN
|
||
-- 构造带 schema 前缀的表名，quote_ident 自动处理 user 等关键字
|
||
tbl_full := quote_ident(rec.schema_name) || '.' || quote_ident(rec.table_name);
|
||
|
||
-- 获取该列当前最大值。COALESCE 处理空表（无数据时返回 0）
|
||
EXECUTE format('SELECT COALESCE(MAX(%I), 0) FROM %s', rec.column_name, tbl_full)
|
||
INTO max_id;
|
||
|
||
-- 获取序列完整名称（含 schema）
|
||
seq_name := pg_get_serial_sequence(tbl_full, rec.column_name);
|
||
|
||
-- 重置序列：
|
||
-- 参数1: 序列名
|
||
-- 参数2: 重置到的值（max_id + 1，空表时为 1）
|
||
-- 参数3: is_called = false，表示 nextval() 下次直接返回该值，不再递增
|
||
-- 效果：下一条 INSERT 拿到的 id 正好是表中未使用的最小值
|
||
PERFORM setval(seq_name, max_id + 1, false);
|
||
|
||
RAISE NOTICE '已修复: %.% (列 %) -> 序列 % 设为 % (表内最大 id = %)',
|
||
rec.schema_name, rec.table_name, rec.column_name,
|
||
seq_name, max_id + 1, max_id;
|
||
fix_count := fix_count + 1;
|
||
|
||
EXCEPTION WHEN OTHERS THEN
|
||
-- 单表异常不阻断整体流程，记录后继续下一张表
|
||
RAISE NOTICE '跳过 %.%: %', rec.schema_name, rec.table_name, SQLERRM;
|
||
err_count := err_count + 1;
|
||
END;
|
||
END LOOP;
|
||
|
||
RAISE NOTICE '完成。修复 % 个序列，跳过/错误 % 个。', fix_count, err_count;
|
||
END $$;
|
||
|
||
-- 验证：查看所有序列当前值，确认 last_value 大于对应表的最大 id
|
||
SELECT
|
||
sequencename,
|
||
last_value
|
||
FROM pg_sequences
|
||
WHERE schemaname = 'public'
|
||
ORDER BY sequencename;
|
||
```
|
||
12. 启动 MoviePilot，如果迁移成功，你应当在日志中看到类似下面的信息：
|
||
```
|
||
INFO: [moviepilot] 5b3355c964bb_2_2_0.py - 发现 21 个表需要检查序列
|
||
INFO: [moviepilot] a946dae52526_2_2_1.py - 开始PostgreSQL数据库userid字段迁移...
|
||
INFO: [moviepilot] a946dae52526_2_2_1.py - PostgreSQL数据库userid字段迁移完成
|
||
INFO: [moviepilot] 41ef1dd7467c_2_2_2.py - SystemConfig 表去重操作已完成。
|
||
INFO: Started server process [129]
|
||
```
|
||
|
||
### 从 PostgreSQL 迁移到 SQLite
|
||
|
||
1. 导出 PostgreSQL 数据
|
||
2. 修改配置为 SQLite
|
||
3. 启动应用，数据库表会自动创建
|
||
4. 导入数据到 SQLite
|
||
|
||
## 数据备份
|
||
|
||
### PostgreSQL 数据备份
|
||
|
||
PostgreSQL 数据存储在 `${CONFIG_DIR}/postgresql/` 目录中，您可以通过以下方式进行备份：
|
||
|
||
#### 1. 文件级备份
|
||
```bash
|
||
# 备份整个PostgreSQL数据目录
|
||
tar -czf postgresql_backup_$(date +%Y%m%d_%H%M%S).tar.gz config/postgresql/
|
||
```
|
||
|
||
#### 2. 数据库级备份
|
||
```bash
|
||
# 进入容器
|
||
docker exec -it moviepilot bash
|
||
|
||
# 使用pg_dump备份
|
||
pg_dump -h localhost -U moviepilot -d moviepilot > /config/moviepilot_backup.sql
|
||
|
||
# 或使用pg_dumpall备份所有数据库
|
||
pg_dumpall -h localhost -U moviepilot > /config/all_databases_backup.sql
|
||
```
|
||
|
||
#### 3. 恢复数据
|
||
```bash
|
||
# 恢复单个数据库
|
||
psql -h localhost -U moviepilot -d moviepilot < /config/moviepilot_backup.sql
|
||
|
||
# 恢复所有数据库
|
||
psql -h localhost -U moviepilot < /config/all_databases_backup.sql
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
### PostgreSQL 优化建议
|
||
|
||
1. **连接池配置**：
|
||
- 根据应用负载调整 `DB_POSTGRESQL_POOL_SIZE`
|
||
- 设置合适的 `DB_POSTGRESQL_MAX_OVERFLOW`
|
||
|
||
2. **数据库配置**：
|
||
- 调整 `shared_buffers`
|
||
- 配置 `work_mem`
|
||
- 设置合适的 `maintenance_work_mem`
|
||
|
||
3. **索引优化**：
|
||
- 为常用查询字段添加索引
|
||
- 定期执行 `VACUUM` 和 `ANALYZE`
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **连接失败**：
|
||
- 检查 PostgreSQL 服务是否启动
|
||
- 验证连接参数是否正确
|
||
- 确认网络连接和防火墙设置
|
||
|
||
2. **权限问题**：
|
||
- 确保用户有足够的数据库权限
|
||
- 检查 `pg_hba.conf` 配置
|
||
|
||
3. **性能问题**：
|
||
- 监控连接池使用情况
|
||
- 检查慢查询日志
|
||
- 优化数据库配置
|
||
|
||
### 日志查看
|
||
|
||
PostgreSQL 相关日志可以在以下位置查看：
|
||
|
||
- Docker 容器：`${CONFIG_DIR}/postgresql/logs/`
|
||
- 系统日志：`journalctl -u postgresql`
|
||
|
||
## 注意事项
|
||
|
||
1. **兼容性**：PostgreSQL 支持从 MoviePilot v2.0 开始
|
||
2. **备份**：建议定期备份数据库
|
||
3. **版本**：建议使用 PostgreSQL 12 或更高版本
|
||
4. **字符集**：确保使用 UTF-8 字符集
|
||
|
||
## 技术支持
|
||
|
||
如果遇到问题，请：
|
||
|
||
1. 查看应用日志
|
||
2. 检查 PostgreSQL 日志
|
||
3. 在 GitHub Issues 中报告问题
|