GitHub - chenxiaolong/BasicSync: Um aplicativo simples para executar o Syncthing no Android · GitHub

O BasicSync é um aplicativo simples para executar o Syncthing no Android.

O aplicativo foi intencionalmente mantido muito básico para que o projeto seja fácil de manter e atualizar. O BasicSync controla apenas quando o Syncthing está em execução. A configuração real é feita através da própria interface web do Syncthing.

• Compatível com Android 8 e versões mais recentes
• Compatível com armazenamento externo, como cartões SD e drives USB
• Compatível com o framework de acesso ao armazenamento do Android
• Suporta importação e exportação da configuração
• Suporta pausar a sincronização com base nas condições de rede e bateria ou em um cronograma periódico
• Suporta as configurações HTTP proxy do Android
• Tile de configurações rápidas para alternar entre modos automáticos e manuais
• Opcionalmente permite que outros aplicativos iniciem e parem o Syncthing
• Executa o Syncthing como uma biblioteca no processo principal
  • Isto torna o BasicSync imune às restrições de processos filhos do Android >=12
• Agregações pequenas à interface web do Syncthing para adicionar um seletor de pastas e um escaneador de códigos QR
• Detecta e relata conflitos de sincronização

1. Baixe a versão mais recente da página de lançamentos. Para verificar a assinatura digital, consulte a seção verificando assinaturas digitais.

2. Conceda as permissões necessárias e defina as condições de execução desejadas.

3. Pronto! Abra a interface web do Syncthing para configurar conforme faria em um computador.

   Por padrão, o BasicSync roda no modo automático onde ele inicia e para o Syncthing com base nas condições de execução especificadas. No entanto, isso pode ser substituído selecionando "Modo manual" na notificação do BasicSync, permitindo controlar manualmente quando o Syncthing está em execução.

• FOREGROUND_SERVICE, FOREGROUND_SERVICE_SPECIAL_USE (Android >=14)
  • Necessário para executar o Syncthing em segundo plano indefinidamente.
• POST_NOTIFICATIONS
  • Usado para exibir o status de sincronização e fornecer uma maneira conveniente de iniciar e parar manualmente o Syncthing.
  • O Android requer serviços em primeiro plano para mostrar uma notificação para funcionar confiavelmente. Notificações indesejadas podem ser ocultas desabilitando a respectiva canal de notificação nas configurações do Android, enquanto ainda concede a permissão geral.
• INTERNET
  • Apenas usado para permitir que o Syncthing se conecte à rede.
  • O BasicSync não tem e nunca terá anúncios ou telemetria própria.
  • O Syncthing possui telemetria opcional e pede aprovação antes de enviar qualquer dado.
  • A coleta de dados sobre falhas do Syncthing está desabilitada porque o BasicSync integra-o em uma maneira que não é suportada upstream.
• ACCESS_LOCAL_NETWORK (Android >=17)
  • Necessário para se conectar diretamente a dispositivos na rede local, em vez de passar por servidores de retransmissão do Syncthing.
• READ_SYNC_SETTINGS
  • Usado para detectar se a configuração automática de sincronização dos dados está habilitada no Android.
• ACCESS_NETWORK_STATE
  • Usado para detectar quando o dispositivo está conectado à rede e se a rede é não-metrificada.
• MANAGE_EXTERNAL_STORAGE (Android >=11), READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE (Android <11)
  • Opcionalmente usado para acessar o armazenamento interno e externo quando uma pasta é configurada para acesso direto a arquivos em vez de usar o armazenamento access framework do Android.
• RECEIVE_BOOT_COMPLETED
  • Necessário para iniciar automaticamente o Syncthing após um reinício.
  • A inicialização automática pode ser desabilitada nas configurações do BasicSync se desejar.
• REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
  • Necessário para permitir solicitar permissão para ignorar otimizações de bateria.
• CAMERA
  • Opcionalmente usado para escanear o código QR de um dispositivo ao adicionar um novo dispositivo.
• ACCESS_WIFI_STATE, ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, ACCESS_BACKGROUND_LOCATION, FOREGROUND_SERVICE_LOCATION
  • Opcionalmente usado para parar o Syncthing a menos que esteja conectado a redes Wi-Fi específicas. O Android não permite acesso ao SSID (nome da rede Wi-Fi) sem permissões de localização.
