（v3.5.13 迁移）完整项目历史迁移

​

完整项目历史迁移

社区版的 3.5.x 版本包含了完整项目历史功能，该功能已在我们的 SaaS 产品 overleaf.com 中提供。

将你的实例升级到 Overleaf CE 3.5.13 后，所有新项目都会默认使用完整项目历史。现有项目将继续使用旧版历史系统，直到它们被迁移。

如果你升级到 3.5.13 后决定降级到更早的版本，则应从完整的系统备份中进行恢复。在 3.5.13 中创建的项目历史与 Overleaf CE 的早期版本不兼容。

新的完整项目历史为用户带来了多项改进：

• 它可以跟踪二进制文件的更改，而旧版系统不支持这一点。
• 支持带标签的版本。
• 系统整体上更加稳健，数据丢失的可能性更小。

有关完整项目历史的更多信息，请查看完整项目历史文档。

​

迁移现有项目

1. 创建备份

   为你的实例创建完整的备份，其中包含 mongo、redis 和 sharelatex 目录的一致性快照。

2. 更新

   将 sharelatex/sharelatex 镜像的版本更新为 3.5.13。

   Toolkit：使用 $ bin/upgrade 脚本将 Toolkit 升级到最新版本，并将 config/version 编辑为 3.5.13。

3. 启动实例

   理想情况下，你应在迁移期间阻止用户访问你的实例，以免在需要恢复备份时造成数据丢失。有关具体做法的更多信息，请参阅离线迁移。

4. 等待所有服务启动并运行

   等待所有服务启动并运行（参见下方命令）

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. 运行迁移脚本

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
   
   # legacy docker-compose.yml users:
   $ docker exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
   

   --force-clean 会清除新系统中部分迁移的项目历史数据，从而允许对之前迁移失败的单个项目重试迁移；

   --fix-invalid-characters 会替换新历史系统不支持的不可打印字符；

   --convert-large-docs-to-file 会将超过 2MB 可编辑大小阈值的文档转换为不可编辑的文件）

   输出应如下所示：

   Migrated Projects  :  1
   Total Projects     :  51
   Remaining Projects :  51
   Total history records to migrate: 98
   Starting migration...
   Migrating project: 63d29b5772dd80015a81bffe
   migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
   Migrating project: 63d29c2e72dd80015a81c0a2
   migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
   
   // …
   
   Migration complete
   ==================
   Projects migrated:  51
   Projects failed:  0
   Done.
   

   如果迁移成功，你会得到退出码 0，并且最后几行显示没有失败：

   Projects failed:  0
   Done.
   

   此时你可以重新向用户开放访问（参见下一步）。如果出现失败，请参阅下方的故障排除部分。即使问题无法立即修复，你仍然可以重新开放站点，未迁移的项目将继续使用旧版历史系统。

6. 重新开放站点

   如果你选择了离线迁移，则需要重新开放站点。如果你仍处于登录状态，需要：

   1. 点击 Admin 按钮并选择 Manage Site
   2. 点击 Open/Close Editor 选项卡
   3. 点击 Reopen Editor 按钮

   如果你已关闭浏览器，则需要使用 $ bin/up 重新启动站点。

​

离线迁移

为防止用户在历史迁移脚本运行期间登录，请按照以下步骤操作：

• 使用管理员账户登录你的 Overleaf 实例
• 点击 Admin 按钮并选择 Manage Site
• 点击 Open/Close Editor 选项卡
• 点击 Close Editor 按钮
• 点击 Disconnect all users 按钮

完成上述操作后，任何已登录的用户都会被重定向到维护页面，任何访问登录页面的新用户都会看到维护页面，并且无法登录。

​

在线迁移

可以在应用程序仍在运行时执行迁移脚本。需要注意以下几点：

• 迁移过程会占用大量 CPU，你应在脚本运行期间监控资源使用情况。
• 如果 --concurrency 值较高，某些服务（尤其是 track-changes）中的事件循环可能会出现阻塞，从而导致用户体验下降。我们建议从默认值 --concurrency=1 开始。
• 你可以随时停止脚本。再次启动时，迁移会从上次停止的地方继续。如果你希望在不太繁忙的时段（例如夜间）运行迁移，这会很有用。

