Songloft 常见问题解答 (FAQ)

关于项目

Q: Songloft 收费吗？可以赞助 / 捐款吗？

A: 不收费，也不接受任何赞助或捐款。 Songloft 是纯粹出于兴趣与热爱开发的开源项目（为爱发电），永久免费：

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

安装与部署

Q: 我应该如何下载 Songloft？

A:

• 后端服务器：从 GitHub Releases 下载适合您系统的版本，支持 Linux、macOS 和 Windows 平台，提供二进制文件和 Docker 镜像两种部署方式。
• Flutter 客户端：从 Flutter 客户端 Releases 下载预编译安装包，支持 Android、iOS、macOS、Windows、Linux 和 Web。

Q: 支持哪些操作系统和架构？

A:

后端服务器：

• Linux: x86_64、ARM64、ARMv7
• macOS: x86_64 (Intel)、ARM64 (Apple Silicon)
• Windows: x86_64、ARM64

Flutter 客户端：

• Android、iOS、macOS、Windows、Linux、Web（6 个平台）

Q: ARMv7 / Armbian 上 Docker 启动报 futexwakeup ... returned -1、SIGSEGV 怎么办？

A: 旧版 Armbian / Debian 等 ARMv7（32 位）宿主机的 libseccomp 可能无法识别 futex_time64 等系统调用，导致容器在默认 seccomp 配置下启动崩溃，甚至执行 -version 也失败。遇到这些日志时，可按以下步骤排查，不能仅凭 SIGSEGV 就认定是这个原因。

1. 查看宿主机环境（以下命令在宿主机执行）：

uname -m
docker version
runc --version

重点查看 runc --version 输出中的 libseccomp 版本。Debian / Ubuntu 系统还可以执行 dpkg-query -W libseccomp2 和 apt-cache policy libseccomp2，查看已安装版本及软件源中的可用版本。

2. 对照测试默认 seccomp 与临时关闭 seccomp：

假设现有容器名为 songloft（其他名称请替换）。以下命令直接使用该容器的镜像 ID，无需下载镜像，也不挂载音乐或数据目录；每行是一条独立命令。

songloft_image_id=$(docker inspect --format '{{.Image}}' songloft)
docker run --rm --entrypoint /app/songloft "$songloft_image_id" -version
docker run --rm --security-opt seccomp=unconfined --entrypoint /app/songloft "$songloft_image_id" -version

如果默认配置下崩溃、临时关闭 seccomp 后正常输出版本，说明启动失败与 seccomp 限制有关，接下来检查宿主机 libseccomp、Docker / runc 及自定义 seccomp 规则。seccomp=unconfined 会关闭系统调用过滤，仅用于临时定位，不建议作为长期运行配置。

3. 升级宿主机组件后，在默认 seccomp 下重新验证：

优先通过当前发行版支持的软件源升级 libseccomp；旧版 Docker / runc 或自定义规则也可能需要更新。升级的是宿主机组件，仅更新 Songloft 镜像不能解决宿主机 libseccomp 过旧的问题。

Issue #507 中，Debian 10（buster）ARMv7 宿主机使用 Docker 24.0.5、runc 1.1.8、libseccomp 2.3.3。其软件源已有 libseccomp2 2.5.1-1~bpo10+1 的 buster-backports 包，在宿主机以 root（或加 sudo）执行以下命令后恢复正常：

apt-get install libseccomp2/buster-backports

这条安装命令仅适用于已配置相应软件源且该包可用的 Debian 10 环境，不要照搬到其他发行版。2.5.1 是该案例验证成功的版本，不代表所有环境的最低版本要求。

升级后，先确认 runc --version 中的 libseccomp 版本也已更新，再执行上面默认 seccomp 下的 -version 命令。正常输出版本后，重启原有容器并检查启动日志（重启会短暂中断服务）：

docker restart songloft
docker logs --tail 50 songloft

该用户升级 libseccomp 到 2.5.1 后，同一个 Songloft v2.13.1 镜像在默认 seccomp 下通过版本检查，完整服务也成功启动，见成功反馈。

