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

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

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

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

```bash
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（与现网一致）：

```bash
# 源：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 补传。

```bash
# 在新加坡机（或可访问 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}'
```