Jocay
21945cc54f
由 163-music-dl CLI 重构为 Web 服务： - 下载流水线、歌词与标签逻辑沿用旧版（node-id3 / ffmpeg） - 网易云（chksz 接口 + music.163.com 元数据）与 QQ 音乐（VIP Cookie）provider - QQ 扫码登录与 musickey 自动续期 - SQLite 持久化的下载队列，SSE 实时进度 - 曲库工具（M3U / ZIP / 回收站 / 补全标签）、历史统计与导出、访问密码 - Vite 8 + Vue 3 前端，浅色 / 深色 - Docker 部署配置（飞牛 NAS） Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
76 lines
4.2 KiB
Markdown
76 lines
4.2 KiB
Markdown
# 声匣 · Sound Case
|
||
|
||
自托管的音乐下载 Web 服务：搜索、试听、批量下载网易云音乐与 QQ 音乐（VIP Cookie），自动写入歌词、封面与完整标签，按「歌手 / 专辑 / 序号. 歌名」归档，可直接被 Navidrome 等播放器识别。
|
||
|
||
> 由 `163-music-dl` CLI 重构而来，不再保留命令行模式。仅供个人对已购买 / 已订阅内容的备份使用。
|
||
|
||
## 功能
|
||
|
||
- **搜索**：网易云 / QQ 音乐切换；粘贴任意分享链接（歌曲、专辑、歌单、歌手，含 QQ 短链）直接跳转
|
||
- **详情页**：专辑、歌单（可筛选）、歌手（热门歌曲 + 专辑墙）；多选 / Shift 区间选 / 只选未下载
|
||
- **下载队列**：并发、全局暂停、单曲暂停 / 继续 / 取消 / 重试，SSE 实时进度；重启后自动恢复
|
||
- **音质**：标准 / 极高 / 无损 / Hi-Res / 超清母带 / 空间音频 / 高清臻品；不可用时自动降级
|
||
- QQ 音乐支持到 Hi-Res（RS01）；母带 / 全景声为加密格式，暂不支持
|
||
- **试听**：服务端代理 320K 音源，底部播放条带滚动歌词；曲库与队列中的本地文件也可直接播放
|
||
- **曲库**：浏览音乐目录（封面墙）、生成 M3U、打包 ZIP、移入回收站、批量补全标签与歌词
|
||
- **历史**：统计（累计、占用、近 30 天、来源与音质分布）、搜索筛选、导出 CSV / JSON
|
||
- **设置**：QQ 账号（导入 Cookie、VIP 状态校验）、下载默认值、并发与间隔、访问密码、浅色 / 深色
|
||
|
||
## 本机运行
|
||
|
||
需要 Node.js ≥ 22.18（服务端直接以 TypeScript 运行，无需编译）。FLAC 写标签需要 ffmpeg（Windows：`winget install Gyan.FFmpeg`）。
|
||
|
||
```bash
|
||
npm install
|
||
npm run build # 打包前端到 dist/web
|
||
npm start # http://localhost:8066
|
||
```
|
||
|
||
开发模式：`npm run dev`（后端 :8066 --watch + Vite :5173 热更新，代理 /api）。
|
||
|
||
默认下载到 `./music`、数据在 `./data`。QQ 音乐 Cookie 会从 `config.json` 的 `qq.cookieFile`（默认 `../cookie.txt`）自动导入，文件更新后重启即重新导入；也可在设置页粘贴。
|
||
|
||
## 配置
|
||
|
||
`config.json`（私有仓库，已包含 chksz apikey），环境变量优先：
|
||
|
||
| 环境变量 | 对应 |
|
||
| --- | --- |
|
||
| `PORT` / `HOST` | `server.port`；监听地址默认 `0.0.0.0` |
|
||
| `MUSIC_DIR` / `DATA_DIR` | `paths.*` |
|
||
| `CHKSZ_API_KEY` | `netease.apikey` |
|
||
| `QQ_COOKIE_FILE` | `qq.cookieFile` |
|
||
| `DEFAULT_QUALITY` | `defaults.quality`：standard / high / lossless / hires / master / spatial / effect |
|
||
| `DEFAULT_LAYOUT` | `defaults.layout`：`album`（歌手/专辑/NN. 歌名）或 `flat`（歌手 - 歌名） |
|
||
| `LEGACY_HISTORY_FILE` | 旧版 CLI 的 `download_history.json`，首次启动导入 |
|
||
|
||
`config.json` 中的 `defaults` 只是初始值，网页设置页修改后保存在数据库中。
|
||
|
||
数据目录内容：`shengxia.db`（历史、队列、设置、加密后的 Cookie）、`secret.key`（本机加密密钥，勿外传）、`.trash/`（曲库回收站）。
|
||
|
||
## 标签规则（沿用旧版）
|
||
|
||
- 标题、歌手、专辑取自音源；曲序 `N/总数`、碟号、专辑艺人、合辑标记、发行日期、流派、唱片公司取自平台专辑详情
|
||
- 作词 / 作曲 / 编曲 / 制作人 / 混音从歌词头部解析；编曲、制作人、混音写入 TXXX（MP3）或同名字段（FLAC）
|
||
- 歌词保存为 `.lrc`，有翻译时额外生成 `.合并翻译.lrc`，并内嵌到音频
|
||
- 专辑目录写入 `cover.jpg`；人名统一使用 ` / ` 分隔
|
||
|
||
## Docker 部署（NAS）
|
||
|
||
```bash
|
||
cd /vol1/1000/dockercompose && git clone <私有仓库地址> shengxia && cd shengxia
|
||
docker compose up -d --build # http://NAS:8066
|
||
```
|
||
|
||
挂载与端口见 `docker-compose.yml` / `.env.example`。容器以 `PUID:PGID`（默认 `1000:1001`）运行。QQ Cookie 可在设置页导入，或设置 `QQ_COOKIE_FILE` 并挂载该文件。
|
||
|
||
## 进度
|
||
|
||
- [x] P0 工程骨架、设计 token、Docker 配置
|
||
- [x] P1 下载核心与网易云 provider
|
||
- [x] P2 QQ 音乐 provider（VIP Cookie）
|
||
- [x] P3 下载队列、SSE 实时进度、设置、访问密码、曲库与历史接口
|
||
- [x] P4 完整前端
|
||
- [ ] P5 QQ 扫码登录与 Cookie 自动续期
|
||
- [ ] P6 NAS 部署验证
|