songloft

🎵 Songloft 快速使用指南

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

💚 纯为爱发电 · 谨防诈骗

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

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

✨ 核心功能

• 🎵 本地音乐管理 — 扫描本地目录，自动提取 MP3/FLAC/WAV/APE/OGG/Opus/M4A/M4B/WMA/AIF/AIFF/MKA/DSF（DSD）等格式的封面和元数据
• 🎬 视频支持 — 扫描 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 界面 — 完整版内置 Lynx 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 等反向代理静态托管。

📱 Lynx 客户端（预览版）

Songloft Player (Lynx) 使用 ReactLynx + TypeScript，支持 Android、iOS、HarmonyOS 和 Web。已实现核心播放、曲库/歌单、歌词、插件、主题与多服务器；目前没有桌面客户端、Bundle 本地后端或客户端内检查更新。

• 开发版下载：main 代码推送后自动打包，五个产物全部成功才更新。
• 正式版本：通过版本 tag 发布；首次成功发版前可能尚无正式包。
• 安装指南 · 构建与运行 · 发版指南。

Android 提供 release 签名 APK，iOS 提供需自行重签的 IPA，HarmonyOS 提供签名 HAP（设备范围由 profile 决定），Web 提供 standalone/embedded 两种压缩包。HarmonyOS 为实验性支持；Web 需 HTTPS 与 COOP/COEP 响应头，子路径部署未验证。详见客户端选择。

🖥️ Songloft Desktop（Electron 客户端）

Songloft Desktop 是 Songloft 官方 Electron 桌面客户端，面向 Windows、macOS 和 Linux。需连接 Songloft 服务端，不含 Bundle 本地后端。

• 下载与安装包：各平台安装方式以仓库说明和 Release 产物为准。
• 项目说明与源码 · 问题反馈。

📺 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 部署

ARMv7 用户：旧版 Armbian / Debian 的宿主机 libseccomp 可能导致容器启动崩溃。遇到 futexwakeup / SIGSEGV 时，请参阅 FAQ 排查步骤。

🌐 从 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 属主。不设置则保持容器默认的 root 运行方式，不影响现有部署。

📥 从 Release 离线导入镜像

适合无法直接访问 Docker Hub 的环境：

# 1️⃣ 下载对应平台的 Docker 镜像 tar 文件（默认即完整版）
wget https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-amd64.tar

# 2️⃣ 导入镜像
docker load -i songloft-docker-linux-amd64.tar

# 3️⃣ 查看导入的镜像标签
docker images | grep songloft

# 4️⃣ 使用上一节的 docker run 命令启动即可（注意替换为导入的镜像标签）

🐙 Docker Compose 部署（推荐）

使用 Docker Compose 可以更方便地管理容器配置：

version: '3.8'

services:
  songloft:
    image: songloft/songloft:latest
    container_name: songloft
    restart: always
    ports:
      - "58091:58091"
    volumes:
      - /path/to/music:/app/music
      - /path/to/data:/app/data
    environment:
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=your_strong_password
      - LISTEN_PORT=58091
      - PUID=1000 # 可选：非 root 运行，改成宿主机对应用户的 uid
      - PGID=1000 # 可选：非 root 运行，改成宿主机对应用户的 gid

将上述内容保存为 docker-compose.yml 文件，然后运行：

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

🏠 方式三：Home Assistant 加载项

如果你在使用 Home Assistant OS（HAOS），可以把 Songloft 作为**加载项（Add-on）**一键安装，无需手动写 docker run。

点击上方徽章会直接在你的 HA 里弹出「添加加载项仓库」对话框；或手动操作：

1. 「设置 → 加载项 → 加载项商店」，右上角菜单「仓库」，添加：https://github.com/songloft-org/home-assistant-addon
2. 刷新后在商店里找到 Songloft，点击安装
3. 到「配置」页填写管理员账号密码、音乐库路径（默认 /media），然后启动
4. 点加载项详情页的「打开 Web UI」访问

音乐文件放进 Home Assistant 的媒体目录（/media）或共享目录（/share）即可被扫描。数据持久化在加载项的 /data 目录，卸载重装不丢。

🔐 安全提示：默认账号 admin/admin 仅适用于本地测试，任何对外访问的部署请先在配置页设置强密码再启动。

📋 使用流程

1️⃣ 启动服务

服务启动后，访问 http://localhost:58091 即可打开 Web 界面（仅完整版内置；精简版请使用 Flutter 客户端 连接）。

