Синхронизация с Dropbox

Позвольте пользователям синхронизировать свои проекты с папкой в их 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 App Console, войдя под учётной записью Dropbox, которой будет принадлежать приложение:

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. Проекты каждого пользователя появляются в папке Apps/<name of your app>/ в его Dropbox, и именно это имя указывается ниже в 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. Нажмите Submit на панели внизу вкладки Permissions. Без нажатия Submit разрешения не сохраняются, и Dropbox отказывается синхронизировать файлы пользователей, которые привязывают свою учётную запись.

Dropbox App Console: разрешения, которые нужно отметить и сохранить кнопкой Submit

4. На вкладке Settings в разделе OAuth 2 введите ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback в поле Redirect URIs, затем нажмите Add. Просто ввести URI недостаточно: он сохраняется только после того, как появится в списке над полем.

Dropbox App Console: введите Redirect URI и нажмите Add

5. На вкладке Settings в разделе Webhooks введите ${OVERLEAF_SITE_URL}/dropbox/webhook в поле Webhook URIs, затем также нажмите Add. Dropbox сразу обращается к этому адресу для проверки, поэтому Overleaf к этому моменту уже должен работать с приведёнными ниже настройками и быть доступен из интернета (см. Webhook). После успешной проверки отображается статус Enabled.

Скопируйте App key и App secret (нажмите Show) на вкладке Settings, затем добавьте следующие настройки в файлы переменных окружения Overleaf. Webhook (шаг 5) можно добавить после того, как Overleaf будет запущен с этими настройками.

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

• Перед настройкой Redirect URI и webhook убедитесь, что OVERLEAF_SITE_URL задан правильно.
• Dropbox фиксирует разрешения токена в момент привязки учётной записи пользователем: отправка разрешений не изменяет уже выданные токены. Пользователям, которые привязали учётную запись до отправки разрешений или до их изменения, необходимо отвязать и заново привязать свою учётную запись Dropbox.
• Новое приложение находится в статусе Development. Если в поле Development users на вкладке Settings указано 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. Затем вставьте:

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 пропускает уже существующие индексы.

Не запускайте вместо этого миграции dropboxEntities из tools/migrations: 20220825160708_recreate_dropboxEntities удаляет коллекцию, а вместе с ней и состояние синхронизации всех пользователей.

​

Webhook

Dropbox сообщает Overleaf об изменениях в Dropbox через webhook, поэтому они появляются в Overleaf в течение нескольких секунд. Webhook направляется на адрес вашего сайта, ${OVERLEAF_SITE_URL}/dropbox/webhook, дополнительный порт не нужен, но Dropbox должен иметь к нему доступ из интернета. Когда вы добавляете его в App Console, Dropbox сразу же его проверяет.

Без webhook, например на сервере, недоступном для Dropbox, изменения в Overleaf по-прежнему отправляются в Dropbox, но изменения в Dropbox возвращаются только тогда, когда пользователь нажимает sync this project now в диалоге Dropbox в редакторе.

​

Как работает синхронизация

• Привязка: когда пользователь привязывает свою учётную запись Dropbox, принадлежащие ему проекты отправляются в Dropbox. Проекты, к которым ему предоставлен доступ, появляются в Dropbox при их следующем изменении.
• Из Overleaf в Dropbox: новые файлы, переименования, перемещения, удаления и переименования проектов отправляются сразу. Правки в редакторе отправляются после того, как Overleaf сохранит их в своё хранилище, через несколько минут после того, как все покинут проект. Чтобы отправить их раньше, нажмите sync this project now в диалоге Dropbox в редакторе (не чаще раза в минуту).
• Из Dropbox в Overleaf: новые и изменённые файлы, новые папки и удаления в папке проекта применяются к проекту. Новая папка на верхнем уровне папки приложения становится новым проектом. Удаление папки проекта в Dropbox помечает проект как удалённый в Overleaf.
• Конфликты: если файл одновременно изменяется в обоих местах, сохраняется последнее изменение. Dropbox может сохранить другую версию как conflicted copy.
• Соавторы: соавторы, которые привязали свой Dropbox, получают проекты, к которым им предоставлен доступ. Пользователи с правами только на просмотр и рецензенты получают проект, но их изменения в Dropbox не синхронизируются обратно в Overleaf.
• Игнорируемые файлы: файлы, которые Overleaf не синхронизирует, например результаты сборки (.aux, .log, …), .DS_Store или виртуальные окружения Python, остаются только в Dropbox.

