┌─ Web UI (浏览器/外网)
│   ├─ 登录页 (admin/admin)
│   ├─ 搜索/下载/任务
│   └─ 设置 (插件导入 / 音乐库 / MCP / 服务状态)
│
├─ MCP (Claude/Hermes AI Agent 接入, SSE 模式)
│
├─ REST API (8765 端口)
│
└─ Backend
    ├─ upstream 多源聚合 (公开 API)
    ├─ PostgreSQL 5 表
    ├─ Worker threads × 2 (原子抢任务, FOR UPDATE SKIP LOCKED)
    ├─ 插件 (Node VM 沙箱) — 需用户自行导入
    └─ 4 层防重 + ID3 tag 自动写入

git clone https://github.com/fangtang0206/cubesugar-music.git
cd cubesugar-music

# 配置环境变量 (可选)
export PG_PASSWORD=your_secure_password
export JWT_SECRET=$(openssl rand -hex 32)
export DOWNLOAD_DIR=/path/to/music  # 默认 ./music

# 启动 (首次会构建镜像，需要 2-3 分钟)
docker compose up -d

# 等 30 秒让服务起来
curl http://127.0.0.1:8765/api/health
# → {"status": "ok", "runtime": "ok", "upstream": "ok", "postgres": "ok", "worker_running": true}

# 打开 Web UI
open http://127.0.0.1:8765/
# 默认账号: admin / admin (登录后立即修改!)

# 1. 准备 PostgreSQL
psql -U root -c "CREATE DATABASE fangtang_music"

# 2. 安装依赖
pip3 install mutagen psycopg[binary]

# 3. 启动 Node runtime
cd node-runtime && node server.js &

# 4. 启动主服务
cd app && python3 server.py

# 复制插件 JS 到 sources 目录
cp /path/to/plugin.js /vol1/1000/docker/cubesugar-music/sources/

# 重启服务 (或点 Web UI 刷新)

# 登录
curl -X POST http://127.0.0.1:8765/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'
# → {"token": "eyJhbG...","user": {...}}

# 后续请求带 token
curl http://127.0.0.1:8765/api/tasks/list \
  -H "Authorization: Bearer eyJhbG..."

# 签发 MCP 长 token (30 天)
curl -X POST http://127.0.0.1:8765/api/auth/mcp-token \
  -H "Authorization: Bearer <token>"
# → {"token": "eyJhbG...","expires_in": 2592000}

# 默认跨源
curl "http://127.0.0.1:8765/search?name=海阔天空&artist=Beyond" \
  -H "Authorization: Bearer <token>"

# 指定源
curl "http://127.0.0.1:8765/search?name=test&source=tx"

curl -X POST http://127.0.0.1:8765/api/tasks/submit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "wy",
    "song_id": "1357375695",
    "name": "海阔天空",
    "artist": "Beyond",
    "quality": "flac"
  }'

curl -X POST http://127.0.0.1:8765/api/playlist/import \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://music.163.com/playlist?id=12345",
    "quality": "flac"
  }'

# 默认 status=all, page=1, page_size=20
curl "http://127.0.0.1:8765/api/tasks/list" -H "Authorization: Bearer <token>"

# 筛选下载成功 / 失败 / 待重试
curl "http://127.0.0.1:8765/api/tasks/list?status=success" -H "Authorization: Bearer <token>"
curl "http://127.0.0.1:8765/api/tasks/list?status=error"   -H "Authorization: Bearer <token>"
curl "http://127.0.0.1:8765/api/tasks/list?status=retry"   -H "Authorization: Bearer <token>"

# 分页
curl "http://127.0.0.1:8765/api/tasks/list?page=2&page_size=50" -H "Authorization: Bearer <token>"

# 状态
curl "http://127.0.0.1:8765/api/library/stats" -H "Authorization: Bearer <token>"

# 查询
curl "http://127.0.0.1:8765/api/library/lookup?artist=Beyond&name=海阔天空" \
  -H "Authorization: Bearer <token>"

# 触发重建 (后台 4-5 分钟)
curl -X POST "http://127.0.0.1:8765/api/library/rescan" -H "Authorization: Bearer <token>"

# ~/.hermes/config.yaml 或 ~/.claude/mcp_servers.json
mcp_servers:
  cubesugar-music:
    url: http://your-host:8765/mcp/sse
    transport: sse
    headers:
      Authorization: Bearer <从 /api/auth/mcp-token 拿到的 30 天 token>
      X-Client: hermes-agent

cubesugar-music/
├── app/                        # Python 主服务
│   ├── server.py               # 主 HTTP 路由
│   ├── fetcher.py            # 多源聚合上游
│   ├── library_index.py        # 本地音乐库扫描器 + 索引查重
│   ├── id3_writer.py           # FLAC/MP3 ID3 tag 写入
│   ├── worker/worker.py        # 后台下歌 worker
│   ├── auth/                   # JWT + PBKDF2 密码哈希
│   ├── db/                     # PostgreSQL 连接池
│   ├── api/mcp.py              # MCP server (SSE)
│   └── playlist.py             # 歌单 URL 解析
├── node-runtime/               # Node 沙箱 (8098 端口)
├── sources/                    # (空) 插件目录 - 用户自行填充
├── docker-compose.yml          # 一键启动
├── Dockerfile
└── README.md

# 1. 启动 postgres
docker run -d --name cubesugar-db \
  -e POSTGRES_PASSWORD=cubeSugar_postgresql \
  -e POSTGRES_DB=fangtang_music \
  -p 54321:5432 \
  postgres:15-alpine

# 2. 启动 runtime
cd node-runtime && node server.js &

# 3. 启动主服务
cd app
PORT=8765 DOWNLOAD_DIR=/vol2/1000/music \
PG_HOST=127.0.0.1 PG_PORT=54321 \
python3 server.py

cd app/
python3 -c "from id3_writer import backfill_existing_files; print(backfill_existing_files('/vol2/1000/music'))"