当你的项目数量少于 1000 个（db.projects.count()）时，我们建议关闭站点，并在维护窗口内离线执行迁移。如果项目数量很多，你可以先运行脚本并监控其进度，然后根据具体情况决定继续在线还是离线运行。

​

清理旧版历史数据

Server Pro 3.5.6、4.0.6 和 4.1.0 中新增了一个用于清理旧版历史数据的脚本。

bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/history/clean_sl_history_data.js"

该脚本可以在所有项目迁移完成后运行。在执行在线迁移期间，也可以使用它来释放部分空间。

在 3.5.13 之前版本的 Server Pro 中，该脚本会删除 docHistory 和 docHistoryIndex 集合的内容。MongoDB 在删除文档后不会释放磁盘空间，而是会将该空间重新用于同一集合中的后续文档。由于历史迁移后不会再有任何内容写入这些集合，这些磁盘空间将一直处于未使用状态。

如果你希望重新释放这些磁盘空间，可以升级到 Server Pro 3.5.13（仍在使用 3.x 版本时）或 Server Pro 4.2.5（使用 4.x 版本时），然后重新运行清理脚本。

3.5.x 最新补丁版本以及最新 4.x.x 版本的 Server Pro 中包含的清理脚本会在最后一步删除这些集合。

重新运行清理脚本是安全的。

​

故障排除

我们会在这里补充故障排除建议。请注意，虽然我们通常只为 Server Pro 客户提供支持，但鉴于此次迁移的性质，对于遇到完整项目历史迁移相关问题的 CE 用户，我们也会尽力提供支持。

如果完整项目历史迁移脚本失败（即以错误退出，或输出的失败项目数不为零），请通过电子邮件 [e-mail] 将以下详细信息发送给我们的支持团队：

主题：Full project history migration problem

• 实例类型：CE 或 Server Pro（删除不适用的选项）
• 安装类型：Overleaf toolkit、docker-compose.yml 或其他（删除不适用的选项）
• 版本：3.5.x（toolkit：$ cat config/version）
• 迁移脚本输出（应位于容器内的 /overleaf/services/web 下）
• 已迁移项目数：（根据迁移脚本输出）
• 项目总数：（根据迁移脚本输出）
• 剩余项目数：（根据迁移脚本输出）
• 迁移持续时间：
• bin/doctor 输出（使用 toolkit 时）
• Toolkit 版本：$ git rev-parse HEAD（使用 Toolkit 时）

建议在邮件中附上 history-v1、project-history 和 track-changes 服务的日志文件。你可以在 sharelatex 容器内的 /var/log/sharelatex 中找到这些文件，并按如下方式导出：

$ docker cp sharelatex:/var/log/sharelatex/history-v1.log history-v1.log
$ docker cp sharelatex:/var/log/sharelatex/project-history.log project-history.log
$ docker cp sharelatex:/var/log/sharelatex/track-changes.log track-changes.log

在附上日志文件之前，请删除其中的所有敏感信息。

​

查找损坏的文件树

对于文件树格式错误的项目（例如文件名为空），迁移可能会失败。你可以使用 find_malformed_filetrees 脚本检查数据库中的所有项目，找出这些问题：

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/find_malformed_filetrees.js"
BAD PATH: 123456789012345678901234 rootFolder.0.1.2.3
BAD PATH: 123456789012345678901234 rootFolder.0.4.5.6
...

要修复无效路径，请使用 fix_malformed_filetree 脚本，针对每个损坏的路径分别运行一次命令：

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.1.2.3"
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.4.5.6"
...

​

将项目从完整项目历史降级为旧版历史

如果某个项目已迁移到完整项目历史，但你希望恢复到旧版历史，请按如下方式使用 downgrade_project 脚本：

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; PROJECT_ID=YOUR