> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/zh-cn/zhi-chi/support-guides/full-project-history-migration.md).

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

## 完整项目历史迁移

该 `3.5.x` 社区版的发布包含 [完整项目历史功能](https://www.overleaf.com/learn/latex/Using_the_History_feature) 该功能已在我们的 SaaS 产品中提供， [overleaf.com](http://overleaf.com/)

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

{% hint style="info" %}
如果你升级到 `3.5.13` 并决定降级到更早版本，那么你应从完整系统备份中恢复。在 `3.5.13` 中创建的项目历史与更早版本的 Overleaf CE 不兼容。
{% endhint %}

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

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

查看 [完整项目历史文档](https://www.overleaf.com/learn/latex/Using_the_History_feature) 以了解有关完整项目历史的更多信息。

### 迁移现有项目

{% stepper %}
{% step %}

#### 创建备份

创建完整 [备份](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) 对你的实例进行一致性快照的 **mongo**, **redis** 和 **sharelatex** 目录。
{% endstep %}

{% step %}

#### 更新

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

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

{% step %}

#### 启动实例

理想情况下，在迁移进行期间，你会希望阻止用户访问你的实例，以避免在需要恢复备份时发生数据丢失。请参见 [离线迁移](https://github.com/overleaf/overleaf/wiki/Full-Project-History-Migration/#offline-migration) 以了解更多操作方法。
{% endstep %}

{% step %}

#### 等待所有服务启动并运行

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

{% code overflow="wrap" %}

```bash
$ bin/docker-compose exec sharelatex /bin/bash -c \"curl http://localhost:3000/status\"
web sharelatex 已运行（api）%
```

{% endcode %}
{% endstep %}

{% step %}

#### 运行迁移脚本

{% code overflow="wrap" %}

```bash
# Overleaf Toolkit 用户：
$ 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\"
```

{% endcode %}

`--force-clean` 清除新系统中部分已迁移的项目历史数据，这使得可以重新尝试迁移先前失败的单个项目；

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

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

输出应如下所示：

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

// …

迁移完成
==================
已迁移项目： 51
失败项目： 0
完成。
```

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

```bash
失败项目： 0
完成。
```

你可以重新向用户开放访问（见下一步）。如果有失败，请参见下面的故障排除部分。如果问题不能立即解决，你仍然可以重新开放站点，而未迁移的项目将保留在旧版历史系统中。
{% endstep %}

{% step %}

#### 重新开放站点

如果你选择执行离线迁移，那么你需要重新开放站点。如果你仍然登录着，你需要：

1. 点击 **管理员** 按钮并选择 **管理站点**
2. 点击 **打开/关闭编辑器** 选项卡
3. 点击 **重新打开编辑器** 按钮

如果你已经关闭浏览器，则需要使用 `$ bin/up`.
{% endstep %}
{% endstepper %}

#### 离线迁移

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

* 使用管理员账户登录你的 Overleaf 实例
* 点击 **管理员** 按钮并选择 **管理站点**
* 点击 **打开/关闭编辑器** 选项卡
* 点击 **关闭编辑器** 按钮
* 点击 **断开所有用户连接** 按钮

完成后，如果有用户已登录，他们将被重定向到维护页面，而任何访问登录页面的新用户将看到维护页面并 **不能** 登录。

#### 在线迁移

在应用仍在运行时也可以执行迁移脚本。需要考虑以下几点：

* 迁移过程会消耗大量 CPU，在脚本运行时应监控资源使用情况。
* 当 `--concurrency` 的值较高时，某些服务（`track-changes` 尤其是）中的事件循环可能会出现一些阻塞，从而导致较差的用户体验。我们建议从默认的 `--concurrency=1` 值开始。
* 你可以随时停止脚本。重新启动它后，它会从你中断的地方继续迁移。如果你更愿意在不太繁忙的时段（例如夜间）运行迁移，这会很有用。

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

#### 清理旧版历史数据

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

{% code overflow="wrap" %}

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

{% endcode %}

该脚本可以在所有项目迁移完成后运行。它也可用于在执行在线迁移时释放一些空间。

{% hint style="info" %}
在 3.5.13 之前的 Server Pro 版本中，该脚本会删除 `docHistory` 和 `docHistoryIndex` 集合中的内容。删除文档后，MongoDB 不会释放磁盘空间，而是会将该空间重用于同一集合中的后续文档。在历史迁移完成后，不会再有内容写入这些集合，因此这部分磁盘空间将一直未被使用。

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

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

可以安全地重新运行清理脚本。
{% endhint %}

### 故障排除

我们将在此处补充故障排除建议。请注意，虽然我们通常只为 Server Pro 客户提供支持，但考虑到此次迁移的性质，对于因完整项目历史迁移而遇到特定问题的 CE 客户，我们也会尽最大努力提供支持。

如果完整项目历史迁移脚本失败（即以错误退出或打印出非零数量的失败项目），请通过电子邮件将以下详细信息发送给我们的支持团队 [support+historymigration@overleaf.com](mailto:support+historymigration@overleaf.com?subject=Full%20project%20history%20migration%20problem\&body=Instance%20Type%3A%20CE%20or%20Server%20Pro%20%28delete%20as%20appropriate%29%0A%0AInstallation%20Type%3A%20Overleaf%20toolkit%20or%20docker-compose.yml%20or%20other%20%28delete%20as%20appropriate%29%0A%0AScript%20output%3A%0A%0Abin%2Fdoctor%20output%20%28if%20using%20toolkit%29%3A%0A)，并附上以下详细信息：

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

* 实例类型：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` 这些服务的日志到邮件中。你可以在以下位置找到它们： `/var/log/sharelatex` 位于 `sharelatex` 容器中，并按如下方式导出：

```bash
$ 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` 脚本来找出这些问题，该脚本会检查数据库中的所有项目：

{% code overflow="wrap" %}

```bash
$ 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
...
```

{% endcode %}

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

{% code overflow="wrap" %}

```bash
$ 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\"
...
```

{% endcode %}

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

如果某个项目已经迁移到完整项目历史，但你想恢复到旧版历史，请使用 `downgrade_project` 脚本，如下所示：

{% code overflow="wrap" %}

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

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ayakaleaf-pro.ayaka.space/on-premises/zh-cn/zhi-chi/support-guides/full-project-history-migration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.