> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# （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` 后，所有新项目都会默认使用完整项目历史。现有项目将继续使用旧版历史系统，直到它们被迁移。

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

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

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

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

### 迁移现有项目

<Steps>
  <Step title="创建备份">
    为你的实例创建完整的[备份](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup)，其中包含 **mongo**、**redis** 和 **sharelatex** 目录的一致性快照。
  </Step>

  <Step title="更新">
    将 sharelatex/sharelatex 镜像的版本更新为 3.5.13。

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

  <Step title="启动实例">
    理想情况下，你应在迁移期间阻止用户访问你的实例，以免在需要恢复备份时造成数据丢失。有关具体做法的更多信息，请参阅[离线迁移](https://github.com/overleaf/overleaf/wiki/Full-Project-History-Migration/#offline-migration)。
  </Step>

  <Step title="等待所有服务启动并运行">
    等待所有服务启动并运行（参见下方命令）

    ```bash wrap theme={null}
    $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
    web sharelatex is alive (api)%
    ```
  </Step>

  <Step title="运行迁移脚本">
    ```bash wrap theme={null}
    # 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 可编辑大小阈值的文档转换为不可编辑的文件）

    输出应如下所示：

    ```bash theme={null}
    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`，并且最后几行显示没有失败：

    ```bash theme={null}
    Projects failed:  0
    Done.
    ```

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

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

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

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

#### 离线迁移

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

* 使用管理员账户登录你的 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` 中新增了一个用于清理旧版历史数据的脚本。

```bash wrap theme={null}
bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/history/clean_sl_history_data.js"
```

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

<Info>
  在 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 中包含的清理脚本会在最后一步删除这些集合。

  重新运行清理脚本是安全的。
</Info>

### 故障排除

我们会在这里补充故障排除建议。请注意，虽然我们通常只为 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) 将以下详细信息发送给我们的支持团队：

主题：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` 中找到这些文件，并按如下方式导出：

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

```bash wrap theme={null}
$ 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` 脚本，针对每个损坏的路径分别运行一次命令：

```bash wrap theme={null}
$ 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` 脚本：

```bash wrap theme={null}
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; PROJECT_ID=YOUR
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.