- 移动开发
- 原生移动
- 网络
【免费下载链接】libretorrent
Free and Open Source, full-featured torrent client for Android. Mirrored from https://gitlab.com/proninyaroslav/libretorrent
导读
LibreTorrent 是一个基于 libtorrent4j 为骨架，结合app/src/main下的源码、Gradle 配置与 AndroidManifest 声明，系统梳理它的核心功能、权限模型、可配置参数、服务架构与构建方式，帮助读者理解"一个 Android 上的全功能 BitTorrent 客户端"从功能承诺到代码落地之间的对应关系，并可直接据此上手使用、构建与二次开发。
一、项目定位与发布渠道
README 将 LibreTorrent 定位为Copylefted libre full-featured torrent client for Android，即"自由版权、完整的 Android 种子客户端"。项目自 2016 年起由 Yaroslav Pronin（proninyaroslav@mail.ru）开发，当前仓库版本号为4.1.1（versionCode9000350，对应app/build.gradle中defaultConfig的声明）。
官方提供的发布渠道包括：F-Droid、OpenAPK、APKMirror、Google Play、Aptoide 以及开发者官网提供的直接 APK 下载。README 特别提醒：对于直接下载的 APK，可以通过 SHA-256 指纹证书进行校验，指纹为：
B0:88:D4:72:A9:80:18:64:5C:DE:EF:8E:93:33:8D:58:B3:F2:38:92:18:7F:DF:63:F7:39:58:38:1E:27:E5:83同时，README 给出了一条面向 Android 12+ 用户的渠道差异提示：Google Play 版本没有"访问所有文件"（All Files Access / MANAGE_EXTERNAL_STORAGE）权限，因此若需要使用完整存储能力，请改用 F-Droid 版本或直接 APK 版本。这一点与源码中的产品风味（product flavor）设计相呼应——app/build.gradle定义了base与play两个deploy维度的 flavor，且play/AndroidManifest.xml与app/src/main/AndroidManifest.xml分离，正是为了对 Play 渠道做权限裁剪。
二、核心功能全景
README 以清单形式列出了项目的主要功能，结合仓库源码可以进一步验证每一项功能的实现落点。以下按功能域分组展开：
2.1 传输协议与网络能力
- BitTorrent 2.0 与 WebTorrent 支持：底层由 libtorrent4j 提供，版本固定为
2.1.0-38（见 gradle/libs.versions.toml）。创建种子时支持 V1、V2 与 HYBRID（V1+V2 混合）三种版本，对应 TorrentBuilder.java 中的TorrentVersion枚举。 - DHT、PeX、LSD、UPnP、NAT-PMP、µTP：这些协议开关全部暴露为网络设置项，源码默认值见 SessionSettings.java：
DHT_ENABLED、LSD_ENABLED、UTP_ENABLED、UPNP_ENABLED、NATPMP_ENABLED默认均为true；对应的 UI 开关定义在 pref_network.xml。 - 加密连接：入站/出站连接加密模式（
EncryptMode）默认均为ENABLED，可在网络设置中分别配置。 - IP 过滤（eMule dat 与 PeerGuardian 格式）：由 IPFilter.java 及
IPFilterParser、IPFilterImpl实现，UI 入口为网络设置中的"IP Filtering"分类（对应pref_key_enable_ip_filtering与pref_key_ip_filtering_file）。 - Tracker 与 Peer 代理：代理设置（
ProxyType）默认NONE，支持为 tracker 与 peer 连接走代理，详见下文"代理配置"小节。 - HTTP/HTTPS 与 magnet 链接：
AndroidManifest.xml为MainActivity注册了VIEWintent-filter，覆盖http、https、file、contentscheme 及application/x-bittorrent、text/xml、application/rss+xml、application/atom+xml等 MIME 类型，同时单独注册了magnetscheme 的VIEWintent-filter，使外部链接、种子文件、RSS/Atom 订阅源都能直接唤起应用添加任务。 - 匿名模式：README 未在功能列表明示，但
pref_network.xml与SessionSettings中存在anonymousMode配置，用于限制上传/下载活动以降低隐私暴露。
2.2 文件管理能力
- 选择性下载文件：添加种子时可勾选下载哪些文件，对应
TorrentContentFileTree与FilePriority模型（app/src/main/java/org/proninyaroslav/libretorrent/core/model/filetree/）。 - 下载过程中移动文件：TorrentEngine 内部通过
FileSystemFacade抽象封装对文件系统的访问，支持下载中迁移文件位置。 - 自动移动已下载文件到其他文件夹或外部驱动器：存储设置中的
pref_key_move_after_download/pref_key_move_after_download_in实现（见 pref_storage.xml）。 - 流式播放（sequential downloads）：README 明确支持流式播放，配合顺序下载策略。源码层由 TorrentStreamServer.java 提供基于 NanoHTTPD 的 HTTP 流媒体服务器，支持 Range 请求（
PARTIAL_CONTENT/RANGE_NOT_SATISFIABLE）与部分格式的 DLNA 声明（内置mp4、avi、mkv三种 DLNA 文件类型映射）；流式 HTTP 服务器的监听地址与端口可在"Streaming"设置中配置（pref_key_streaming_hostname/pref_key_streaming_port，见 pref_streaming.xml）。 - 监听目录（watch directory）：监控指定目录，自动添加新出现的种子文件，并可选在添加后删除原文件（
pref_key_watch_dir等配置项）。
2.3 任务管理与自动化工具体
- 任务调度（Scheduling）：支持设置定时启动与定时关闭，可设定时间、是否只运行一次、是否同时切换 Wi-Fi，配置见 pref_scheduling.xml，对应的
SchedulerReceiver、Scheduler与BootReceiver位于 receiver 与 service。 - RSS/Atom 自动下载管理器：README 强调 "Auto-downloading, with Atom/RSS manager"。源码侧，
FeedChannel、FeedItem等实体与FeedDao、FeedRepository组成持久层；FeedFetcherWorker.java 是基于 WorkManager 的 Worker，负责抓取 RSS/Atom 频道的条目（支持抓取单频道、频道列表与全部频道三种动作）；FeedDownloaderWorker.java 则按订阅规则自动下载匹配条目。RSS 解析器位于com.ernieyu.feedparser包（RSS 1.0/2.0、Atom、EzRss、MediaRSS 等解析实现）。相关设置见 pref_feed.xml 与 pref_feed_auto_refresh.xml，包括自动刷新开关、刷新间隔、仅在非计费网络刷新、保留条目的时长、自动开始下载、去重等。 - 创建种子：支持以多个/大文件创建 torrent，
TorrentBuilder暴露设置种子路径、piece 大小、tracker 列表（Tracker(url, tier)记录）与 torrent 版本（V1/V2/HYBRID）等能力，并可通过Progress(piece, numPieces)反馈创建进度。
2.4 设备与界面适配
- Android TV：Manifest 中声明了
android.software.leanbackfeature（required=false），MainActivity同时声明LEANBACK_LAUNCHER类别；应用还提供ic_banner等 TV 资源。 - Material Design、深色/纯黑主题与平板 UI：主题偏好由
PrefTheme管理（pref_key_theme_v2、pref_key_theme_dynamic_colors、theme_black_backgrounds等），布局资源中专门提供了layout-large-port、layout-sw600dp-land等平板/横屏变体。 - 35+ 种翻译：仓库
app/src/main/res/values-*目录下存在 40 余个语言版本（含简体中文values-zh-rCN与繁体中文values-zh-rTW），翻译托管于 Hosted Weblate。
三、安装与权限模型
3.1 系统要求与构建基线
根据 app/build.gradle：
minSdkVersion 24（Android 7.0）targetSdkVersion 35、compileSdkVersion 36- ABI 过滤：
armeabi-v7a、arm64-v8a、x86、x86_64 - 启用 Java 17 编译与 core library desugaring
3.2 权限清单解析
app/src/main/AndroidManifest.xml声明了以下权限，可据此判断应用的运行模型：
| 权限 | 用途推断 |
|---|---|
INTERNET/ACCESS_NETWORK_STATE/ACCESS_WIFI_STATE/CHANGE_WIFI_STATE | BitTorrent 网络通信与网络状态感知 |
WAKE_LOCK | 下载期间保持设备唤醒 |
RECEIVE_BOOT_COMPLETED/QUICKBOOT_POWERON | 开机自启恢复下载会话 |
VIBRATE | 完成通知震动 |
FOREGROUND_SERVICE+FOREGROUND_SERVICE_DATA_SYNC/FOREGROUND_SERVICE_SPECIAL_USE | 前台服务运行下载引擎 |
READ/WRITE_EXTERNAL_STORAGE+MANAGE_EXTERNAL_STORAGE | 管理外部存储（requestLegacyExternalStorage="true"） |
SCHEDULE_EXACT_ALARM | 定时调度 |
POST_NOTIFICATIONS | Android 13+ 通知权限 |
Manifest 中的TorrentService声明为foregroundServiceType="dataSync|specialUse"，并附带PROPERTY_SPECIAL_USE_FGS_SUBTYPE说明，阐述 BitTorrent 协议需要长时间监听网络、无法限制在 6 小时内，因此申请 special use 前台服务类型——这正是 Android 12+ 上保持下载持续运行的合规设计。
3.3 种子/订阅链接唤起
应用通过多种 intent-filter 支持"点链接即添加"：
VIEW+application/x-bittorrent/text/xml/application/rss+xml/application/atom+xml/application/xml：打开种子文件或订阅源；VIEW+magnetscheme：打开 magnet 链接；SEND+text/plain等：从其他应用"分享"链接或种子文件；SEND+pathPattern（*.torrent、*.xml、*.rss、*.atom）：分享带扩展名的文件。
四、核心配置参数详解
LibreTorrent 的偏好键定义在 pref_keys.xml，各设置面板的 XML 位于 app/src/main/res/xml。以下选取 README 提及功能对应的关键配置做说明，默认值以 SessionSettings.java 为准。
4.1 限制（Limitations）设置 —— 见 pref_limitations.xml
| 配置键 | 默认值 | 说明 |
|---|---|---|
pref_key_auto_manage | false | 启用 libtorrent 的自动任务管理（auto-managed 模式） |
pref_key_max_connections | 200（MIN_CONNECTIONS_LIMIT为 2） | 全局最大连接数 |
pref_key_max_connections_per_torrent | 40 | 单种子最大连接数 |
pref_key_max_uploads_per_torrent | 4 | 单种子最大上传连接数 |
pref_key_max_download_speed | 0（不限速，KiB/s） | 全局下载限速 |
pref_key_max_upload_speed | 0（不限速，KiB/s） | 全局上传限速 |
4.2 网络（Network）设置 —— 见 pref_network.xml
- 协议开关：
pref_key_enable_dht/pref_key_enable_lsd/pref_key_enable_utp/pref_key_enable_upnp/pref_key_enable_natpmp默认全部开启。 - 监听端口：
pref_key_use_random_port默认true；关闭随机端口后可在pref_key_port_range_first（默认37000）与pref_key_port_range_second（默认57010）之间指定端口范围。 - 加密：入站/出站连接加密模式均为
ListPreference，可选项来自@array/pref_enc_mode_entries。 - 匿名模式：
pref_key_anonymous_mode，默认关闭。 - Tracker 校验：
pref_key_validate_https_trackers默认true，验证 HTTPS tracker 证书。
4.3 代理（Proxy）设置 —— 见 pref_proxy.xml
pref_key_proxy_type：默认NONE；代理类型选项由@array/pref_proxy_type_entries提供。pref_key_proxy_address、pref_key_proxy_port（默认8080）：代理服务器地址与端口。pref_key_proxy_peers_too（默认true）：是否对 peer 连接也走代理。pref_key_proxy_require_all_connections：是否要求所有连接都必须走代理。pref_key_proxy_requires_auth+pref_key_proxy_login/pref_key_proxy_password：启用代理认证时填写凭据。
4.4 存储（Storage）设置 —— 见 pref_storage.xml
pref_key_save_torrents_in：默认保存目录。pref_key_move_after_download/pref_key_move_after_download_in：下载完成后自动移动到目标文件夹或外部驱动器。pref_key_save_torrent_files/pref_key_save_torrent_files_in：是否保存 .torrent 文件及保存位置。pref_key_watch_dir/pref_key_dir_to_watch/pref_key_watch_dir_delete_file：监听目录、目录位置、添加后是否删除源文件。pref_key_posix_disk_io（默认false）：是否启用 POSIX 磁盘 I/O。
4.5 流媒体（Streaming）设置 —— 见 pref_streaming.xml
pref_key_streaming_enable：开关内嵌 HTTP 流媒体服务器。pref_key_streaming_hostname：监听主机名。pref_key_streaming_port：监听端口。
4.6 Feed（RSS/Atom）设置 —— 见 pref_feed.xml 与 pref_feed_auto_refresh.xml
pref_key_feed_auto_refresh：开启自动刷新。pref_key_feed_refresh_interval：刷新间隔（选项来自@array/pref_feed_refresh_intervals_entries）。pref_key_feed_auto_refresh_unmetered_connections_only：仅在非计费网络（如 Wi-Fi）下自动刷新。pref_key_feed_auto_refresh_enable_roaming：允许漫游网络下刷新。pref_key_feed_keep_items_time：条目的保留时长。pref_key_feed_start_torrents：订阅命中后自动开始下载。pref_key_feed_remove_duplicates：自动去重。
4.7 调度（Scheduling）设置 —— 见 pref_scheduling.xml
pref_key_enable_scheduling_start/pref_key_scheduling_start_time：启用并设定定时启动时间（TimePickerPreference）。pref_key_enable_scheduling_shutdown/pref_key_scheduling_shutdown_time：启用并设定定时关闭时间。pref_key_scheduling_switch_wifi：调度时联动切换 Wi-Fi。pref_key_scheduling_run_only_once：仅执行一次。
4.8 会话级默认参数（SessionSettings）
SessionSettings中还定义了大量引擎级默认值，可直接对应 UI 之外的行为：activeDownloads=4、activeSeeds=4、maxPeerListSize=200、tickInterval=1000ms、inactivityTimeout=60、activeLimit=6、inetAddress="0.0.0.0"、日志默认上限maxLogSize=10000、日志过滤器默认仅开启 session 级别等。这些参数在会话启动时通过session.setSettings(pref.readSessionSettings(), false)注入（见 TorrentEngine.java 构造函数）。
五、运行时架构与关键代码路径
5.1 三层结构：Service → Engine → Session
从源码结构看，LibreTorrent 的运行时采用典型的"前台服务 + 单例引擎 + 会话封装"三层：
- TorrentService：前台 Service，持有引擎、通知栏常驻通知（每 1000ms 刷新一次）、WakeLock、网络状态监听、过滤/排序状态，并提供
ACTION_SHUTDOWN、ACTION_RESTART_FOREGROUND_NOTIFICATION等动作。 - TorrentEngine：单例（double-checked locking 的
getInstance），负责组装TorrentSession、TorrentRepository、TagRepository、SettingsRepository、FileSystemFacade、TorrentNotifier、TorrentFileObserver，并注册PowerReceiver（充电/电量策略）与ConnectionReceiver（网络切换策略）；支持"下载完成后自动停止"（shutdownDownloadsComplete）等行为。 - TorrentSessionImpl：直接继承 libtorrent4j 的
SessionManager，通过 Alert 机制（ADD_TORRENT、METADATA_RECEIVED、SESSION_ERROR、PORTMAP_ERROR、SAVE_RESUME_DATA等）驱动状态更新，并向TorrentInfoProvider广播，最终反映到 UI。
这种设计使 BitTorrent 状态更新与 Android UI 生命周期解耦：即使界面关闭，前台服务仍可维持下载会话，并在重启（BootReceiver）后恢复。
5.2 存储层：Room + Repository
数据持久化基于 AndroidX Room：AppDatabase定义于 AppDatabase.java，其 schema 快照存放在 app/schemas（当前包含 5～9 号版本），迁移逻辑见 DatabaseMigration.java，并有对应的迁移测试 DatabaseMigrationTest.java。实体包括Torrent、FastResume、FeedChannel、FeedItem、TagInfo、TorrentTagInfo等，DAO 与 Repository 位于core/storage/dao与core/storage包。
5.3 文件系统抽象：SAF 与 POSIX 并存
为兼容 Android 分区存储与现代存储框架，项目定义了FileSystemFacade、FsModule、FileDescriptorWrapper等接口，并提供SafFileSystem/SafFsModule（SAF 路径）与DefaultFsModule（传统路径）两种实现，由FsModuleResolver根据 URI 类型选择（见 core/system 包）。AndroidTest 中的 FileSystemFacadeTest.java 与FakeFsModule等桩类用于验证该抽象。
5.4 UI 结构
MainActivity基于 Navigation 组件组织页面：main_graph.xml、home_two_pane_graph.xml、feed_two_pane_graph.xml、settings_two_pane_graph.xml、tag_graph.xml、error_report_graph.xml、nav_bar_graph.xml等导航图位于 app/src/main/res/navigation。主要页面包括主页种子列表、种子详情（信息/文件/Peers/Pieces/Tracker 列表）、RSS 频道与条目、文件管理器、日志、设置、创建种子、添加种子/链接/订阅等。
六、从源码构建与开发
6.1 构建准备
项目使用 Gradle 构建，settings.gradle仅包含:app一个模块，依赖仓库为 Google、Maven Central 与 JitPack。系统要求：JDK 17（sourceCompatibility/targetCompatibility均为 17），Android Gradle Plugin 版本见 gradle/libs.versions.toml（agp = "9.2.1"）。典型构建命令：
./gradlew assembleBaseDebug # 构建 base flavor 的 debug 包 ./gradlew assemblePlayRelease # 构建 play flavor 的 release 包 ./gradlew test # 运行单元测试 ./gradlew connectedAndroidTest # 运行仪器化测试6.2 签名与发布风味
app/build.gradle对签名做了"可选化"处理：若仓库根目录存在key.properties与 keystore（格式参考 key.properties.example），release 构建将自动签名；否则（如 F-Droid 场景）release 包保持未签名，交由渠道方自行签名。proguard-rules.pro与minifyEnabled true、shrinkResources true用于 release 混淆瘦身。
6.3 测试体系
项目同时包含 JVM 单元测试（app/src/test）与仪器化测试（app/src/androidTest）。代表性的测试覆盖：TorrentEngineTest、TorrentInfoProviderTest、InputFilterRangeTest、FileSystemFacadeTest、DatabaseMigrationTest、FileManagerViewModelTest等；app/build.gradle通过room.schemaLocation把 Room schema 输出到app/schemas，并把该目录加入 androidTest assets，用于数据库迁移测试的基准校验。
6.4 代码贡献指引
CONTRIBUTING.md 给出了贡献流程：新代码应在文件头部版权声明中按Name <e-mail>格式署名；改动需保证现有与新增测试全部通过；编码遵循 KISS 与 DRY 原则，提交合并请求时详细说明修复的问题；翻译贡献则直接编辑 app/src/main/res 下的values-*资源目录。
七、隐私、许可与社区
- 隐私政策：详见 PRIVACY.md。
- 许可证：项目采用 GPL-3.0，LICENSE.md 声明 "free software, can be redistributed and/or modified under the terms of the GNU General Public License version 3 or any later version"。README 中的 Copyleft 口号 "Use, see, change and share; with all" 是对其开源精神的概括。
- 翻译：托管于 Hosted Weblate，仓库内已含 35+ 语言资源，欢迎社区继续补充。
- 社区沟通：项目设有 Matrix 房间与 Telegram 频道（见 README 徽章区），问题跟踪使用 GitLab Issues。
八、总结
LibreTorrent 的价值在于"移动端 BitTorrent 功能密度"与"可审计的开源实现"：既有 BitTorrent 2.0/WebTorrent、选择性下载、流式播放、RSS 自动下载、任务调度、代理与 IP 过滤等完整功能集，又将引擎会话（libtorrent4jSessionManager）、前台服务（TorrentService）、数据持久化（Room）与文件系统抽象（SAF/POSIX 双实现）分层解耦，且通过base/play双 flavor 适配不同应用商店的权限约束。无论作为日常下载工具，还是作为研究 Android 平台上 BitTorrent 客户端工程化的参考实现，它都是一个值得深入阅读的样例。如需进一步阅读，可依次浏览 README.md、app/build.gradle、AndroidManifest.xml、SessionSettings.java 与 TorrentEngine.java。
- 移动开发
- 原生移动
- 网络
【免费下载链接】libretorrent
Free and Open Source, full-featured torrent client for Android. Mirrored from https://gitlab.com/proninyaroslav/libretorrent
相关推荐
LibreTorrent：自由开源的Android文件传输客户端
LibreTorrent是一款功能强大、完全免费的Android文件传输和网络传输客户端，不仅注重功能实现，更强调用户隐私和软件自由。该项目遵循开源精神，鼓励用
移动开发原生移动网络Elk：开源 Mastodon Web 客户端的功能全景与源码解析
Elk：开源 Mastodon Web 客户端的功能全景与源码解析 Elk 是一个运行在浏览器中的开源 Mastodon Web 客户端，定位是"nimble"
前端社交Android BT客户端终极指南：LibreTorrent实战技巧全解析
Android BT客户端终极指南：LibreTorrent实战技巧全解析 在移动互联网时代，你是否经常遇到BT下载的困扰？速度不稳定、隐私泄露风险、操作复杂难
移动开发原生移动网络
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
