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

完整项目历史迁移

该 3.5.x 社区版的发布包含 完整项目历史功能 该功能已在我们的 SaaS 服务中提供， overleaf.com

在将您的实例升级到 Overleaf CE 之后 3.5.13，所有新项目默认将使用完整项目历史。现有项目将继续使用遗留的历史系统，直到它们被迁移。

如果您升级到 3.5.13 并决定降级到早期版本，则应从完整系统备份中还原。在 3.5.13 中创建的项目历史与早期版本的 Overleaf CE 不兼容。

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

• 它跟踪二进制文件的更改，遗留系统不支持此功能。

• 支持标记版本（labelled versions）。

• 该系统总体更健壮，数据丢失的几率更小。

查看 完整项目历史文档 以获取有关完整项目历史的更多信息。

迁移现有项目

1

创建备份

创建一个完整的 备份 包含一致快照的实例，以及 mongo, redis 和 sharelatex 目录。

2

更新

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

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

3

启动实例

理想情况下，您应在迁移进行时阻止用户访问您的实例，以避免在需要还原备份时发生数据丢失。请参阅 离线迁移 以获取有关如何执行此操作的更多信息。

4

等待所有服务启动并运行

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

$ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
web sharelatex 存活 (api)%

5

运行迁移脚本

# Overleaf 工具包用户：
$ 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"

# 旧版 docker-compose.yml 用户：
$ 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 可编辑大小阈值的文档转换为不可编辑文件）

输出应如下所示：

已迁移项目数  :  1
项目总数         :  51
剩余项目数       :  51
需迁移的历史记录总数: 98
开始迁移...
正在迁移项目: 63d29b5772dd80015a81bffe
迁移结果 { upgraded: true, historyType: 'NoneWithoutConversion' }
正在迁移项目: 63d29c2e72dd80015a81c0a2
迁移结果 { upgraded: true, historyType: 'NoneWithoutConversion' }

// …

迁移完成
==================
已迁移项目:  51
迁移失败项目:  0
Done.

如果迁移成功，您将获得退出代码为 0，并且最后几行显示没有失败：

迁移失败项目:  0
Done.

您可以重新开放对用户的访问（见下一步）。如果有失败，请参见下面的故障排除部分。如果问题未立即修复，您仍然可以重新开放站点，未迁移的项目将保留在遗留历史系统中。

6

重新打开站点

如果您选择执行离线迁移，则需要重新打开站点。如果您仍然已登录，则需要：

1. 点击 管理 按钮并选择 管理站点

2. 点击 打开/关闭编辑器 选项卡

3. 点击 重新打开编辑器 按钮

如果您已关闭浏览器，则需要使用以下命令重启站点 $ bin/up.

离线迁移

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

• 使用管理员帐户登录到您的 Overleaf 实例

• 点击 管理 按钮并选择 管理站点

• 点击 打开/关闭编辑器 选项卡

• 点击 关闭编辑器 按钮

• 点击 断开所有用户连接 按钮

完成此操作后，任何已登录的用户将被重定向到维护页面，任何新访客在访问登录页面时也将看到维护页面并且 将不会 能够登录。

在线迁移

可以在应用仍然运行时运行迁移脚本。需要考虑一些事项：

• 迁移过程对 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 不会释放磁盘空间，而是会在相同集合中为将来的文档重用这些空间。历史迁移完成后不会再向这些集合写入任何内容，因此磁盘空间将保持未使用状态。

如果您想让磁盘空间重新可用，可以在仍使用 3.x 发行版时升级到 Server Pro 3.5.13，或在使用 4.x 发行版时升级到 Server Pro 4.2.5，然后重新运行清理脚本。

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

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

故障排除

我们将在此处添加故障排除建议。请注意，尽管我们通常仅为 Server Pro 客户提供支持，但鉴于此迁移的性质，我们也将尽力支持在完整项目历史迁移过程中遇到问题的 CE 客户。

如果完整项目历史迁移脚本失败（即以错误退出或打印出非零数量的失败项目），请将以下详细信息通过电子邮件发送给我们的支持团队 [email protected]，详细说明：

主题：完整项目历史迁移问题

• 实例类型：CE 或 Server Pro（请按需删除）

• 安装类型：Overleaf 工具包或 docker-compose.yml 或其他（请按需删除）

• 版本：3.5.x（工具包： $ cat config/version)

• 迁移脚本输出（应位于容器的 /overleaf/services/web)

• 迁移项目数： （以迁移脚本输出为准）

• 项目总数： （以迁移脚本输出为准）

• 剩余项目数： （以迁移脚本输出为准）

• 迁移持续时间：

• bin/doctor 输出（使用工具包时）

• 工具包版本： $ git rev-parse HEAD （使用工具包时）

考虑将 history-v1, project-history 和 track-changes 服务的日志文件附加到邮件。您可以在以下位置找到这些文件： /var/log/sharelatex 在 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"
错误路径： 123456789012345678901234 rootFolder.0.1.2.3
错误路径： 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