Đồng bộ hóa Dropbox

Cho phép người dùng đồng bộ dự án của họ với một thư mục trong Dropbox của họ.

Tính năng này được phát triển bởi ayaka-notes/ayakaleaf-pro. Tính năng được giới thiệu trong v6.3.1 dưới dạng bản xem trước sớm (early preview) và sẽ được phát hành chính thức trong v6.4.0, vì vậy cấu hình và hành vi của tính năng vẫn có thể thay đổi. Nếu gặp bất kỳ vấn đề nào, chúng tôi rất mong nhận được phản hồi của bạn.

Đồng bộ hóa Dropbox giữ các dự án của người dùng luôn đồng bộ với Dropbox của họ, giống như trên Overleaf Cloud: sau khi người dùng liên kết tài khoản Dropbox, mỗi dự án của họ sẽ xuất hiện dưới dạng một thư mục trong Apps/<your Dropbox app>/, các thay đổi trong Overleaf được gửi sang Dropbox, và các thay đổi thực hiện trong Dropbox được đưa trở lại Overleaf.

​

Thiết lập đồng bộ hóa Dropbox

Bạn cần bật git-bridge trước: nếu không có git-bridge, phần cài đặt tài khoản sẽ ẩn mục đồng bộ dự án.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Tạo một ứng dụng trong Dropbox App Console, đăng nhập bằng tài khoản Dropbox sẽ sở hữu ứng dụng:

1. Nhấp Create app, sau đó điền thông tin trên trang:
   • 1. Choose an API: chọn Scoped access.
   • 2. Choose the type of access you need: chọn App folder, không chọn Full Dropbox. Overleaf chỉ đồng bộ bên trong thư mục của ứng dụng.
   • 3. Name your app: nhập một tên, ví dụ Overleaf. Tên này phải là duy nhất trên Dropbox. Các dự án của mỗi người dùng sẽ xuất hiện trong Apps/<name of your app>/ trong Dropbox của họ, và tên này chính là DROPBOX_APP_NAME bên dưới.
   • Nhấp Create app. Ứng dụng sẽ mở ở tab Settings.
2. Trong tab Permissions, mục Files and folders, chọn files.metadata.write, files.content.write và files.content.read. account_info.read và files.metadata.read được chọn cùng và không thể bỏ chọn. Không chọn các quyền khác.
3. Nhấp Submit trong thanh ở cuối tab Permissions. Nếu không nhấp Submit, các quyền sẽ không được lưu, và Dropbox sẽ từ chối đồng bộ tệp cho những người dùng liên kết tài khoản của họ.

Dropbox App Console: các quyền cần chọn, được lưu bằng Submit

4. Trong tab Settings, mục OAuth 2, nhập ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback vào Redirect URIs, sau đó nhấp Add. Chỉ nhập URI là chưa đủ: URI chỉ được lưu khi nó hiển thị trong danh sách phía trên ô nhập.

Dropbox App Console: nhập redirect URI, sau đó nhấp Add

5. Trong tab Settings, mục Webhooks, nhập ${OVERLEAF_SITE_URL}/dropbox/webhook vào Webhook URIs, sau đó cũng nhấp Add. Dropbox sẽ gọi địa chỉ này ngay lập tức để kiểm tra, vì vậy Overleaf phải đang chạy với các cài đặt bên dưới và có thể truy cập được từ internet (xem Webhook). Trạng thái của nó sẽ hiển thị Enabled khi kiểm tra thành công.

Sao chép App key và App secret (nhấp Show) từ tab Settings, sau đó thêm các cài đặt sau vào tệp biến môi trường của Overleaf. Bạn có thể thêm webhook (bước 5) sau khi Overleaf đã chạy với các cài đặt này.

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

• Trước khi cấu hình redirect URI và webhook, hãy đảm bảo OVERLEAF_SITE_URL đã được đặt chính xác.
• Dropbox cố định các quyền của một token khi người dùng liên kết tài khoản: việc gửi quyền không làm thay đổi các token hiện có. Những người dùng đã liên kết trước khi các quyền được gửi, hoặc trước khi bạn thay đổi chúng, phải hủy liên kết và liên kết lại tài khoản Dropbox của họ.
• Một ứng dụng mới ở trạng thái Development. Nếu Development users trong tab Settings hiển thị Only you, chỉ tài khoản Dropbox của bạn có thể được liên kết: nhấp Enable additional users để cho phép những người dùng khác liên kết tài khoản của họ. Sau đó mục này sẽ hiển thị số người dùng đã liên kết, ví dụ 1 / 500: một ứng dụng Development chỉ nhận tối đa 500 người dùng. Để có thêm người dùng, nhấp Apply for production, và Dropbox sẽ xét duyệt ứng dụng.