Q: Docker 部署时容器无法访问音乐文件怎么办？

A: 确保使用绝对路径挂载卷：

docker run -d \
  -v /absolute/path/to/music:/app/music \
  -v /absolute/path/to/data:/app/data \
  songloft/songloft:latest

Q: Docker 部署时定时任务时间不对（时区错误）怎么办？

A: 需要设置 TZ 环境变量指定时区：

docker run -d \
  -e TZ=Asia/Shanghai \
  -v /absolute/path/to/music:/app/music \
  -v /absolute/path/to/data:/app/data \
  songloft/songloft:latest

Docker Compose 中同样添加：

environment:
  - TZ=Asia/Shanghai

Q: 如何通过反向代理子路径部署（Sub Path）？

A: Songloft 支持通过 -base-path 参数或 BASE_PATH 环境变量配置子路径，适用于 Nginx 反向代理多服务合并到同一端口的场景。

启动配置：

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

# 或环境变量
BASE_PATH=/songloft ./songloft

# Docker
docker run -d -e BASE_PATH=/songloft ...

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;
}

配置后通过 http://your-domain/songloft/ 即可访问。Flutter 嵌入模式会自动从 <base href> 检测子路径。

Q: 完整版和精简版有什么区别？

A:

• 完整版（默认）：将 Flutter Web 前端嵌入到 Go 二进制中，访问后端地址即可直接使用 Web 界面
• 精简版（-tags lite）：不包含前端，仅提供 API 服务，需要单独部署前端或使用客户端

配置与运行

Q: 如何配置多个音乐目录？

A: Songloft 只支持设置一个音乐根目录，但扫描器完整支持软链接（符号链接），可以通过在根目录下创建软链接来聚合多个目录。

Linux / macOS：

# 假设音乐根目录为 /app/music（Docker 默认）或 ~/music
# 将其他目录通过软链接挂入根目录

ln -s /mnt/nas/music /app/music/nas-music
ln -s /home/user/downloads/music /app/music/downloads

扫描时会自动跟随软链接递归扫描，并检测循环链接防止死循环。

Docker 部署：直接挂载多个卷到音乐根目录的子目录即可，无需软链接：

services:
  songloft:
    image: songloft/songloft:latest
    volumes:
      - /path/to/data:/app/data
      - /mnt/nas/music:/app/music/nas-music
      - /home/user/local-music:/app/music/local-music

Windows：使用 mklink /D 创建目录链接：

mklink /D C:\music\nas-music \\NAS\music

注意：排除目录（exclude_dirs）对所有子目录生效，包括通过软链接引入的目录。

Q: 如何修改服务端口？

A: 有两种方式：

1. 使用命令行参数：./songloft -port 8080
2. 使用环境变量：LISTEN_PORT=8080 ./songloft

默认端口为 58091。命令行参数优先级高于环境变量。

Q: 如何修改默认密码？

A: 默认账号密码为 admin / admin，建议修改。根据部署方式选择对应方法。

提示：Docker 用户推荐通过环境变量 ADMIN_PASSWORD 设置密码，避免使用命令行参数方式（容易因旧进程未停止而不生效）。

Docker 启动：通过环境变量 ADMIN_PASSWORD 设置：

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

Docker Compose 启动：修改 docker-compose.yml 中的 ADMIN_PASSWORD：

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_secure_password
      - LISTEN_PORT=58091

命令行启动：使用 -password 参数：

./songloft -password your_secure_password

Windows 平台：新建 songloft.bat 文件放到 songloft.exe 同目录，写入：

songloft.exe -password your_secure_password

然后双击 songloft.bat 启动（注意不是双击 songloft.exe）。

Q: 支持哪些音乐文件格式？

A: 支持主流音频格式：MP3、FLAC、WAV、APE、OGG、M4A、MP4、MOV、WMA、AIF/AIFF、DSF（DSD） 等（MP4/MOV 为 ISO-BMFF/QuickTime 容器，按 M4A 同族处理）。

