GithubBackup/MoviePilot

Fork 0

mirror of https://github.com/jxxghp/MoviePilot.git synced 2026-08-14 02:05:13 +08:00

Files

GoingTime 12b054c316 优化从 SQLite 迁移到 PostgreSQL (#6264 )

2026-08-10 06:53:07 +08:00

11 KiB

Raw Blame History

PostgreSQL 数据库配置指南

MoviePilot 现在支持 PostgreSQL 数据库，您可以根据需要选择使用 SQLite 或 PostgreSQL。

配置选项

1. 数据库类型选择

在 config/app.env 文件中设置：

# 使用 SQLite（默认）
DB_TYPE=sqlite

# 使用 PostgreSQL
DB_TYPE=postgresql

2. PostgreSQL 配置参数

当 DB_TYPE=postgresql 时，以下配置生效：

# 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 设置为套接字目录。

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 服务：

确保外部 PostgreSQL 服务已启动并可访问
设置环境变量指向外部服务：

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 下操作为例）

关闭 SQLite 的 WAL 模式（如果此前已经开启），并关闭 MoviePilot
备份现有的 SQLite 数据库文件（config/user.db）
按照上述要求修改配置为 PostgreSQL
注意，由于 SQLite 与 PostgreSQL 对部分字段的类型（例如json类型）定义不同，请勿通过user.db在迁移阶段直接在空数据库的基础上创建表结构，而应按照下一条要求通过 MoviePilot 的初始化自动创建正确的表结构，只有在这种情况下迁移工具才能正确处理数据类型
启动应用，让 MoviePilot 自动创建表结构，确认创建完成后关闭 MoviePilot
使用如下 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;

安装 Java 21 或更新的版本，并下载 dimitri/pgloader 中的 v4 版本 jar 包，即pgloader.jar
创建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)
;

使用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
清理孤儿索引：DROP INDEX IF EXISTS "idx__PRIMARY";
修正 Alembic 版本号：UPDATE alembic_version SET version_num = 'd58298a0879f';
由于 SQLite 与 PostgreSQL 的自增序列原理不同，直接导入会出现冲突，需手动更新自增序列，执行：

-- 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;

启动 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

导出 PostgreSQL 数据
修改配置为 SQLite
启动应用，数据库表会自动创建
导入数据到 SQLite

数据备份

PostgreSQL 数据备份

PostgreSQL 数据存储在 ${CONFIG_DIR}/postgresql/ 目录中，您可以通过以下方式进行备份：

1. 文件级备份

# 备份整个PostgreSQL数据目录
tar -czf postgresql_backup_$(date +%Y%m%d_%H%M%S).tar.gz config/postgresql/

2. 数据库级备份

# 进入容器
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. 恢复数据

# 恢复单个数据库
psql -h localhost -U moviepilot -d moviepilot < /config/moviepilot_backup.sql

# 恢复所有数据库
psql -h localhost -U moviepilot < /config/all_databases_backup.sql

性能优化

PostgreSQL 优化建议

连接池配置：
- 根据应用负载调整 DB_POSTGRESQL_POOL_SIZE
- 设置合适的 DB_POSTGRESQL_MAX_OVERFLOW
数据库配置：
- 调整 shared_buffers
- 配置 work_mem
- 设置合适的 maintenance_work_mem
索引优化：
- 为常用查询字段添加索引
- 定期执行 VACUUM 和 ANALYZE

故障排除

常见问题

连接失败：
- 检查 PostgreSQL 服务是否启动
- 验证连接参数是否正确
- 确认网络连接和防火墙设置
权限问题：
- 确保用户有足够的数据库权限
- 检查 pg_hba.conf 配置
性能问题：
- 监控连接池使用情况
- 检查慢查询日志
- 优化数据库配置

日志查看

PostgreSQL 相关日志可以在以下位置查看：

Docker 容器：${CONFIG_DIR}/postgresql/logs/
系统日志：journalctl -u postgresql

注意事项

兼容性：PostgreSQL 支持从 MoviePilot v2.0 开始
备份：建议定期备份数据库
版本：建议使用 PostgreSQL 12 或更高版本
字符集：确保使用 UTF-8 字符集

技术支持

如果遇到问题，请：

查看应用日志
检查 PostgreSQL 日志
在 GitHub Issues 中报告问题

11 KiB Raw Blame History Unescape Escape