spf20081/melodyhub repository overview
🌟 项目亮点
🎨 极致美学
|
⚡ 卓越性能
|
✨ 功能特性
🎧 沉浸式音乐体验
🎵 多平台音源支持
- 网易云音乐 - 完整支持扫码/手机登录、每日推荐、私人 FM
- QQ 音乐 - 海量曲库、高品质音源
- LX 音源解析 - 支持酷我、酷狗等多平台音源
- 自定义脚本 - 上传自己的音源解析脚本
🎨 智能元数据增强
告别乱码和封面缺失！MelodyHub 独创多源元数据聚合引擎：
- 三源合一 - 同时从 iTunes、网易云、QQ 音乐聚合数据
- 超清封面 - 优先匹配 iTunes 3000x3000px 超高清专辑封面
- 详尽标签 - 自动写入流派、发行年份、光盘号、作曲家等
- 智能匹配 - 即使第三方源下载的歌曲也能自动匹配元数据
⬇️ 专业下载管理
- 多格式支持 - MP3 (320k) / FLAC (无损) / M4A (Hi-Res)
- 自动同步 - "我喜欢的音乐"自动同步下载到服务器
- 完美标签 - 下载后的文件已内嵌完美标签和封面
- 批量下载 - 支持专辑、歌单批量下载
🎼 高级播放功能
- 无损音质 - 支持 Hi-Res / FLAC 无损播放
- 逐字歌词 - 支持逐字歌词、翻译歌词、罗马音
- 私人 FM - 智能推荐，发现新音乐
- 音质标签 - 直观显示音质等级（标准/高品质/无损）
🚀 快速开始
方式一：Docker 一键部署（推荐）
docker run -d \
--name melodyhub \
-p 80:80 \
-v ./downloads:/app/downloads \
-v ./data:/app/data \
-v ./music-api-scripts:/app/music-api/uploads/scripts \
-e DOWNLOAD_API_PASSWORD=your_secure_password \
--restart unless-stopped \
spf20081/melodyhub:latest
方式二:Docker Compose
创建 docker-compose.yml:
version: '3.8'
services:
melodyhub:
image: spf20081/melodyhub:latest
container_name: MelodyHub
ports:
- "80:80"
volumes:
- ./downloads:/app/downloads
- ./data:/app/data
- ./music-api-scripts:/app/music-api/uploads/scripts
environment:
- DOWNLOAD_API_PASSWORD=your_secure_password
restart: unless-stopped
启动服务:
docker-compose up -d
方式三:本地开发
# 克隆项目
git clone https://github.com/spfnas/MelodyHub.git
cd MelodyHub
# 安装依赖
npm install
# 启动开发服务器
npm run serve
# 构建生产版本
npm run build
📁 目录结构
MelodyHub/
├── 📂 downloads/ # 下载的音乐文件
├── 📂 data/ # 用户数据和配置
├── 📂 music-api-scripts/ # 自定义音源脚本
├── 📂 src/ # 前端源代码
│ ├── 📂 components/ # Vue 组件
│ ├── 📂 views/ # 页面视图
│ ├── 📂 utils/ # 工具函数
│ └── 📂 assets/ # 静态资源
├── 📂 music-api/ # LX 音源解析 API
│ ├── 📂 src/
│ │ ├── 📂 routes/ # API 路由
│ │ └── 📂 utils/ # 工具函数
│ └── 📂 uploads/scripts/ # 上传的脚本
└── 📂 server/ # 下载服务器
🔧 API 文档
🎼 LX 音源解析 API
📋 获取支持的音源
GET /music-api/api/music/sources
响应示例:
{
"code": 200,
"data": {
"sources": ["kw", "kg", "mg"],
"scripts": ["custom_script_1", "custom_script_2"]
}
}
🔍 搜索音乐
GET /music-api/api/music/search
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| keyword | string | ✅ | 搜索关键词 |
| source | string | ✅ | 音源 (kw/kg/mg) |
| page | number | ❌ | 页码 (默认 1) |
| limit | number | ❌ | 每页数量 (默认 30) |
响应示例:
{
"code": 200,
"data": {
"list": [
{
"name": "歌曲名",
"singer": "歌手",
"songmid": "歌曲ID",
"albumName": "专辑名"
}
],
"total": 100
}
}
🎵 获取播放 URL
GET /music-api/api/music/url/{source}/{songmid}?quality={quality}
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| source | string | ✅ | 音源标识 |
| songmid | string | ✅ | 歌曲 ID |
| quality | string | ❌ | 音质 (128k/320k/flac) |
📤 上传音源脚本
POST /music-api/api/scripts/upload
Content-Type: multipart/form-data
参数:
script: 脚本文件 (.js)id: 脚本 ID (可选)
📜 获取脚本列表
GET /music-api/api/scripts/list
🗑️ 删除脚本
DELETE /music-api/api/scripts/{id}
⚙️ 配置说明
🔐 环境变量
| 变量名 | 默认值 | 说明 |
|---|---|---|
DOWNLOAD_API_PASSWORD | - | 下载 API 访问密码 （强烈建议设置） |
DOWNLOAD_DIR | /app/downloads | 音乐文件存储路径 |
DATA_DIR | /app/data | 用户数据存储路径 |
PORT | 80 | 服务监听端口 |
📊 存储卷说明
| 卷路径 | 说明 | 建议 |
|---|---|---|
/app/downloads | 下载的音乐文件 | 映射到大容量存储 |
/app/data | 用户数据和配置 | 定期备份 |
/app/music-api/uploads/scripts | 自定义脚本 | 可选映射 |
🎯 使用指南
1️⃣ 登录网易云音乐
- 点击右上角头像
- 选择"登录"
- 使用手机扫码或账号密码登录
2️⃣ 启用 Music API
- 进入"设置" → "音源设置"
- 启用"Music API"
- 配置 API 地址 (默认:
/music-api)
3️⃣ 上传自定义脚本
- 进入"设置" → "音源设置" → "脚本管理"
- 点击"上传脚本"
- 选择
.js脚本文件 - 脚本自动加载并显示支持的音源
4️⃣ 下载音乐
- 在歌曲列表中点击下载图标
- 选择音质 (MP3/FLAC/M4A)
- 文件自动下载到
downloads目录 - 已自动嵌入完美标签和封面
📝 更新日志
🎉 v1.2.1 (2026-01-28) - UI 美化与性能优化
✨ 新增
- 播放器音质标签渐变效果
- 搜索框 focus 动画和阴影
- 搜索历史 hover 平移动画
- 音源标签优化显示
🎨 优化
- 暗色模式配色调整
- 用户卡片高度减少 20%
- 搜索历史下拉框样式
- Modal 和 ContextMenu 视觉效果
⚡ 性能
- 移除所有 backdrop-filter
- 优化歌词滚动性能 (50ms → 100ms)
- 移除 enableScrolling 调用
- 代码格式化和清理
🔧 修复
- 脚本上传文件名保留
- 删除按钮样式优化
🚀 v1.2.0 (2026-01-25) - 元数据革命
✨ 新增
- 集成 iTunes Search API
- 支持 3000px 超高清封面
- 专业标签写入 (流派、年份、光盘号等)
- 智能元数据匹配算法
🎵 v1.1.0 (2026-01-08) - 下载管理
✨ 新增
- 内置下载管理器
- 批量下载功能
- 收藏歌曲自动同步
🛠️ 开发指南
技术栈
- 前端: Vue.js 2.x + Vue Router + Vuex
- UI: SCSS + 自定义组件库
- 后端: Node.js + Express
- API: NeteaseCloudMusicApi + 自研 LX 解析
- 部署: Docker + Nginx
构建命令
# 开发环境
npm run serve
# 生产构建
npm run build
# 代码格式化
npm run prettier
# Lint 检查
npm run lint
# Docker 构建
docker build -t melodyhub:custom .
贡献流程
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
🤝 贡献指南
我们欢迎所有形式的贡献！无论是:
- 🐛 报告 Bug
- 💡 提出新功能建议
- 📝 改进文档
- 🔧 提交代码修复
- 🎨 优化 UI/UX
请查看 贡献指南 了解更多信息。
💖 致谢
特别感谢以下开源项目:
- qier222/YesPlayMusic - 优秀的前端项目
- Binaryify/NeteaseCloudMusicApi - 网易云 API
- LX Music - LX 音源解析方案
- Vue.js - 渐进式 JavaScript 框架
📊 项目统计
⚠️ 免责声明
重要提示
本项目仅供个人学习研究使用，请勿用于商业用途。
请尊重音乐版权，支持正版音乐。本项目不提供任何音乐资源，所有音乐来源于第三方平台。
📄 许可证
本项目基于 MIT License 开源。
MIT License
Copyright (c) 2026 MelodyHub Team
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
Tag summary
Content type
Image
Digest
sha256:71272b002…
Size
102.6 MB
Last updated
8 months ago
docker pull spf20081/melodyhub