2️⃣ 登录系统

使用配置的管理员账号密码登录。

3️⃣ 配置音乐目录

首次登录后，进入「设置」页面配置音乐文件目录（music_path）。Docker 部署时通常配置为 /app/music。

4️⃣ 扫描音乐

在 Web 界面中点击"扫描"按钮，系统会自动扫描音乐目录中的音频文件并提取元数据。

5️⃣ 播放音乐

扫描完成后，即可在界面中浏览和播放音乐。

⚙️ 配置说明

Songloft 仅依赖少量启动期配置（凭证、端口、数据库路径）通过环境变量或命令行参数指定，其余业务配置（音乐目录、扫描规则、封面存储等）都保存在数据库 config 表中，启动后通过 Web 界面管理。

🌍 环境变量

变量名	说明	默认值
ADMIN_USERNAME	👤 管理员用户名	admin
ADMIN_PASSWORD	🔐 管理员密码	admin
LISTEN_PORT	🔌 服务端口	58091
DB_PATH	💾 数据库文件路径	data/songloft.db
BASE_PATH	🔗 URL 基础路径（反向代理子路径部署用，如 /songloft）	空（根路径）
MUSIC_DIR	🎵 音乐目录（非空时覆盖数据库中的默认值，等价于 -music 参数）	空
PUID	👤 （仅 Docker） 设置后以该 uid 非 root 运行主程序，未设置时保持 root 运行	空（root）
PGID	👤 （仅 Docker） 设置后以该 gid 非 root 运行主程序，未设置时保持 root 运行	空（root）
FIX_MUSIC_PERMISSIONS	🔧 （仅 Docker） 设为 true 时递归修复 /app/music 下所有文件的属主为 PUID:PGID（默认仅修复顶层目录，音乐库较大时递归修复可能耗时较长，一般只在升级为非 root 运行后需要用一次）	false

📁 Docker 镜像中音乐目录与数据目录默认为 /app/music 与 /app/data，通过 -v 挂载即可；如需指向其他路径，可用 MUSIC_DIR 指定音乐目录。 👤 非 root 运行：PUID/PGID 任一设置即启用，未设置的一方默认补 1000；/app/data 会自动递归修复属主（解决从 root 运行升级过来的历史文件），/app/music 默认仅修复顶层目录，如需连同库内历史文件一起修复请设置 FIX_MUSIC_PERMISSIONS=true。

💻 命令行参数

# 查看帮助
./songloft -help

# 指定端口
./songloft -port 8080

# 指定数据库文件路径
./songloft -db data/songloft.db

# 指定管理员账号（不推荐，密码会出现在 shell history 和 ps 进程列表中）
./songloft -username admin -password your_password

# 指定子路径（反向代理部署时使用）
./songloft -base-path /songloft

⚙️ 优先级：命令行参数 高于 环境变量。若两者均未提供，则回退到默认值（管理员账号为 admin/admin）。 ⚠️ 参数格式：Songloft 使用单横杠参数（如 -help），不支持双横杠参数（如 --help）。 🔐 密码安全：推荐通过环境变量 ADMIN_PASSWORD 传入密码，避免 -password 在进程列表中明文暴露。

🌐 反向代理子路径部署

如果你通过 Nginx 等反向代理将 Songloft 挂在子路径下（如 https://nas.example.com/songloft/），需要配置 BASE_PATH 环境变量。

配置步骤

1. 启动 Songloft 时指定 BASE_PATH：

# 环境变量方式
BASE_PATH=/songloft ./songloft

# 或命令行参数方式
./songloft -base-path /songloft

# Docker 方式
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 BASE_PATH=/songloft \
  -e PUID=$(id -u) -e PGID=$(id -g) \
  songloft/songloft:latest

2. 配置 Nginx 反向代理：