• SCHEDULE_EXACT_ALARM
  • Opcionalmente usado para a funcionalidade de agendamento por tempo. Caso contrário, o Android pode adiar significativamente tanto o início quanto o fim dos intervalos de tempo.
  • O aplicativo não solicitará esta permissão porque é necessário apenas quando as otimizações de bateria ainda estão habilitadas, o que é fortemente desencorajado de qualquer maneira.
• INTERACT_ACROSS_USERS (Android >=17)
  • Opcionalmente usado para permitir que duas instâncias separadas do BasicSync instaladas em diferentes perfis ou usuários do Android se comuniquem entre si por localhost. Pode ser concedido apenas via adb. Consulte a seção de comunicação interusuário para mais detalhes.

O Syncthing escuta na interface loopback e está disponível via 127.0.0.1:8384 por padrão. O BasicSync tentará usar a mesma porta em cada início, mas automaticamente escolherá uma nova porta aleatória se houver conflito. O número da porta atual pode ser encontrado na Web UI -> Ações -> Configurações -> GUI. HTTPS e autenticação básica são ambos forçosamente habilitados toda vez que o Syncthing é iniciado.

Para a autenticação básica, a senha é o token da API. Geração de novos tokens da API é suportada, mas definir uma senha arbitrária não é. O BasicSync internamente define a senha como o token da API em cada início.

Para usuários do GrapheneOS: Use a funcionalidade de escopos de armazenamento no nível do sistema operacional em vez disso. Isso permite acesso direto aos arquivos sem as limitações descritas abaixo do armazenamento access framework do Android.

O BasicSync suporta o acesso a arquivos via estrutura de armazenamento do Android (SAF) como uma alternativa ao acesso direto a arquivos. Isso limita as permissões para que o Syncthing tenha acesso apenas a pastas específicas em vez de todo o armazenamento interno e externo.

No entanto, apesar de não ter permissões granulares, ainda é recomendado usar o acesso direto a arquivos. O SAF é desencorajado porque não está bem adaptado ao modo como o Syncthing acessa os arquivos.

• O acesso a arquivos por caminho é extremamente ineficiente. Por exemplo, não é possível acessar diretamente um arquivo aninhado como a/b/c. Em vez disso, o Android lista todos os arquivos em a e b e consulta seus metadados antes que c seja acessível. Para reduzir o impacto dessa situação, o BasicSync cacheia listagens de diretórios e metadados de arquivo, mas ainda será significativamente mais lento do que o armazenamento interno.

• O SAF não pode relatar eventos de monitoramento mais específicos do que "algum arquivo mudou nesta pasta". Quando um arquivo é alterado, o Syncthing precisa rescanear a pasta em que ele está armazenado em vez de apenas o arquivo. Dito isso, manter os monitores de arquivos ativados ainda é uma boa ideia se os arquivos não estiverem sendo frequentemente alterados.

• O SAF não pode garantir que a criação de um arquivo terá o nome esperado. Quando vários processos tentam criar o mesmo arquivo ao mesmo tempo, file.txt pode ser criado como, por exemplo, file (1).txt. O BasicSync tenta reduzir as chances disso acontecer dentro do Syncthing, mas não pode proteger de outros aplicativos escrevendo nos mesmos arquivos.

Ao usar o SAF, há uma maior chance de encontrar erros de sincronização inesperados. Se ocorrerem, aguarde 5 minutos para que os caches do BasicSync expirem e então acione um rescan da pasta a partir da interface web do Syncthing. Devido às limitações do SAF, isso é o melhor que pode ser feito.

NOTA: O suporte ao SAF é uma funcionalidade do BasicSync e não do Syncthing. O BasicSync tem um grande volume de código para conectar o suporte personalizado do sistema de arquivos do Syncthing ao SAF. Isso significa que se a configuração do Syncthing for exportada do BasicSync e importada em outro aplicativo, as pastas usando o SAF não funcionarão corretamente.

Esquema de sistema de arquivos personalizado do SAF

Para desenvolvedores de outros aplicativos do Syncthing, o esquema de sistema de arquivos personalizado que o BasicSync usa é:

