hnxgf/music-player repository overview

⁠音乐播放器 · Web Music Player

一个零依赖的网页音乐播放器，单容器部署，不需要数据库、不需要 npm install。

主要能力

• 歌单三级可见性：公开 / 链接分享（带令牌）/ 私有
• 网页版内置 App 下载页：顶栏「App 下载」→ 列出 Android 客户端的安装包（含体积与 SHA-256）与安装说明。镜像里预置了默认下载地址（arm64 / 32 位，固定用 音乐播放器-latest-<arch>.apk 这种文件名），所以拉下来打开 /app 就能直接下载，换客户端版本也不用改地址；版本号与校验值跟着客户端编译自动更新。也可以在「管理后台 → App 下载」里改成自己的地址（改过就以你的配置为准），或把 apk 放进挂载的 downloads/ 目录
• 播放与歌词更抗网络抖动：请求带超时与自动重试；取流失败会自愈重试并给「重试播放」；歌词本地优先（毫秒级），不再因为联网匹配卡住而显示不出来
• 不再乱配歌词：修掉了「短词命中长句」导致的错配（如候选标题「存在」被误认成查询串本身）
• LRC 歌词自动匹配：网易云 / LRCLIB / 酷我三源检索，本地已有就复用，不重复下载
• 版本限定符识别：「边走边爱」和「边走边爱(国)」按两首歌处理，各配各的歌词，不会混用
• 专辑封面自动匹配：网易云 / iTunes / MusicBrainz 三源检索，按「歌手 + 专辑」归档，同一张专辑只存一张图
• 热榜与官方歌单：搜索面板可切「热榜」（五平台 12 榜单）与「官方歌单」（网易云 / 酷我 / QQ 歌单广场），数据全部实时获取透传、不落库，点歌直接播放（歌曲 / 歌词 / 封面均不保存到服务器）
• 在线封面全平台补齐（服务端图片代理）：各平台 CDN 的封面带 Referer 防盗链，直接加载多半 403。现在所有在线封面统一经 /api/img 代理下发（服务端带正确 Referer 取图并缓存 6 小时，带 SSRF 防护）；酷我 / 酷狗搜索逐条补封面、咪咕相对路径补域名、QQ 搜索软限流自动重试——热榜 / 官方歌单 / 五平台搜索的专辑封面不再一片空白
• 封面库 / 歌手头像管理：后台「封面库」弹窗可一键清除未使用的封面（只删没有歌曲引用的文件，正在使用的绝不动）；「歌手头像」面板集中管理 App 曲库歌手列表的头像——获取、换一张、删除、清理不再使用的头像
• 当前歌词居中高亮（KTV 式），支持点击跳转、拖动进度
• 播放记录续播：关掉浏览器再打开，自动回到上次那首歌与进度，接着听
• 在线搜索与下载：搜索本地 + 在线音乐（落雪音源），试听 / 下载按最好音质逐级尝试，下载自动进「默认」歌单，下载后播放器自动刷新（扩展名按实际内容识别）
• 播放中切换歌单不打断播放状态，按钮图标始终与实际状态一致
• 车机 / 蓝牙对接（默认生效）：播放时自动把歌曲信息、当前歌词与下一句歌词、播放模式推送到车机屏；车机可拖动进度、切上下曲；歌词放哪一行、是否屏幕常亮等全部在后台设置
• 后台界面改版：设置类页面用卡片网格（宽屏 2~3 栏、窄屏自动堆叠），设置项「标签左 · 控件右」，车机按键支持情况有对照表
• 播放模式默认不推送：行宽留给歌词，需要时后台一键打开
• 歌词两句同屏：当前歌词与下一句歌词可分占车机屏的两行，车机屏幕能同时看到两句（无多余前缀）
• 车机三行可自定义：第 1/2/3 行分别放歌名 / 歌手 / 专辑的任意组合；歌名行还能带「3/12」列表位置
• 播放顺滑优化：当前曲主动预载、下一首提前预热、512KB 流式读块 + 长缓存，真的等数据时显示「缓冲中」
• 搜索权限可控：后台可分别开放「游客试听」「游客下载」，默认仅管理员
• 上传音频时按文件名 歌手 - 歌名.mp3 自动识别歌名与歌手，支持批量上传
• 19 种音频格式，深浅主题，从 4K 到手机全分辨率自适应

⁠支持的平台

拉取时会自动选择匹配的架构，不用手动指定。

⁠快速开始

⁠方式一：一条命令（推荐）

# 1. 建两个目录存数据（路径随意，这里用当前目录下的 music-player）
mkdir -p music-player/data music-player/uploads

# 2. 启动
docker run -d \
  --name music-player \
  --restart unless-stopped \
  -p 5177:5177 \
  -e HOST=0.0.0.0 \
  -e TZ=Asia/Shanghai \
  -e MAX_UPLOAD_MB=512 \
  -e SEED_DEMO=0 \
  -v "$(pwd)/music-player/data:/data" \
  -v "$(pwd)/music-player/uploads:/uploads" \
  hnxgf/music-player:latest

然后：

• 播放器 → http://你的服务器IP:5177/
• 后台管理 → http://你的服务器IP:5177/admin.html
• 默认账号 → admin / admin123（⚠️ 登录后请立刻到「账号安全」改掉）

⁠方式二：docker compose

