songloft

Songloft 快速使用指南

简体中文 • English 面向个人用户的自托管音乐服务器 — 仅管理你合法拥有的音乐

关于改名：本项目自 v2.0 起由 MiMusic 更名为 Songloft（内核与功能不变，仅品牌升级）。老的 mimusic-org GitHub 组织与 hanxi/mimusic Docker 镜像保留至少一年作跳转，但不再更新。详见 GitHub Releases。

GitHub • 下载 • 文档 • 问题反馈 • 微信群 • Telegram 群 • Telegram 频道 • 截图

纯为爱发电 · 谨防诈骗

Songloft 是完全免费的开源项目，纯粹出于兴趣与热爱开发，与任何商业利益无关：

• ✅ 永久免费 —— 没有任何收费功能、内购或会员
• ✅ 无广告 —— 不含任何广告或商业推广
• ✅ 不接受赞助 / 捐款 —— 官方不设任何收款渠道
• ⚠️ 谨防诈骗 —— 官方渠道仅有 GitHub 仓库、文档站、官方微信群、Telegram 群 与 Telegram 频道。任何以 Songloft 名义收费、售卖付费版本、代部署收费或索要赞助的行为都与本项目无关；即便在群内，我们也从不向任何人收取任何费用，请勿上当受骗。

✨ 核心功能

• 本地音乐管理 — 扫描本地目录，自动提取 MP3/FLAC/WAV/APE/OGG/Opus/M4A/M4B/WMA/AIF/AIFF/MKA 等格式的封面和元数据
• 视频支持 — 扫描 MP4/MOV/M4V/MKV/WebM/AVI/TS/MPG/MPEG/FLV/WMV/RM/RMVB/3GP 等视频容器并探测真实视频轨，客户端内渲染画面
• JS 插件体系 — 基于 QuickJS 沙箱运行，支持权限模型、健康检查、热更新，可自由扩展音源 / 元数据 / 设备控制等能力
• 跨平台客户端 — Flutter 客户端支持 Android、iOS、macOS、Windows、Linux、Web 六端
• Bundle 本地模式 — 客户端内嵌 Go 后端，无需部署服务器，手机/电脑直接播放本地音乐
• Kodi 插件客户端 — 支持 Xbox、Apple TV、树莓派、Android TV 等大屏设备，专为遥控器操作优化，带来流畅的客厅影音体验
• Web 界面 — 完整版内置 Web 前端，开箱即用
• JWT 认证 — 双 Token 机制（Access Token + Refresh Token），支持多设备管理
• 网络歌曲 & 电台 — 支持添加网络音频 URL 与电台流，播放时透明缓存到服务端
• 完整 REST API — 内置 Swagger 文档，方便集成和二次开发
• ⚡ 轻量高效 — Go 编写，CGO-free，无外部依赖，适合 NAS / 树莓派等低功耗设备

️ 界面截图

更多界面（歌曲库、歌单、设置等，含桌面 / 移动端与亮 / 暗双主题）见 界面截图一览。

⚖️ 版权与免责声明

Songloft 是一款面向个人用户的自托管工具，定位为帮助用户管理自己合法拥有的音乐文件。在使用本项目前，请务必阅读并理解以下条款：

• 不提供任何音乐内容 — Songloft 本身不内置、不分发、不存储任何受版权保护的音乐资源，仅是一个供你管理本地音乐库的开源软件
• ✅ 请仅管理合法来源的音乐 — 用户应仅使用 Songloft 管理自己合法获得的音乐文件，包括但不限于：
  • 自行购买并下载的数字音乐
  • 从实体唱片转录的个人备份
  • 自己创作或录制的作品
  • 公有领域（Public Domain）作品
  • 明确以 CC（Creative Commons）等开源协议授权的作品
• 第三方插件免责 — JS 插件由第三方社区维护，主仓库不预置、不分发任何第三方音源插件成品。插件接入的任何网络音源、元数据、歌词内容版权均归原权利人所有。使用网络音源等功能时，用户须自行承担版权合规责任，并遵守所在国家 / 地区的法律法规
• 仅供个人非商业使用 — 严禁将本项目用于商业用途、对外公开分发版权内容，或搭建面向不特定多数人的公共服务
• ⚠️ 责任自担 — 因不当使用本项目（包括但不限于侵犯第三方版权）所引发的任何法律责任、纠纷或损失，均由使用者本人承担，本项目作者及贡献者不承担任何责任
• 侵权举报 — 如果你是版权持有人，认为本项目代码、文档或官方分发的插件侵犯了你的合法权益，请通过 GitHub Issues 或邮件 ([email protected]) 联系我们，我们将在核实后及时处理。对于第三方社区插件的侵权问题，请直接联系该插件的维护者
• ™️ 商标声明 — 本项目及内置插件中提到的所有品牌、协议、产品名称（包括但不限于「MIoT」「Bluetooth」「Android」「iOS」「macOS」「Windows」「Docker」等）均归各自商标权人所有。相关名称的出现仅出于互操作和指示性合理使用目的，Songloft 与上述商标持有人无任何关联，也未获得任何形式的授权或背书。详见 NOTICE
• 隐私 — 不采集任何用户数据；官方构建仅上报匿名运行统计（版本号、崩溃栈），自编译版本零遥测。详见 PRIVACY.md

