# 本地曲库（muse.db）— 更新方法与版本记录

> 支线文档（自建歌曲源），不涉及本体 App 代码。
> 工具：`/home/zijun/dsh_data/maidongktv/tools/muse-sync.py`（本机复刻 App 的 `MuseDbSync` 协议）

## 一、更新方法

```bash
cd /home/zijun/dsh_data/maidongktv
python3 tools/muse-sync.py --check      # 只比对远端/本地版本
python3 tools/muse-sync.py --update     # 有更新才下载安装（412MB gz → 969MB db）
python3 tools/muse-sync.py --update --force   # 强制重下
MUSE_SYNC_HOST=mws.cherryonline.cn python3 tools/muse-sync.py --update   # 换同步主机
```

安装时会：**下载 → 校验 md5 → 解压 → 旧库改名 `muse.db.backup` → 写入新库 + 更新 `db_version.txt`**。

## 二、协议要点（2026-10-10 实测）

| 步骤 | 说明 |
|---|---|
| 登录 | `POST https://mconn.cherryonline.cn/mls-api/v1/login`，body `{encrypted_data: RSA_PKCS1v15({"device_id":"s00e04b021b2d"}), ip, dns, router, subnet_mask, channel:common, mode:ott}` → 取 `Set-Cookie: muse-portal-connector=…` |
| 同步 | `POST {host}/mls-api/v1/sqlite/sync`，body `{"last_sync_at":0,"music_file_type":214}`，**必须带上面的 Cookie** |
| 主机 | **`mconn.cherryonline.cn` 与 `mws.cherryonline.cn` 实测都能返回文件**（同一后台） |
| 无 Cookie | 返回 **401 Unauthorized** —— 登录 cookie 是唯一门槛，**每次同步前都要重新登录** |
| 响应 | `{"errcode":0,"files":[{"day":"261009","db_vc":10100,"md5":"…","url":"https://ali.pri.mcdn.cherryonline.cn/muse.portal.ott_common.full.261009.db.gz?Expires=…&Signature=…"}]}` |

> ⚠️ **踩坑记录（是我自己的 bug，不是服务端限制）**：首版脚本用「按固定下标插入 `-H Cookie`」拼接 curl 参数，
> 把前一个 `-H` 的取值切断 → Cookie 没发出去 → `sync` 返回**空 files**，被误判成"服务端未授权、拿不到库"。
> 真相是**渠道正常**。修复方式：所有 `-H` 用追加（`cmd += [...]`），不要按下标插入。
> 另注意该库的下发**与歌曲源取址的卡密/试用是两套东西** —— 曲库同步不看卡密。

## 三、版本对照（本机留档）

| 版本 | 曲库标识 | 歌曲数 | 文件 | md5 | 备注 |
|---|---|---|---|---|---|
| 旧（已备份 `muse.db.backup`） | `db_version=20260717.211050` | 670,304 | 1,036,038,144 B | `0bc6a5b51f0e24009ccfef2eee2d4d37` | **含** `cloud_url` / `block_status` 等列（44 列）|
| **新（当前 `muse.db`）** | `day=261009` / `db_vc=10100` / `db_version=1791504483411` | **696,393** | 1,015,771,136 B | `2ad0b46eacfa2620f0224237d36eb348` | 官方版（29 列，**无** `cloud_url`）|

**新库 schema 变化**（对比旧库少 15 列）：
`cloud_url`、`block_status`、`block_at`、`created_at`、`fav_at`、`media_id`、`p_origin`、`p_accomp`、
`p_volume`、`search_at`、`singer_names`、`source`、`source_id`、`store_id`、`updated_at` 均**不存在**；
表也精简为：`songs / singers / song_singer_relations / playlists / playlist_songs / song_langs /
tag_groups / tag_relations / singer_areas / singer_types / albums / movies`（后三者空）。

> 对本体 App 无影响：`MuseDatabase.kt` 的注释早已写明"官方曲库无 `cloud_url` 冗余列"，
> `SongApiClient` 的 DB 兜底是历史遗留路径，不会因缺列崩溃。

## 四、当前统计快照（新库，2026-10-10）

- **歌曲总数：696,393 首**（对比旧库 +26,089，+3.9%）
- 语言：国语 629,947（90.46%）· 粤语 24,646 · 闽南语 15,967 · 英语 14,701 · 其它 5,407 · 韩语 3,548 · 日语 2,115 · 未标注 62
- 歌手：137,462 位；歌曲-歌手关联 771,261 条，覆盖 692,579 首（99.5%）
- 歌单：276 个 / 43,054 条关联
- 文件名：绝大多数为 `<编号>.ts`（自建服务器可直接沿用该命名）

## 五、清单产物（`selfhost-source/inventory/`）

| 文件 | 内容 |
|---|---|
| `song-stats.md` | 统计报告（总数/语言/标签/歌手/维度分布）|
| `songs-all.csv` | 全量清单 696,393 行（44 MB）：`编号,歌名,语言,文件名,专辑,歌手,热度` |
| `songs-<语言>.csv` | 按语言拆分 8 份（国语 40 MB / 粤语 / 闽南语 / 英语 / 其它 / 韩语 / 日语 / 未标注）|
| `singers-top.csv` | 全量歌手榜（按歌曲数）|
| `playlists.csv` | 歌单清单 |

生成脚本：`selfhost-source/build_inventory.py`（**已做 schema 容错**：列/表不存在时自动跳过，适配不同曲库版本）。