​

Q&A

Почему пользователь не может привязать свою учётную запись Dropbox?

• Папка Dropbox, которая ещё неизвестна Overleaf, сопоставляется с проектом по имени, поэтому пользователю, у которого есть проекты с одинаковыми именами, предлагается сначала их переименовать. Имена сравниваются без учёта регистра, и архивированные проекты, а также проекты в корзине тоже учитываются.
• Учётную запись Dropbox можно привязать только к одной учётной записи Overleaf.

Почему учётная запись Dropbox была отвязана?

Ответ: Overleaf отвязывает учётную запись Dropbox, когда Dropbox отклоняет её токен (например, после того как пользователь удалил приложение в Dropbox), когда Dropbox заполнен или когда Dropbox заблокировал учётную запись. Уведомление в списке проектов сообщает пользователю, что именно произошло, пока он снова не привяжет учётную запись. После устранения проблемы пользователь может привязать её снова.

Можно ли переименовать папку проекта в Dropbox?

Ответ: Пожалуйста, переименуйте проект в Overleaf: его папка в Dropbox тоже будет переименована. Для Overleaf переименование папки в Dropbox означает удаление папки проекта и создание новой, поэтому старый проект помечается как удалённый, а из файлов создаётся новый проект.

Почему некоторые папки проектов пронумерованы, например «Thesis (1)»?

Ответ: У каждого проекта есть собственная папка, даже если у двух проектов одинаковое имя. Dropbox не может хранить две папки с одинаковым именем, поэтому добавляет номер к папке, созданной позже. Номер зависит от того, какие имена были свободны в Dropbox в тот момент, а не от того, какой проект старше. Overleaf знает папку каждого проекта, поэтому изменения никогда не попадают в папку другого проекта с тем же именем.

Загруженный проект, имя которого уже занято, в Overleaf тоже получает имя с номером, например «Thesis (1)».

Что произойдёт, если удалить папку проекта в Dropbox?

• Если ни у какого другого проекта нет имени этой папки, проект помечается в Overleaf как удалённый. Его файлы и история сохраняются.
• Если это имя есть у нескольких проектов, Overleaf не может определить, какому из них принадлежала папка. Он отвязывает учётную запись Dropbox и показывает уведомление с просьбой переименовать проекты. Дайте проектам разные имена, прежде чем удалять их папки в Dropbox.
• Пронумерованная папка, например «Thesis (1)», не совпадает ни с одним именем проекта, поэтому её удаление не изменяет проект в Overleaf. Нажмите sync this project now в диалоге Dropbox в редакторе, чтобы снова отправить проект в Dropbox.

Что произойдёт в Dropbox, если удалить проект в Overleaf?

Ответ: Ничего, его папка остаётся в Dropbox. Удалите папку в Dropbox, если она вам больше не нужна.

Что происходит с изменениями в Dropbox, пока проект находится в архиве или в корзине?

Ответ: Они не применяются к проекту, и восстановление проекта их тоже не переносит. После восстановления Overleaf перестаёт отправлять свои изменения тех файлов, которые за это время были изменены в Dropbox, поэтому две стороны расходятся.

Чтобы снова синхронизировать такой файл, сохраните его ещё раз в Dropbox. Тогда Overleaf примет версию из Dropbox: изменения, внесённые в файл в Overleaf после восстановления, будут заменены, но останутся в истории проекта. Восстанавливайте проект до того, как изменять его в Dropbox.

Почему ссылка на Dropbox в редакторе открывает главную страницу Dropbox?

Ответ: Ссылка ведёт на Apps/<app folder>/<project> на dropbox.com, как в Overleaf Cloud. Если Dropbox показывает свою папку Apps под переведённым именем, например 应用 на китайском, ссылка не находит папку, и Dropbox вместо этого открывает свою главную страницу. Откройте папку проекта из переведённой папки Apps в Dropbox.

Почему некоторые файлы проекта отсутствуют в Dropbox?

Ответ: Изменения, внесённые, пока служба синхронизации не работала, например во время её перезапуска, позже в Dropbox не отправляются. Нажмите sync this project now в диалоге Dropbox в редакторе: проект будет отправлен целиком заново.