DSF 默认可扫描入库，支持读取内嵌标签和封面。已有部署升级后会自动将 dsf 补入扫描格式列表，重新扫描即可发现文件。原生客户端沿用 libmpv 播放；浏览器或不支持 DSD 的 DLNA 设备需显式请求服务端 ffmpeg 转码，例如 GET /api/v1/songs/{id}/play?format=mp3（也可用 format=flac，以设备兼容性为准）。当前 Web 客户端不会为 DSF 自动添加转码参数。DSF 暂不支持将标签、歌词或封面写回音频文件。

此外也支持扫描常见视频容器：MKV、WEBM、AVI、TS（连同带画面的 MP4/MOV）。扫描时后端会用 ffprobe 探测文件是否含真实视频轨并标记 is_video（内嵌封面图不算视频）。这类文件常见于电子书、网课等以"听"为主的音视频混合内容：

• 始终可播放其中的音频轨；
• 含画面的文件可投屏到 DLNA 电视/盒子观看画面（投屏时按真实容器类型声明 mime）；
• 也可在应用内直接显示视频画面：全平台（桌面 Windows/Linux、macOS、Android/iOS、Web）默认支持，视频不可用时回退为封面。

可通过数据库配置 scan_config 自定义支持的格式列表。

Q: 如何查看当前版本？

A:

• 命令行：./songloft -help（会打印版本信息）
• API: curl http://localhost:58091/api/v1/version

使用问题

Q: 音乐文件无法播放怎么办？

A: 检查以下几点：

1. 确认音乐文件格式是否受支持
2. 确保音乐文件路径配置正确
3. 检查文件权限是否允许读取
4. 可选安装 ffprobe 以获取更完整的音频技术参数
5. 网络歌曲检查 URL 是否可访问

Q: 电台（HLS 流）无法播放怎么办？

A: 部分电台源站有 Referer / User-Agent 防盗链，或在 Web 嵌入模式下受 CORS 限制，导致客户端直接拉流失败。可在客户端 设置 → HLS 代理 中打开该开关：

• 开启后，服务端会代拉并改写 .m3u8、代理所有切片 / key / init 段，规避源站防盗链与浏览器跨域限制。
• 代价：所有切片走服务器带宽，请留意流量成本；不需要时可关闭（默认关闭，此时电台 .m3u8 直接由客户端拉取源站）。

Q: 如何扫描音乐库？

A: 添加或修改音乐文件后，必须手动触发扫描才能在歌曲库中看到。在客户端的 设置 → 扫描管理 中点击扫描按钮（注意该按钮是长条形的，不是提示框）。扫描是异步执行的，可以通过进度接口查看状态，也可以取消正在进行的扫描。

Q: Flutter 客户端如何连接后端？

A:

• 嵌入模式（Web）：Flutter Web 嵌入 Go 后端，自动使用同域地址，无需配置
• 独立部署模式：在登录页面输入后端服务器地址（如 http://192.168.1.100:58091），地址会自动保存

Q: 在 Firefox 下 Web 端小控件点不到、点击位置偏移怎么办？

A: 这是 Flutter Web（CanvasKit 渲染引擎）在 Firefox 系浏览器下已知的点击命中测试（hit-test）坐标偏移问题（参见 flutter/flutter#182764、flutter/flutter#117531），属于渲染引擎/浏览器层行为，非 Songloft 分辨率适配问题。典型现象：设置大项能切换、细项小控件点不到；JS 插件页面（原生 HTML）不受影响。

解决与规避：

• 优先使用 Chromium 系浏览器（Chrome / Edge / Chromium）访问 Web 端，可完全规避。
• 若必须用 Firefox，可尝试调整页面缩放比例（Ctrl + + / -）到能命中小控件的比例——偏移量随缩放变化，某些比例下坐标恰好对齐。

Q: 如何安装和使用插件？

A:

1. 在设置页面的 插件管理 中上传 .jsplugin.zip 格式的插件文件
2. 上传后插件自动解析 plugin.json、校验权限
3. 点击 启用 按钮激活插件（双层 SHA256 校验通过后注册子路由）
4. 启用的插件会在首页显示入口