我们尊重并支持知识产权保护。如果你喜欢某位艺术家的作品，请通过正版渠道购买或订阅以支持创作者。

版本说明

Songloft 提供三种版本，满足不同使用场景：

版本	后缀	说明	适用场景
完整版	无后缀	包含 Web 前端，开箱即用	推荐初次使用，访问服务地址即可看到 Web 界面
精简版	-lite	不包含 Web 前端，体积更小	配合 Flutter 桌面/移动客户端，或前后端分离部署
Bundle 版	bundled-	Flutter 客户端内嵌 Go 后端	无需部署服务器，手机/电脑直接播放本地音乐

推荐：初次使用直接下载默认的 完整版，开箱即用，无需额外配置前端。 想在手机或电脑上独立使用，无需部署服务器？可下载 Bundle 版。

️ 平台支持

二进制文件

完整版（推荐）

包含 Web 前端，开箱即用：

平台	架构	下载链接
Linux	x86_64	songloft-linux-amd64
Linux	ARM64	songloft-linux-arm64
Linux	ARMv7	songloft-linux-armv7
macOS	x86_64 (Intel)	songloft-darwin-amd64
macOS	ARM64 (Apple Silicon)	songloft-darwin-arm64
Windows	x86_64	songloft-windows-amd64.exe
Windows	ARM64	songloft-windows-arm64.exe

精简版（Lite）

不包含 Web 前端，体积更小：

平台	架构	下载链接
Linux	x86_64	songloft-linux-amd64-lite
Linux	ARM64	songloft-linux-arm64-lite
Linux	ARMv7	songloft-linux-armv7-lite
macOS	x86_64 (Intel)	songloft-darwin-amd64-lite
macOS	ARM64 (Apple Silicon)	songloft-darwin-arm64-lite
Windows	x86_64	songloft-windows-amd64-lite.exe
Windows	ARM64	songloft-windows-arm64-lite.exe

Bundle 版（内嵌后端，无需服务器）

客户端内嵌 Go 后端，首次启动点击「使用本地模式」选择音乐目录即可使用：

平台	架构	下载链接
Android	ARM64 + ARMv7	songloft-bundled-android-arm64-v8a.apk
Linux	x86_64	songloft-bundled-linux-x64.tar.gz
macOS	ARM64 (Apple Silicon)	songloft-bundled-macos-arm64.dmg
Windows	x86_64	songloft-bundled-windows-x64.zip
iOS	ARM64	songloft-bundled-ios-arm64.ipa

Docker 镜像

完整版（推荐）

平台	下载链接
Linux x86_64	songloft-docker-linux-amd64.tar
Linux ARM64	songloft-docker-linux-arm64.tar
Linux ARMv7	songloft-docker-linux-arm-v7.tar

精简版（Lite）

平台	下载链接
Linux x86_64	songloft-docker-linux-amd64-lite.tar
Linux ARM64	songloft-docker-linux-arm64-lite.tar
Linux ARMv7	songloft-docker-linux-arm-v7-lite.tar

Flutter 客户端

除了 Web 界面，Songloft 还提供功能更强大的跨平台 Flutter 客户端，支持后台播放、本地缓存、媒体控制（耳机/锁屏/通知栏）等服务端 Web 界面无法实现的能力，覆盖 iOS、Android、macOS、Windows、Linux 和 Web 六端。

GitHub 仓库：songloft-org/songloft-player

• 标准版（需连接服务器）：songloft-player Releases
• Bundle 版（内嵌后端，无需服务器）：songloft Releases（下载 songloft-bundled-* 文件）

Windows 用户：可通过 Scoop 一键安装与更新，该 Bucket 提供三个应用，可按需选择：

scoop bucket add songloft https://github.com/songloft-org/songloft-scoop
scoop install songloft-player    # Flutter 客户端（GUI，需连接服务器）
scoop install songloft-server    # 服务端（CLI，仅命令行程序）
scoop install songloft-bundled   # Bundle 版（服务端 + 客户端一体化，无需单独部署服务器）
# 更新：scoop update songloft-player（其余同理）
# 卸载：scoop uninstall songloft-player（加 --purge 一并删除配置数据）

⚠️ songloft-bundled 与 songloft-server、songloft-player 存在文件冲突，不能同时安装；songloft-server 与 songloft-player 可以共存。

