Dropbox 同步

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

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

​

設定 Dropbox 同步

您需要先啟用 git-bridge：若未啟用，帳號設定中會隱藏專案同步區塊。

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

請以將擁有該應用程式的 Dropbox 帳號登入 Dropbox App Console，並建立應用程式：

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 也會拒絕為連結帳號的使用者同步檔案。

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

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

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

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

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

config/variables.env

# 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

• 在設定重新導向 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 帳號之前執行一次。Server CE 與 Server Pro 不會建立 Dropbox 同步所使用的索引，若缺少這些索引，每次同步查詢都會掃描整個集合。

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

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 會略過已存在的索引。

請勿改為執行 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

為什麼使用者無法連結其 Dropbox 帳號？

• Overleaf 尚未認得的 Dropbox 資料夾會依名稱對應至專案，因此專案有同名情況的使用者，會被要求先將它們重新命名。名稱比對不區分大小寫，已封存與已移至垃圾桶的專案也會納入計算。
• 一個 Dropbox 帳號只能連結至一個 Overleaf 帳號。

為什麼 Dropbox 帳號被解除連結？

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

我可以在 Dropbox 中重新命名專案資料夾嗎？

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

為什麼有些專案資料夾帶有編號，例如「Thesis (1)」？

回答：每個專案都有自己的資料夾，即使兩個專案同名也是如此。Dropbox 無法容納兩個同名資料夾，因此會在較晚建立的資料夾名稱加上編號。編號取決於當時 Dropbox 中哪些名稱尚未被使用，而非哪個專案較早建立。Overleaf 知道每個專案對應的資料夾，因此變更絕不會傳送至另一個同名專案的資料夾。

若上傳的專案名稱已被使用，它在 Overleaf 中也會以加上編號的名稱命名，例如「Thesis (1)」。

在 Dropbox 中刪除專案資料夾會發生什麼事？

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

在 Overleaf 中刪除專案時，Dropbox 中會發生什麼事？

回答：什麼都不會發生，其資料夾會保留在 Dropbox 中。若不再需要，請在 Dropbox 中刪除該資料夾。

專案被封存或移至垃圾桶期間，Dropbox 中的變更會如何處理？

回答：這些變更不會套用至專案，還原專案也不會將其帶入。還原後，對於在此期間於 Dropbox 中被變更的檔案，Overleaf 會停止傳送其變更，因此兩邊會出現差異。

若要讓這類檔案重新同步，請在 Dropbox 中再儲存一次。Overleaf 接著會採用 Dropbox 的版本：還原後在 Overleaf 中對該檔案所做的變更會被取代，但仍保留在專案歷史記錄中。請先還原專案，再於 Dropbox 中修改它。

為什麼編輯器中的 Dropbox 連結會開啟 Dropbox 首頁？

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

為什麼專案的部分檔案在 Dropbox 中遺失？

回答：同步服務未執行期間（例如重新啟動時）所做的變更，之後不會再傳送至 Dropbox。請在編輯器的 Dropbox 對話框中點擊「立即同步此專案」：它會重新傳送整個專案。