> ## 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 同步

> 讓使用者將專案與其 Dropbox 中的資料夾同步。

> [!NOTE]
>
> 此功能由 [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) 開發，於 v6.3.1 以早期預覽版推出，並將在 v6.4.0 正式發布，因此其設定與行為仍可能變更。如果您遇到任何問題，歡迎提供回饋。

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

### 設定 Dropbox 同步

> [!WARNING]
>
> 您需要先啟用 [git-bridge](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)：若未啟用，帳號設定中會隱藏專案同步區塊。
>
> ```dotenv title="config/overleaf.rc" theme={null}
> GIT_BRIDGE_ENABLED=true
> ```

請以將擁有該應用程式的 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 也會拒絕為連結帳號的使用者同步檔案。

![](https://mintcdn.com/ayakaleaf-pro/34P8O6kHo91beEvQ/images/on-premises/dropbox-app-permissions.png?fit=max\&auto=format\&n=34P8O6kHo91beEvQ\&q=85\&s=8e99711b1fcf03d3d1655f65fea3a6b8)

Dropbox App Console：需勾選的權限，並以 Submit 儲存

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

![](https://mintcdn.com/ayakaleaf-pro/34P8O6kHo91beEvQ/images/on-premises/dropbox-app-redirect-uri.png?fit=max\&auto=format\&n=34P8O6kHo91beEvQ\&q=85\&s=d980dc4dec22a90b5bf1f7e147cfc7c0)

Dropbox App Console：輸入重新導向 URI，然後點擊 Add

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 審查該應用程式。

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

#### 建立資料庫索引

請在使用者連結 Dropbox 帳號之前執行一次。Dropbox 同步所使用的索引不會自動建立，若缺少這些索引，每次同步查詢都會掃描整個集合。

Toolkit 使用者：執行 `bin/mongo`。Docker Compose 使用者：執行 `docker compose exec mongo mongosh sharelatex`。然後貼上：

```js theme={null}
db.dropboxEntities.createIndex(
  { 'overleaf.userId': 1, 'dropbox.id': 1 },
  { name: 'overleaf.userId_1_dropbox.id_1', unique: true,
    partialFilterExpression: { 'dropbox.id': { $exists: true } } })
db.dropboxEntities.createIndex(
  { 'overleaf.userId': 1, 'overleaf.id': 1 },
  { name: 'overleaf.userId_1_overleaf.id_1', unique: true,
    partialFilterExpression: { 'overleaf.id': { $exists: true } } })
db.dropboxEntities.createIndex({ 'overleaf.userId': 1, 'dropbox.pathLower': 'hashed' })
db.dropboxProjects.createIndex({ userId: 1, projectId: 1 }, { name: 'projectId_userId_1', unique: true })
db.dropboxProjects.createIndex({ userId: 1, dropboxId: 1 }, { name: 'userId_dropboxId_1', unique: true })
```

重複執行不會造成任何影響：MongoDB 會略過已存在的索引。

> [!CAUTION]
>
> 請勿改為執行 `tools/migrations` 中的 `dropboxEntities` 遷移：`20220825160708_recreate_dropboxEntities` 會刪除該集合，進而刪除所有使用者的同步狀態。

### 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] 為什麼使用者無法連結其 Dropbox 帳號？
>
> **回答：**
>
> * Overleaf 尚未認得的 Dropbox 資料夾會依名稱對應至專案，因此專案有同名情況的使用者，會被要求先將它們重新命名。名稱比對不區分大小寫，已封存與已移至垃圾桶的專案也會納入計算。
> * 一個 Dropbox 帳號只能連結至一個 Overleaf 帳號。

> [accordion] 為什麼 Dropbox 帳號被解除連結？
>
> \*\*回答：\*\*當 Dropbox 拒絕其權杖（例如使用者在 Dropbox 中移除了該應用程式）、Dropbox 空間已滿，或 Dropbox 停用了該帳號時，Overleaf 會解除該 Dropbox 帳號的連結。專案清單中的通知會告知使用者是哪一種情況，直到其重新連結帳號為止。問題解決後，使用者可以重新連結。

> [accordion] 我可以在 Dropbox 中重新命名專案資料夾嗎？
>
> \*\*回答：\*\*請改為在 Overleaf 中重新命名專案：其在 Dropbox 中的資料夾也會一併重新命名。對 Overleaf 而言，在 Dropbox 中重新命名資料夾等同於刪除專案資料夾並建立新資料夾，因此舊專案會被標記為已刪除，並以這些檔案建立新專案。

> [accordion] 為什麼有些專案資料夾帶有編號，例如「Thesis (1)」？
>
> \*\*回答：\*\*每個專案都有自己的資料夾，即使兩個專案同名也是如此。Dropbox 無法容納兩個同名資料夾，因此會在較晚建立的資料夾名稱加上編號。編號取決於當時 Dropbox 中哪些名稱尚未被使用，而非哪個專案較早建立。Overleaf 知道每個專案對應的資料夾，因此變更絕不會傳送至另一個同名專案的資料夾。
>
> 若上傳的專案名稱已被使用，它在 Overleaf 中也會以加上編號的名稱命名，例如「Thesis (1)」。

> [accordion] 在 Dropbox 中刪除專案資料夾會發生什麼事？
>
> **回答：**
>
> * 若沒有其他專案與該資料夾同名，該專案會在 Overleaf 中被標記為已刪除。其檔案與歷史記錄會被保留。
> * 若有多個專案使用該名稱，Overleaf 無法判斷該資料夾屬於哪一個專案。它會解除該 Dropbox 帳號的連結，並顯示通知要求重新命名這些專案。在 Dropbox 中刪除專案資料夾之前，請先為專案設定不同的名稱。
> * 帶有編號的資料夾（例如「Thesis (1)」）不會對應到任何專案名稱，因此刪除它不會變更 Overleaf 中的專案。請在編輯器的 Dropbox 對話框中點擊「*立即同步此專案*」，將專案重新傳送至 Dropbox。

> [accordion] 在 Overleaf 中刪除專案時，Dropbox 中會發生什麼事？
>
> \*\*回答：\*\*什麼都不會發生，其資料夾會保留在 Dropbox 中。若不再需要，請在 Dropbox 中刪除該資料夾。

> [accordion] 專案被封存或移至垃圾桶期間，Dropbox 中的變更會如何處理？
>
> \*\*回答：\*\*這些變更不會套用至專案，還原專案也不會將其帶入。還原後，對於在此期間於 Dropbox 中被變更的檔案，Overleaf 會停止傳送其變更，因此兩邊會出現差異。
>
> 若要讓這類檔案重新同步，請在 Dropbox 中再儲存一次。Overleaf 接著會採用 Dropbox 的版本：還原後在 Overleaf 中對該檔案所做的變更會被取代，但仍保留在專案歷史記錄中。請先還原專案，再於 Dropbox 中修改它。

> [accordion] 為什麼編輯器中的 Dropbox 連結會開啟 Dropbox 首頁？
>
> \*\*回答：\*\*該連結指向 dropbox.com 上的 `Apps/<app folder>/<project>`，與 Overleaf Cloud 相同。當 Dropbox 以翻譯後的名稱顯示其 `Apps` 資料夾時（例如中文的 `应用`），連結會找不到該資料夾，Dropbox 便會改為開啟其首頁。請在 Dropbox 中從翻譯後的 `Apps` 資料夾開啟專案資料夾。

> [accordion] 為什麼專案的部分檔案在 Dropbox 中遺失？
>
> \*\*回答：\*\*同步服務未執行期間（例如重新啟動時）所做的變更，之後不會再傳送至 Dropbox。請在編輯器的 Dropbox 對話框中點擊「*立即同步此專案*」：它會重新傳送整個專案。


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