MeowMusicServer/使用说明.md

# 🎵 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设备支持
- 简单收藏功能

---

**祝您使用愉快！** 🎵