Nếu bạn ở khu vực có hạn chế truy cập mạng, có thể bạn cần cấu hình proxy để truy cập Dropbox. Hãy đặt biến môi trường sau: DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808. Đây phải là một proxy chuyển tiếp HTTP/HTTPS tiêu chuẩn và không được sử dụng 127.0.0.1.

​

Tạo các chỉ mục cơ sở dữ liệu

Hãy chạy lệnh này một lần, trước khi người dùng liên kết tài khoản Dropbox của họ. Các chỉ mục mà đồng bộ hóa Dropbox sử dụng không được tạo tự động, vì vậy nếu thiếu chúng, mỗi lần tra cứu đồng bộ sẽ phải quét toàn bộ collection.

Người dùng Toolkit: chạy bin/mongo. Người dùng Docker Compose: chạy docker compose exec mongo mongosh sharelatex. Sau đó dán:

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 })

Chạy lại lệnh này cũng không gây hại: MongoDB sẽ bỏ qua các chỉ mục đã tồn tại.

Không chạy các migration dropboxEntities của tools/migrations để thay thế: 20220825160708_recreate_dropboxEntities sẽ xóa collection, làm mất trạng thái đồng bộ của mọi người dùng.

​

Webhook

Dropbox thông báo cho Overleaf về các thay đổi trong Dropbox thông qua webhook, nhờ đó các thay đổi xuất hiện trong Overleaf chỉ trong vài giây. Webhook được gửi đến địa chỉ trang của bạn, ${OVERLEAF_SITE_URL}/dropbox/webhook, không cần thêm cổng nào, nhưng Dropbox phải có thể truy cập địa chỉ này từ internet. Khi bạn thêm nó trong App Console, Dropbox sẽ kiểm tra ngay lập tức.

Nếu không có webhook, ví dụ trên một máy chủ mà Dropbox không thể truy cập, các thay đổi trong Overleaf vẫn được gửi sang Dropbox, nhưng các thay đổi trong Dropbox chỉ được đưa trở lại khi người dùng nhấp sync this project now trong hộp thoại Dropbox của trình soạn thảo.

​

Cách đồng bộ hoạt động

• Liên kết: khi người dùng liên kết tài khoản Dropbox, các dự án mà họ sở hữu sẽ được gửi sang Dropbox. Các dự án được chia sẻ với họ sẽ xuất hiện trong Dropbox khi có thay đổi tiếp theo.
• Từ Overleaf sang Dropbox: các tệp mới, việc đổi tên, di chuyển, xóa và đổi tên dự án được gửi ngay lập tức. Các chỉnh sửa trong trình soạn thảo được gửi khi Overleaf lưu chúng vào bộ lưu trữ, vài phút sau khi mọi người đã rời khỏi dự án. Để gửi sớm hơn, nhấp sync this project now trong hộp thoại Dropbox của trình soạn thảo (một lần mỗi phút).
• Từ Dropbox sang Overleaf: các tệp mới và tệp đã thay đổi, thư mục mới và các thao tác xóa trong thư mục dự án được áp dụng vào dự án. Một thư mục mới ở cấp cao nhất của thư mục ứng dụng sẽ trở thành một dự án mới. Xóa một thư mục dự án trong Dropbox sẽ đánh dấu dự án là đã xóa trong Overleaf.
• Xung đột: khi một tệp thay đổi ở cả hai nơi cùng lúc, thay đổi sau cùng sẽ được giữ lại. Dropbox có thể giữ phiên bản còn lại dưới dạng conflicted copy.
• Cộng tác viên: các cộng tác viên liên kết Dropbox của họ sẽ nhận được các dự án được chia sẻ với họ. Người xem chỉ có quyền đọc và người review cũng nhận được dự án, nhưng các thay đổi của họ trong Dropbox không được đồng bộ trở lại Overleaf.
• Tệp bị bỏ qua: các tệp mà Overleaf không đồng bộ, như đầu ra biên dịch (.aux, .log, …), .DS_Store hoặc môi trường ảo Python, chỉ được giữ trong Dropbox.

​

Q&A

Tại sao người dùng không thể liên kết tài khoản Dropbox của họ?

• Một thư mục Dropbox mà Overleaf chưa biết sẽ được ghép với một dự án theo tên, vì vậy người dùng có các dự án trùng tên sẽ được yêu cầu đổi tên chúng trước. Tên được so sánh không phân biệt chữ hoa chữ thường, và các dự án đã lưu trữ hoặc đã chuyển vào thùng rác cũng được tính.
• Một tài khoản Dropbox chỉ có thể được liên kết với một tài khoản Overleaf.

Tại sao một tài khoản Dropbox bị hủy liên kết?

