MeowMusicServer/使用说明.md

🎵 Meow Music 使用说明

📋 功能概览

Meow Music 是一个完整的音乐播放和管理系统，包含以下功能：

✨ 核心功能

1. 用户系统

   • 用户注册和登录
   • 密码加密存储（bcrypt）
   • Token认证机制

2. 音乐搜索

   • 实时搜索音乐
   • 显示歌曲标题和艺术家
   • 搜索结果缓存

3. 在线播放

   • 内置音频播放器
   • 显示当前播放信息
   • 支持标准音频控制

4. 我喜欢

   • 快速收藏喜欢的歌曲
   • 查看收藏列表
   • 移除收藏

5. 歌单管理

   • 创建自定义歌单
   • 添加/删除歌曲
   • 查看歌单详情

---

🚀 快速开始

1. 启动服务器

Windows:

# 方式1：双击启动
双击 start.bat

# 方式2：命令行启动
cd d:\esp32-music-server\Meow\MeowEmbeddedMusicServer
go run .

Linux/macOS:

cd /path/to/MeowEmbeddedMusicServer
./start.sh
# 或
go run .

2. 访问应用

打开浏览器，访问：

• 主应用: http://localhost:2233
• 测试版本: http://localhost:2233/test
• 经典界面: http://localhost:2233/classic

---

📖 使用指南

第一次使用

1. 注册账户

   • 访问 http://localhost:2233
   • 点击"注册"标签
   • 填写：用户名、邮箱、密码（至少6位）
   • 点击"注册"按钮
   • 注册成功后会自动进入主界面

2. 登录

   • 使用注册的用户名和密码登录
   • 注意：登录时使用用户名，不是邮箱

搜索音乐

1. 在搜索框输入歌曲名或艺术家名
2. 按回车键开始搜索
3. 搜索结果会显示在下方

播放音乐

1. 在搜索结果中点击"播放"按钮
2. 底部会出现播放器
3. 使用播放器控制播放、暂停、音量等

收藏音乐

1. 点击歌曲旁边的"喜欢"按钮
2. 歌曲会自动添加到"我喜欢"列表
3. 切换到"我喜欢"标签查看所有收藏

管理歌单

1. 切换到"我的歌单"标签
2. 点击"+ 新建歌单"创建新歌单
3. 输入歌单名称和描述
4. 点击歌单查看详情（开发中）

---

🔧 API接口

用户认证

注册

POST /api/auth/register
Content-Type: application/json

{
  "username": "用户名",
  "email": "邮箱",
  "password": "密码"
}

登录

POST /api/auth/login
Content-Type: application/json

{
  "username": "用户名",
  "password": "密码"
}

获取当前用户

GET /api/auth/me
Authorization: Bearer {token}

登出

POST /api/auth/logout
Authorization: Bearer {token}

音乐搜索

搜索歌曲

GET /api/search?query={关键词}

收藏管理

添加到收藏

POST /api/favorite/add
Content-Type: application/json

{
  "title": "歌曲名",
  "artist": "艺术家",
  "url": "播放链接"
}

获取收藏列表

GET /api/favorite/list

从收藏移除

POST /api/favorite/remove
Content-Type: application/json

{
  "title": "歌曲名",
  "artist": "艺术家"
}

歌单管理

获取用户歌单

GET /api/user/playlists
Authorization: Bearer {token}

创建歌单

POST /api/user/playlists/create
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "歌单名称",
  "description": "歌单描述"
}

添加歌曲到歌单

POST /api/user/playlists/add-song?playlist_id={歌单ID}
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "歌曲名",
  "artist": "艺术家",
  "url": "播放链接"
}

从歌单移除歌曲

DELETE /api/user/playlists/remove-song?playlist_id={歌单ID}&title={歌曲名}&artist={艺术家}
Authorization: Bearer {token}

删除歌单

DELETE /api/user/playlists/delete?playlist_id={歌单ID}
Authorization: Bearer {token}

---

📁 文件结构

MeowEmbeddedMusicServer/
├── main.go                 # 主程序入口
├── user.go                 # 用户管理
├── playlist.go             # 歌单管理
├── index.go                # 路由处理
├── struct.go               # 数据结构
├── start.bat              # Windows启动脚本
├── start.sh               # Linux/macOS启动脚本
├── files/                 # 数据文件目录
│   ├── users.json         # 用户数据
│   ├── user_playlists.json # 用户歌单数据
│   └── playlists.json     # 遗留歌单数据
└── theme/                 # 前端文件
    ├── full-app.html      # 完整应用（主界面）
    ├── test-app.html      # 测试版本
    ├── simple-app.html    # 简化版本
    └── index.html         # 经典界面

---

⚙️ 配置

修改端口

编辑 main.go，找到：

port := "2233"

修改为您想要的端口号。

数据存储位置

所有数据存储在 ./files/ 目录下：

• users.json - 用户账户信息（包含加密密码）
• user_playlists.json - 用户创建的歌单
• playlists.json - 遗留的公共歌单

---

🐛 故障排除

问题1：端口被占用

listen tcp :2233: bind: Only one usage of each socket address...

解决方法：

# 查找占用端口的进程
netstat -ano | findstr :2233

# 关闭进程（替换{PID}为实际进程ID）
taskkill /F /PID {PID}

问题2：登录失败

invalid username or password

可能原因：

1. 用户名或密码错误
2. 使用了邮箱而不是用户名登录
3. 服务器重启后数据未正确加载

解决方法：

• 确认使用用户名登录，不是邮箱
• 检查 files/users.json 是否存在且格式正确
• 重新注册一个新账户测试

问题3：搜索无结果

可能原因：

• 网络连接问题
• 搜索关键词不正确
• 音乐源服务不可用

解决方法：

• 检查网络连接
• 尝试更常见的歌曲名
• 查看服务器日志

问题4：无法播放音乐

可能原因：

• 音乐链接失效
• 浏览器不支持音频格式
• 跨域问题

解决方法：

• 尝试播放其他歌曲
• 使用Chrome或Firefox浏览器
• 检查浏览器控制台错误信息

---

🔒 安全建议

1. 不要在公网暴露此服务 - 仅供本地或局域网使用
2. 定期备份数据 - 备份 files/ 目录
3. 使用强密码 - 建议至少8位，包含字母和数字
4. 不要共享Token - 登录凭证是私密的

---

📞 支持

• QQ交流群: 865754861（喵波音律-音乐家园）
• 项目问题: 查看服务器日志进行调试

---

🎉 更新日志

v2.0.0 (2025-11-23)

• ✅ 添加完整的用户系统
• ✅ 实现歌单管理功能
• ✅ 修复死锁问题
• ✅ 修复密码存储问题
• ✅ 创建完整的Web界面
• ✅ 优化用户体验

v1.0.0 (初始版本)

• 基础音乐搜索和播放
• ESP32设备支持
• 简单收藏功能

---

祝您使用愉快！ 🎵