NeriPlayer自建同步完整指南：把歌单和播放统计同步到自己的GitHub与WebDAV

NeriPlayer自建同步完整指南把歌单和播放统计同步到自己的GitHub与WebDAV【免费下载链接】NeriPlayerA native Android audio player that combines multi-source streaming, local control, rich lyrics, and self-hosted sync. / ✨ 一个把多源在线播放、本地管理、歌词体验和自建同步做进原生 Android 的音频播放器 项目地址: https://gitcode.com/gh_mirrors/ne/NeriPlayerNeriPlayer 是一款原生 Android 音频播放器除了多源在线播放与本地管理外最实用的一条链路就是「自建同步」把本地歌单、收藏、最近播放和播放统计同步到你自己的 GitHub 仓库或 WebDAV 远端数据完全由你掌控不经过任何中心化服务。本文是一份面向新手的操作指南讲清楚同步什么、怎么配置 GitHub / WebDAV 两端、以及自动同步和立即同步的触发机制。NeriPlayer 同步会同步哪些数据同步载荷是一个统一的元数据包定义在 SyncDataModels.kt 中包含同步对象说明 本地歌单你创建的歌单、排序与歌曲 收藏歌单收藏的内容 最近播放播放历史及删除记录 播放统计播放次数、累计收听时长、首次/最近播放时间、每日统计桶 歌单使用统计歌单打开次数、本地歌单累计/每日播放⏭️ B站跳过规则Bilibili 视频跳过区间规则 明确的同步边界不会上传音频缓存、下载文件、本地音频文件、Cookie 或播放 Token。同步的是「元数据」不是媒体内容。播放统计支持按日/周/月/年/总计查看同步合并时按设备分片累加多设备的收听数据不会互相覆盖。快速上手3步开启GitHub自建同步入口都在设置 → 备份与恢复页面对应源码 SettingsBackupRestoreSection.kt。第1步配置 GitHub Token 和仓库在 GitHub 上创建一个 Personal Access Token需要repo权限。在「GitHub 同步」卡片点击「配置」应用内完成 Token 验证。选择「创建新仓库」或「使用现有仓库」。应用内新建仓库时默认创建为私有仓库也支持接入owner/repo格式的已有仓库。第2步开启自动同步配置成功后卡片会切换出「自动同步」开关与「立即同步」按钮。打开自动同步后本地数据变更会自动触发同步。第3步验证结果「立即同步」行会显示上次同步时间同步过程中显示进度圈。同步成功/失败会汇总到「同步提示」卡片可查看最近结果和失败原因。Token 和仓库信息保存在Android Keystore EncryptedSharedPreferences中见 SecureTokenStorage.kt不会明文散落。自动同步是怎么调度的本地数据变更后触发一次延迟 5 秒的同步同时存在每小时一次的周期同步调度逻辑见 SyncCoordinator.kt。同步任务依赖WorkManager仅在存在可用网络时执行并带失败重试GitHubSyncWorker.kt。这是后台双向同步、最终一致性模型不是实时秒级推送——理解这一点能减少为什么还没同步的困惑。省流通道减少同步流量「GitHub 同步」卡片里还有一个「省流通道」开关sync_data_saver。开启后同步文件backup-raw.bin直接写入原始GZIP(ProtoBuf)字节比 JSON 更小关闭时保存为backup.json。切换前应用会弹窗提醒切换可能导致不同步终端之间不一致建议确认同一仓库的其他终端都支持新格式后再切换。5分钟接入WebDAV自建同步不想用 GitHubWebDAV 提供的是同一套同步数据的另一条出口配置项在 WebDavStorage.kt 与 WebDavSyncManager.kt服务器 URL如https://example.com/davNAS 的 WebDAV 服务地址即可。用户名 / 密码WebDAV 账号凭证。初始路径如backup/neriplayer。点击「验证并保存」应用会先验证连通性再落库。保存成功后数据会写为固定名称neriplayer-sync.json自动拼接到你指定的目录下。URL、用户名和密码同样保存在本地加密存储中。安全细节值得注意WebDAV 优先使用 ETag/Last-Modified 做条件写入服务器不支持条件令牌时只有在远端 SHA-256 指纹未变化才允许回退无条件写入否则按并发冲突失败——避免两台设备同时写时互相覆盖。冲突与数据安全新手最关心的3个问题① 多台设备会互相覆盖吗不会。同步采用三路合并分别处理歌单、收藏、历史、删除记录和播放统计。新增或从备份恢复的歌曲携带成员 token旧的删除记录只会移除它实际观察到的成员因此撤销删除后的歌曲不会在下一轮同步再消失。删除记录recentPlayDeletions、playlistSongDeletions会与撤销操作一起参与合并策略。② 旧数据、缺字段的快照能读吗能。读取 JSON/ProtoBuf 快照时兼容缺字段旧数据过滤无可解析歌曲身份或无效删除时间的异常记录缺失addedAt的歌曲会排到已有时间歌曲之后不会打乱歌单顺序。③ 远端文件是加密的吗不是。GitHub 仓库与 WebDAV 文件都不是端到端加密备份远端文件由你自行保管建议 GitHub 用私有仓库、WebDAV 用 HTTPS。 另外同步使用本地生成的 UUID 作为设备标识不依赖ANDROID_ID隐私更友好。播放历史更新频率怎么设「备份与恢复」里的「播放历史」卡片可以设置播放历史更新频率对应 PlayHistorySyncPreferences.kt四档可选档位说明立即每次播放后立即同步默认每10分钟攒一批再同步更省资源每15分钟同上每30分钟最低频写入侧本身也采用延迟批量策略在关键生命周期 flush日常使用不必纠结这一项按流量敏感度选择即可。常见问题清单Token 验证失败确认 Token 有repo权限且未过期应用会明确提示「Token 已过期请重新配置」。提示仓库不存在或无权访问检查owner/repo格式是否正确以及该仓库 Token 是否有权限。WebDAV 提示用户名或密码错误先在浏览器或webdav客户端验证服务器连通性再回应用重试「验证并保存」。想换设备迁移除了云端同步还可以用「本地备份」中的完整配置导入/导出一次性迁移设置、语言、平台授权、GitHub/WebDAV 配置与一起听设置。注意完整配置文件包含授权信息仅适合自用迁移。源码结构速览想深入了解实现可以从这些模块入手同步载荷与合并模型data/sync/model/GitHub 同步链路data/sync/github/GitHubSyncManager、三路合并策略、SyncDataSerializer等WebDAV 同步链路data/sync/webdav/设置页「备份与恢复」UISettingsBackupRestoreSection.kt官方说明README.md 中的「GitHub 同步」与「WebDAV 同步」章节按上面的步骤几分钟就能把歌单和播放统计落到自己的 GitHub 或 WebDAV 上——数据归你同步交给 NeriPlayer 的后台调度即可。【免费下载链接】NeriPlayerA native Android audio player that combines multi-source streaming, local control, rich lyrics, and self-hosted sync. / ✨ 一个把多源在线播放、本地管理、歌词体验和自建同步做进原生 Android 的音频播放器 项目地址: https://gitcode.com/gh_mirrors/ne/NeriPlayer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考