DESKTOP-L8OUL9F\gfl0034 d3a68c3cad feat(music): 分类多对多、后台完整编辑与 OpenAPI

新增总/子分类与曲目绑定；playlist 可按 categoryId 筛选并返回分类树；
popadmin 支持行内改曲名/排序/上下架/会员开关与封面背景音频上传；文档同步。

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-09-24 10:38:06 +08:00

4.3 KiB

Raw Blame History

popadmin 音乐 / 小说 & sparkapi `/docs` 部署要点

1. spark-server（音乐 API + OpenAPI）

# 本机（Windows/WSL）：构建并部署到新加坡机
make deploy
# 会：linux 交叉编译 → docker image → 上传 ECS → spark-migrate（含 0020_music / 0021_music_background / 0022_music_categories）→ 重启容器 → nginx reload

新加坡机手工补跑迁移（仅 image 已更新但 migrate 未跑时）：

docker exec spark-server spark-migrate -config /app/configs/config.yaml
# 或 compose 目录下：docker compose run --rm spark-server spark-migrate -config /app/configs/config.yaml
sudo nginx -t && sudo nginx -s reload
# 确认 include 了 popadmin-spark-admin-locations.conf（含 music，client_max_body_size 55m）

Admin JWT（必对齐，否则音乐列表登录循环）

/api/admin/spark/music* 经 nginx 反代到 spark-server，走 AdminAuth，必须与 Java popadmin 登录签发密钥一致：

侧	配置
Java	`/etc/wyrs-admin/app.env` → `WYRS_ADMIN_JWT_SECRET`（未设则用 jar 默认 `...-production-2025`）
spark	`/data/spark-server/configs/config.yaml` → `admin.jwt_secret` 或 `SPARK_ADMIN_JWT_SECRET`

注意：

spark prod 会拒绝 jar 默认值 wyrs-admin-jwt-secret-change-in-production-2025（无法启动）。生产应两边写同一套非默认密钥；改后 docker restart spark-server + systemctl restart wyrs-admin，用户需重新登录一次。
Java 签发算法为 HS512；spark AdminAuth 与 popadmin-im（:8091，/api/admin/sg/*、/spark/im/*）均需同时接受 HS512 / HS256。仅 HS256 时仪表盘轮询 /sg/host-metrics 会 401，前端 api() 清会话 → 全局登录循环。
三处密钥须一致：/etc/wyrs-admin/app.env 的 WYRS_ADMIN_JWT_SECRET、/etc/popadmin-im/env 同名变量、spark admin.jwt_secret（或 SPARK_ADMIN_JWT_SECRET）。

症状：带 popadmin token 调 music 返回 401 + 登录已失效 → 密钥不一致或算法不兼容；IM 等仍走 Java :8090 故可正常。

验证：

GET https://sparkapi.wyrs365.com/v1/music/playlist → code=0，曲目含 coverUrl / backgroundUrl（可空）/ audioUrl
GET https://sparkapi.wyrs365.com/docs → 可见 music / admin-music
popadmin 重新登录后「音乐列表」不再跳登录；GET /api/admin/spark/music → 200 + success:true
popadmin「音乐列表」：封面 / 背景 / mp3 上传；POST /api/admin/spark/music/{id}/background

2. Aliyun wyrs-admin（popadmin 静态）

热更音乐背景图 UI（与现网一致）：

# 源：spark-server/deploy/popadmin/popadmin.js（已含背景列与上传）
scp -i ~/.ssh/wyrs_shanghai_deploy.pem deploy/popadmin/popadmin.js \
  root@47.236.66.9:/opt/wyrs-admin/static-override/popadmin.js
# 若 index 带 ?v= 缓存戳，同步 bump popadmin.index.html

新加坡若用 static-override，覆盖后强刷浏览器即可。

3. FullStoryNovel CMS（小说 iframe）

部署 static/admin/admin.js（embed=1&from=popadmin + postMessage SSO）
部署 nginx：去掉 X-Frame-Options SAMEORIGIN，改为
Content-Security-Policy: frame-ancestors 'self' https://popadmin.wyrs365.com
确认 fullstorynovel.service :8095 与 adopt-ops-session 可用

验证：popadmin →「小说内容管理」iframe 加载 novels；或新窗口打开 https://admin.fullstorynovel.com/admin/。

4. 设备登录文档（devices-client）

OpenAPI 已按 Spark资源文档/devices-client.md 更新契约。
当前 Go 实现仍为旧登录（Body 必填客户端 device_id、字符串 device_type，JWT 无 aid）。上线新契约前需改 auth/login、JWT、meta 枚举。

5. Demo 曲目（可选）

仓库旁 _demo_music/：tracks.json + 01..10.mp3/png + upload_demo.py。
背景图可空，demo 不强制补背景；脚本勿删已有曲目（仅 POST 新建）。背景可用 upload_backgrounds.py 补传。

# 在新加坡机（或可访问 popadmin 登录与 spark admin API 的环境）
export SPARK_ADMIN_BASE=http://127.0.0.1:18080
export POPADMIN_LOGIN=http://127.0.0.1:8090/api/admin/auth/login
python3 upload_demo.py
curl -sS https://sparkapi.wyrs365.com/v1/music/playlist | jq '.data.items|length,.data.items[0]|{title,coverUrl,backgroundUrl,audioUrl}'

4.3 KiB Raw Blame History Unescape Escape

popadmin 音乐 / 小说 & sparkapi /docs 部署要点