MoviePilot 默认使用 SQLite + 进程内缓存(cachetools)。初次部署无需 PostgreSQL 或 Redis,先验证业务流程,再根据数据量、并发与维护能力决定是否切换。
| 组件 | 负责什么 | 不负责什么 |
|---|---|---|
| SQLite / PostgreSQL | 保存用户、订阅、站点、历史和系统配置等持久数据 | 不直接存放媒体文件 |
| 进程内缓存 / Redis | 缓存与运行时共享数据 | 不替代主数据库和备份 |
| 文件系统 | 媒体、配置文件、插件文件数据和日志 | 不自动包含外部数据库 |
将缓存切换到 Redis 不会把 SQLite 数据自动迁移到 PostgreSQL。
默认数据库位于实际配置目录的 user.db。配置目录应持久化,并使用可靠的本地文件系统;避免让多个实例并发写同一份文件。
DB_WAL_ENABLE 当前默认开启。数据库忙、写入慢或磁盘满时,先检查实际磁盘、并发任务和日志,不要通过删除 WAL 文件或修改迁移版本号处理。
需要在线备份时使用 moviepilot database backup,见备份与恢复。
适合愿意维护独立数据库的场景。使用前创建专用数据库与账号,并保证账号拥有主库迁移所需权限;使用插件独立 schema 时,还要核对插件需要的 schema 使用、建表权限。
MoviePilot 连接参数:
DB_TYPE=postgresql
DB_POSTGRESQL_HOST=postgresql
DB_POSTGRESQL_PORT=5432
DB_POSTGRESQL_DATABASE=moviepilot
DB_POSTGRESQL_USERNAME=moviepilot
DB_POSTGRESQL_PASSWORD=请替换为独立的复杂密码
postgresql 适用于同一 Compose 网络里的服务名。数据库在宿主机或其他机器时应使用 MoviePilot 实际可达的地址,而不是直接照抄 localhost。密钥文件部署见配置参考。
/var/lib/postgresql/data;官方 18+ 镜像调整了目录布局,具体以所选镜像说明为准。pg_dump、pg_restore 需要与服务端版本兼容;不要用旧客户端备份更高主版本服务器。官方镜像的目录与升级约定见Postgres 镜像说明。
默认池大小和溢出参数见配置项索引。调大连接池前,应核对数据库 max_connections、同步与异步连接池、插件连接及其他客户端的总额度。
全功能 MoviePilot 使用单个 API worker。不要通过增大 API_WORKERS 解决数据库并发问题,否则会涉及调度、监控和插件控制面的重复运行;诊断见Doctor。
需要外部缓存时,先部署带认证与持久化策略的 Redis,再配置:
CACHE_BACKEND_TYPE=redis
CACHE_BACKEND_URL=redis://:请替换为Redis密码@redis:6379/0
@、: 等保留字符时,需要正确 URL 编码。FLUSHALL 来清理 MoviePilot 缓存。配置后重启并检查日志,确认使用的是预期缓存后端。
修改 DB_TYPE 只会更换连接目标,不会复制旧数据。SQLite 与 PostgreSQL 的迁移还涉及字段类型、JSON、约束、自增序列、插件独立数据和当前 Alembic revision。
建议流程:
不要照搬旧版本文档里的固定
alembic_version值,也不要手动改版本号绕过迁移。V2 到 V3 的正常升级本身不要求更换数据库;保留原数据库连接即可。
遇到结构冲突时先保存错误与备份,按故障排除定位,不在生产库反复执行网上拼凑的清表脚本。