chenxiaolong/BasicSync 源代码：https://github.com/chenxiaolong/BasicSync # BasicSync BasicSync 是一款用于在 Android 上运行 Syncthing 的简单应用。该应用刻意保持极简，以便项目易于维护和持续更新。BasicSync 仅控制 Syncthing 的运行时机。实际配置通过 Syncthing 自带的 Web UI 完成。 ## 功能特性 * 支持 Android 8 及更高版本 * 支持外部存储，如 SD 卡和 USB 驱动器 * 支持 Android 的存储访问框架 * 支持导入和导出配置 * 支持根据网络和电池状态或按周期计划暂停同步 * 支持 Android 的 HTTP 代理设置 * 快速设置磁贴，用于在自动模式和手动模式之间切换 * 可选允许其他应用启动和停止 Syncthing * 以库的形式在主进程中运行 Syncthing * 这使得 BasicSync 不受 Android >=12 的子进程限制影响 * 对 Syncthing 的 Web UI 做了一些小增强，添加了文件夹选择器和二维码扫描器 * 检测并报告同步冲突 ## 使用方法 1. 从发布页面（https://github.com/chenxiaolong/BasicSync/releases）下载最新版本。要验证数字签名，请参阅验证数字签名部分。 2. 授予所需的权限并设置期望的运行条件。 3. 就这些了！打开 Syncthing Web UI，像在电脑上一样进行配置。 默认情况下，BasicSync 以自动模式运行，根据指定的运行条件启动和停止 Syncthing。但是，可以通过在 BasicSync 的通知中选择“手动模式”来覆盖此设置，从而手动控制 Syncthing 的运行时机。 ## 权限 * FOREGROUND_SERVICE、FOREGROUND_SERVICE_SPECIAL_USE（Android >=14） * 需要用于在后台无限期运行 Syncthing。 * POST_NOTIFICATIONS * 用于显示同步状态，并提供方便的手动启动和停止 Syncthing 的方式。 * Android 要求前台服务显示通知才能可靠运行。如果不想要某些通知，可以在 Android 设置中禁用相应的通知渠道，同时仍授予整体权限。 * INTERNET * 仅用于允许 Syncthing 连接网络。 * BasicSync 不会也永远不会有自己的广告或遥测。 * Syncthing 有可选的遥测功能，并且在发送任何数据之前会征求批准。 * Syncthing 的崩溃报告已禁用，因为 BasicSync 以上游不支持的方式集成了它。 * ACCESS_LOCAL_NETWORK（Android >=17） * 需要用于直接连接本地网络上的设备，而不是通过 Syncthing 的中继服务器。 * READ_SYNC_SETTINGS * 用于检测 Android 的自动同步数据设置是否已启用。 * ACCESS_NETWORK_STATE * 用于检测设备何时连接到网络以及网络是否不计流量。 * MANAGE_EXTERNAL_STORAGE（Android >=11）、READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE（Android <11） * 可选，用于在文件夹配置为直接文件访问而不是使用 Android 的存储访问框架时访问内部和外部存储。 * RECEIVE_BOOT_COMPLETED * 需要用于在重启后自动启动 Syncthing。 * 如果需要，可以在 BasicSync 的设置中禁用自动启动。 * REQUEST_IGNORE_BATTERY_OPTIMIZATIONS * 需要用于允许请求禁用电池优化的权限。 * CAMERA * 可选，用于在添加新设备时扫描设备的二维码。 * ACCESS_WIFI_STATE、ACCESS_COARSE_LOCATION、ACCESS_FINE_LOCATION、ACCESS_BACKGROUND_LOCATION、FOREGROUND_SERVICE_LOCATION * 可选，用于在未连接到特定 Wi-Fi 网络时停止 Syncthing。Android 不允许在没有位置权限的情况下访问 SSID（Wi-Fi 网络名称）。 * SCHEDULE_EXACT_ALARM * 可选，用于时间计划功能。否则，Android 可能会显著延迟时间窗口的开始和结束。 * 应用不会提示请求此权限，因为它只在电池优化仍然启用时才需要，而电池优化无论如何都是强烈不建议保留的。 * INTERACT_ACROSS_USERS（Android >=17） * 可选，用于允许安装在不同 Android 配置文件或用户中的两个独立 BasicSync 实例通过 localhost 相互通信。只能通过 adb 授予。有关更多详细信息，请参阅跨用户通信部分。 ## 远程 Web UI 访问 Syncthing 监听回环接口，默认可通过 127.0.0.1:8384 访问。BasicSync 会在每次启动时尝试使用相同的端口，但如果发生冲突，会自动选择一个新的随机端口。当前端口号可以在 Web UI -> Actions -> Settings -> GUI 中找到。 HTTPS 和基本认证在每次 Syncthing 启动时都会被强制启用。对于基本认证，密码是 API 令牌。支持生成新的 API 令牌，但不支持设置任意密码。BasicSync 会在每次启动时在内部将密码设置为 API 令牌。 ## 存储访问框架 对于 GrapheneOS 用户：请改用操作系统级别的存储作用域功能。它允许直接文件访问，不受下文所述的 Android 存储访问框架的限制。 BasicSync 支持通过 Android 的存储访问框架（SAF）进行文件访问，作为直接文件访问的替代方案。这会限制权限，使 Syncthing 只能访问特定文件夹，而不是所有内部和外部存储。但是，尽管没有细粒度权限，仍然建议使用直接文件访问。不推荐使用 SAF，因为它不太适合 Syncthing 访问文件的方式。 * 按路径访问文件效率极低。例如，无法直接访问像 a/b/c 这样的嵌套文件。相反，Android 会列出 a 和 b 中的每个文件并查询其元数据，然后才能访问 c。为了减少这种影响，BasicSync 会缓存目录列表和文件元数据，但它仍然会比内部存储慢得多。 * SAF 无法报告比“此文件夹中有文件发生了变化”更具体的事件。当文件被更改时，Syncthing 需要重新扫描存储该文件的文件夹，而不仅仅是该文件。话虽如此，如果文件不经常更改，通常仍然建议启用文件监视器。 * SAF 无法保证创建的文件具有预期的文件名。当多个进程同时尝试创建同名文件时，file.txt 可能会被创建为，例如，file (1).txt。BasicSync 会尽量降低 Syncthing 内部发生这种情况的概率，但无法防止其他应用写入相同的文件。 使用 SAF 时，遇到意外同步错误的可能性更高。如果发生此类错误，请等待 5 分钟让 BasicSync 的缓存过期，然后从 Syncthing 的 Web UI 触发对文件夹的重新扫描。由于 SAF 的限制，这已经是能做到的最好程度了。 注意：SAF 支持是 BasicSync 的功能，而不是 Syncthing 的功能。BasicSync 拥有大量代码，用于将 Syncthing 的自定义文件系统支持桥接到 SAF。这意味着如果从 BasicSync 导出 Syncthing 配置并导入到另一个应用中，使用 SAF 的文件夹将无法正常工作。 ### SAF 自定义文件系统方案 对于其他 Syncthing 应用的开发者，BasicSync 使用的自定义文件系统方案是： * 文件系统类型：saf * 文件系统初始化路径：[/] * SAF 树 URI 是 Android 的 ACTION_OPEN_DOCUMENT_TREE 文件夹选择器返回的 content:///tree/ URI。 * SAF 树 URI 经过 URL 编码，以防止包含正斜杠，同时保持字符串相对易读。它不能包含正斜杠，因为 Syncthing 对该字符串使用 filepath API，而且 URI 不应被拆分，因为它是一个不透明值。 * 当使用空字符串初始化时，将返回一个虚拟根目录，其中包含用户已授予权限的每个持久化 SAF URI 对应的子条目。子条目的名称是每个持久化 URI 的 URL 编码，与针对该 URI 初始化自定义文件系统时相同。 * 如果存在子路径，它表示第一个路径组件所指示的 SAF 树内的相对路径。 * 同时支持空路径和子路径，以便 Syncthing 的 /rest/system/browse?filesystem=saf API 端点能够正常工作。 ## 远程控制 当“允许远程控制”设置启用时，BasicSync 允许其他应用通过 Android 的广播机制控制 Syncthing 的运行时机。支持以下广播操作，其行为与 BasicSync 通知中相应的按钮完全相同： * com.chiller3.basicsync.AUTO_MODE * 切换到自动模式，Syncthing 根据配置的运行条件运行。 * com.chiller3.basicsync.MANUAL_MODE * 切换到手动模式，手动启动和停止 Syncthing，但保持现有状态。 * 如果之前正在运行，则继续运行。如果之前已停止，则保持停止。 * com.chiller3.basicsync.START * 切换到手动模式并启动 Syncthing。 * com.chiller3.basicsync.STOP * 切换到手动模式并停止 Syncthing。 这些广播也可以通过 adb 发送。例如： bash adb shell am broadcast -a com.chiller3.basicsync.AUTO_MODE com.chiller3.basicsync ## Android TV BasicSync 对 Android TV 提供基本支持。UI 仍然是相同的手机/平板电脑 UI，因此导航可能有些不便，但大多数功能都可以使用电视遥控器的方向键访问，包括 Syncthing 的 Web UI。但是，由于 Android TV 的限制，有些事情无法支持： * 导入和导出配置，以及通过调试模式保存日志，均不受支持，因为 Android TV 不包含 DocumentsUI（系统文件管理器和文件选择器）。 * 无法查看 BasicSync 的通知，因为 Android TV 根本不支持第三方应用的通知。BasicSync 仍然需要请求无用的通知权限，才能在后台可靠地运行 Syncthing。 * Android TV 没有用于禁用“电池”优化的 UI，但这也是 Syncthing 在后台可靠运行所必需的。必须通过 adb 来完成： bash adb shell dumpsys deviceidle whitelist +com.chiller3.basicsync ## 持久通知 Android 14 及更高版本不再允许（https://developer.android.com/about/versions/14/behavior-changes-all#non-dismissable-notifications）普通应用阻止持久通知被关闭。为了解决这个问题，BasicSync 会在持久通知被关闭时自动再次显示它。若要一开始就防止通知被关闭（消除重新显示通知时的 UI 卡顿），请使用 adb 授予 SYSTEM_EXEMPT_FROM_DISMISSIBLE_NOTIFICATIONS appops 权限： bash adb shell appops set com.chiller3.basicsync SYSTEM_EXEMPT_FROM_DISMISSIBLE_NOTIFICATIONS allow # 要撤销更改，请将 "allow" 改为 "default"。 此外，如果不想要持久通知，可以在 Android 设置中关闭 BasicSync 的两个“持久通知”通知渠道来禁用它。只要整体通知权限仍然被授予，即使通知不可见，Syncthing 也会继续正常运行。 ## 跨用户通信 Android 17 不再允许（https://developer.android.com/about/versions/17/behavior-changes-all#block-cross-profile-loopback）应用在不同用户中运行时通过 localhost 相互通信。这既影响实际用户，也影响配置文件（例如私人空间或工作资料）。对于运行多个 BasicSync 实例以在用户之间本地同步文件的用户，由于此限制，同步流量现在被迫通过 Syncthing 的中继服务器。但是，跨配置文件/用户通信权限仍然可以手动授予。这需要 adb 和 BasicSync 3.2 或更高版本。 1. 从此仓库下载 interact_across_users.sh 脚本。（使用工具栏中的“Raw”按钮以纯文本形式获取文件。） 2. 将脚本推送到设备： bash adb push interact_across_users.sh /tmp/ 3. 授予 INTERACT_ACROSS_USERS 权限： bash adb shell sh /tmp/interact_across_users.sh grant 这将向任何用户中已安装的每个 BasicSync 副本授予权限，并重启该应用。如果稍后在新的用户中安装 BasicSync，则需要重新运行该脚本。要撤销更改并撤消权限，请运行： bash adb shell sh /tmp/interact_across_users.sh revoke 要通过 localhost 实际设置两个 BasicSync 设备之间的通信： 1. 在每个 BasicSync 实例中，转到 Web UI -> Actions -> Settings -> Connections -> Sync Protocol Listen Addresses，并设置具有固定端口号的监听地址，例如 tcp://:22000。每个实例需要使用不同的端口号。 2. 将一个 BasicSync 实例添加为另一个 BasicSync 实例的远程设备后，转到 Web UI -> -> Edit -> Advanced -> Addresses，并将值从 dynamic 改为 tcp://localhost:。这是必要的，因为 Syncthing 默认不会尝试通过 localhost 进行连接。 ## 验证数字签名 首先，使用 apksigner 打印 APK 签名证书的摘要： apksigner verify --print-certs BasicSync---release.apk 然后，检查 APK 签名证书的 SHA-256 摘要是否为： 08f8267bbd8827eaafc6f43294e5fb13e8e36e0bb2af2648d4e7b906cae713fa ## 从源码构建 构建之前，必须安装以下工具： * Android SDK * Android NDK * go（golang 编译器） * 我们使用 golang 的一个分支，其中包含针对 MTE 相关崩溃的修复。但是，仍然必须安装现有的 golang 编译器才能从源码构建该分支。 * https://github.com/golang/go/issues/27610 * https://github.com/golang/go/issues/59090 安装好依赖项后，可以像大多数其他 Android 应用一样，使用 Android Studio 或 gradle 命令行构建 BasicSync。 要构建 APK： bash ./gradlew assembleDebug APK 将使用默认的自动生成的调试密钥进行签名。要使用特定的签名密钥创建发布构建，请设置以下环境变量： bash 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 然后构建发布 APK： bash ./gradlew assembleRelease ### Android Studio 在 Android Studio 中加载项目时，可能需要先构建一次 stbridge： bash ./gradlew stbridge 尽管 AGP（Android Gradle 插件）已设置为使 stbridge 成为所有 Android 相关组件的 preBuild 依赖项，但如果 stbridge 的 .aar 文件尚不存在，Android Studio 似乎在同步 gradle 项目时会有问题。在命令行上构建则没有问题。 ## 贡献 欢迎并非常感谢 Bug 修复拉取请求！ 翻译更新主要通过托管的 Weblate 项目（https://hosted.weblate.org/projects/syncthing/android/basicsync/）接受，该项目由上游 Syncthing 项目慷慨提供。不过，通过拉取请求提交的翻译更新也同样接受。 如果您有兴趣实现新功能并希望将其包含在 BasicSync 中，请先打开一个 issue 进行讨论。这是一个我出于兴趣维护的副项目，因此对于添加我自己不会使用的功能会比较谨慎。我打算让 BasicSync 尽可能简单且易于维护。