企业官网建设流程全解析

Folia跨平台密码安全存储：macOS钥匙串与Linux secret-service实现

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major

Folia 是一款专注绚丽歌词动画的本地音乐播放器，同时支持 Navidrome、QQ 音乐、酷狗等在线音源。为了让在线账号登录在重启后依然有效，Folia 的 Electron 主进程采用系统级密码保险库做跨平台密码安全存储：macOS 使用钥匙串（Keychain），Linux 走 GNOME secret-service（libsecret / D-Bus Secret Service API），并配合 Electron 的safeStorage加密模块，确保 QQ 的 musickey、酷狗的登录 token 等敏感凭据永远不会以明文落在配置文件里。

为什么不能把登录凭据写成明文

在线音源（QQ 音乐、酷狗）登录后会拿到一串凭据：QQ 侧是musickey、刷新密钥与设备上下文，酷狗侧是token、userid、dfid等 cookie。这些凭据一旦写入普通配置文件，任何能读取用户目录的程序都能拿去冒用你的账号。

Folia 的取舍很明确：能用系统加密就加密，不能加密就只保留在内存里，而不是退而求其次写一份"打了一层混淆"的明文。

macOS 钥匙串：Electron safeStorage 的默认通道

在 macOS（以及 Windows 的 DPAPI）上，Folia 直接复用 Electron 内置的safeStorage模块：

1. 主进程调用safeStorage.encryptString()把凭据序列化后的 JSON 加密成密文；
2. 密文以 base64 写入应用配置（electron-store）；
3. 重启后读取密文，调用safeStorage.decryptString()借助钥匙串中的密钥还原。

加密密钥由系统钥匙串托管，应用自身拿不到明文密钥，跨用户、跨机器拷贝配置文件也无法解密——这正是"密码安全存储"与"普通文件加密"的本质区别。

Linux secret-service：为 Wayland 桌面补上加密缺口

Linux 的坑在于：Chromium 内核（Electron 的底座）按XDG_CURRENT_DESKTOP选择密码后端，遇到它不认识的环境（Hyprland、Sway、i3、river 等 Wayland 合成器）会静默回退到basic_text后端——那只是简单混淆，并不具备真实加密能力。

为此 Folia 在应用早期就显式指定后端，核心逻辑见 linuxPasswordStore.cjs：

• 非 KDE 桌面：统一注入--password-store=gnome-libsecret，把密码后端锁定到 secret-service（GNOME Keyring / KWallet 兼容的 libsecret 实现），在 main.cjs 中于ready事件前追加该启动参数；
• KDE 会话：保持 Chromium 自有的 KWallet 检测，避免把已写入 KWallet 的凭据"孤儿化"；
• 手动覆盖：设置环境变量FOLIA_PASSWORD_STORE可强制指定basic、gnome-libsecret、kwallet5等后端，或设为auto交还给系统检测，方便排障。

启动后还有一道自检（见 main.cjs）：若最终后端仍是basic_text或加密不可用，控制台会明确告警"在线账号将不会持久化"，而不是让用户重启后莫名其妙丢失登录。

凭据仓库：加密不可用就拒绝落盘

QQ 与酷狗两条凭据链路共用同一套防护模式，实现分别在 qqAuthSessionRepository.cjs 与 kugouApiBridge.cjs：

• 保存前校验：每次写入前调用isEncryptionAvailable()检查系统保险库状态；Linux 上额外确认后端不是basic_text，否则直接抛出"拒绝使用未加密后端"错误；
• 失败即内存化：加密不可用时，登录本身仍然可用（凭据保存在主进程内存中），只是不做持久化——宁可每次重启重新扫码，也不把 QQ musickey 写到磁盘；
• 旧数据升级：酷狗凭据早期的 V1 明文键在读取后会被立即删除，下一次保存时自动升级为 V2 加密格式，见 kugouApiBridge.cjs；
• 渲染进程隔离：QQ 的 musickey 等敏感字段只存在于主进程加密仓库中，界面层仅持有不透明的会话标识，登录响应的 token 也会在下发给渲染进程前被剔除（见sanitizeRendererBody）。

小结

Folia 用"系统钥匙串优先 + 明文零容忍"的策略，把跨平台密码安全存储做成了普通用户完全无感的体验：登录一次，重启即恢复；而一旦系统保险库不可用，它宁可让你重新登录，也绝不让凭据裸奔。如果你想深入了解在线音源的账号与凭据持久化边界，可以阅读 src/services/onlineMusic/README.md。

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major