MeowMusicServer/本地部署指南.md

# 🚀 Meow Music Server - 本地部署指南

## 📋 系统要求

### 必需环境
- **Go语言**: 1.19 或更高版本
- **操作系统**: Windows / Linux / macOS
- **浏览器**: Chrome / Firefox / Edge / Safari (现代浏览器)

### 可选工具（用于音频处理功能）
- **FFmpeg**: 用于音频压缩和转换
- **FFprobe**: 用于获取音频时长

---

## 🔧 Windows 本地部署

### 步骤 1: 检查 Go 环境

打开命令提示符（CMD）或 PowerShell，检查 Go 是否已安装：

```bash
go version
```

**如果未安装 Go：**
1. 访问 https://golang.org/dl/
2. 下载 Windows 安装包
3. 运行安装程序
4. 重新打开终端验证安装

### 步骤 2: 进入项目目录

```bash
cd d:\esp32-music-server\Meow\MeowEmbeddedMusicServer
```

### 步骤 3: 安装依赖

```bash
go mod tidy
```

### 步骤 4: 配置环境变量（可选）

复制配置文件模板：
```bash
copy .env.example .env
```

编辑 `.env` 文件（使用记事本或其他编辑器）：
```env
# 服务器端口
PORT=2233

# 网站信息
WEBSITE_NAME_CN=我的音乐服务器
WEBSITE_NAME_EN=My Music Server

# API 源（默认已配置，无需修改）
API_SOURCES=kuwo
API_SOURCES_1=netease
API_SOURCES_2=migu
API_SOURCES_3=baidu
```

### 步骤 5: 启动服务器

**方式 1：使用启动脚本（推荐）**
```bash
start.bat
```

**方式 2：手动启动**
```bash
go run .
```

### 步骤 6: 访问应用

服务器启动后，在浏览器中访问：

- **新版用户界面**: http://localhost:2233/app
- **经典界面**: http://localhost:2233/

### 步骤 7: 首次使用

1. 打开浏览器访问 http://localhost:2233/app
2. 点击"注册"创建账户
3. 填写用户名、邮箱和密码
4. 注册成功后自动登录
5. 开始搜索和收藏音乐！

---

## 🐧 Linux / macOS 部署

### 步骤 1: 检查 Go 环境

```bash
go version
```

**如果未安装：**
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install golang-go

# macOS (使用 Homebrew)
brew install go

# CentOS/RHEL
sudo yum install golang
```

### 步骤 2: 进入项目目录

```bash
cd /path/to/MeowEmbeddedMusicServer
```

### 步骤 3: 安装依赖

```bash
go mod tidy
```

### 步骤 4: 配置环境

```bash
cp .env.example .env
nano .env  # 或使用 vim/其他编辑器
```

### 步骤 5: 启动服务器

```bash
go run .
```

或者后台运行：
```bash
nohup go run . > server.log 2>&1 &
```

### 步骤 6: 访问应用

在浏览器中打开：
- http://localhost:2233/app

---

## 🏗️ 生产环境部署

### 编译可执行文件

**Windows:**
```bash
go build -o meow-music-server.exe
meow-music-server.exe
```

**Linux/macOS:**
```bash
go build -o meow-music-server
./meow-music-server
```

### 使用 systemd 服务（Linux）

创建服务文件 `/etc/systemd/system/meow-music.service`：

```ini
[Unit]
Description=Meow Music Server
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/path/to/MeowEmbeddedMusicServer
ExecStart=/path/to/MeowEmbeddedMusicServer/meow-music-server
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
```

启动服务：
```bash
sudo systemctl daemon-reload
sudo systemctl start meow-music
sudo systemctl enable meow-music
```

查看状态：
```bash
sudo systemctl status meow-music
```

---

## 🌐 局域网访问配置

### 步骤 1: 找到本机 IP 地址

**Windows:**
```bash
ipconfig
```
查找 "IPv4 地址"，例如：192.168.1.100

**Linux/macOS:**
```bash
ifconfig
# 或
ip addr show
```

### 步骤 2: 修改 .env 配置

```env
WEBSITE_URL=http://192.168.1.100:2233
EMBEDDED_WEBSITE_URL=http://192.168.1.100:2233
```

### 步骤 3: 防火墙设置

**Windows 防火墙:**
1. 控制面板 → Windows Defender 防火墙
2. 高级设置 → 入站规则 → 新建规则
3. 选择"端口" → TCP → 特定本地端口 → 2233
4. 允许连接 → 完成

**Linux (UFW):**
```bash
sudo ufw allow 2233/tcp
sudo ufw reload
```

### 步骤 4: 其他设备访问

在同一局域网的其他设备浏览器中访问：
```
http://192.168.1.100:2233/app
```

---

## 📁 目录结构说明

部署后的目录结构：

```
MeowEmbeddedMusicServer/
├── main.go                    # 主程序入口
├── user.go                    # 用户认证模块
├── playlist.go                # 歌单管理
├── api.go                     # 音乐搜索API
├── helper.go                  # 工具函数
├── struct.go                  # 数据结构
├── go.mod                     # Go依赖配置
├── .env                       # 环境配置（需创建）
├── start.bat                  # Windows启动脚本
│
├── theme/                     # 前端界面
│   ├── music-app.html         # 新版用户界面
│   └── index.html             # 经典界面
│
├── files/                     # 数据存储目录（自动创建）
│   ├── users.json             # 用户数据
│   ├── user_playlists.json    # 用户歌单
│   └── playlists.json         # 全局歌单（兼容）
│
└── cache/                     # 音乐缓存（自动创建）
    └── music/                 # 下载的音乐文件
