AGENTS.md

本文件为 Codex (Codex.ai/code) 提供项目指导，包含架构说明、开发流程和关键实现细节。

📋 项目概述

MOODY 音乐库 V2 是一个现代化的音乐存储与流媒体系统，采用纯 Worker 架构：

• 边缘计算：Cloudflare Worker (TypeScript/Hono) - 所有 API 和数据存储
• 前端界面：极简播放器 + 管理后台（纯静态 HTML/CSS/JS）
• 存储系统：Cloudflare R2（对象存储）+ D1 数据库
• 部署方式：Docker (Nginx) 托管前端 + Cloudflare Worker 提供 API

技术栈

• 边缘计算：Cloudflare Workers + Hono + D1 数据库
• 存储：Cloudflare R2（兼容 S3 API）
• 前端：纯静态 HTML/CSS/JavaScript（无框架）
• 部署：Docker + Nginx

🌐 生产环境配置

域名和端口

前端播放器：https://ddjokbqwfbce.ap-southeast-1.clawcloudrun.com
管理后台：  https://qbxnkwidzabx.ap-southeast-1.clawcloudrun.com
Worker API： https://moody-worker.changgepd.workers.dev

⚠️ 重要架构理解（v13.0 纯 Worker 架构）

为什么采用纯 Worker 架构？

• Cloudflare Worker 与 R2 同地域，上传速度提升 10x+
• Worker 直接绑定 D1 和 R2，无需网络调用
• 全球 CDN 加速，边缘计算低延迟
• 无需维护后端服务器，降低运维成本

数据流向：

用户请求 → Cloudflare Worker（边缘计算 + D1 数据库）
           ↓
       R2 对象存储（音乐文件）

Docker 容器角色：

• 只托管前端静态文件（HTML/CSS/JS）
• Nginx 提供 HTTP 服务
• 不处理后端逻辑（全部由 Worker 接管）

🔧 开发命令

Cloudflare Worker（核心 API）

cd cloudflare-worker

# 安装依赖
npm install

# 本地开发
npx wrangler dev

# 部署到 Cloudflare
npx wrangler deploy

# 类型检查
npx tsc --noEmit

Wrangler 配置：

• wrangler.toml 定义了 D1 数据库绑定（moody-d1-test）
• R2 bucket 绑定（moody-music-asset）
• 部署前确保已登录：npx wrangler login

前端（本地调试）

cd frontend

# 前端为纯静态 HTML/CSS/JS，无需构建
# 直接用浏览器打开即可

# 或使用简易 HTTP 服务器
python -m http.server 8000
# 然后访问 http://localhost:8000

Docker（生产部署）

# 构建镜像
docker build -t moodymusic:latest .

# 运行容器（测试）
docker run -p 80:80 moodymusic:latest

Docker 构建：

• 基于 nginx:alpine 镜像
• 只包含前端静态文件（~20MB）
• 自动配置 Nginx 和 Worker 代理

🏗️ 核心架构

纯 Worker 架构

┌─────────────────────────────────────┐
│   用户（浏览器）                    │
└──────────────┬──────────────────────┘
               │
               ↓
┌──────────────────────────────────────┐
│  Docker 容器（Nginx + 前端静态文件）  │
│  - 端口 80                           │
│  - 只托管 HTML/CSS/JS                │
│  - 代理 API 请求到 Worker            │
└──────────────┬───────────────────────┘
               │
               ↓
┌──────────────────────────────────────┐
│  Cloudflare Worker（边缘计算）       │
│  - Hono 框架                         │
│  - D1 数据库                         │
│  - R2 存储绑定                       │
└──────────────┬───────────────────────┘
               │
               ↓
┌──────────────────────────────────────┐
│  Cloudflare R2（对象存储）           │
│  - 音乐文件（.mp3）                  │
│  - 专辑封面                          │
│  - 歌词文件（.lrc）                  │
└──────────────────────────────────────┘

目录结构

