Архитектура Drive Sync: URL, scopes и аудит

Это справочник Drive Sync для разработчиков. Он предназначен для интеграции синхронизации рядом с REST API или MCP server, создания инструментов поверх TrekMail Drive и аудита применения разрешений фасадом WebDAV.

Если нужно лишь подключить rclone или Finder к Drive, начните с обзора Drive Sync.

Что такое Drive Sync

Drive Sync представляет собой интерфейс WebDAV к TrekMail Drive. Совместимое приложение синхронизации получает доступ к тем же файлам, что видны в Dashboard и Webmail, используя отдельный пароль устройства и выбранные разрешения.

Интерфейс использует стандартные методы WebDAV по фиксированному префиксу. Поддержка клиентов различается, поэтому перед рабочей миграцией или резервным копированием проверьте нужные операции в тестовой папке.

Структура URL

URL Drive создается для развертывания и показывается на экране Sync devices. Копируйте его, а не составляйте из домена Dashboard. Путь начинается с /dav/files/:

https://YOUR-DRIVE-HOST/dav/files/

Ниже корня расположены дерево аккаунта и деревья почтовых ящиков. Доступ пароля зависит и от его привязки к ящику, и от выбранных разрешений.

Дерево всего аккаунта

/dav/files/account/
    ├── (top-level account-drive folders the dashboard shows)
    └── (top-level files at the account-drive root)

Это Account Drive из Dashboard. Пароль без ограничения одним ящиком видит дерево при наличии разрешения Account Drive.

Дерево почтового ящика

/dav/files/mailbox-{N}/
    ├── (the mailbox's personal Drive files and folders)
    └── Shared/
        ├── (account-drive folders flagged "shared with all mailboxes")
        └── ...

Пароль, ограниченный одним ящиком, видит только его личное дерево. Если ящику доступен личный Drive, а у аккаунта есть общие папки, коллекция Shared/ показывает папки аккаунта, общие для всех ящиков.

Такой пароль не видит Account Drive или другой ящик. Пароль без ограничения может перечислять пространства Drive аккаунта, но каждый путь все равно требует соответствующего разрешения аккаунта или ящика.

Создание пароля устройства

Пароль можно создать на Sync devices в Dashboard или из Webmail для текущего ящика. Dashboard может создать пароль всего аккаунта или ограничить его одним ящиком. Webmail создает пароль только для вошедшего ящика.

Укажите понятную метку, выберите только нужные приложению разрешения и задайте срок действия для временного подключения. Секрет показывается один раз. Сохраните его в приложении или менеджере паролей до закрытия подтверждения.

Пароль устройства можно отозвать без изменения обычного пароля TrekMail. Отозванный или просроченный пароль немедленно перестает работать.

Вход с паролем устройства

Синхронизация использует HTTP Basic поверх HTTPS. Введите имя пользователя с экрана Sync devices и созданный пароль устройства. Не используйте пароль Dashboard TrekMail в приложении синхронизации.

После отзыва или истечения срока приложение обычно снова запрашивает учетные данные. Статус аккаунта, доступ к ящику и Drive, а также выбранные разрешения проверяются при каждом запросе.

Модель scopes

Drive Sync использует те же строки scopes, что REST API, в форме drive:{family}:{action}. Для паролей устройств применяются восемь:

Для чтения пути требуется соответствующее разрешение :read. Для создания, изменения, перемещения, копирования или удаления требуется :write. Путь определяет доступ к аккаунту или ящику, поэтому ограниченный пароль не достигает Account Drive или другого ящика.

Экран Sync devices предлагает только подходящие приложению синхронизации разрешения. Billing permissions не входят в пароль устройства.

Разрешения Share и purge

Форма может показывать разрешения :share и :purge, если аккаунт имеет на них право. Текущий guard маршрута WebDAV сопоставляет файловые операции только с :read и :write, поэтому выбор этих разрешений не добавляет команду WebDAV для ссылки или окончательного удаления.

Обычный DELETE WebDAV требует :write и перемещает файл в Trash. WebDAV не поддерживает замену файла на месте или окончательную очистку. Для этих задач используйте интерфейс Drive.

Безопасность имен файлов

Имена должны быть безопасны в разных ОС. Пустые имена, разделители пути, управляющие и вводящие в заблуждение символы, а также имена, конфликтующие после нормализации Windows или Unicode, отклоняются. Максимум составляет 255 видимых символов.

При ошибке проверки переименуйте объект в приложении и повторите. Не пытайтесь обходить ошибку, помещая путь в имя файла.

Загрузка частями

Малые файлы используют обычный PUT. Клиенты с Nextcloud chunked-upload v2 создают сеанс в /dav/uploads/{session-uuid}/, загружают нумерованные части, затем используют MOVE для сборки файла в конечном месте.

Лимиты зависят от развертывания и клиента. Неудачный или просроченный сеанс считайте новой попыткой. Если другой клиент первым создал назначение, используйте ответ о конфликте, чтобы выбрать новое имя или обновить папку.

Журнал аудита

Успешные изменения Sync появляются в истории активности Drive. Запись содержит объект, действие, время и пароль устройства, поэтому администратор может расследовать неожиданное изменение и отозвать пароль.

Клиенты change feed видят изменения WebDAV. Если сервис требует полной повторной синхронизации, пересоберите локальное представление из свежего снимка до продолжения с сохраненным cursor.

Ограничения частоты

Запросы Drive Sync ограничиваются для защиты сервиса и файлов. При ответе 429 уменьшите concurrency, соблюдайте Retry-After, если он указан, и повторите небольшую операцию до возобновления задания.

Доступность

Drive Sync доступен в production. Аккаунту нужен доступ к Drive, а разрешения пароля зависят от аккаунта, ящика, плана и создающего пароль пользователя. Клиенты White Label используют тот же сервис. Всегда копируйте текущий URL с Sync devices, а не создавайте его самостоятельно.

Что дальше

• Настройка пользователя: обзор Drive Sync.
• Интерфейс Dashboard для паролей: Sync devices.
• Эквиваленты REST API и MCP: обзор Drive API и scopes и permissions Drive API.
• Модель хранилища и квот: объяснение общих квот хранилища.