外观
服务端部署使用教程
服务端有两种部署方式，按官方 README 的说明：
- 方式一：GitHub Fork + Cloudflare 一键连接 —— 面板一键连接，最省事，推荐。
- 方式二：wrangler CLI 本地部署 —— 代码托管在 Codeberg 时用这个。Cloudflare 的 Git 集成只支持 GitHub 与 GitLab，连不上 Codeberg。
两种方式部署出来的效果完全一样，区别只在「代码怎么上去」。
前置条件
| 项目 | 要求 |
|---|---|
| Cloudflare 账号 | 免费账号即可 |
| 代码 | 一份服务端仓库副本（Fork 或 clone） |
| Node.js | 仅方式二需要，18 或更高（node -v 确认） |
方式一：GitHub Fork + Cloudflare 一键连接
第 1 步：Fork 本项目
在 GitHub 打开服务端仓库，点右上角 Fork → 确认创建。
第 2 步：连接 GitHub 并部署
- 打开 Cloudflare Dashboard → 左侧 Workers 和 Pages；
- 右上角 创建应用程序 → 选 Connect GitHub（不是「创建 Worker」）；
- 首次使用会提示授权 GitHub → 点 Connect GitHub → 授权；
- 选 Continue with GitHub，在仓库列表里选中你刚 Fork 的服务端仓库；
- 项目名填
cf-phg-music-server（不能有下划线）； - 点 部署。
第 3 步：创建 D1 数据库
左侧 存储和数据库 → D1 SQL 数据库 → 创建数据库，名称填 cf-phg-music-db。
第 4 步：把 D1 绑定到 Worker
- 进入刚部署的 Worker 项目 → 左上角菜单 绑定；
- 弹窗里选 D1 数据库 → 添加；
- 变量名称填
DB（必须大写），数据库选cf-phg-music-db； - 点 添加绑定。
第 5 步：改 API_KEY，加 PUBLIC_KEY 与管理员账号
进入 Worker 项目 → 设置 → 变量和机密：
| 变量 | 填什么 |
|---|---|
API_KEY | 你自己的密钥，一定要改。默认值写在公开仓库里，不改等于任何人都能访问你的接口 |
PUBLIC_KEY | 32 位 hex 字符串，供客户端访问用；不设置时该路由不可用 |
ADMIN_EMAIL | 管理后台登录邮箱 |
ADMIN_PASSWORD | 管理员初始密码，填你能记住的即可 |
API_KEY 是部署里最关键的一步
默认 API_KEY 是公开的。API_KEY 兼作 Owner Key，用于管理路由；PUBLIC_KEY 是 v1.0.10 新增的独立密钥，用于客户端路由，两者分开鉴权。
ADMIN_EMAIL / ADMIN_PASSWORD 只在第一次登录时用
账号建好后，再改这两个变量不会影响登录 —— 要改密码请到后台「系统设置 → 修改管理员密码」。
第 6 步：拿到访问地址
设置 → 域和路由 → 复制 workers.dev 对应的值（形如 xxxx.workers.dev）。
用浏览器打开 https://xxxx.workers.dev/（根路径）就是管理后台。
第 7 步：注册域名（如需国内访问）
Workers 默认域名 *.workers.dev 在中国大陆无法访问，要绑自定义域名才能正常用。
README 里给的免费域名渠道：INDEVS.in（免费域名，单用户限 5 个，1 年有效期）等支持 Cloudflare 托管的平台。
第 8 步：把域名托管到 Cloudflare
绑自定义域之前，必须先把域名的 DNS 交给 Cloudflare，否则下一步会失败。
- Cloudflare → 域名 → 添加域名 → 输入你的域名 → 继续；
- 套餐选 Free（免费） → 继续；
- Cloudflare 会自动扫描现有 DNS 记录，确认后继续；
- 页面会给出两个名称服务器（形如
xxa.ns.cloudflare.com），复制； - 到域名注册商后台，把名称服务器替换成这两个；
- 回 Cloudflare 点 完成，检查名称服务器，等状态变成「活跃」（几分钟到数小时，最长 24 小时）。
第 9 步：绑定自定义域名
Worker 项目 → 设置 → 域和路由 → 添加 → 选 自定义域 → 输入域名 → 添加域。
绑定完成后，https://你的域名/ 就是管理后台。
第 10 步：登录后台并初始化
- 浏览器打开
https://你的域名/（根路径即后台，不需要带 API_KEY）； - 用第 5 步的
ADMIN_EMAIL和密码登录； - 进「音源插件」→ 在线导入 / 本地导入，添加你自己的音源脚本，支持批量启用、停用、删除；
- 进「系统设置」确认对外域名与部署信息，并改掉默认管理员密码；
- 点右上角「复制服务器地址」，粘到客户端设置页的服务器地址栏。
方式二：wrangler CLI 本地部署
适用于代码托管在 Codeberg 的场景。
第 1 步：获取代码并装依赖
bash
git clone https://codeberg.org/erikjamesgz/cf_phg_music_server.git
cd cf_phg_music_server
npm install依赖里包含 QuickJS 的 WebAssembly 文件（约 500 KB），首次安装需要联网。
第 2 步：登录并部署
bash
npx wrangler login # 浏览器打开授权页，点 Allow
npx wrangler deploy服务器上没有浏览器时，改用 API 令牌：Cloudflare 后台「我的个人资料 → API 令牌」按 Edit Cloudflare Workers 模板创建，然后
bash
export CLOUDFLARE_API_TOKEN=你的令牌 # Windows 命令行用 set部署成功后会输出 Worker 地址，形如 https://cf-phg-music-server.你的账户.workers.dev。
第 3 步：后续配置
从这一步起与方式一的第 3～10 步完全相同：创建 D1 → 绑定 DB → 配 API_KEY / PUBLIC_KEY 与管理员账号 → 登录后台 → 绑自定义域名。
D1 绑定在 Cloudflare 控制台做
D1 不写进 wrangler.toml：每个部署者的 database_id 都不一样，写死在配置里没有意义。请按方式一第 3、4 步在控制台创建数据库、绑定到 Worker，变量名用 DB。
部署或更新版本之后，顺手到 Worker 的「绑定」页确认 DB 还在；如果发现丢了，重新添加一次即可。
以后更新版本
bash
git pull
npm install
npx wrangler deploy验证部署
bash
# 服务信息（注意路径是 /{apiKey}/status）
curl https://你的域名/<API_KEY>/status返回 {"code":200,...} 且 serverVersion 正常即部署成功。
常见问题
打开根路径是管理后台，为什么还需要 API_KEY？
管理后台页面本身不需要 API_KEY（登录走账号密码），但客户端连接服务器时要填 域名/API_KEY。登录后台后点右上角「复制服务器地址」可以直接拿到完整地址。
部署后登录提示「数据库未绑定」？
说明 Worker 上没有名为 DB 的 D1 绑定。到 Worker 项目 →「绑定」页确认有一条 D1 绑定、变量名是 DB、指向你自己的 cf-phg-music-db；没有就按第 4 步补一个，然后重新打开后台。
在面板改了变量，重新部署后又被改回去？
因为 wrangler deploy 会用 wrangler.toml 里的值覆盖面板中的同名变量。敏感项请改用 wrangler secret put，或从 [vars] 里移除。
国内访问不了 *.workers.dev？
这是默认域名的限制，不是部署失败。按第 7～9 步绑一个自定义域名即可。
免费套餐够用吗？
够。免费版每天 10 万次请求，按每人每天约 45 次请求估算，可支撑约 2000 人/天。具体配额见服务端架构。
必须用 GitHub 授权部署吗？
不必须，但 README 把「Fork + 一键连接」列为推荐路径（最省事）。代码在 Codeberg 上用方式二。