☁️ 私有云盘:挂载与增量同步全指南
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 常见) 留空即可(登录后本来就被关在自家目录里)。
- 服务器地址:主机名或 IP,如
- 🔐 证书信任(TOFU)—— 第一次连接会被拒绝,这是正常的:FTPS 也走 TLS,自签证书同样没有可信 CA
可校验,所以 App 按服务器固定证书指纹:
- 第一次保存会被拒绝,弹窗直接给出服务器出示的完整证书 SHA-256 指纹;
- 点弹窗里的「检查证书」,App 会再连一次,并显示服务器真实出示的指纹与主题 / 颁发者;
- 核对无误后点「信任此证书」,之后才能保存与使用;信任状态随时可以「取消信任」撤回。
- 指纹一定要和服务端上的一致:可以在服务器上执行
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 共享用户
- IP 地址:如
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里乱逛。
- 服务器地址:主机名或 IP,如
- 🔐 主机密钥信任(TOFU)—— 第一次连接会被拒绝,这是正常的:SFTP 没有像 HTTPS 那样的
「可信 CA」体系,所以 App 用**按服务器固定指纹(TOFU,首次使用即信任)**的方式防中间人:
- 第一次保存时连接会被拒绝,弹窗直接给出服务器出示的完整主机密钥 SHA-256 指纹与
密钥算法(如
ssh-ed25519)—— 不是一句干巴巴的"连接失败"; - 点弹窗里的「检查主机密钥」,App 会再连一次,并显示服务器真实出示的指纹;
- 核对无误后点「信任此主机密钥」,之后才能保存与使用;信任状态随时可以「取消信任」撤回。
- 指纹一定要和服务端上的一致:可以在服务器上执行
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub取到同一串指纹来交叉核对; - ⚠️ 如果提示"主机密钥已变化"而你自己并没有换过密钥,请不要信任 —— 可能是服务器重装过,更可能连接正在被中间人劫持;
- 指纹只对这一台服务器生效,不会顺手放开其他云盘的校验。
- 第一次保存时连接会被拒绝,弹窗直接给出服务器出示的完整主机密钥 SHA-256 指纹与
密钥算法(如
- 它是可读写的:浏览、上传、下载(支持断点续传)、新建目录、删除,以及双向 / 单向 / 镜像同步 都能用;云端歌曲也支持在线播放(含拖动进度)。
- ⚠️ 没有服务端转码: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 地址时不可用。
- 服务器 URL:如
- 它是可读写的:浏览、上传、下载(支持断点续传)、新建目录、删除,以及双向 / 单向 / 镜像同步都能用。
- S3 没有真正的目录,「新建目录」实际是写一个零字节的
<目录名>/标记对象,空目录因此能留住; 不写标记直接传目录/文件.mp3也能浏览到该目录。
- S3 没有真正的目录,「新建目录」实际是写一个零字节的
- ⚠️ 没有服务端转码: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 差异预检机制:
- 预检计算:点「立即同步」后,引擎先在内存中比对文件路径、大小与修改时间戳;
- 差异清单展示:弹窗详细列出:
- 🟢 即将下载:
3 首新歌曲 (共 120MB) - 🔵 即将上传:
1 首新歌曲 (共 45MB) - 🔴 即将删除:
0 首 (或列出具体待删文件)
- 🟢 即将下载:
- 用户确认后执行:只有在用户核对无误并点击「确认执行同步」后,底层任务才会正式写入文件系统。
📲 五、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 是不会生效的, 要明显低于链路容量才看得出效果。也不会因为并发调高而突破这个上限。