```

---

## 🔍 故障排除

### 问题 1: 端口被占用

**错误信息**: `bind: address already in use`

**解决方法**:

**Windows:**
```bash
# 查看占用端口的进程
netstat -ano | findstr :2233

# 结束进程（替换PID）
taskkill /PID <进程ID> /F
```

**Linux/macOS:**
```bash
# 查看占用端口的进程
lsof -i :2233

# 结束进程
kill -9 <PID>
```

或者修改 `.env` 文件使用其他端口：
```env
PORT=3000
```

### 问题 2: 无法访问页面

**检查清单**:
- [ ] 服务器是否正常启动？
- [ ] 浏览器地址是否正确？
- [ ] 防火墙是否允许端口访问？
- [ ] 端口号是否正确（默认2233）？

### 问题 3: 依赖下载失败

**错误信息**: `go: downloading ... failed`

**解决方法**:

设置 Go 代理（中国大陆用户）：
```bash
# Windows PowerShell
$env:GOPROXY="https://goproxy.cn,direct"

# Windows CMD
set GOPROXY=https://goproxy.cn,direct

# Linux/macOS
export GOPROXY=https://goproxy.cn,direct
```

永久设置：
```bash
go env -w GOPROXY=https://goproxy.cn,direct
```

### 问题 4: 找不到 .env 文件

**解决方法**:

如果 `.env` 文件不存在，服务器会使用默认配置。可以手动创建：

```bash
# Windows
copy .env.example .env

# Linux/macOS
cp .env.example .env
```

### 问题 5: 搜索不到音乐

**可能原因**:
- API源暂时不可用
- 网络连接问题
- 歌曲名称输入错误

**解决方法**:
1. 检查网络连接
2. 尝试不同的歌曲名称
3. 等待片刻后重试
4. 查看服务器日志确认API响应

---

## 📊 性能优化

### 1. 编译优化

```bash
# 编译时优化
go build -ldflags="-s -w" -o meow-music-server
```

### 2. 缓存目录

定期清理 `cache/` 目录中的旧文件，避免占用过多磁盘空间。

### 3. 数据备份

定期备份 `files/` 目录：
```bash
# Windows
xcopy /E /I files files_backup

# Linux/macOS
cp -r files files_backup
```

---

## 🔒 安全建议

### 1. 修改默认端口

编辑 `.env` 文件：
```env
PORT=8080  # 使用非默认端口
```

### 2. 使用强密码

注册时使用：
- 至少8个字符
- 包含大小写字母
- 包含数字和特殊字符

### 3. 局域网隔离

如果仅本机使用，不要配置局域网访问。

### 4. 定期更新

```bash
git pull origin main
go mod tidy
```

---

## 📞 获取帮助

### 遇到问题？

1. **查看日志**: 服务器启动后的控制台输出
2. **检查文档**: 阅读 `USER_SYSTEM_README.md`
3. **社区支持**: 喵波音律-音乐家园QQ群：865754861
4. **GitHub Issues**: 在项目仓库提交问题

### 常用命令

```bash
# 查看Go版本
go version

# 查看项目依赖
go list -m all

# 清理编译缓存
go clean -cache

# 重新下载依赖
go mod download
```

---

## ✅ 部署检查清单

部署前请确认：

- [ ] Go 已安装（1.19+）
- [ ] 项目代码已下载
- [ ] 依赖已安装（go mod tidy）
- [ ] .env 文件已配置（可选）
- [ ] 端口 2233 未被占用
- [ ] 防火墙允许端口访问
- [ ] 浏览器版本较新

部署后验证：

- [ ] 服务器成功启动
- [ ] 可以访问 http://localhost:2233/app
- [ ] 可以注册新用户
- [ ] 可以搜索音乐
- [ ] 可以创建歌单
- [ ] 可以播放音乐

---

## 🎉 开始使用

部署完成后，按照以下步骤开始：

1. ✅ 访问 http://localhost:2233/app
2. ✅ 注册您的账户
3. ✅ 搜索喜欢的音乐
4. ✅ 创建个人歌单
5. ✅ 享受音乐！

---

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

有问题随时查看文档或联系社区支持！