location /songloft/ {
    proxy_pass http://127.0.0.1:58091;
    proxy_read_timeout 52w;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

⚠️ 注意：proxy_pass 末尾不要加斜杠。Nginx 会将完整路径（含 /songloft/）转发给后端，由 Songloft 自行处理前缀剥离。

客户端连接

客户端类型	服务器地址填写
内置 Web 前端	浏览器直接访问 https://nas.example.com/songloft/，自动工作
Flutter 桌面/移动客户端	填写 https://nas.example.com/songloft

Docker Compose 示例

version: '3.8'

services:
  songloft:
    image: songloft/songloft:latest
    container_name: songloft
    restart: always
    ports:
      - "58091:58091"
    volumes:
      - /path/to/music:/app/music
      - /path/to/data:/app/data
    environment:
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=your_strong_password
      - BASE_PATH=/songloft
      - PUID=1000 # 可选：非 root 运行，改成宿主机对应用户的 uid
      - PGID=1000 # 可选：非 root 运行，改成宿主机对应用户的 gid

💻 系统要求

项目	要求
操作系统	🐧 Linux / 🍎 macOS / 🪟 Windows
架构	x86_64 / ARM64 / ARMv7
可选依赖	🔧 ffprobe（用于获取音频技术参数，不安装也可正常运行）

✅ 校验文件完整性

每个 Release 都包含 checksums.txt 文件，用于验证下载文件的完整性：

# 下载校验和文件
wget https://github.com/songloft-org/songloft/releases/latest/download/checksums.txt

# 验证文件
sha256sum -c checksums.txt

📌 版本检查

# 查看版本信息（含 Git Commit / 构建时间 / 构建类型）
./songloft -version

# 查看完整帮助
./songloft -help

# 通过 API 检查版本
curl http://localhost:58091/api/v1/version

输出示例：

Songloft Version: x.y.z
Git Commit: abc1234
Build Time: 2026-01-01_00:00:00
Build Type: full

🔌 插件系统

Songloft 内置 JS 插件引擎，插件运行在 QuickJS 沙箱中，支持权限模型、健康检查与热更新，可自由扩展音源 / 元数据 / 设备控制等能力。

🎯 插件获取

每个插件在自己的 GitHub 仓库下分发：进到对应仓库的 Releases 页下载最新版的 .jsplugin.zip，再到 Songloft 客户端的「插件管理」页上传即可启用。可在 插件合集 Issue 找到当前可用的插件清单。

想看更多插件或共建？欢迎在 插件合集 Issue 留言。

⚠️ 版权提示：第三方插件接入的任何网络音源、歌词、封面等内容，版权均归原权利人所有。请仅将插件用于访问你本人享有合法使用权的内容，下载 / 转存 / 二次分发等行为请遵守所在国家或地区的法律法规。详见上文 版权与免责声明。

🛠️ 插件开发

如需开发自定义插件，请参考以下资源：

• 开发工具链: songloft-org/plugin-toolchain — @songloft/plugin-sdk + @songloft/plugin-builder + 脚手架
• 快速开始: pnpm create songloft-plugin <name>，详见 JS 插件开发指南

📖 API 文档

完整的 API 文档（Swagger/OpenAPI 格式）可在以下地址查看：

• Swagger API 文档: swagger.json
• Swagger UI 在线查看: petstore.swagger.io
• 本地查看: 启动服务后访问 http://localhost:58091/swagger/index.html

主要接口概览

接口组	路径	说明
认证	/api/v1/auth/*	登录、刷新 Token、登出、Token 管理
歌曲	/api/v1/songs/*	歌曲 CRUD、封面、播放、歌词
歌单	/api/v1/playlists/*	歌单 CRUD、歌单歌曲管理、导入导出
JS 插件	/api/v1/jsplugins/*	插件上传、启用、禁用、删除、检查更新
扫描	/api/v1/scan/*	音乐库扫描
配置	/api/v1/configs/*	系统配置管理（通用 KV）
设置	/api/v1/settings/*	业务功能设置（音乐目录、HLS 代理、HTTP 代理、自动扫描等）
缓存管理	/api/v1/cache-manage/*	缓存统计、清理、配置
升级	/api/v1/upgrade/*	版本检查、升级（仅 Docker）
版本	/api/v1/version	版本信息
健康检查	/api/v1/health	服务健康状态
资源代理	/api/v1/proxy	资源代理（解决 CORS 问题）
日志	/api/v1/logs/export	日志导出

❓ 常见问题

遇到问题？请查看 常见问题与解决方案 💬

🛠️ 技术支持

• GitHub: songloft-org/songloft
• Issues: 问题与反馈
• 💬 加入微信群交流：微信群二维码
• 💬 加入 Telegram 群交流：songloft_dev
• 📣 订阅 Telegram 频道：Songloft
• 🐧 QQ群: 220515636 (满了可以搜新群)

📝 更新日志

详细的版本更新记录请查看 CHANGELOG.md。

---

📄 许可证

本项目基于 Apache-2.0 License 开源。