（v5.5.7 迁移）二进制文件迁移

二进制文件迁移

即将发布的主要版本 6.0 Server Pro 和 Community Edition 的发行版将使二进制文件的存储使用减半。版本中包含在线迁移， 5.5.7 ，允许在升级时实现最小停机时间。

自 Server Pro 重新命名为以来，二进制文件被存储两次：在“filestore”的活动文件存储中以及在完整项目历史系统中。今后，每个文件将在完整项目历史系统中仅保存一份副本。

向合并存储系统的迁移由两部分组成：用于控制迁移阶段的新标志以及用于处理所有活动和软删除项目的脚本。

阶段：

• OVERLEAF_FILESTORE_MIGRATION_LEVEL=0 （默认），文件从 filestore 读写。文件异步写入历史。

• OVERLEAF_FILESTORE_MIGRATION_LEVEL=1 ，文件从历史读取，回退到 filestore，且写入到 filestore 和历史。可以降级到 OVERLEAF_FILESTORE_MIGRATION_LEVEL=0 。

• OVERLEAF_FILESTORE_MIGRATION_LEVEL=2 文件仅从历史读取和写入。除非以“离线”方式执行，否则无法降级到 OVERLEAF_FILESTORE_MIGRATION_LEVEL=1 。

在将数据存储在 S3 并为 filestore（OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID）和历史（OVERLEAF_HISTORY_S3_ACCESS_KEY_ID）使用单独服务帐户时：请授予 filestore 用户对历史 bucket 的 blob 的读取权限 OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET 。未来 filestore 服务将为编译器服务提供读取。

强烈建议先在非生产/沙箱环境中执行二进制文件迁移。

标准 Server Pro 许可允许您在生产环境以及一个非生产/沙箱环境中运行该应用；我们强烈建议您准备一个非生产环境以进行测试。

如果您升级到 Server Pro/CE 版本 6.0 并在随后决定降级到早期版本，则应从完整系统备份恢复。

迁移程序

1

创建备份

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

2

更新

工具包： 使用 $ bin/upgrade 将 工具包升级到最新版本的脚本。 当被询问时，执行 不要 确认提示 升级 image? — 改为手动编辑 config/version 文件并将值设置为 5.5.7.

旧版 docker-compose.yml： 更新 sharelatex 服务到 5.5.7.

3

估算受影响项目的数量

# Overleaf 工具包用户：
$ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report"

# 旧版 docker-compose.yml 用户：
$ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report"

示例输出：

当前状态：
- 项目总数：10
- 已删除项目总数：5
正在对 1000 个项目抽样以估算进度...
项目抽样统计：
- 抽样项目：9（占所有项目的 90%）
- 抽样项目中所有哈希均存在：5
- 需要回填哈希的项目百分比：44%（估计）
- 抽样项目有 11 个文件需要与完整项目历史系统核对。
- 抽样项目有 3 个文件需要上传到完整项目历史系统（估计占所有文件的 27%）。
已删除项目抽样统计：
- 抽样已删除项目：4（占所有已删除项目的 80%）
- 抽样已删除项目中所有哈希均存在：3
- 需要回填哈希的已删除项目百分比：25%（估计）
- 抽样已删除项目有 2 个文件需要与完整项目历史系统核对。
- 抽样已删除项目有 1 个文件需要上传到完整项目历史系统（估计占所有文件的 50%）。

4

刷新项目历史队列

# Overleaf 工具包用户：
$ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues

# 旧版 docker-compose.yml 用户：
$ docker compose exec sharelatex /overleaf/bin/flush-history-queues

重复刷新直到所有项目都已刷新（"project_ids":0).

