DIAN115把旧 SQLite 数据迁移到 PostgreSQL
停止旧实例，备份原配置目录，将当前业务数据迁入空的 PostgreSQL 数据库，再使用同一配置目录和 PostgreSQL 连接启动。历史废表、废列自动忽略。
脚本需要所选镜像包含 /usr/local/bin/dian115-db。2026-10-27 核对时 Docker Hub 尚无 5.0.42 标签；dian115-pgsql:local 是已取得的本地兼容镜像示例，不能当作官方可拉取标签。先取得兼容镜像，再执行迁移；新装 PG 不需要迁移。
1. 停止旧实例并备份配置目录
在原 compose.yml 所在目录操作。先停止 DIAN115，再备份整个配置目录，包含所有 SQLite 分库、密钥和本地资源。示例的 ./config 要换成当前容器 /config 对应的真实宿主机目录；不要只复制 dian115.db。
docker compose stop dian115
cp -a ./config "./config-sqlite-backup-$(date +%Y%m%d-%H%M%S)"2. 准备空目标库并修改连接配置
按“使用 PostgreSQL 新装 DIAN115”准备数据库。已有 PostgreSQL 时新建一个空数据库供此次迁移使用。在原 dian115 服务加入 DIAN115_DB_DRIVER=pgsql 和 DIAN115_PG_DSN，保留原来的所有 volumes、端口和其他配置。此时先不要启动 dian115。若新建同机 PostgreSQL，只启动 postgres 服务。
docker compose up -d postgres3. 下载公开迁移脚本
在运行 DIAN115 的 Linux / NAS Docker 宿主机下载脚本。脚本调用所选镜像内的 /usr/local/bin/dian115-db，执行 migrate --db /config/dian115.db。请准备实际包含该工具的 v5.0.42 或更新兼容镜像；latest 名称不保证满足版本要求。只需 Docker，不需要项目源码或宿主机数据库客户端。完整参数、网络和失败恢复教程见 GitHub 的 tools/database-migration/README.md。 2026-10-27 核对时 Docker Hub 尚无 5.0.42 标签，不能直接按此标签拉取；示例 dian115-pgsql:local 表示已经取得的本地兼容镜像，请替换为实际名称。
curl --fail --location 'https://raw.githubusercontent.com/madbrolab/dian115/main/tools/database-migration/migrate-sqlite-to-pgsql.sh' --output migrate-sqlite-to-pgsql.sh
sh migrate-sqlite-to-pgsql.sh --help4. 设置连接并运行一次迁移
--config 填原容器 /config 对应的完整 Linux 宿主机目录；--image 填实际取得的兼容镜像，后续应用使用同一兼容版本。默认 host 网络适用于 Linux，同机 PG 填宿主机地址和映射端口。脚本逐表导入，最终输出 {"backend":"pgsql","ready":true} 并提示迁移完成，再启动原应用。不要只看到部分表完成就启动；不需要报告或额外复验命令。
export DIAN115_PG_DSN='postgres://dian115:YourPassword@127.0.0.1:15432/dian115_pg?sslmode=disable'
export DIAN115_IMAGE='dian115-pgsql:local'
sh migrate-sqlite-to-pgsql.sh --config /mnt/appdata/dian115/config --image "$DIAN115_IMAGE"
docker compose up -d dian1155. Docker 网络、特殊密码与自定义参数
若 PG 通过同一 Docker 网络服务名访问，使用服务名和容器端口，并加 --network 网络名；后续 DIAN115 也加入该网络。桥接容器里的 127.0.0.1 指向容器自己。连接串内保留字符需百分号编码，例如密码 Demo@2026#1 写为 Demo%402026%231，数据库中仍设置原始密码。自定义主库名使用 --db 文件名；总时限默认 2h，较大迁移可通过 --timeout 6h 调整。
export DIAN115_PG_DSN='postgres://dian115:YourPassword@postgres:5432/dian115_pg?sslmode=disable'
sh migrate-sqlite-to-pgsql.sh --config /mnt/appdata/dian115/config --image "$DIAN115_IMAGE" --network dian115-storage6. 迁移保留哪些数据
迁入当前业务使用的表和字段，保留记录 ID、自增序号与加密凭据，音乐数据转换为当前结构。历史废表、废列、旧索引和无关文件会忽略；未使用过的可选分库、表或升级字段按当前默认值初始化。原 SQLite 文件不会删除。
7. 确认已经切换
登录后打开“系统设置 → 基础设置 → 数据库维护”，确认显示 PostgreSQL 与目标库名。查看账号、整理规则、任务和音乐等原有内容。迁移后新增数据写入 PostgreSQL，不会同步回原 SQLite。
8. 连接或导入失败时处理
连接或字段转换错误会停止脚本，并保留非零退出码。修正具体地址、权限或数据问题后，换新的空目标库重试；音乐分阶段导入失败时可能已留下部分目标数据，脚本不提供断点续传。原配置目录和备份保留，不要向已有新业务数据的 PG 库重复导入。需要回退时先停止 PG 模式实例，移除两个 PG 环境变量，使用原 SQLite 目录或备份启动；PG 新增数据不会自动写回 SQLite。
参数说明
| 参数 | 填写方法 |
|---|---|
| --config | 必填：原 /config 对应的完整宿主机目录，保留全部分库、密钥和本地资源。 |
| --image / DIAN115_IMAGE | 包含 dian115-db 的兼容镜像；未指定时默认 madbrolab/dian115:latest，推荐明确填写版本或摘要。 |
| --network | 默认 host，适用于 Linux；使用 PG 服务名时填写同一 Docker 网络名。 |
| --db | 原主库文件名，默认 dian115.db，不填路径，不要为迁移随意重命名分库。 |
| --timeout | 迁移总时限，默认 2h，例如 6h。 |
| DIAN115_PG_DSN | 空目标 PG 库的完整连接串；使用实际用户、编码后的密码、地址和端口。 |
常见问题
找不到旧 SQLite 主库
核对原 Compose 的 /config 宿主机目录及主库文件名。默认文件为 dian115.db，自定义文件使用 --db 指定。
迁移后账号或资源不可用
保留并使用原 /config 整个目录，尤其是原有业务密钥与本地图片、歌词等文件。确认应用连接的是此次迁移的库名。
镜像内找不到 dian115-db
镜像不含迁移工具。取得兼容镜像并通过 --image 指定。外部脚本只调用镜像内程序，本身不包含数据转换逻辑。
无法解析 postgres 或连接被拒绝
服务名只能在对应 Docker 网络内解析；加 --network 后使用 PG 容器端口，或使用 host 网络及宿主机映射端口。确认 PG 已运行。
目标重复主键、音乐导入中断或迁移超时
保留原库，排除具体问题；必要时加长 --timeout，再换一个空目标库重试。不要把重复执行当作断点续传。