Trả lời: Overleaf hủy liên kết một tài khoản Dropbox khi Dropbox từ chối token của nó (ví dụ sau khi người dùng xóa ứng dụng trong Dropbox), khi Dropbox đã đầy, hoặc khi Dropbox tạm ngưng tài khoản. Một thông báo trong danh sách dự án cho người dùng biết trường hợp nào đã xảy ra, cho đến khi họ liên kết lại tài khoản. Người dùng có thể liên kết lại sau khi vấn đề được giải quyết.

Tôi có thể đổi tên thư mục dự án trong Dropbox không?

Trả lời: Vui lòng đổi tên dự án trong Overleaf thay vì làm vậy: thư mục của dự án trong Dropbox cũng sẽ được đổi tên theo. Đối với Overleaf, việc đổi tên thư mục trong Dropbox tương đương với xóa thư mục dự án và tạo một thư mục mới, vì vậy dự án cũ sẽ bị đánh dấu là đã xóa và một dự án mới được tạo từ các tệp.

Tại sao một số thư mục dự án được đánh số, như “Thesis (1)”?

Trả lời: Mỗi dự án có một thư mục riêng, kể cả khi hai dự án có cùng tên. Dropbox không thể chứa hai thư mục cùng tên, vì vậy nó thêm một số vào thư mục được tạo sau. Con số này phụ thuộc vào những tên còn trống trong Dropbox tại thời điểm đó, chứ không phụ thuộc vào dự án nào cũ hơn. Overleaf biết thư mục của từng dự án, vì vậy các thay đổi không bao giờ đi vào thư mục của một dự án khác có cùng tên.

Một dự án được tải lên có tên đã bị sử dụng cũng sẽ được đặt tên kèm số trong Overleaf, ví dụ “Thesis (1)”.

Điều gì xảy ra khi tôi xóa một thư mục dự án trong Dropbox?

• Nếu không có dự án nào khác mang tên của thư mục đó, dự án sẽ bị đánh dấu là đã xóa trong Overleaf. Các tệp và lịch sử của dự án vẫn được giữ lại.
• Nếu có nhiều dự án mang tên đó, Overleaf không thể biết thư mục thuộc về dự án nào. Overleaf sẽ hủy liên kết tài khoản Dropbox và hiển thị thông báo yêu cầu đổi tên các dự án. Hãy đặt cho các dự án những tên khác nhau trước khi xóa thư mục của chúng trong Dropbox.
• Một thư mục được đánh số, như “Thesis (1)”, không khớp với tên dự án nào, vì vậy việc xóa nó không làm thay đổi dự án trong Overleaf. Nhấp sync this project now trong hộp thoại Dropbox của trình soạn thảo để gửi lại dự án sang Dropbox.

Điều gì xảy ra trong Dropbox khi tôi xóa một dự án trong Overleaf?

Trả lời: Không có gì xảy ra, thư mục của dự án vẫn ở lại trong Dropbox. Hãy xóa thư mục trong Dropbox nếu bạn không còn cần đến nó.

Điều gì xảy ra với các thay đổi trong Dropbox khi dự án đang được lưu trữ hoặc nằm trong thùng rác?

Trả lời: Các thay đổi này không được áp dụng vào dự án, và việc khôi phục dự án cũng không đưa chúng vào. Sau khi khôi phục, Overleaf ngừng gửi các thay đổi của mình đối với những tệp đã bị thay đổi trong Dropbox trong thời gian đó, vì vậy hai bên sẽ khác nhau.

Để đồng bộ lại một tệp như vậy, hãy lưu tệp đó thêm một lần nữa trong Dropbox. Khi đó Overleaf sẽ lấy phiên bản trong Dropbox: các thay đổi đối với tệp trong Overleaf kể từ khi khôi phục sẽ bị thay thế, nhưng vẫn còn trong lịch sử dự án. Hãy khôi phục dự án trước khi bạn thay đổi nó trong Dropbox.

Tại sao liên kết Dropbox trong trình soạn thảo lại mở trang chủ Dropbox?

Trả lời: Liên kết trỏ đến Apps/<app folder>/<project> trên dropbox.com, giống như trên Overleaf Cloud. Khi Dropbox hiển thị thư mục Apps dưới một tên đã được dịch, ví dụ 应用 trong tiếng Trung, liên kết sẽ không tìm thấy thư mục và Dropbox mở trang chủ thay thế. Hãy mở thư mục dự án từ thư mục Apps đã được dịch trong Dropbox.

Tại sao một số tệp của dự án bị thiếu trong Dropbox?

Trả lời: Các thay đổi được thực hiện trong lúc dịch vụ đồng bộ không chạy, ví dụ trong lúc nó khởi động lại, sẽ không được gửi sang Dropbox sau đó. Nhấp sync this project now trong hộp thoại Dropbox của trình soạn thảo: thao tác này sẽ gửi lại toàn bộ dự án.