账号与云端同步

注册瓜子音乐账号后，你的收藏、歌单、播放记录和个人设置可以在多台设备之间同步。换电脑、重装系统也能无缝接上你的音乐世界。

注册账号

1. 点击左侧边栏底部的用户头像图标，打开用户中心
2. 切换到 注册 标签页
3. 输入用户名、邮箱和密码
4. 点击发送验证码，检查你的邮箱获取验证码
5. 输入验证码后完成注册

邮箱注册

• 一个邮箱只能注册一个账号
• 邮箱用于接收验证码、找回密码，不会公开显示
• 建议使用主流邮箱（QQ、163、Gmail、Outlook）

登录账号

1. 打开用户中心
2. 输入用户名（或邮箱）和密码
3. 点击 登录

登录成功后，系统会自动从云端拉取你之前同步的数据。

云端同步

同步的内容

数据类型	说明
我喜欢的音乐	收藏的歌曲列表
用户歌单	自建歌单及其歌曲
播放记录	最近播放的歌曲
个人设置	语言、播放模式、外观偏好等（不含本地路径、API Key、WebDAV 密码等敏感信息）

隐私保护

同步的设置由 pickSyncableSettings() 函数筛选，仅包含可同步的偏好：

• ✅ 同步：语言、播放模式、音质偏好、外观主题等
• ❌ 不同步：API Key、WebDAV 密码、本地路径、缓存目录等

同步方式

• 自动同步：登录后，本地数据的变更会在几秒后自动推送到云端（防抖 4s）
• 手动同步：在用户中心点击 立即同步 按钮，强制执行一次完整同步

同步策略

场景	行为
首次登录 + 本地有数据	将本地数据推送到云端
首次登录 + 本地为空 + 云端有数据	自动从云端拉取覆盖本地
日常使用	本地数据优先，变更后推送覆盖云端
多设备使用	每个设备修改后都会推送，以最后修改为准

手动同步说明

syncNow 在 hasLocal 时以本地为准 push；hasRemote && !hasLocal 时 pull 覆盖本地。手动同步成功后当前实现会 window.location.reload() 全页刷新。

跨设备播放推送

登录同一账号的不同设备之间可以互相推送歌曲：

• 在 A 设备播放歌曲时，可以在用户中心将其推送到 B 设备
• B 设备会自动接收并开始播放
• 每台设备会定时发送心跳保持在线状态

适用场景

• 在书房电脑上发现一首好歌，推送到客厅 HTPC 上用大音响听
• 在工作电脑上选好歌单，推送到家用电脑继续

数据存储说明

• 个人中心统计卡片显示的是本地 SQLite 数据（favoriteIds.length 等），标注为「本地数据」
• **管理后台「云端数量」**是解析 JSON 后的条目数
• 本地与云端不一致时：用户需点「立即同步」

数据模型

m7_user_data 按 类型 + data_key 存 JSON 块：

• favorites / recent：{ ids, addedAt/playedAt, tracks }
• playlists：歌单数组
• settings：pickSyncableSettings() 结果

每种类型通常只有 1 块（key: 'default'），块内才是真实列表。

退出登录

在用户中心点击 退出登录：

• 本地数据（歌单、收藏、播放记录）不会丢失，仍保留在本机
• 退出后不再自动云端同步
• 重新登录后可以再次拉取云端数据

常见问题

注册时收不到验证码？

• 检查垃圾邮件箱，验证码邮件可能会被误判
• 确认邮箱地址输入正确
• 尝试重新发送验证码（间隔 60 秒后可重试）
• 部分企业邮箱可能屏蔽了验证码邮件，建议使用个人邮箱
• 如果多次尝试仍收不到，可能是邮件服务暂时异常，稍后再试

同步后收藏列表和之前不一样？

• 云端同步以最新修改为准，如果在另一台设备做了大量修改，会覆盖本机数据
• 如果需要恢复，可以使用 立即同步 重新拉取
• 同步前如担心冲突，建议在一台设备上完成所有修改后再使用另一台设备

登录状态总是掉？

• 检查网络连接是否稳定
• 如果长期未使用，登录凭证可能会过期（默认 7 天）
• 重新登录即可恢复
• 多个设备同时登录同一账号不会互踢

忘记密码？

• 在登录界面点击 忘记密码
• 输入注册邮箱，获取验证码后重置密码
• 重置后新密码立即生效，旧密码失效

同步速度慢？

• 同步数据量较大时（如收藏数千首歌）首次同步可能需要数秒
• 后续增量同步只推送变更部分，速度很快
• 网络延迟也会影响同步速度

重复点击「立即同步」3 次会怎样？

• syncingRef 防止并发，重复点击不会触发多次同步
• UI 侧 m7Syncing 状态 + 按钮 disabled，避免重复操作
• 同步成功后会全页刷新，不会重复 push