# compose.yaml
services:
  music-player:
    image: hnxgf/music-player:latest
    container_name: music-player
    restart: unless-stopped
    ports:
      - "5177:5177"
    environment:
      HOST: 0.0.0.0
      TZ: Asia/Shanghai
      MAX_UPLOAD_MB: "512"
      SEED_DEMO: "0"
      # 前面有反向代理时打开，登录限流才会按真实客户端 IP 计数
      # TRUST_PROXY: "1"
    volumes:
      - ./data:/data
      - ./uploads:/uploads
    # NAS 上报 EACCES 时打开这行，改成你实际的 uid:gid（用 id 用户名 查）
    # user: "1026:100"

docker compose up -d
docker compose logs -f      # 看到「🎵 音乐播放器 v1.0.0 已启动」即成功

⁠方式三：NAS 图形界面（群晖 / 威联通）

群晖 DSM（Container Manager）

1. 套件中心安装 Container Manager
2. 注册表 → 搜索 hnxgf/music-player → 下载 latest
3. 映像 → 选中刚下载的 → 运行：
   • 勾选「启用自动重新启动」
   • 端口设置：本地 5177 → 容器 5177
   • 存储空间：加两个文件夹
     • <共享文件夹>/docker/music-player/data → 挂载路径 /data
     • <共享文件夹>/docker/music-player/uploads → 挂载路径 /uploads
   • 环境：TZ=Asia/Shanghai、MAX_UPLOAD_MB=512、SEED_DEMO=0
4. 访问 http://群晖IP:5177/

威联通 QNAP（Container Station）

1. App Center 安装 Container Station
2. 映像 → 提取，输入 hnxgf/music-player:latest
3. 容器 → 创建：端口 5177，绑定装载两个目录到 /data 与 /uploads，环境变量同上

unRAID：Docker → Add Container，Repository 填 hnxgf/music-player:latest，加两个 Path（/data、/uploads）和一个 Port（5177）。

⁠环境变量

健康检查接口 GET /api/health，返回 {"ok":true,"version":"1.0.0",...}，可直接用于监控探活（镜像已内置 HEALTHCHECK）。

⁠数据、备份与升级

只需要备份两个目录，复制走就是完整备份：

升级

docker pull hnxgf/music-player:latest
docker compose up -d          # 或 docker stop music-player && docker rm music-player && 重新 run

升级不会动 /data 和 /uploads，歌单和音频都还在。生产环境建议把 :latest 固定成具体版本号（如 :1.0.0），避免哪天升级出意外。

⁠反向代理（可选）

想用域名 + HTTPS 访问，在前面挂一层 Nginx：

server {
    listen 443 ssl;
    server_name music.example.com;

    # 上传大文件必须放开，否则会 413
    client_max_body_size 512m;

    location / {
        proxy_pass http://127.0.0.1:5177;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # 音频拖动进度条依赖 Range，必须透传
        proxy_set_header Range $http_range;
        proxy_set_header If-Range $http_if_range;
        proxy_buffering off;
    }
}

配完记得给容器加 TRUST_PROXY=1。

⁠常见问题

Q：启动后访问不了？ 看日志 docker compose logs -f；确认端口映射了；确认 HOST=0.0.0.0。

Q：报 EACCES: permission denied？ 容器里的进程是 uid 1000。二选一：

# 把目录交给容器用户
sudo chown -R 1000:1000 /path/to/data /path/to/uploads

# 或者让容器用你的身份跑（推荐，文件属主更好管理）
# 在 docker run 里加 --user 1026:100 （群晖 admin 常见）
#                      --user 1000:1000（威联通常见）

Q：上传大文件报 413？ 反代的 client_max_body_size 没放开，同时确认 MAX_UPLOAD_MB 够大。

Q：歌词 / 封面匹配不到？ 歌曲的歌名、歌手要和主流音乐库一致。冷门曲目可能各源都没有。容器需要能访问外网（网易云 / LRCLIB / 酷我 / iTunes / MusicBrainz）；纯内网环境不影响已有数据，只是匹配功能不可用。后台可以点「匹配歌词」「找封面」查看候选手动挑。

Q：APE / WMA 放不出来？ 浏览器内核本身不支持（WebM/MP3/FLAC/WAV/AAC/OGG 才能直放）。上传时界面会明确提示，转成 MP3 或 FLAC 即可。

Q：忘记后台密码？ 删掉 /data/db.json 后重启会重建数据库，但歌单也会一起丢。更好的做法是改密码前先备份 db.json。

Q：磁盘占用越来越大？ 后台「歌词库」按钮 → 看「未使用文件」→ 一键清理（只删没有任何歌曲引用的音频；歌词属于共享库，不会被删）。 后台「封面库」弹窗 → 一键清除未使用的封面（只删没有歌曲引用的封面）；「歌手头像」面板可清理歌手已不在歌单里的头像。

⁠资源占用

• 内存：空载约 40–60 MB；播放不占服务端内存（音频是流式转发）
• CPU：几乎为零
• 镜像：约 165 MB
• 并发：单进程足够家庭与小型团队（几十人同时听）；音频走 HTTP Range 流式传输

⁠安全提示

• 一定要改掉默认密码 admin123
• 用 HTTPS，只放行 80/443，不要把 5177 直接暴露到公网
• 反代后设置 TRUST_PROXY=1
• 定期备份 /data
• 分享链接泄露后，后台点「重置链接」立即失效

内置的安全措施：安全响应头（CSP / nosniff / frame-options）、上传后缀白名单、路径穿越防护、防 SSRF、登录失败限流、上传中断垃圾清理、数据原子落盘（先写临时文件再改名）。