Songloft完整使用指南：从扫描曲库到手机播放的6步快速上手

Songloft完整使用指南：从扫描曲库到手机播放的6步快速上手

【免费下载链接】songloft🎵 插件化、无广告的免费音乐服务器项目地址: https://gitcode.com/gh_mirrors/so/songloft

Songloft 是一款插件化、无广告的免费音乐服务器（开源自托管音乐服务器），用 Go 编写，无需 CGO 依赖，扫描本地曲库、自动提取封面和元数据，即可在手机、电脑、NAS、树莓派上随时随地播放自己的音乐。本文带你用 6 步从零搭起属于自己的音乐服务器。

🚀 第1步：部署并启动 Songloft 音乐服务器

Songloft 提供三种部署方式，新手推荐Docker 部署（NAS 用户尤其推荐）：

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' \ songloft/songloft:latest

三个关键点：

• 📁/path/to/music：指向你存放音乐的目录（Docker 内挂载为/app/music）
• 💾/path/to/data：存放数据库和缓存的目录
• 🔑 默认账号admin/admin仅适合本地测试，对外访问前务必设置强密码

Windows / macOS 用户可直接下载完整版二进制，创建music与data目录后运行songloft.exe即可，无需 Docker。

⚠️ 安全提醒：默认管理员账号admin / admin只能用于本地测试，多设备访问的部署请先通过ADMIN_PASSWORD环境变量设置强密码再启动。

🔐 第2步：登录 Web 界面并配置音乐目录

服务启动后，浏览器访问http://localhost:58091（远程设备则填服务器 IP），即可打开内置 Web 界面（完整版开箱即用，精简版需搭配 Flutter 客户端）。

用第 1 步设置的账号密码登录后，进入「设置 → 音乐库管理」配置音乐目录：

• Docker 部署：音乐目录填/app/music
• 二进制部署：填你的音乐文件夹绝对路径

同时在设置中可选择亮色 / 暗色主题，以及开启哪些功能菜单（歌曲库、歌单、智能音箱、插件等）。

🔍 第3步：一键扫描曲库，自动提取封面与元数据

在「音乐库管理」中点击扫描按钮，Songloft 会异步扫描音乐目录下的所有音频文件：

• 🎵 支持 MP3 / FLAC / WAV / APE / OGG / Opus / M4A / WMA / AIFF / MKA 等格式
• 🖼️ 自动提取封面、歌手、专辑、年份、流派等元数据
• 🎬 还能识别 MP4 / MKV / MOV 等视频文件并探测视频轨
• 📊 扫描进度实时可见，可随时取消

扫描支持「自动创建歌单」「歌单归并模式」「自动计算音频指纹」等选项，适合按艺术家 / 专辑整理曲库的用户。扫描逻辑实现于 internal/handlers/scan.go、扫描进度模型见 internal/services/scan_progress.go。

🎵 第4步：浏览歌曲库，管理你的歌单

扫描完成后，首页即展示「我的歌单」卡片墙；进入歌曲库可按「全部 / 本地 / 网络 / 电台」筛选、搜索歌曲，支持按封面、歌手、专辑浏览。

歌单功能很完整：

• ✅ 新建 / 收藏 / 置顶歌单，拖拽排序
• 📥 歌单导入导出（备份曲库结构很方便）
• 🔗 支持添加网络歌曲 URL 与电台流，播放时自动缓存到服务端
• 📖 播放历史自动记录

📱 第5步：手机连接服务器，开始播放

手机上有三种玩法：

① 浏览器直接访问（零安装） 手机浏览器打开http://服务器IP:58091，Web 界面自适应移动端，可直接播放。

② Flutter 客户端（体验最佳） 官方 Flutter 客户端支持 Android / iOS / macOS / Windows / Linux / Web 六端，登录页填入服务器地址即可连接，支持后台播放、本地缓存、锁屏 / 耳机媒体控制等 Web 端无法实现的能力。

③ Bundle 本地模式（无需服务器） 下载songloft-bundled-*客户端，首次启动点击「使用本地模式」→ 选择手机内的音乐目录 → 自动完成，手机直接播放本地音乐，随时可在设置中切换本地 / 远程模式。

播放界面为沉浸式全屏设计：大封面、进度条、播放控制一应俱全。

⚙️ 第6步：进阶配置，让音乐服务器更强大

基础流程跑通后，这些进阶能力可以让 Songloft 更顺手：

常用环境变量速查（完整说明见仓库根目录 README.md）：

ADMIN_USERNAME # 管理员用户名（默认 admin） ADMIN_PASSWORD # 管理员密码（默认 admin） LISTEN_PORT # 服务端口（默认 58091） DB_PATH # 数据库文件路径（默认 data/songloft.db） BASE_PATH # 反向代理子路径部署，如 /songloft MUSIC_DIR # 音乐目录（非空时覆盖数据库默认值）

💡 需要克隆源码自行编译时，仓库地址为https://gitcode.com/gh_mirrors/so/songloft，克隆后执行make build即可得到完整版二进制。

🎉 总结：6 步拥有自己的免费音乐服务器

Songloft 完全免费、无广告、永久开源，适合个人管理自己合法拥有的音乐。从docker run一条命令到手机上播放第一首歌，整个过程不超过 10 分钟——现在就可以开始搭建你的私有音乐服务器了 🎧

📖 更多界面截图与部署细节，可参考文档：docs/screenshots.md、常见问题 docs/faq.md

【免费下载链接】songloft🎵 插件化、无广告的免费音乐服务器项目地址: https://gitcode.com/gh_mirrors/so/songloft