Music-Archiv-V2/
├── cloudflare-worker/          # 核心业务逻辑
│   ├── src/
│   │   ├── index.ts           # Worker 主文件
│   │   └── upload.ts          # 上传处理逻辑
│   └── wrangler.toml          # Cloudflare 配置
├── frontend/                   # 前端静态文件
│   ├── admin/                 # 管理后台
│   │   ├── index.html
│   │   ├── admin.js
│   │   ├── admin.css
│   │   └── album-manager.js   # 专辑管理功能
│   └── src/                   # 播放器
├── docs/                      # 文档
│   ├── API.md                 # API 文档
│   └── archive/               # 旧文档归档
├── Dockerfile                 # Docker 构建文件
└── README.md                  # 项目说明

🔌 核心 API 接口

公共 API（Worker）

GET /api/skeleton              # 艺人列表
GET /api/songs                 # 完整歌曲数据
GET /api/search?q={query}      # 全局搜索
GET /api/welcome-images        # 背景图片

管理 API（Worker）

GET  /api/admin/stats                      # 系统统计
GET  /api/admin/albums/search?keyword=xx   # 搜索专辑
GET  /api/admin/albums/detail?album_id=xx  # 专辑详情
POST /api/admin/songs/batch-update          # 批量更新歌曲
POST /api/admin/songs/delete-all            # 清空专辑歌曲
POST /api/admin/songs/batch-insert          # 批量插入歌曲
POST /api/admin/songs/cleanup-no-path       # 清理无路径歌曲
POST /api/admin/albums/delete               # 删除专辑
POST /api/admin/cleanup-duplicates          # 清理重复专辑
POST /api/admin/upload                      # 批量上传

完整 API 文档：查看 docs/API.md

API 响应规范（必须遵守）

新增或修改接口时必须保持响应结构稳定，方便 Android App 和前端统一处理：

成功响应：

{
  "code": 200,
  "message": "success",
  "data": {}
}

• 新接口的业务数据必须放在 data 中。
• 兼容旧接口时，可以同时保留顶层业务字段，例如 claim_token 与 data.claim_token 同时返回，避免 Android BaseResponse<T>.data 解析为空。
• 不要只把业务字段放在顶层，尤其是认证、注册、登录、刷新 Token 等 App 强依赖接口。
• 认领注册接口的 email 是可选项；不要要求用户注册时输入邮箱。Supabase Auth 使用后端生成的纯 ASCII 内部邮箱，用户真实邮箱只在后续绑定邮箱流程中写入。

错误响应：

{
  "code": 1304,
  "error_key": "CLAIM_SECURITY_ANSWER_MISMATCH",
  "message": "第 2 道问题答案不正确",
  "details": {
    "question_index": 2
  }
}

• HTTP 状态码只表达协议层分类，JSON code 表达具体业务原因。
• code 必须全局唯一，不允许不同错误复用同一个业务码。
• App 端应优先按 code 或 error_key 分支，不要把所有业务失败都压成 401。
• Worker 侧应优先使用 cloudflare-worker/src/error.ts 中的 fail()、serverError() 和错误码字典，不要手写散落的 { code: 400 } / { code: 401 }。

💾 数据库架构

Cloudflare D1（生产环境）

核心表结构：

-- 艺人表
artists (id, name, region, bio, photo_url)

-- 专辑表
albums (id, title, release_date, genre, cover_url, artist_id)

-- 歌曲表
songs (id, title, duration, file_path, lrc_path, album_id, storage_id, track_index)

-- 用户相关
users, playlists, playlist_songs

重要字段说明：

• file_path：相对路径，带 music/ 前缀（如 music/李宗盛/不舍/s_10025.mp3）
• storage_id：存储标识（primary）
• track_index：歌曲在专辑中的排序
• UTF-8 编码严格强制：所有文本字段使用 UTF-8

🚀 部署流程

CI/CD 流程

1. 推送代码到 main 分支
2. GitHub Actions 自动构建 Docker 镜像（~2 分钟）
3. 镜像推送到 Docker Hub (changgepd/moodymusic:latest)
4. 手动在 ClawCloud 点击 Update

⚠️ ClawCloud 部署（关键步骤）