• Tipo de sistema de arquivos: saf
• Caminho de inicialização do sistema de arquivos: <URL-encoded SAF tree URI>[/<subpath>]
  • O URI da árvore SAF é o content://<authority>/tree/<document ID> URI retornado pelo seletor de pastas do Android ACTION_OPEN_DOCUMENT_TREE.
  • O URI da árvore SAF é URL-encoded para evitar a inclusão de barras invertidas, mantendo a string relativamente legível. Não deve ter barras invertidas porque o Syncthing usa APIs filepath na string e o URI nunca deve ser dividido em partes separadas, pois é um valor opaco.
  • Caso seja inicializado com uma string vazia, um diretório virtual raiz é retornado contendo uma entrada de filho para cada URI persistida que o usuário concedeu permissões. Os nomes dos filhos são a URL-encoding de cada URI persistida, da mesma forma se o sistema de arquivos personalizado fosse inicializado para aquele URI.
  • Caso um subcaminho esteja presente, ele representa um caminho relativo dentro da árvore SAF indicada pelo primeiro componente do caminho.
  • O suporte ao caminho vazio e também a subcaminhos permite que o endpoint /rest/system/browse?filesystem=saf da API Syncthing funcione.

Quando a configuração "Permitir controle remoto" está habilitada, o BasicSync permite que outros aplicativos controlem quando o Syncthing roda via mecanismo de broadcast do Android. As seguintes ações de broadcast são suportadas e funcionam exatamente da mesma forma que os botões correspondentes na notificação do BasicSync:

• com.chiller3.basicsync.AUTO_MODE
  • Muda para o modo automático onde o Syncthing roda com base nas condições de execução configuradas.
• com.chiller3.basicsync.MANUAL_MODE
  • Muda para o modo manual onde o Syncthing é iniciado e parado manualmente, mas mantém o estado existente.
  • Caso estivesse previamente em execução, ainda estará em execução. Caso tenha sido previamente interrompido, ainda estará interrompido.
• com.chiller3.basicsync.START
  • Muda para o modo manual e inicia o Syncthing.
• com.chiller3.basicsync.STOP
  • Muda para o modo manual e interrompe o Syncthing.

Esses broadcasts também podem ser enviados via adb. Por exemplo:

adb shell am broadcast -a com.chiller3.basicsync.AUTO_MODE com.chiller3.basicsync

O BasicSync tem suporte básico para Android TV. A interface do usuário ainda é a mesma UI de telefone/tablet, então a navegação pode ser um pouco desconfortável, mas a maioria das funcionalidades está acessível usando as setas do controle remoto da TV, incluindo o web UI do Syncthing.

No entanto, existem várias coisas que não podem ser suportadas devido às limitações do Android TV:

• A importação e exportação da configuração, bem como a salvação de logs via modo debug, não são suportados porque o Android TV não inclui DocumentsUI (o gerenciador de arquivos do sistema e seletor de arquivos).

• Não há maneira de ver a notificação do BasicSync porque o Android TV não suporta notificações de aplicativos de terceiros. O BasicSync ainda precisa solicitar as permissões de notificações inúteis para executar o Syncthing confiavelmente em segundo plano.

• O Android TV não tem uma interface do usuário para desabilitar "otimizações" de bateria, mas também é necessário para que o Syncthing execute confiavelmente em segundo plano. Isso deve ser feito via adb:

  adb shell dumpsys deviceidle whitelist +com.chiller3.basicsync

O Android 14 e versões mais recentes não permitem mais que aplicativos regulares previnam notificações persistentes de serem descartadas. Para contornar isso, o BasicSync mostrará automaticamente a notificação persistente novamente sempre que ela for descartada.

Para evitar que a notificação seja descartável no primeiro lugar (eliminando o jank da IU ao reexibir a notificação), use adb para conceder a permissão de appops SYSTEM_EXEMPT_FROM_DISMISSIBLE_NOTIFICATIONS:

adb shell appops set com.chiller3.basicsync SYSTEM_EXEMPT_FROM_DISMISSIBLE_NOTIFICATIONS allow
# Para desfazer a alteração, mude "allow" para "default".

Além disso, se a notificação persistente não for desejada, ela pode ser desativada nas configurações do Android desligando os dois canais de notificação "Persistent notification" para o BasicSync. O Syncthing continuará a funcionar normalmente mesmo que a notificação não seja visível, desde que a permissão geral de notificações ainda esteja concedida.

O Android 17 não permite mais que aplicativos se comuniquem entre si por localhost quando estão em usuários diferentes. Isso afeta tanto os usuários reais quanto perfis (por exemplo, espaço privado ou perfil de trabalho). Para pessoas que executam várias instâncias do BasicSync para sincronizar arquivos localmente entre usuários, o tráfego de sincronização agora é forçado a passar pelos relés do Syncthing devido a essa restrição.