找到项目 {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"}
总计 {"succeededProjects":0,"failedProjects":0}

如果 "failedProjects" 不为零，请联系支持并不要继续进行二进制文件迁移。

5

将迁移阶段推进到 1

工具包：设置 OVERLEAF_FILESTORE_MIGRATION_LEVEL=1 中设置 config/variables.env.

旧版 docker-compose.yml：设置 OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1' 在 环境 在 sharelatex 服务。

6

应用配置更改并启动实例

工具包： bin/up -d

旧版 docker-compose.yml： docker compose up -d

7

验证对二进制文件的访问

在浏览器中打开 Overleaf 编辑器的项目并选择二进制文件，例如图片。

8

运行迁移脚本

# Overleaf 工具包用户：
$ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all"

# 旧版 docker-compose.yml 用户：
$ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all"

如果您正在 将日志持久化到 容器之外的文件，确保日志目录的所有者设置为 sharelatex 用户（uid=33），以便输出的日志文件可以被写入。 www-data 将 UV_THREADPOOL_SIZE 设置为 16

输出应如下所示：

{"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Loading backend","time":"2025-07-25T15:00:58.166Z","v":0}
将日志写入 /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log
开始项目文件备份...
已加载全局 blobs：0
处理中未删除的项目...
已处理 1 个项目，耗时 0s
已完成更新活动项目
处理中已删除的项目...
集合 deletedProjects 似乎是空的。
已完成更新已删除的项目

日志文件将如下所示（使用脚本打印的路径）：
Done.

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

Done.

$ docker cp sharelatex:/var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log .

$ cat file-migration-2025-07-25T15_00_58_199Z.log
{"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"end":"68839a8f577b9f009d947b27 (2025-07-25T14:54:07.000Z)","msg":"actually completed batch","time":"2025-07-25T15:00:58.379Z","v":0}
{"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"time":"2025-07-25T15:00:58.383Z","LOGGING_IDENTIFIER":"4effa2000000000000000000","projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063,"eventLoop":{"idle":48.277844,"active":381.53244699971054,"utilization":0.8876763888372498},"diff":{"eventLoop":{"idle":48.223536,"active":134.04030200059555,"utilization":0.7354190687027976},"projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063},"deferredBatches":[],"msg":"file-migration stats","v":0}
停止实例

9

bin/stop sharelatex

工具包： 使旧文件对应用程序不可访问

旧版 docker-compose.yml： docker compose stop sharelatex

10

您现在可以将旧文件移动到二级存储。我们建议保留这些文件一段时间，以防之后出现问题。

# 工具包用户：

$ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files
# 我们假设您使用的是 /var/lib/overleaf 中的默认绑定挂载

# 旧版 docker-compose.yml 用户：
$ docker compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files
# 如果您使用选择性的绑定挂载，您可以在容器内简单地移除 /var/lib/overleaf/data/user_files 的绑定挂载。
将迁移阶段推进到 2

11

OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'

工具包：设置 OVERLEAF_FILESTORE_MIGRATION_LEVEL=2 中设置 config/variables.env.

旧版 docker-compose.yml：设置 如果您希望在二进制文件迁移脚本运行时阻止用户登录，请按照以下步骤操作： 在 环境 在 sharelatex 服务。

12

应用配置更改并启动实例

工具包： bin/up -d

旧版 docker-compose.yml： docker compose up -d

13

验证对二进制文件的访问

在浏览器中打开 Overleaf 编辑器的项目并选择二进制文件，例如图片。

离线迁移

重启实例时需要重复这些步骤。要重新打开站点，只需重启实例。

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

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

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

• 点击 关闭编辑器 按钮

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

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

迁移过程 IO 强度较高，脚本运行时应监控资源使用情况。

在线迁移

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

• 在较高处理并发下，

• 服务中的事件循环可能会出现一些阻塞，导致用户体验下降。我们建议从默认值开始： filestore --concurrency=10 --concurrent-batches=1 和 您可以随时停止脚本。再次启动时会验证之前的项目并跳过已处理的文件。如果您希望在较为空闲的时段（例如夜间）运行迁移，此功能很有用。 .

• 我们的建议是在维护窗口中关闭站点并离线运行迁移，当您的项目数量少于 1000 个项目时（参见使用

--report 运行迁移脚本时的输出）。）在维护窗口内关闭站点并离线运行迁移。如果项目数量较大，您可以运行脚本并监控其进度，然后根据具体情况决定是继续在线运行还是离线运行。

清理遗留的二进制文件数据

完成迁移并验证项目仍能访问其所有文件后，您可以删除旧的文件存储位置 /var/lib/overleaf/data/user_files。我们强烈建议保留这些文件一段时间——您可以先通过重命名该文件夹使它们对应用程序不可访问。

故障排除

我们将在此处添加故障排除建议。请注意，尽管我们通常仅为 Server Pro 客户提供支持，但考虑到此次迁移的性质，我们也将尽最大努力支持遇到与二进制文件迁移相关问题的 CE 客户。

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

主题：二进制文件迁移问题

正文：

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

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

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

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

• 报告：（以 运行迁移脚本时的输出）。)

• 运行迁移脚本）

• 迁移持续时间：

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

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

考虑将 filestore 已处理的项目：（根据脚本的最后一次运行） 将服务的日志发送到该电子邮件。您可以在以下位置找到它： 在 sharelatex 容器并按如下方式导出它们：

/var/log/overleaf/filestore.log
$ docker cp sharelatex:/var/log/overleaf/filestore.log .
# 用脚本打印的时间戳替换 <timestamp>

在附加日志文件之前，请删除其中的任何敏感信息。

$ docker cp sharelatex:/var/log/overleaf/file-migration-<timestamp>.log .

丢失的文件

旧版本的 Server Pro/CE 在用户上传完成之前创建文件树条目，这可能在上传失败时导致文件显示为丢失。处理所有文件树时，您可能会发现有少量此类情况被报告为错误。

如果丢失文件的数量较少，请考虑手动审核这些情况并在浏览器的编辑器中将其删除。

查找损坏的文件树

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

如果丢失文件的数量较多，请考虑联系支持，见上面的电子邮件模板。

要修复无效路径，请使用 fix_malformed_filetree 脚本，对每个错误路径执行一次命令：

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web && /sbin/setuser www-data node scripts/find_malformed_filetrees.mjs > /tmp/malformed-file-trees.json"