重要：代码推送后，容器不会自动更新！必须手动操作：

1. 登录 ClawCloud 管理控制台
2. 找到 moodymusic 实例
3. 点击 "Update" 按钮（不是 "Restart"）
4. 等待容器拉取最新镜像并重启

如果 Update 无效：

1. 停止容器（Stop）
2. 删除容器（Delete）
3. 重新创建，使用最新镜像：changgepd/moodymusic:v13.0-pure-worker

原因：

• "Restart" 仅重启当前容器，不会拉取新代码
• "Update" 会检查 Docker Hub 的版本更新并拉取

健康检查

# 检查前端
curl https://ddjokbqwfbce.ap-southeast-1.clawcloudrun.com

# 检查 Worker API
curl https://moody-worker.changgepd.workers.dev/api/admin/stats

📝 常见开发任务

添加新音乐

使用管理后台：

1. 访问 https://qbxnkwidzabx.ap-southeast-1.clawcloudrun.com
2. 点击"☁️ 超级上传"
3. 拖拽音乐文件到上传区域
4. 点击"🚀 执行入库"

批量更新歌曲信息

使用管理后台的专辑管理功能：

1. 点击"💿 专辑管理"
2. 搜索专辑
3. 点击"批量编辑歌曲"
4. 在文本框中编辑歌曲信息
5. 点击"保存更改"

或通过 API：

import requests, json

API_BASE = "https://moody-worker.changgepd.workers.dev"
updates = [
    {"id": 10025, "title": "新的歌曲名", "track_index": 1}
]

response = requests.post(
    f"{API_BASE}/api/admin/songs/batch-update",
    data=json.dumps({"updates": updates}, ensure_ascii=False).encode('utf-8'),
    headers={"Content-Type": "application/json; charset=utf-8"}
)

🔧 故障排查

前端页面没有更新

1. 硬刷新浏览器：Ctrl + Shift + R（Windows）或 Cmd + Shift + R（Mac）
2. 检查 Docker 镜像版本：

   curl -I https://ddjokbqwfbce.ap-southeast-1.clawcloudrun.com
   

3. 在 ClawCloud 重新部署：Stop → Delete → 重新创建

API 请求失败

1. 检查 Worker 状态：访问 https://moody-worker.changgepd.workers.dev/api/admin/stats
2. 重新部署 Worker：

   cd cloudflare-worker
   npx wrangler deploy
   

数据未更新

1. 确认在 ClawCloud 点击了 "Update"（不是 Restart）
2. 检查 Worker 是否需要重新部署
3. 验证 Cloudflare D1 数据库状态

📚 相关文档

• README.md - 中文项目概述
• docs/API.md - 完整 API 文档
• docs/archive/ - 历史文档归档

🎯 快速参考

域名速查

生产前端：https://ddjokbqwfbce.ap-southeast-1.clawcloudrun.com
生产管理：https://qbxnkwidzabx.ap-southeast-1.clawcloudrun.com
Worker API：https://moody-worker.changgepd.workers.dev

常用 API

# 获取艺人列表
curl https://moody-worker.changgepd.workers.dev/api/skeleton

# 获取完整数据
curl https://moody-worker.changgepd.workers.dev/api/songs

# 系统统计
curl https://moody-worker.changgepd.workers.dev/api/admin/stats

💡 最佳实践

1. Worker 优先：所有业务逻辑在 Worker 中实现
2. UTF-8 优先：所有文本数据使用 UTF-8 编码
3. 批量操作：使用 Worker 的 batch API 提高性能
4. 测试先行：先在测试环境验证，再应用到生产环境
5. 手动部署：ClawCloud 需要手动点击 Update

最后更新：2026-03-19 维护者：zhangjing02 版本：v13.0 (纯 Worker 架构)

🔍 进一步阅读

项目演进历史

• docs/archive/云端上传架构设计方案.md - Worker 架构设计决策
• docs/archive/上传失败问题修复报告.md - 上传问题排查
• docs/archive/李宗盛专辑修复总结.md - 数据修复案例