> 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/wei-hu/s3-migration.md).

# S3 迁移

## S3 迁移

{% hint style="info" %}
这些说明适用于 v5.x 及更高版本。如果您正在为更早版本遵循本指南，请使用 `sharelatex` 而不是 `overleaf` 在路径名中以及 `SHARELATEX_` 前缀，而不是 `OVERLEAF_` 用于环境变量。
{% endhint %}

{% hint style="warning" %}
Server Pro 客户：在将数据迁移到 S3 之前，请先联系支持团队。
{% endhint %}

{% hint style="success" %}
**我们很乐意听取您的反馈！** 如果您愿意与我们分享您迁移了多少文件、总体数据量以及迁移耗时，请发送邮件至 [`support@overleaf.com`](mailto:support@overleaf.com) .
{% endhint %}

本指南将引导您完成从磁盘存储迁移到 S3 兼容对象存储的过程。它引用了介绍文档中的相关部分，位于 [S3 设置](/on-premises/zh-cn/pei-zhi/overleaf-toolkit/s3.md).

### 要求

* 一个可连接的 S3 兼容对象存储，参见 [S3](/on-premises/zh-cn/pei-zhi/overleaf-toolkit/s3.md#s3-setup) 以获取选项
* 用于迁移现有数据的可用磁盘空间，约为当前磁盘占用大小
* 用于执行实际迁移的维护窗口
* 完整备份，包括配置，以便可从中恢复

### 估算迁移所需的磁盘空间

我们可以使用 `du` 来计算当前磁盘使用量：

```shell
docker exec sharelatex \\
  du --human-readable --max-depth=0 /var/lib/overleaf/data/user_files

docker exec sharelatex \\
  du --human-readable --max-depth=0 /var/lib/overleaf/data/template_files
```

如果当前服务器上可用磁盘空间不足，请尝试为服务器挂载另一块磁盘。

{% hint style="info" %}
history 目录已经具有正确的布局。您可以直接从绑定挂载的源文件夹上传，这不需要额外的磁盘空间。
{% endhint %}

### 迁移步骤

#### 步骤 0：关闭实例

我们需要确保所有用户/模板文件都会被迁移。最好关闭实例，以避免遗漏新上传的文件。

有关关闭流程，请参阅我们关于执行一致性备份的指南。

#### 步骤 1：重写目录布局

我们需要重写项目文件的目录布局，以便将它们上传到 S3。filestore 中本地存储的目录布局是 `<project-id>_<file-id>` 而 S3 中的目录布局是 `<project-id>/<file-id>`.

下面， `/srv/overleaf-s3-migration` 用于按新的目录布局存储文件。

我们可以使用 `tar` 来重写布局：

```shell
mkdir -p /srv/overleaf-s3-migration/user_files \\
         /srv/overleaf-s3-migration/template_files
docker exec sharelatex \\
  tar --create --directory /var/lib/overleaf/data/user_files . \\
| tar --extract --directory /srv/overleaf-s3-migration/user_files \\
  --transform=sx_x/x
docker exec sharelatex \\
  tar --create --directory /var/lib/overleaf/data/template_files . \\
| tar --extract --directory /srv/overleaf-s3-migration/template_files \\
  --transform=sx_x/xg
```

#### 步骤 2：上传文件

根据您的偏好，您可以使用 minio mc S3 客户端或 aws cli 将文件上传到您的 S3 兼容对象存储。

**aws cli**

{% hint style="info" %}

* 这里您应将 `overleaf-user-files`, `overleaf-template-files`, `overleaf-project-blobs` 和 `overleaf-chunks` 替换为您的 S3 存储桶名称。
* 同时还要将 `/srv/overleaf-bind-mount` 替换为 `/var/lib/overleaf` 绑定挂载的本地路径。默认情况下，这是 `~/overleaf_data` 在 docker-compose.yml 部署中，以及 `<toolkit-checkout>/data/overleaf` 在使用 Toolkit 时。
  {% endhint %}

{% code overflow="wrap" %}

```shell
aws s3 sync /srv/overleaf-s3-migration/user_files s3://overleaf-user-files
aws s3 sync /srv/overleaf-s3-migration/template_files s3://overleaf-template-files

aws s3 sync /srv/overleaf-bind-mount/data/history/overleaf-project-blobs s3://overleaf-project-blobs
aws s3 sync /srv/overleaf-bind-mount/data/history/overleaf-chunks s3://overleaf-chunks
```

{% endcode %}

**minio mc**

这里我们使用服务器别名“s3”，您也可能选择了其他名称。

{% code overflow="wrap" %}

```shell
mc mirror /srv/overleaf-s3-migration/user_files s3/overleaf-user-files
mc mirror /srv/overleaf-s3-migration/template_files s3/overleaf-template-files

mc mirror /srv/overleaf-bind-mount/data/history/overleaf-project-blobs s3/overleaf-project-blobs
mc mirror /srv/overleaf-bind-mount/data/history/overleaf-chunks s3/overleaf-chunks
```

{% endcode %}

#### 步骤 3：使用 S3 启动实例

将所有与 S3 相关的变量添加到您的配置中，详见 [变量概览](/on-premises/zh-cn/pei-zhi/overleaf-toolkit/s3.md#overview-of-variables) 中的 [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) 设置指南。

对于 Docker Compose 部署，您还可以从 volumes 部分移除数据目录的绑定挂载。

{% hint style="success" %}
请保留 [用于临时文件的 scratch 磁盘绑定挂载](/on-premises/zh-cn/zhi-chi/troubleshooting.md#running-overleaf-with-an-nfs-filesystem) 保持不变。
{% endhint %}

现在您可以启动实例并验证迁移：

* 可以在编辑器中预览二进制文件
* 可以编译包含图片的 PDF
* 可以上传新文件

### 回滚

您可以通过反向执行这些步骤来平稳回滚迁移：

1. 关闭实例
2. 通过反转源/目标顺序将文件镜像回去
3. 使用反向的方式将新文件写回本地目录 `变换`
4. 使用旧配置重新启动实例

{% code overflow="wrap" %}

```shell
# 使用 aws cli 时
aws s3 sync s3://overleaf-user-files /srv/overleaf-s3-migration/user_files
aws s3 sync s3://overleaf-template-files /srv/overleaf-s3-migration/template_files
aws s3 sync s3://overleaf-project-blobs /srv/overleaf-bind-mount/data/history/overleaf-project-blobs
aws s3 sync s3://overleaf-chunks /srv/overleaf-bind-mount/data/history/overleaf-chunks

# 使用 minio mc 时
mc mirror s3/overleaf-user-files /srv/overleaf-s3-migration/user_files
mc mirror s3/overleaf-template-files /srv/overleaf-s3-migration/template_files
mc mirror s3/overleaf-project-blobs /srv/overleaf-bind-mount/data/history/overleaf-project-blobs
mc mirror s3/overleaf-chunks /srv/overleaf-bind-mount/data/history/overleaf-chunks
```

{% endcode %}

```shell
# 将文件写入本地 Server CE/Server Pro
tar --create --directory /srv/overleaf-s3-migration/user_files . \\
| docker exec --interactive sharelatex \\
    tar \\
      --extract \\
      --keep-old-files \\
      --directory /var/lib/overleaf/data/user_files \\
      --transform=sx./xx --transform=sx/x_x \\
      --wildcards '*/*/*'

tar --create --directory /srv/overleaf-s3-migration/template_files . \\
| docker exec --interactive sharelatex \\
    tar \\
      --extract \\
      --keep-old-files \\
      --directory /var/lib/overleaf/data/template_files \\
      --transform=sx./xx --transform=sx/x_xg \\
      --wildcards '*/*/*/*/pdf-converted-cache/*' \\
      --wildcards '*/*/*/*/pdf' \\
      --wildcards '*/*/*/*/zip'
```

{% hint style="info" %}
第一个 transform 会删除顶层文件夹。第二个 transform 会将目录布局改为扁平结构。通配符确保只提取文件，而不提取其父级（项目）文件夹。
{% endhint %}


---

# 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/wei-hu/s3-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.