第33章 从 V3 升级到 V4

从 V3.x.x 升级到 V4.0.x 时，以下数据将会丢失： - 离线下载等后台任务的记录； - 订单记录； - 举报滥用记录； - 用户自定义的侧边栏； - 用户的硬件验证器； - 主题色配置； - 由缩略图代理生成的、来自非本地存储策略的缩略图； - 其他 V4 中不再支持的配置项。 升级后，V3 的分享链接和直链仍然有效。

1. 准备工作

检查当前版本

V3 到 V4 的升级工具基于 Cloudreve V3.8.x 开发，更早的版本未经测试。建议先将 Cloudreve 升级到 V3.8.x，再进行 V4 的升级。

关闭站点

请先关闭当前站点和 Cloudreve V3 进程，防止新数据写入数据库。

备份数据库

请先备份现有数据库。可以使用 mysqldump 等第三方工具创建数据库备份；SQLite 数据库则直接备份 cloudreve.db 文件即可。

升级工具只会读取 V3 数据库并将其转换为 V4 格式，不会修改 V3 数据库中的数据。但由于操作失误或程序缺陷，仍有可能损坏 V3 数据库，请务必确认备份完成后，再进行后续操作。

备份配置文件

请备份现有 V3 版本的配置文件 conf.ini。

2. 转换数据库

2.1 获取 V4 可执行文件

参考快速开始，获取 V4.0.x 版本的主程序，将其命名为 cloudreve_v4，并放在与当前 cloudreve 相同的目录下。

# 将当前的 Cloudreve V3 可执行文件重命名为 cloudreve_v3
mv cloudreve cloudreve_v3

# 将 V4 主程序重命名为 cloudreve
mv cloudreve_v4 cloudreve

# 创建 data 目录，用于存放 V4 的配置文件和数据
mkdir data

2.2 准备 V4 配置文件和数据库

参考配置文件，为 V4 准备一份配置文件 conf.ini，放在上一步创建的 data 目录中。请在 V4 配置文件的 Database 配置项中填写 V4 的数据库连接信息，并为 V4 新建一个与 V3 分开的数据库。

你也可以直接把 V3 的配置文件 conf.ini 复制到 data 目录，修改其中的数据库连接信息：将 Database 配置项中的 Name 改为 V4 数据库的名称，或通过 DBFile 配置项指定一个新的 SQLite 数据库文件位置。

# 将 V3 配置文件 conf.ini 复制到上一步创建的 data 目录
cp conf.ini data/conf.ini

# 修改 V4 配置文件中的数据库连接信息
# 请为 V4 新建一个与 V3 分开的数据库
nano data/conf.ini

2.3 运行升级工具

# 运行升级工具
./cloudreve migrate --v3-conf conf.ini -c data/conf.ini

通过 -c 参数指定 V4 配置文件路径，通过 --v3-conf 参数指定 V3 配置文件路径。升级工具会读取 V3 数据库中的数据，转换为 V4 格式后写入 V4 数据库。

视数据量大小，升级工具可能需要几分钟到几小时不等。

3. 启动 V4

升级工具运行完成后，即可启动 V4 站点。

# 启动 V4
./cloudreve

4. 后续步骤

升级完成后访问站点时如果仍看到 V3 页面，请清除浏览器缓存，并确认你没有使用自定义前端。

确认 V4 站点运行正常后，可以删除 V3 所使用的数据库数据。

常见问题

升级过程中断，如何重试？

直接重新运行升级工具即可。Cloudreve 会将升级进度保存到 migration_state.json 文件中，再次启动时会从中断处继续。如果需要从头开始升级：

1. 删除 V4 数据库中已生成的所有数据表和数据；
2. 删除 migration_state.json 文件，或使用 --force-reset 参数重新开始升级。

升级失败：hash ID salt is not set, please set it from v3 conf file

请检查 V3 配置文件 conf.ini 中是否配置了 HashIDSalt 配置项。该配置会影响所有分享链接和直链。V3 默认会在启动时自动生成并填入该值，但你可能手动删除了它。解决方法如下：

1. 在 V3 配置文件 conf.ini 的 [System] 配置项中添加 HashIDSalt 配置项，并填入一个随机值；
2. 重新运行升级程序。

升级完成后，V3 的所有分享链接和直链都会失效。如果想避免这种情况，请手动进入数据库，将 settings 表中的 hash_id_salt 字段设置为空字符串。

升级失败：Failed to migrate: failed creating schema resources: sql/schema: copy rows from old table "xxx" to new temporary table "new_xxx"

此错误说明 V4 和 V3 使用了同一个数据库，数据表发生了冲突。请在 V4 配置文件中指定一个新的数据库。

升级失败：Error 1071: Specified key was too long; max key length is 1000 bytes

使用 MySQL 时，请将数据库默认引擎修改为 InnoDB。