No entanto, a permissão de comunicação transversal de perfil/usuario ainda pode ser concedida manualmente. Isso requer adb e o BasicSync versão 3.2 ou posterior.

1. Baixe o script interact_across_users.sh deste repositório. (Use o botão "Raw" na barra de ferramentas para obter o arquivo como texto puro.)

2. Empurre o script para o dispositivo:

   adb push interact_across_users.sh /tmp/
   

3. Conceda a permissão INTERACT_ACROSS_USERS:

   adb shell sh /tmp/interact_across_users.sh grant
   

   Isso concederá a permissão para cada cópia instalada do BasicSync em qualquer usuário e reiniciará o aplicativo. Se o BasicSync for posteriormente instalado em um novo usuário, o script precisa ser reexecutado.

   Para desfazer as alterações e revogar a permissão, execute:

   adb shell sh /tmp/interact_across_users.sh revoke
   

Para realmente configurar a comunicação entre dois dispositivos BasicSync via localhost:

1. Em cada instância do BasicSync, vá para Web UI -> Actions -> Settings -> Connections -> Sync Protocol Listen Addresses e defina um endereço de escuta com um número de porta fixo, como tcp://:22000. Cada instância precisa ter números de portas diferentes.

2. Depois de adicionar uma instância do BasicSync como dispositivo remoto em outra instância do BasicSync, vá para Web UI -> <Device name> -> Edit -> Advanced -> Addresses e altere o valor de dynamic para tcp://localhost:<port>. Isso é necessário porque o Syncthing não tenta se conectar por localhost por padrão.

   Verificando assinaturas digitais

   Primeiro, use o comando apksigner para imprimir os resumos do certificado de assinatura da APK:

   apksigner verify --print-certs BasicSync-<version>-<arch>-release.apk
   

   Em seguida, verifique se o resumo SHA-256 do certificado de assinatura da APK é:

   08f8267bbd8827eaafc6f43294e5fb13e8e36e0bb2af2648d4e7b906cae713fa
   

   Antes de construir, os seguintes recursos devem ser instalados:

   • Android SDK
   • Android NDK
   • go (compilador golang)
     • Nos usamos uma versão forkada do golang que inclui um fix para falhas relacionadas ao MTE. No entanto, ainda é necessário ter instalado o compilador golang existente para construir a versão forkada a partir da fonte.

   Uma vez que as dependências são instaladas, BasicSync pode ser construído como a maioria dos outros aplicativos Android usando o Android Studio ou a linha de comando do gradle.

   Para construir a APK:

   A APK será assinada com a chave de depuração gerada automaticamente padrão.

   Para criar uma versão de lançamento com uma chave específica de assinatura, defina as seguintes variáveis de ambiente:

   export RELEASE_KEYSTORE=/path/to/keystore.jks
   export RELEASE_KEY_ALIAS=alias_name
   read -r -s RELEASE_KEYSTORE_PASSPHRASE
   read -r -s RELEASE_KEY_PASSPHRASE
   export RELEASE_KEYSTORE_PASSPHRASE
   export RELEASE_KEY_PASSPHRASE

   e então construa a APK de lançamento:

   ./gradlew assembleRelease

   Ao carregar o projeto no Android Studio, pode ser necessário construir stbridge uma vez primeiro:

   Embora AGP (Android Gradle Plugin) seja configurado para que stbridge seja uma dependência de pré-construção de todos os componentes relacionados ao Android, o Android Studio parece ter dificuldade em sincronizar o projeto gradle se o arquivo .aar do stbridge ainda não existir. Não há problemas quando a construção é feita na linha de comando.

   Solicitações de pull para correção de bugs são bem-vindas e muito apreciadas!

   Atualizações de tradução são aceitas principalmente via o projeto Weblate hospedado, generosamente fornecido pelo projeto upstream Syncthing. No entanto, atualizações de tradução por meio de solicitações de pull também são aceitas.

   Se você está interessado em implementar uma nova funcionalidade e gostaria de vê-la incluída no BasicSync, por favor abra um problema para discuti-lo primeiro. Este é um projeto secundário que trabalho por diversão, então sou hesitante em adicionar recursos que eu mesmo não usarei. Tenho a intenção de manter o BasicSync tão simples e com baixa manutenção quanto possível.

   O próprio BasicSync está licenciado sob GPL-3.0-only. Consulte LICENSE para o texto completo da licença.

   A versão embutida do Syncthing, junto com os patches adicionais aplicados em o fork do BasicSync, está licenciada sob MPL-2.0.