☁️ 私有云盘:挂载与增量同步全指南

JuJu音乐支持将云端与局域网存储无缝接入为 App 的在线曲库,并首创了带差异预检 (Dry-Run) 的双向增量同步引擎。

支持的存储(顺序与 App 里「添加云盘」弹窗的协议选择器一致): FTP / FTPS、局域网 SMB/CIFS、SFTP、WebDAV、Subsonic / Navidrome、 S3 兼容对象存储、阿里云盘。 其中只有 Subsonic / Navidrome 是只读协议(云端 → 本地单向),其余都支持上传、新建目录与删除; 不过 FTP / SMB / SFTP / WebDAV 的实际写权限由你自己的服务器决定,S3 则由这组 Access Key 的桶策略决定 —— 只读账号会在写入时被服务端拒绝并给出提示。

端口填在哪:FTP / SFTP / SMB 的表单里有一个独立端口框(默认 21 / 22 / 445,一般留空); WebDAV / Subsonic / S3 没有端口框 —— 它们的地址就是服务器 URL,端口天然写在地址里(http://192.168.1.10:5005)。


🔌 一、支持的存储协议与挂载方法

进入 App 设置 ->「云盘存储」,点击「添加云盘」:

1. FTPS(FTP + TLS)

  • 适用服务:vsftpd / proftpd / IIS 这类 FTP 服务器,以及不少 NAS 上那个「FTP over TLS」(显式)开关。
    • FTPS ≠ SFTP:SFTP 是 SSH 上的文件传输子系统(默认端口 22);FTPS 是 FTP + TLS —— 控制连接走常用的 TCP 21,每次列目录 / 传输还会另开一条独立的数据连接,是另一种协议,两者不共用代码。
    • ⚠️ 本 App 只支持显式 FTPS:先明文打招呼,再用 AUTH TLS 升级,默认端口 21; 隐式 FTPS(一上来就是 TLS,常用 990 端口)不支持,填了也连不上。
  • 填写参数:
    • 服务器地址:主机名或 IP,如 192.168.1.10 或 nas.local —— 不要写 ftps:// 前缀, 直接填主机名 / IP 就行;
    • 端口:选填,默认 21;
    • 用户名 / 密码:你的 FTP 账号(密码与密码字段一样加密落库);
    • 根目录:选填,如 /data;留空 = 登录后的默认目录。chroot 的服务端(vsftpd 常见) 留空即可(登录后本来就被关在自家目录里)。
  • 🔐 证书信任(TOFU)—— 第一次连接会被拒绝,这是正常的:FTPS 也走 TLS,自签证书同样没有可信 CA 可校验,所以 App 按服务器固定证书指纹:
    1. 第一次保存会被拒绝,弹窗直接给出服务器出示的完整证书 SHA-256 指纹;
    2. 点弹窗里的「检查证书」,App 会再连一次,并显示服务器真实出示的指纹与主题 / 颁发者;
    3. 核对无误后点「信任此证书」,之后才能保存与使用;信任状态随时可以「取消信任」撤回。
    • 指纹一定要和服务端上的一致:可以在服务器上执行 openssl x509 -in /etc/ssl/certs/vsftpd.pem -noout -fingerprint -sha256 取到同一串指纹来交叉核对;
    • ⚠️ 如果提示证书已变化而你自己并没有换过证书,请不要信任 —— 连接可能正在被中间人劫持;
    • FTPS 客户端的默认行为往往"连上了就算数"(自签证书也照收),本 App 不会那样: 不核对指纹、也不受系统信任的证书一律拒绝。
  • ⚠️ 被动模式端口(用户最常踩的坑):App 只支持被动模式。服务端必须开放一段被动端口 (vsftpd 的 pasv_min_port / pasv_max_port),并且这段端口要能从手机访问到; 服务端在 docker / NAT 后面时,还要把这段端口一并映射出去。
    • 症状:账号能登录,但一列目录 / 一开始传输就失败 —— 提示里会直接点出 「数据连接建不起来……被动模式端口」,此时先去服务端查这一段端口,而不是怀疑账号密码。
  • 它是可读写的:浏览、上传、下载(支持 REST 断点续传)、新建目录、删除(目录可递归删), 以及双向 / 单向 / 镜像同步都能用;云端歌曲也支持在线播放(含拖动进度)。
  • ⚠️ 没有服务端转码:FTPS 做不到像 Subsonic 那样按「在线播放码率」转码降码率,弱网时选它对 FTPS 不生效(流式播放与本地缓存照常)。
  • 💡 上传是可靠的:上传走「中转文件 + 续传 + 改名」,传输中断会保留断点, 重试时只补缺失的那部分,不会从头再来一遍。
  • ⚠️ 550 有两种含义:FTP 把「路径不存在」和「没有权限」合在同一个 550 回复码里 (App 里的报错也如实这么写),遇到时先去服务端确认真实原因。

2. 局域网 SMB / CIFS 共享

  • 适用场景:Windows 电脑共享文件夹、路由器外挂移动硬盘、家庭 NAS。
  • 填写参数:
    • IP 地址:如 192.168.1.50(端口有单独的框,默认 445,一般留空)
    • 共享文件夹名:如 Music 或 SharedAudio
    • 用户名/密码:Windows 登录账号或 NAS 共享用户

3. SFTP(SSH 上的文件传输)

  • 适用服务:任何开了 SSH 的机器 —— OpenSSH 自建服务器、群晖 / 威联通 NAS、Linux 主机、 macOS 的「远程登录」,以及路由器上跑的 SSH。
    • SFTP ≠ FTPS:SFTP 是 SSH 上的文件传输子系统(走的是 SSH 端口,默认 22); FTPS 是 FTP + TLS(TCP 21 + 数据连接),是另一种协议,本 App 里由单独的一节接入(见上面第 1 节),两者不共用代码。
  • 填写参数:
    • 服务器地址:主机名或 IP,如 192.168.1.10 或 nas.local —— 不要写 sftp:// 前缀,直接填主机名 / IP 就行;
    • 端口:选填,默认 22;
    • 用户名 / 密码:你的 SSH 账号(密码与密码字段一样加密落库);
    • 根目录:选填,如 /data;留空 = 文件系统根。chroot 的 SFTP 服务端留空即可 (登录后本来就被关在自家目录里);非 chroot 的自建服务端建议显式填 /data 这类目录, 免得在 /etc、/bin 里乱逛。
  • 🔐 主机密钥信任(TOFU)—— 第一次连接会被拒绝,这是正常的:SFTP 没有像 HTTPS 那样的 「可信 CA」体系,所以 App 用**按服务器固定指纹(TOFU,首次使用即信任)**的方式防中间人:
    1. 第一次保存时连接会被拒绝,弹窗直接给出服务器出示的完整主机密钥 SHA-256 指纹与 密钥算法(如 ssh-ed25519)—— 不是一句干巴巴的"连接失败";
    2. 点弹窗里的「检查主机密钥」,App 会再连一次,并显示服务器真实出示的指纹;
    3. 核对无误后点「信任此主机密钥」,之后才能保存与使用;信任状态随时可以「取消信任」撤回。
    • 指纹一定要和服务端上的一致:可以在服务器上执行 ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub 取到同一串指纹来交叉核对;
    • ⚠️ 如果提示"主机密钥已变化"而你自己并没有换过密钥,请不要信任 —— 可能是服务器重装过,更可能连接正在被中间人劫持;
    • 指纹只对这一台服务器生效,不会顺手放开其他云盘的校验。
  • 它是可读写的:浏览、上传、下载(支持断点续传)、新建目录、删除,以及双向 / 单向 / 镜像同步 都能用;云端歌曲也支持在线播放(含拖动进度)。
  • ⚠️ 没有服务端转码:SFTP 做不到像 Subsonic 那样按「在线播放码率」转码降码率,弱网时选它对 SFTP 不生效(流式播放与本地缓存照常)。
  • ⚠️ 只支持密码登录:私钥登录的界面入口还没做(库本身支持,只是入口与私钥的安全存储形态还没定), 属于"没做",不是"做不到"。
  • 💡 一个使用提示:同步会有多次 SSH 握手。App 没有做连接池,每个操作都会做一次 SSH 握手 —— 这是故意的:SFTP 通道不是线程安全的,而同步引擎会用并发工作池, 多个传输共用一个 SFTP 通道会把报文流搅碎。自建 NAS 走内网时握手只要毫秒级,体感不明显。

4. WebDAV 协议挂载

  • 适用服务:AList 聚合云盘、群晖 NAS (Synology WebDAV Server)、坚果云、Nextcloud / ownCloud。
  • 填写参数:
    • 服务器地址:如 http://192.168.1.100:5244/dav(或公网域名)
    • 账号与密码:对应服务的 WebDAV 凭据
    • 挂载根路径:如 /Music(留空默认根目录)
  • 连通性测试:填好后点「保存」,App 会先发送标准 PROPFIND 指令做一次真的网络往返校验,通过才落库。
  • 🔐 自签证书的 NAS 也能连(v4.5.0 新增):很多 NAS 默认就是 https + 自签证书。这类地址第一次会提示 「该服务器的 HTTPS 证书不受信任」,此时点弹窗里的「检查证书」——App 会连一次并显示服务器 真实出示的证书指纹(SHA-256)与有效期,你核对无误后点「信任此证书」即可。
    • 指纹只对这一台服务器生效,不会顺手放开其他云盘的证书校验;
    • 服务器换过证书后需要重新确认一次;随时可以点「取消信任」撤回;
    • 地址请把 https:// 写全(不写协议头会被当作 http),并且 端口要写在地址里 (如 https://192.168.1.100:5006/dav)—— WebDAV 的表单里没有单独的端口框。

5. Subsonic / Navidrome 音乐服务

  • 适用服务:Navidrome、Airsonic(-Advanced)、Gonic、Astiga 等一切实现了 Subsonic / OpenSubsonic API 的音乐服务器。
  • 填写参数:
    • 服务器地址:如 http://navidrome.example.com:4533(反向代理挂在子路径也行,如 https://music.example.com/navidrome)
    • 用户名 / 密码:Subsonic 账号(App 用 t=md5(密码+salt) 令牌方式鉴权,密码不会明文上网)
  • 浏览形态与文件树不同:按音乐库的组织方式展示三类虚拟目录 —— 艺术家 / 专辑 / 歌单(歌曲列在各自目录内), 歌曲按 艺术家/专辑/歌名.ext 落地到本地。
  • ⚠️ 它是只读的:Subsonic 没有上传接口,所以同步方向只能是「云端 → 本地」 (App 会自动只留这一个方向,并隐藏新建文件夹等写入口,不会给你一个点了必然失败的按钮)。
  • 顺手能拿到的:封面与内嵌歌词直接来自你的服务器(不需要再联网匹配), 弱网时还能选「在线播放码率」让服务端转码降码率播放。

6. S3 兼容对象存储

  • 适用服务:MinIO、Ceph RGW、Cloudflare R2、Backblaze B2、腾讯 COS、阿里 OSS、AWS S3 等一切 S3 兼容对象存储;协议类型直接填厂商名也行(别名 s3 / minio / r2 / b2 / cos / oss / ceph,大小写不敏感)。
  • 填写参数:
    • 服务器 URL:如 http://192.168.1.10:9000 或 https://s3.us-west-2.amazonaws.com —— 不写协议头会被当作 http,公有云请把 https:// 写全;
    • 端口写在地址里:如 http://192.168.1.10:9000(表单里没有单独的端口框);
    • Access Key ID:填在「用户名」栏;
    • Secret Access Key:填在「密码」栏(与密码一样加密落库);
    • Bucket(桶名):单独填在 Bucket 栏,不要填成 https://host/bucket 这种带路径的地址;
    • Region:可留空(默认 us-east-1);Cloudflare R2 填 auto;AWS 填桶所在区域 —— 填错时 App 会把服务端返回的正确 region 写进报错里;
    • 寻址风格:默认 路径风格(Path),MinIO / Ceph / R2 / B2 用它;虚拟主机(V-Host) 需要域名与通配证书,用 IP 地址时不可用。
  • 它是可读写的:浏览、上传、下载(支持断点续传)、新建目录、删除,以及双向 / 单向 / 镜像同步都能用。
    • S3 没有真正的目录,「新建目录」实际是写一个零字节的 <目录名>/ 标记对象,空目录因此能留住; 不写标记直接传 目录/文件.mp3 也能浏览到该目录。
  • ⚠️ 没有服务端转码:S3 做不到像 Subsonic 那样按「在线播放码率」转码降码率,弱网时选它对 S3 不生效 (流式播放与本地缓存照常)。
  • ⚠️ 单次上传上限 5 GB:首版未实现分片上传,超过上限会失败并给出提示 (音频文件远小于该上限,正常用不到)。
  • 🔐 自签证书(自建 MinIO / Ceph 常见):与 WebDAV 一样,在弹窗里点「检查证书 → 信任此证书」, 按服务器固定指纹;不要为了连通去改用 http。

7. 阿里云盘 (Aliyun Drive) 挂载

  • 直传与官方 OpenAPI:采用阿里云盘官方开发者接口,支持在线无损串流与超高速直传。
  • 挂载方式:
    • 网页登录授权:在「添加云盘」里选「阿里云盘」,点「获取令牌」打开阿里云盘网页登录;登录成功后 App 会自动提取并填入刷新令牌。也可以直接粘贴已有的 Refresh Token;
    • 免密续期:内置 Refresh Token 自动轮转机制,长期有效无需反复登录。

⚡ 二、云端在线流式播放与智能缓存

  • 即点即播:挂载成功后,云盘内容会按该协议对应的形态展示(文件类协议为目录树;Subsonic / Navidrome 为艺术家 / 专辑 / 歌单三类虚拟目录),点击任意歌曲即可通过分片流式加载在线播放。
  • 元数据与歌词秒级匹配:播放云端歌曲时,App 会自动提取 ID3 标签并在线匹配精准滚动歌词。
  • 本地无损缓存:听过的云端歌曲会自动缓存到本机 Download/JuJuDownload/JuJuCache,下次离线时亦可直接高保真播放。

🔄 三、四大增量同步模式详解

在工具箱点「云盘目录同步」(或进入「云盘存储」页点「目录同步」),即可将手机本地的音乐目录与云端指定目录建立自动同步任务:

同步模式 行为逻辑 适用场景
双向同步 (Two-way) 本地新增上传云端,云端新增下载到本地;两端保持完全一致。 手机与家用电脑/NAS 音乐库多端协同。
设备优先 (Local First) 本地有更新时单向推送到云端,覆盖云端旧文件。 手机作为主曲库,将手机音乐定期备份到云盘。
云端优先 (Cloud First) 云端有更新时单向拉取到本地,覆盖本地旧文件。 NAS 或云盘为主曲库,手机仅单向下载最新专辑。
镜像删除 (Mirror Delete) 开启后,若某一端删除了歌曲,另一端对应的歌曲也会被同步清理。 严格保持两端曲库文件完全镜像对齐。

后台同步:切出去也不会断

同步任务运行在 dataSync 前台服务上,因此:

  • 锁屏、切到别的 App、息屏都不会中断,整张专辑可以挂后台慢慢传;
  • 进度会显示在通知栏(当前文件名 + 已完成数量),通知栏里可以直接「取消」;
  • 进度弹窗里的「后台运行」可以把界面让出来,回到 App 时会自动接回进度弹窗;
  • 任务真正结束时,通知栏会保留一条结果(成功 / 失败项数),「取消」的会明确显示为已取消, 不会被记成"同步完成"。

⚠️ 两点仍然要注意:① 从最近任务里划掉 App 后,部分品牌的系统会连带结束进程, 这种情况请等同步跑完再划;② Android 15 及以上对后台数据传输类前台服务有每天累计 6 小时的 系统上限,超时会主动取消同步(大曲库建议分批同步)。

网络抖动会自动重试

传输失败时不会立刻记成"失败":App 会自动重试最多 2 次(指数退避;如果服务端明确要求 等待多久,则听服务端的)。此时通知栏与进度弹窗会显示「重试 2/3」这类字样 —— 看到它说明在自愈,不要手动取消。只有确认无意义的重试才会跳过:账号密码错、文件不存在、 云盘配额满、磁盘空间不足这类问题会立刻失败并给出原因。


🛡️ 四、Dry-Run 差异预检与安全防误删

为了避免因误操作造成珍贵的无损音乐丢失,JuJu音乐引入了 Dry-Run 差异预检机制:

  1. 预检计算:点「立即同步」后,引擎先在内存中比对文件路径、大小与修改时间戳;
  2. 差异清单展示:弹窗详细列出:
    • 🟢 即将下载:3 首新歌曲 (共 120MB)
    • 🔵 即将上传:1 首新歌曲 (共 45MB)
    • 🔴 即将删除:0 首 (或列出具体待删文件)
  3. 用户确认后执行:只有在用户核对无误并点击「确认执行同步」后,底层任务才会正式写入文件系统。

📲 五、P2P 局域网直传与 10 分钟即焚云端共享

无需数据线,在两台设备之间极速互传音乐:

  • 面对面扫码互传:发送方选择歌曲生成专属二维码,接收方打开 App 扫码,双方通过 WiFi 局域网直连,传输速率取决于当时的局域网环境。
  • 10 分钟即焚中转站:若两台设备处于不同网络(跨公网),发送方可一键上传至云端中转站生成 6 位提取码。接收方输入提取码下载,10 分钟后或下载完成后云端自动物理粉碎销毁,保护版权与隐私。

并发与限速

  • 并发文件数:同一时刻处理几个文件,可选 1 / 2 / 4 / 8,默认 4。音乐库多为小文件,串行时瓶颈是“每个文件的多次往返”,从 1 调到 4 通常能明显加快;设为 1 即逐文件串行(怕打扰 NAS 时可用)。
  • 带宽限速:所有并发传输合计的上限(不限速 / 512KB/s / 1MB/s / 2MB/s / 5MB/s)。 注意它约束的是平均速率:如果链路本身就只有 3Mbps(约 375KB/s),限到 512KB/s 是不会生效的, 要明显低于链路容量才看得出效果。也不会因为并发调高而突破这个上限。