OmniX-Space/MeowMusicServer
1
0
Fork 0
Code Issues Pull Requests Releases Activity

rebase

Browse Source
This commit is contained in:
苏雨洛
2025-12-09 16:33:44 +08:00
parent 345af5e2a3
commit 1d42f5ea50
49 changed files with 12015 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

493
本地部署指南.md Executable file
View File

@@ -0,0 +1,493 @@
# 🚀 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. ✅ 享受音乐！
---
**祝您使用愉快！** 🎵✨
有问题随时查看文档或联系社区支持！