> For the complete documentation index, see [llms.txt](https://overleaf-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://overleaf-pro.ayaka.space/on-premises/zh-tw/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-tw/she-ding/overleaf-toolkit/s3.md).

### 需求

* 可供連線的相容 S3 物件儲存，請參見 [S3](/on-premises/zh-tw/she-ding/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 目錄已經具有正確的結構。您可以直接從以 bind mount 掛載的來源資料夾上傳，這不需要額外磁碟空間。
{% 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 bucket 名稱。
* 同時也將 `/srv/overleaf-bind-mount` 替換為 `/var/lib/overleaf` bind mount 的本機路徑。預設為 `~/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-tw/she-ding/overleaf-toolkit/s3.md#overview-of-variables) 一節，位於 [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) 設定指南中。

對於 Docker Compose 部署，您也可以從 volumes 區段中移除資料目錄的 bind mount。

{% hint style="success" %}
請保留 [用於暫存檔案的 scratch disk bind mount](/on-premises/zh-tw/zhi-yuan/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://overleaf-pro.ayaka.space/on-premises/zh-tw/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.