rebase

2025-12-09 16:33:44 +08:00
parent 345af5e2a3
commit 1d42f5ea50
49 changed files with 12015 additions and 1 deletions
--- a/使用说明.md
+++ b/使用说明.md
@@ -0,0 +1,363 @@
+# 🎵 Meow Music 使用说明
+
+## 📋 功能概览
+
+Meow Music 是一个完整的音乐播放和管理系统，包含以下功能：
+
+### ✨ 核心功能
+
+1. **用户系统**
+   - 用户注册和登录
+   - 密码加密存储（bcrypt）
+   - Token认证机制
+
+2. **音乐搜索**
+   - 实时搜索音乐
+   - 显示歌曲标题和艺术家
+   - 搜索结果缓存
+
+3. **在线播放**
+   - 内置音频播放器
+   - 显示当前播放信息
+   - 支持标准音频控制
+
+4. **我喜欢**
+   - 快速收藏喜欢的歌曲
+   - 查看收藏列表
+   - 移除收藏
+
+5. **歌单管理**
+   - 创建自定义歌单
+   - 添加/删除歌曲
+   - 查看歌单详情
+
+---
+
+## 🚀 快速开始
+
+### 1. 启动服务器
+
+#### Windows:
+```powershell
+# 方式1：双击启动
+双击 start.bat
+
+# 方式2：命令行启动
+cd d:\esp32-music-server\Meow\MeowEmbeddedMusicServer
+go run .
+```
+
+#### Linux/macOS:
+```bash
+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接口
+
+### 用户认证
+
+#### 注册
+```http
+POST /api/auth/register
+Content-Type: application/json
+
+{
+  "username": "用户名",
+  "email": "邮箱",
+  "password": "密码"
+}
+```
+
+#### 登录
+```http
+POST /api/auth/login
+Content-Type: application/json
+
+{
+  "username": "用户名",
+  "password": "密码"
+}
+```
+
+#### 获取当前用户
+```http
+GET /api/auth/me
+Authorization: Bearer {token}
+```
+
+#### 登出
+```http
+POST /api/auth/logout
+Authorization: Bearer {token}
+```
+
+### 音乐搜索
+
+#### 搜索歌曲
+```http
+GET /api/search?query={关键词}
+```
+
+### 收藏管理
+
+#### 添加到收藏
+```http
+POST /api/favorite/add
+Content-Type: application/json
+
+{
+  "title": "歌曲名",
+  "artist": "艺术家",
+  "url": "播放链接"
+}
+```
+
+#### 获取收藏列表
+```http
+GET /api/favorite/list
+```
+
+#### 从收藏移除
+```http
+POST /api/favorite/remove
+Content-Type: application/json
+
+{
+  "title": "歌曲名",
+  "artist": "艺术家"
+}
+```
+
+### 歌单管理
+
+#### 获取用户歌单
+```http
+GET /api/user/playlists
+Authorization: Bearer {token}
+```
+
+#### 创建歌单
+```http
+POST /api/user/playlists/create
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "name": "歌单名称",
+  "description": "歌单描述"
+}
+```
+
+#### 添加歌曲到歌单
+```http
+POST /api/user/playlists/add-song?playlist_id={歌单ID}
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "title": "歌曲名",
+  "artist": "艺术家",
+  "url": "播放链接"
+}
+```
+
+#### 从歌单移除歌曲
+```http
+DELETE /api/user/playlists/remove-song?playlist_id={歌单ID}&title={歌曲名}&artist={艺术家}
+Authorization: Bearer {token}
+```
+
+#### 删除歌单
+```http
+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`，找到：
+```go
+port := "2233"
+```
+修改为您想要的端口号。
+
+### 数据存储位置
+
+所有数据存储在 `./files/` 目录下：
+- `users.json` - 用户账户信息（包含加密密码）
+- `user_playlists.json` - 用户创建的歌单
+- `playlists.json` - 遗留的公共歌单
+
+---
+
+## 🐛 故障排除
+
+### 问题1：端口被占用
+```
+listen tcp :2233: bind: Only one usage of each socket address...
+```
+
+**解决方法：**
+```powershell
+# 查找占用端口的进程
+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设备支持
+- 简单收藏功能
+
+---
+
+**祝您使用愉快！** 🎵