> 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-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" %}
歷史目錄的版面配置已經正確。您可以直接從 bind-mounted 來源資料夾上傳，這不需要額外的磁碟空間。
{% 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` 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" %}
請保留 [暫存磁碟的 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 會將目錄版面配置改成扁平結構。wildcards 可確保只會解出檔案，而不是它們的父層（專案）資料夾。
{% 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-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.