Arquitetura do Drive Sync: URLs, escopos e auditoria

Esta é a referência do Drive Sync voltada a desenvolvedores. Se você está integrando o acesso de sincronização à API REST ou ao servidor MCP, criando ferramentas sobre o TrekMail Drive ou auditando como a interface WebDAV aplica permissões, esta página é para você.

Se você só quer conectar o rclone ou o Finder ao Drive, comece pela visão geral do Drive Sync.

O que é o Drive Sync

O Drive Sync é uma interface WebDAV para o TrekMail Drive. Ele permite que um aplicativo de sincronização compatível acesse os mesmos arquivos que você vê no painel e no webmail, usando uma senha de dispositivo própria e permissões selecionadas.

A interface usa métodos WebDAV padrão em um prefixo fixo. O suporte varia entre clientes, portanto teste as operações necessárias em uma pasta descartável antes de usar o aplicativo em uma migração ou um backup de produção.

Estrutura de URLs

A URL do Drive é gerada para a implantação e exibida em Sync devices. Copie essa URL em vez de montar uma com base no domínio do painel. O caminho começa com /dav/files/:

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

Abaixo dessa raiz há uma árvore da conta e árvores de caixas de correio. O que uma senha pode abrir depende tanto da vinculação dela a uma caixa quanto das permissões selecionadas:

Árvore de toda a conta

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

Este é o Account Drive do painel. Uma senha que não esteja limitada a uma única caixa de correio pode ver essa árvore quando tem uma permissão do Account Drive.

Árvore limitada a uma caixa de correio

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

Quando uma senha de dispositivo é restrita a uma caixa de correio, ela só pode ver a árvore pessoal dessa caixa. Se a caixa tem acesso ao Drive pessoal e a conta possui pastas compartilhadas, a coleção Shared/ mostra as pastas da conta compartilhadas com todas as caixas.

Uma senha limitada a uma caixa não pode ver o Account Drive nem outra caixa. Uma senha sem limite de caixa pode listar os espaços do Drive da conta, mas cada caminho ainda exige a permissão correspondente de conta ou caixa de correio.

Criar uma senha de dispositivo

Você pode criar uma senha em Sync devices no painel ou, para a caixa que está usando no momento, pelo webmail. O painel pode criar uma senha para toda a conta ou limitá-la a uma caixa. O webmail cria uma senha apenas para a caixa com a sessão iniciada.

Escolha um rótulo claro, selecione somente as permissões necessárias ao aplicativo e defina uma validade quando a conexão for temporária. O segredo é mostrado uma única vez. Salve-o no aplicativo ou em um gerenciador de senhas antes de fechar a tela de confirmação.

Você pode revogar uma senha de dispositivo a qualquer momento sem alterar sua senha normal de acesso ao TrekMail. Uma senha revogada ou expirada deixa de funcionar imediatamente.

Entrar com uma senha de dispositivo

A sincronização usa HTTP Basic por HTTPS. Digite o nome de usuário exibido em Sync devices e a senha de dispositivo gerada. Não use a senha do painel do TrekMail em um aplicativo de sincronização.

Se a senha for revogada ou expirar, o aplicativo normalmente solicitará as credenciais novamente. O status da conta, o acesso à caixa de correio, o acesso ao Drive e as permissões selecionadas são verificados em cada solicitação.

Modelo de escopos

O Drive Sync usa as mesmas strings de escopo da API REST, no formato drive:{family}:{action}. Estas são as oito aplicáveis às senhas de dispositivo:

A leitura de um caminho exige a permissão :read correspondente. Criar, alterar, mover, copiar ou excluir exige :write. O caminho determina se o aplicativo está solicitando acesso à conta ou à caixa, então uma senha limitada a uma caixa não pode acessar o Account Drive nem outra caixa.

A tela Sync devices oferece somente as permissões adequadas a um aplicativo de sincronização. Permissões de cobrança não fazem parte de uma senha de dispositivo.

Permissões de compartilhamento e expurgo

O formulário de senha de dispositivo pode mostrar as permissões :share e :purge quando a conta tem direito a elas. A proteção atual das rotas WebDAV associa operações de arquivo somente a :read e :write, portanto não presuma que selecionar uma dessas permissões adiciona ao WebDAV um comando de link de compartilhamento ou exclusão permanente.

No WebDAV, um DELETE comum exige :write e move o arquivo para a lixeira. O WebDAV não permite substituir um arquivo no mesmo local nem executar um expurgo permanente. Use a interface do Drive para essas tarefas.

Segurança dos nomes de arquivo

Nomes de arquivos e pastas precisam ser seguros em diferentes sistemas operacionais. Nomes vazios, separadores de caminho, caracteres de controle, caracteres enganosos e nomes que entrariam em conflito após a normalização do Windows ou Unicode são rejeitados. Os nomes podem ter até 255 caracteres visíveis.

Se um aplicativo receber um erro de validação, renomeie o item no aplicativo e tente novamente. Não tente contornar o erro colocando um caminho no nome de um arquivo.

Uploads em partes

Arquivos pequenos podem usar um PUT normal. Clientes compatíveis com o fluxo de upload em partes v2 do Nextcloud podem criar uma sessão de upload em /dav/uploads/{session-uuid}/, enviar partes numeradas e depois usar MOVE para montar o arquivo no destino final.

Os limites de upload podem variar conforme a implantação e o cliente. Trate uma sessão com falha ou expirada como uma nova tentativa de upload. Se outro cliente criar o destino primeiro, use a resposta de conflito para escolher um novo nome ou atualize a pasta antes de tentar novamente.

Trilha de auditoria

As alterações concluídas pelo Sync aparecem no histórico de atividades do Drive. O registro identifica o item afetado, a ação, o horário e a senha de dispositivo usada. Assim, um administrador pode investigar alterações inesperadas e revogar a senha relevante.

Clientes que usam o feed de alterações do Drive podem ver mudanças feitas via WebDAV. Se o serviço solicitar uma ressincronização completa, recrie a visualização local a partir de um snapshot recente antes de continuar com o cursor salvo.

Limites de requisições

As solicitações do Drive Sync têm limites para proteger o serviço e seus arquivos. Se um cliente receber 429, reduza a simultaneidade, respeite Retry-After quando esse cabeçalho for fornecido e tente novamente uma operação pequena antes de retomar a tarefa.

Disponibilidade

O Drive Sync está disponível em produção. As contas precisam ter acesso ao Drive, e as permissões disponíveis para senhas de dispositivo ainda dependem da conta, da caixa de correio, do plano e da pessoa que cria a senha. Clientes White Label usam o mesmo serviço Drive Sync. Sempre copie a URL atual de Sync devices em vez de construí-la.

Próximos passos

• Para a configuração por usuários finais, consulte a visão geral do Drive Sync.
• Para a interface do painel que emite senhas de dispositivo, consulte Sync devices.
• Para os equivalentes dessas operações na API REST e no MCP, consulte a Visão geral da API do Drive e Escopos e permissões da API do Drive.
• Para o modelo de armazenamento e cotas que a sincronização compartilha com os demais recursos, consulte Explicação das cotas de armazenamento compartilhado.