外观
服务端架构
拼好歌服务端是一个用 Cloudflare Workers + QuickJS（WASM） 构建的后端服务框架：在边缘节点提供 JavaScript 沙箱与网络代理通道，动态执行使用者自行导入的音源插件，并内置 Web 管理后台与用户账号体系，支持多设备歌单与使用记录同步。
本项目不提供音乐数据
服务端不提供音乐数据，也不内置任何音源插件；数据全部由使用者自行导入的插件返回。代码开源且免费。
关联项目
| 项目 | 说明 |
|---|---|
| 客户端（小程序端） | 同一套 uni-app 代码，Android 与桌面端另有安装包 |
架构概览
客户端
│ HTTPS
▼
Cloudflare Worker（路由 / 鉴权 / 限流 / 用量统计）
├─► D1 数据库（账号、歌单、收藏、会话）
├─► QuickJS（WASM）沙箱 ── 执行使用者导入的插件
└─► 管理后台（HTML 内联于 Worker，无需单独部署前端）模块划分
| 目录 | 职责 |
|---|---|
src/worker.ts | Worker 入口与路由分发 |
src/http/ | 请求解析与统一响应 |
src/services/ | 业务服务（账号、同步、歌单、设置等） |
src/runtime/ | 脚本运行时与沙箱加载 |
src/admin/ | 管理后台页面与接口 |
src/data/ | 数据访问与存储 |
src/observability/ | 日志、耗时与用量统计 |
src/utils/ | 通用工具 |
能力清单
| 能力 | 说明 |
|---|---|
| 账号体系 | 邮箱注册 / 登录 / 重置密码 / 设备会话管理，注册需管理员发放的邀请码 |
| 数据同步 | 歌单、收藏、播放历史、设置的多端同步，含单条体积上限 |
| 插件沙箱 | 在隔离的 QuickJS 环境中执行使用者导入的插件 |
| 管理后台 | 插件在线/本地导入与批量管理、音源调优、黑名单、熔断复位、服务器设置 |
| 听歌识曲 | 音频指纹识别接口 |
| AI 推荐与热搜 | 基于 Cloudflare AI 绑定，模型可配置 |
| 用量统计 | 按请求维度统计，便于配额控制 |
| 短链服务 | 歌单分享短链 |
管理后台
部署完成后访问 Worker 的根路径（https://你的域名/）即可打开后台，不需要带 API_KEY。后台由 Worker 直接返回纯 HTML（内联 CSS/JS），无需单独部署前端项目。
- 登录：用
ADMIN_EMAIL/ADMIN_PASSWORD登录；首次登录会自动创建管理员账号，之后在「系统设置 → 修改管理员密码」改密码。 - 服务器地址：登录后点右上角「复制服务器地址」一键复制（按钮左侧会直接显示完整地址），粘到客户端即可；也可以自己拼
域名/API_KEY。 - 鉴权：后台写操作均走服务端鉴权，会话失效统一返回
401 + authExpired:true，前端据此清理凭证并引导重新登录。
路由与鉴权
| 路由形态 | 用途 | 用什么密钥 |
|---|---|---|
/{apiKey}/api/...、/owner/{apiKey}/... | 管理路由 | API_KEY（兼作 Owner Key） |
/{publicKey}/... | 客户端路由 | PUBLIC_KEY |
两者分开鉴权：客户端只需持有 PUBLIC_KEY；不设置 PUBLIC_KEY 时该路由不可用。
环境变量
| 变量 | 说明 |
|---|---|
API_KEY | API 密钥（兼作 Owner Key），有公开默认值，部署后一定要改 |
PUBLIC_KEY | 客户端访问密钥（v1.0.10 新增），32 位 hex |
ADMIN_EMAIL | 管理后台管理员邮箱 |
ADMIN_PASSWORD | 管理员初始密码，仅用于首次登录建号；配置里是明文，后台不明文保存 |
AI_MODEL | AI 模型名称，默认 @cf/qwen/qwen3-30b-a3b-fp8 |
DB | D1 数据库绑定，变量名必须大写 |
AI | Cloudflare AI 绑定 |
费用与配额
以 Cloudflare 官方定价为准：
| 资源 | 免费版 | 付费版 |
|---|---|---|
| 请求次数 | 10 万次/天 | 1000 万次/月（≈33 万次/天） |
| CPU 时间 | 10ms/次 | 3000 万 ms/月 |
| D1 读取 | 500 万次/天 | 1 亿次/月 |
| D1 写入 | 10 万次/天 | 1000 万次/月 |
| D1 存储 | 5GB | 无限制 |
按每人每天 3 小时听歌（约 45 次请求/天）估算：免费版约可支撑 2000 人/天，付费版约 7000 人/天。
免费套餐的 CPU 上限
Workers 免费套餐对单次请求的 CPU 时间有上限（10ms）。项目通过 QuickJS 的 WASM 同步构建与运行参数调优来适配该限制，具体配置在服务端部署使用教程中说明。
统一响应与错误码
所有接口返回统一 JSON：
json
{ "code": 200, "msg": "success", "data": {} }| 状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 400 | 参数错误 |
| 403 | 无权限（Owner Key 错误） |
| 410 | 尚未导入任何音源插件 |
| 411 | 没有支持该源的插件 |
| 412 | 换源失败（候选音源均不可用） |
| 429 | 用量已达上限 |
| 500 | 服务器内部错误 |
安全建议
- 先改默认凭据：
API_KEY、ADMIN_PASSWORD的默认值写在公开仓库里，部署完第一件事就是换掉； - 敏感项不要写进
wrangler.toml：用wrangler secret put写入；wrangler deploy会用文件里的值覆盖面板改动； - D1 绑定在控制台维护：不写进
wrangler.toml（database_id因人而异）；部署后若提示「数据库未绑定」，到 Worker「绑定」页确认DB存在； - 管理后台只自己访问：不建议对公网开放注册，邀请码由管理员在后台生成后单独发放。