Q: macOS 上 Token 存储报错怎么办？

A: Flutter 的 secure_storage 在 macOS 未签名沙盒环境下可能无法使用 Keychain。Songloft 已内置降级机制，会自动回退到 SharedPreferences 存储，不影响正常使用。

Q: 如何添加网络歌曲或网络电台？

A: 在客户端 电台收藏 歌单中点击添加按钮，输入电台流媒体地址（如 .m3u、.pls 或直接的音频流 URL）。网络歌曲可通过 JS 插件搜索添加到歌单中。目前不支持扫描本地 .m3u 文件自动导入电台。

Q: TV 端如何使用？

A: TV 端推荐使用专门的 songloft-tv 客户端，专为 Android TV 设计，支持遥控器操作。

升级与维护

Q: 如何升级或更新 Songloft？

A:

• 二进制部署：下载最新版本替换旧文件，重启服务
• Docker 部署：可通过设置页面的 升级管理 在线检查和执行升级
• Flutter 客户端：设置页面会提示前端新版本，可跳转到 GitHub Releases 下载

数据库会自动迁移，无需手动操作。如果升级后出现异常，可尝试删除 data/songloft.db 后重启（会丢失用户数据）。

Q: 如何验证下载文件的完整性？

A: 每个 Release 都包含 checksums.txt 文件：

wget https://github.com/songloft-org/songloft/releases/latest/download/checksums.txt
sha256sum -c checksums.txt

API 使用

Q: 如何通过 API 获取访问令牌？

A:

curl -X POST http://localhost:58091/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your_password"}'

响应中包含 access_token 和 refresh_token。Access Token 用于日常 API 访问，Refresh Token 用于刷新过期的 Access Token。

Q: 如何在 API 请求中使用 Token？

A: 在请求头中添加 Authorization：

curl -X GET http://localhost:58091/api/v1/songs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

音乐文件、封面、歌词均通过歌曲 ID 端点访问，并以 access_token query 参数认证：

http://localhost:58091/api/v1/songs/{song_id}/play?access_token=YOUR_TOKEN
http://localhost:58091/api/v1/songs/{song_id}/cover?access_token=YOUR_TOKEN
http://localhost:58091/api/v1/songs/{song_id}/lyric?access_token=YOUR_TOKEN

旧版 /music/* 和 /cover/* Base62 编码路径已下线。

Q: 如何查看 API 文档？

A: 使用开发模式启动（make run），访问 http://localhost:58091/swagger/index.html 查看交互式 Swagger 文档。生产环境不包含 Swagger。

系统要求

Q: 必须安装 ffprobe 吗？

A: 不是必须的。Songloft 使用纯 Go 库（hanxi/tag）提取音频元数据和封面，无需任何外部依赖。安装 ffprobe 后可以获取更精确的音频技术参数（时长、比特率、采样率）。Docker 镜像中已包含 ffprobe。

Q: 开发环境需要什么？

A:

• 后端开发：Go 1.26+
• 前端开发：Flutter 3.29+ / Dart 3.7+
• Android 构建：需要先接受 SDK 许可证 sdkmanager --licenses

---

Q: 本地 .lrc 歌词文件不显示 / 改了 .lrc 不生效怎么办？

A:

• 确认 .lrc 文件名与音频文件名一致（如 song.mp3 对应 song.lrc），大小写扩展名（.LRC/.Lrc）和 song.mp3.lrc 形式均已支持。
• 后放的 .lrc 文件在下次扫描时自动生效（不需要勾选「重新导入」）。
• 如需立刻生效，在播放页点「重新抓取歌词」（客户端会先清本地缓存再带 refresh 请求）。
• 若曾手动调整过时间轴（manual 歌词），旁挂 .lrc 不会覆盖手调版本——这是设计行为。
• 空文件（0 字节）的 .lrc 不会被识别为有效歌词。

---

获取帮助

• GitHub Issues: https://github.com/songloft-org/songloft/issues
• 项目主页: https://github.com/songloft-org/songloft
• Flutter 客户端: https://github.com/songloft-org/songloft-player