LibreFind FOSS目录从哪里来:F-Droid数据同步到本地边缘缓存的完整链路
LibreFind FOSS目录从哪里来:F-Droid数据同步到本地边缘缓存的完整链路
LibreFind 是一款帮助你发现并用 FOSS(自由开源软件)替代品替换专有的 Android 应用,它的核心能力来自一份持续更新的 FOSS 目录。这篇文章带你完整看懂这份目录是如何从 F-Droid 数据源同步到云端数据库、再下发到你手机本地缓存的全过程,理解 LibreFind "离线优先(offline-first)" 设计的底层逻辑。
🗺️ 完整数据链路一图看懂
F-Droid index-v2.json ─┐
├─▶ Node 同步脚本 ─▶ Supabase 云端数据库 ─▶ 手机 App 本地缓存(Room)
IzzyOnDroid index ─────┘ (每 150 条批量写入) (solutions / targets 表) (6 小时 TTL)
│
本地 PackageManager 扫描 ────────────────────────────▶ 实时分类:FOSS / 专有 / 未知
整条链路分为 5 步:抓取源数据 → 清洗入库 → 云端存储 → 本地缓存 → 离线匹配分类。下面逐步拆解。
📥 第一步:流式同步 F-Droid 索引(而不是整包下载)
目录的"原料"来自 F-Droid 官方索引 index-v2.json。这个文件非常大,LibreFind 的同步脚本 sync-fdroid.mjs 没有把它整个加载进内存,而是用流式 JSON 解析器逐包处理:
- 边读边写:HTTP 响应体通过
parser.onValue逐条产出应用条目,内存占用始终稳定 - 批量刷盘:每累积
BATCH_SIZE = 150条就暂停解析、调用 Supabase RPC 一次性写入,避免无限制堆积(见脚本中的flushBatches()函数) - 只挑稳定版:
selectLatestVersion()会在全部版本中优先选出versionCode最高的稳定版,并提取版本号、APK 大小、权限列表等"技术档案" - 多语言归一:
pickLocalized()优先取en-US,回退到en,保证入库文案一致
每个应用最终被写入两类数据:主记录(包名、名称、描述、图标、许可证、来源仓库)和技术信息(版本、权限、minSdk 等),分别进入 upsert_solutions_guarded 和 upsert_app_technical_info 两个数据库函数。
🧩 第二步:IzzyOnDroid 仓库补位
除了 F-Droid 主仓库,脚本还会同步 IzzyOnDroid 的索引作为补充源。两个来源的数据靠优先级区分:
| 数据源 | source_priority |
说明 |
|---|---|---|
fdroid |
100 | 主源,权威度高 |
izzyondroid |
50 | 补充源,提供主仓库没有的应用 |
通过 SYNC_REPO 环境变量,运维可以只跑其中一个源(fdroid / izzy / all)。同步结束后脚本会打印处理总数、写入行数与错误数,方便监控。
☁️ 第三步:落库 Supabase 云端数据库
所有清洗后的数据统一进入 Supabase 的 solutions 表(开源替代方案),与社区提交的 targets 表(专有应用清单)配合,构成完整的"专有 → 替代"映射关系。
一个值得注意的细节:仓库里的 Supabase 边缘函数 sync-catalogue/index.ts 并不负责同步数据本身——它只从数据库读取 last_synced_at 时间戳并对外报告。真正的同步由定时触发的自动化工作流完成(即上一步的 Node 脚本)。这种"同步与查询分离"的设计让目录查询端轻量、可缓存。
📲 第四步:App 把云端目录搬进本地边缘缓存
轮到你的手机了。App 启动扫描时,CacheRepositoryImpl.kt 会执行"边缘缓存"策略:
- 批量拉取:
refreshCache()一次性从远端取回全部专有目标(targets及其替代方案数量)和全部解决方案包名(solutions) - 整表替换:先
clearTargets()/clearSolutions()清空旧数据,再批量 upsert,保证缓存与远端严格一致 - 6 小时有效期:
CACHE_TTL_MS设为 6 小时,isCacheValid()通过记录里的lastUpdated时间戳判断缓存是否过期 - 持久化到本地数据库:数据存放在 AppCacheDao.kt 管理的
cached_targets与cached_solutions两张表中,结构见 CachedTarget.kt
关键点:缓存里只存包名、替代数量这类轻量指纹,而不是每个应用的完整详情。详情(图标、评分、评论)只在用户点开某个应用时才按需请求远端——这就是"边缘缓存 + 按需加载"的经典权衡。
🔍 第五步:本地扫描,两级发射的分类结果
缓存就绪后,真正的主角登场:ScanInventoryUseCase.kt 编排了 Dashboard 的核心工作流,具体实现在 DeviceInventoryRepoImpl.kt:
- 读取本机应用:InventorySource.kt 通过
PackageManager拿到所有已安装应用,你的应用清单永远不会离开设备 - 先用本地缓存立即出结果:扫描流程会先 emit 一份完全基于本地缓存的分类结果——即使缓存已过期甚至离线,界面也不会卡住
- 后台静默刷新:若
isCacheValid()为 false,就在后台refreshCache()拉新数据,再用新鲜数据重新 emit 一遍结果 - 分类规则:缓存未命中时还会兜底——远端批量查询、安装器启发式(如来自 F-Droid 的按 FOSS 处理)、以及签名指纹校验
其中签名指纹来自 TrustedRomSignerDb.kt:代码内置一批 AOSP 平台与 ROM 应用的签名摘要(bundled),并由 SignerFeedWorker.kt 定期从远端 signers.json 拉取增量更新(带 ETag 缓存),两者合并后用于识别"伪装成 com.android.* 的真系统应用"。
⚡ 为什么这样设计?
这套链路的收益非常直观:
- 秒开:扫描结果第一帧完全来自本地 Room 数据库,网络好坏不影响首屏
- 离线可用:断网时目录匹配照常工作,只是数据可能略旧
- 隐私:本机应用列表只用于本地比对,不上传、不留痕
- 可扩展:新增数据源只需给同步脚本加一个分支并调整
source_priority
📚 关键文件索引
| 环节 | 文件路径 |
|---|---|
| F-Droid / Izzy 同步脚本 | sync-fdroid.mjs |
| 同步状态查询函数 | index.ts |
| 云端缓存仓库实现 | CacheRepositoryImpl.kt |
| 本地缓存 DAO 与实体 | AppCacheDao.kt |
| 设备扫描与分类核心 | DeviceInventoryRepoImpl.kt |
| 本机应用清单读取 | InventorySource.kt |
| 签名指纹数据库 | TrustedRomSignerDb.kt |
从 F-Droid 的一行 JSON,到你 Dashboard 上一个绿色的 "FOSS" 徽章,数据其实跨越了抓取、清洗、入库、下发、缓存、匹配六个环节。理解这条链路,你就理解了 LibreFind 如何在"目录永远在变化"的前提下,依然做到离线秒级响应 🚀