Bundle 版使用方式：首次启动在登录页点击「使用本地模式」→ 选择音乐目录 → 自动完成。支持随时在设置页切换本地/远程模式。

使用 精简版（-lite） 服务端时，推荐直接搭配 Flutter 客户端使用（无需额外部署 Web 前端）；如确实需要独立 Web 前端，可参考 songloft-player 仓库的 flutter build web 流程自行构建并由 Nginx 等反向代理静态托管。

TV / 车机客户端

除 Flutter 客户端外，TV 端和车机端推荐使用专门的 songloft-tv 客户端，专为 Android TV 及车载信息娱乐系统设计，支持遥控器和触屏操作。

Kodi 插件

除 Flutter 客户端外，Songloft 还提供官方 Kodi 插件，让你在 Kodi 媒体中心中直接播放 Songloft 音乐库。适合 Xbox、Apple TV、树莓派、Android TV 等支持 Kodi 的大屏设备，专为遥控器操作优化，带来流畅的客厅影音体验。

GitHub 仓库：songloft-org/plugin.audio.songloft 下载：GitHub Releases

路由器 / 光猫部署

路由器与光猫是家庭中常见的基础网络设备，天然支持 24 小时不间断运行，非常适合用于部署 Songloft。社区项目 songloft-for-router 提供了面向 OpenWrt、Entware 与梅林（Merlin，含 SWRTdev / Koolshare 软件中心）三类主流路由器固件生态的插件安装包，帮助你在路由器 / 光猫上轻松管理 Songloft 服务。

GitHub 仓库：songloft-org/songloft-for-router

第三方客户端

以下第三方客户端由社区开发者独立维护，已适配 Songloft 服务端，为你提供更多平台选择：

客户端	平台	说明
音乐方舟	HarmonyOS	HarmonyOS NEXT 多源媒体播放器，16 类媒体库一站聚合
箭头音乐	Android / iOS / HarmonyOS / Windows / macOS	现代化多平台音乐播放器，兼容多种音乐服务器协议
音流	Android / iOS / macOS / Windows	跨平台 NAS 音乐播放器，支持多种自托管音乐服务
流云音盒	HarmonyOS	HarmonyOS 无损音乐播放器，聚合本地、云盘、WebDAV 与 NAS 私有曲库
流云音乐	iOS	网盘音乐播放器，支持 WebDAV、Navidrome 等多种云盘与自托管音乐服务

第三方客户端由各自开发者维护，与 Songloft 项目无直接关联。如遇问题请联系对应客户端的开发者。

快速开始

安全提示（必读）：默认管理员账号是 admin / admin，仅适用于本地测试。任何对外网暴露或多设备访问的部署，请务必通过环境变量 ADMIN_USERNAME / ADMIN_PASSWORD 设置强密码后再启动；否则你的音乐库可能被陌生人访问。

方式一：直接运行二进制文件

Linux / macOS

# 1️⃣ 下载对应平台的二进制文件（默认即完整版）
# 例如 Linux x86_64:
wget https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-amd64
mv songloft-linux-amd64 songloft

# 2️⃣ 添加执行权限
chmod +x songloft

# 3️⃣ 创建必要目录
mkdir -p music data

# 4️⃣ 启动（推荐通过环境变量传入凭证，避免出现在 shell history / 进程列表中）
ADMIN_USERNAME=admin ADMIN_PASSWORD='your_strong_password' ./songloft

macOS 用户注意：从 GitHub 下载的二进制带有 Gatekeeper 隔离属性，首次运行会被拦截。运行前请先执行：

xattr -d com.apple.quarantine ./songloft

Windows

# 1️⃣ 下载对应平台的二进制文件（默认即完整版），并重命名为 songloft.exe
# 例如 Windows x86_64: songloft-windows-amd64.exe

# 2️⃣ 创建必要目录
mkdir music
mkdir data

# 3️⃣ 设置环境变量并启动（PowerShell）
$env:ADMIN_USERNAME = "admin"
$env:ADMIN_PASSWORD = "your_strong_password"
.\songloft.exe

方式二：Docker 部署

从 Docker Hub 拉取（推荐）

#  完整版（推荐，包含 Web 前端，:latest 即完整版）
docker pull songloft/songloft:latest

#  精简版（不含 Web 前端，需搭配 Flutter 客户端使用）
docker pull songloft/songloft:lite

# 运行容器
docker run -d \
  --name songloft \
  -p 58091:58091 \
  -v /path/to/music:/app/music \
  -v /path/to/data:/app/data \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD='your_strong_password' \
  -e PUID=$(id -u) -e PGID=$(id -g) \
  songloft/songloft:latest

非 root 运行（可选）：加上 -e PUID=$(id -u) -e PGID=$(id -g) 后，容器内主程序会以宿主机当前用户身份运行，挂载目录下新产生的文件不再是 root 属主。不设置则保持容器默认的