> ## 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.

# Dropbox 同步

<Info>
  此功能由 [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) 開發，自 v6.4.0 起推出，目前仍處於 Beta 階段。如果您遇到任何問題，歡迎提供回饋。
</Info>

Dropbox 同步會讓使用者的專案與其 Dropbox 保持同步，就像在 Overleaf Cloud 上一樣：使用者連結 Dropbox 帳號後，其每個專案都會以資料夾的形式出現在 `Apps/<your Dropbox app>/` 中，在 Overleaf 中所做的變更會傳送至 Dropbox，而在 Dropbox 中所做的變更也會回傳至 Overleaf。

### 設定 Dropbox 同步

<Warning>
  您需要先啟用 [git-bridge](/zh-TW/on-premises/configuration/overleaf-toolkit/git-integration)：若未啟用，帳號設定中會隱藏專案同步區塊。

  ```dotenv title="config/overleaf.rc" theme={null}
  GIT_BRIDGE_ENABLED=true
  ```
</Warning>

請以將擁有該應用程式的 Dropbox 帳號登入 [Dropbox App Console](https://www.dropbox.com/developers/apps)，並建立應用程式：

1. 點擊 **Create app**，然後填寫頁面：
   * **1. Choose an API**：選擇 **Scoped access**。
   * **2. Choose the type of access you need**：選擇 **App folder**，而非 **Full Dropbox**。Overleaf 只會在應用程式的資料夾內進行同步。
   * **3. Name your app**：輸入名稱，例如 `Overleaf`。此名稱在 Dropbox 上必須是唯一的。每位使用者的專案都會出現在其 Dropbox 的 `Apps/<name of your app>/` 中，而此名稱即為下方的 `DROPBOX_APP_NAME`。
   * 點擊 **Create app**。應用程式會在 **Settings** 分頁中開啟。
2. 在 **Permissions** 分頁的 **Files and folders** 下，勾選 `files.metadata.write`、`files.content.write` 與 `files.content.read`。`account_info.read` 與 `files.metadata.read` 會隨之勾選，且無法取消勾選。請勿勾選其他權限。
3. 點擊 **Permissions** 分頁底部列中的 **Submit**。**若未點擊 Submit，權限就不會被儲存**，Dropbox 也會拒絕為連結帳號的使用者同步檔案。

<Frame caption="Dropbox App Console：需勾選的權限，並以 Submit 儲存">
  <img src="https://mintcdn.com/ayakaleaf-pro/34P8O6kHo91beEvQ/images/on-premises/dropbox-app-permissions.png?fit=max&auto=format&n=34P8O6kHo91beEvQ&q=85&s=8e99711b1fcf03d3d1655f65fea3a6b8" alt="" width="2302" height="1444" data-path="images/on-premises/dropbox-app-permissions.png" />
</Frame>

4. 在 **Settings** 分頁的 **OAuth 2** 下，於 **Redirect URIs** 中輸入 `${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback`，然後**點擊 Add**。只輸入 URI 並不夠：只有當它出現在欄位上方的清單中時，才算儲存完成。

<Frame caption="Dropbox App Console：輸入重新導向 URI，然後點擊 Add">
  <img src="https://mintcdn.com/ayakaleaf-pro/34P8O6kHo91beEvQ/images/on-premises/dropbox-app-redirect-uri.png?fit=max&auto=format&n=34P8O6kHo91beEvQ&q=85&s=d980dc4dec22a90b5bf1f7e147cfc7c0" alt="" width="2788" height="1450" data-path="images/on-premises/dropbox-app-redirect-uri.png" />
</Frame>

5. 在 **Settings** 分頁的 **Webhooks** 下，於 **Webhook URIs** 中輸入 `${OVERLEAF_SITE_URL}/dropbox/webhook`，然後同樣**點擊 Add**。Dropbox 會立即呼叫此網址進行檢查，因此 Overleaf 必須已使用下方的設定執行，且可從網際網路存取（請參閱 [Webhook](#webhook)）。檢查通過後，其狀態會顯示為 **Enabled**。

從 **Settings** 分頁複製 **App key** 與 **App secret**（點擊 **Show**），接著將以下設定加入您的 Overleaf 環境變數檔案。您可以在 Overleaf 使用這些設定執行後，再加入 webhook（步驟 5）。

```dotenv title="config/variables.env" wrap theme={null}
# used to encrypt the user's Dropbox refresh token.
# How to generate: `openssl rand -hex 32`
DROPBOX_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Dropbox Sync Settings
DROPBOX_ENABLED=true
DROPBOX_APP_KEY=
DROPBOX_APP_SECRET=
# the name of your Dropbox app (step 1), which is the folder name in Apps/
DROPBOX_APP_NAME=Overleaf

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback
# Webhook is: ${OVERLEAF_SITE_URL}/dropbox/webhook
# (Optional) DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808
```

<Warning>
  * 在設定重新導向 URI 與 webhook 之前，請確認 `OVERLEAF_SITE_URL` 已正確設定。
  * Dropbox 會在使用者連結帳號時固定權杖的權限：提交權限並不會變更既有的權杖。在權限提交之前（或在您變更權限之前）就已連結的使用者，必須解除連結後再重新連結其 Dropbox 帳號。
  * 新建立的應用程式處於 **Development** 狀態。如果 **Settings** 分頁中的 **Development users** 顯示 **Only you**，則只有您的 Dropbox 帳號可以連結：請點擊 **Enable additional users**，讓其他使用者也能連結自己的帳號。之後會顯示已連結的使用者人數，例如 `1 / 500`：**處於 Development 狀態的應用程式最多只能容納 500 位使用者**。若需要更多使用者，請點擊 **Apply for production**，由 Dropbox 審查該應用程式。
</Warning>

如果您位於網路存取受限的地區，可能需要設定代理伺服器才能存取 Dropbox。請設定以下環境變數：`DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808`。它必須是標準的 HTTP/HTTPS 正向代理伺服器，且不得使用 `127.0.0.1`。

### Webhook

Dropbox 會透過 webhook 通知 Overleaf 在 Dropbox 中發生的變更，因此這些變更會在幾秒內出現在 Overleaf 中。Webhook 會傳送至您網站的位址 `${OVERLEAF_SITE_URL}/dropbox/webhook`，不需要額外的連接埠，但 **Dropbox 必須能從網際網路存取它**。當您在 App Console 中加入 webhook 時，Dropbox 會立即進行檢查。

若沒有 webhook（例如在 Dropbox 無法存取的伺服器上），在 Overleaf 中所做的變更仍會傳送至 Dropbox，但在 Dropbox 中所做的變更只有在使用者於編輯器的 Dropbox 對話框中點擊「*立即同步此專案*」時才會回傳。

### 同步的運作方式

* **連結**：當使用者連結 Dropbox 帳號時，其擁有的專案會傳送至 Dropbox。與其共用的專案會在下一次變更時出現在 Dropbox 中。
* **Overleaf 至 Dropbox**：新檔案、重新命名、移動、刪除與專案重新命名會立即傳送。在編輯器中所做的編輯，會在 Overleaf 將其儲存至儲存空間後傳送，也就是所有人離開專案幾分鐘後。若要提早傳送，請在編輯器的 Dropbox 對話框中點擊「*立即同步此專案*」（每分鐘一次）。
* **Dropbox 至 Overleaf**：專案資料夾中的新增與變更檔案、新資料夾及刪除都會套用至專案。在應用程式資料夾最上層新增的資料夾會成為新專案。在 Dropbox 中刪除專案資料夾，會在 Overleaf 中將該專案標記為已刪除。
* **衝突**：當檔案同時在兩處被變更時，以最後一次變更為準。Dropbox 可能會將另一個版本保留為「*衝突的複本*」。
* **協作者**：連結 Dropbox 的協作者會取得與其共用的專案。唯讀檢視者與審閱者也會取得專案，但他們在 Dropbox 中所做的變更不會同步回 Overleaf。
* **忽略的檔案**：Overleaf 不會同步的檔案，例如建置輸出（`.aux`、`.log`、…）、`.DS_Store` 或 Python 虛擬環境，只會保留在 Dropbox 中。

### Q\&A

<Accordion title="為什麼使用者無法連結其 Dropbox 帳號？">
  <strong>回答：</strong>

  * 專案是依名稱對應至 Dropbox 資料夾，因此擁有兩個同名專案的使用者，會被要求先將其中一個重新命名。
  * 一個 Dropbox 帳號只能連結至一個 Overleaf 帳號。
</Accordion>

<Accordion title="為什麼 Dropbox 帳號被解除連結？">
  <strong>回答：</strong>當 Dropbox 拒絕其權杖（例如使用者在 Dropbox 中移除了該應用程式）、Dropbox 空間已滿，或 Dropbox 停用了該帳號時，Overleaf 會解除該 Dropbox 帳號的連結。問題解決後，使用者可以重新連結。
</Accordion>

<Accordion title="我可以在 Dropbox 中重新命名專案資料夾嗎？">
  <strong>回答：</strong>請改為在 Overleaf 中重新命名專案。對 Overleaf 而言，在 Dropbox 中重新命名資料夾等同於刪除專案資料夾並建立新資料夾，因此舊專案會被標記為已刪除，並以這些檔案建立新專案。
</Accordion>


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