MeowBox-Core/本地部署指南.md

🚀 Meow Music Server - 本地部署指南

📋 系统要求

必需环境

• Go语言: 1.19 或更高版本
• 操作系统: Windows / Linux / macOS
• 浏览器: Chrome / Firefox / Edge / Safari (现代浏览器)

可选工具（用于音频处理功能）

• FFmpeg: 用于音频压缩和转换
• FFprobe: 用于获取音频时长

---

🔧 Windows 本地部署

步骤 1: 检查 Go 环境

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

go version

如果未安装 Go：

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

步骤 2: 进入项目目录

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

步骤 3: 安装依赖

go mod tidy

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

复制配置文件模板：

copy .env.example .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：使用启动脚本（推荐）

start.bat

方式 2：手动启动

go run .

步骤 6: 访问应用

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

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

步骤 7: 首次使用

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

---

🐧 Linux / macOS 部署

步骤 1: 检查 Go 环境

go version

如果未安装：

# Ubuntu/Debian
sudo apt update
sudo apt install golang-go

# macOS (使用 Homebrew)
brew install go

# CentOS/RHEL
sudo yum install golang

步骤 2: 进入项目目录

cd /path/to/MeowEmbeddedMusicServer

步骤 3: 安装依赖

go mod tidy

步骤 4: 配置环境

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

步骤 5: 启动服务器

go run .

或者后台运行：

nohup go run . > server.log 2>&1 &

步骤 6: 访问应用

在浏览器中打开：

• http://localhost:2233/app

---

🏗️ 生产环境部署

编译可执行文件

Windows:

go build -o meow-music-server.exe
meow-music-server.exe

Linux/macOS:

go build -o meow-music-server
./meow-music-server

使用 systemd 服务（Linux）

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

[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

启动服务：

sudo systemctl daemon-reload
sudo systemctl start meow-music
sudo systemctl enable meow-music

查看状态：

sudo systemctl status meow-music

---

🌐 局域网访问配置

步骤 1: 找到本机 IP 地址

Windows:

ipconfig

查找 "IPv4 地址"，例如：192.168.1.100

Linux/macOS:

ifconfig
# 或
ip addr show

步骤 2: 修改 .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):

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:

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

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

Linux/macOS:

# 查看占用端口的进程
lsof -i :2233

# 结束进程
kill -9 <PID>

或者修改 .env 文件使用其他端口：

PORT=3000

问题 2: 无法访问页面

检查清单:

• 服务器是否正常启动？
• 浏览器地址是否正确？
• 防火墙是否允许端口访问？
• 端口号是否正确（默认2233）？

问题 3: 依赖下载失败

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

解决方法:

设置 Go 代理（中国大陆用户）：

# Windows PowerShell
$env:GOPROXY="https://goproxy.cn,direct"

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

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

永久设置：

go env -w GOPROXY=https://goproxy.cn,direct

问题 4: 找不到 .env 文件

解决方法:

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

# Windows
copy .env.example .env

# Linux/macOS
cp .env.example .env

问题 5: 搜索不到音乐

可能原因:

• API源暂时不可用
• 网络连接问题
• 歌曲名称输入错误

解决方法:

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

---

📊 性能优化

1. 编译优化

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

2. 缓存目录

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

3. 数据备份

定期备份 files/ 目录：

# Windows
xcopy /E /I files files_backup

# Linux/macOS
cp -r files files_backup

---

🔒 安全建议

1. 修改默认端口

编辑 .env 文件：

PORT=8080  # 使用非默认端口

2. 使用强密码

注册时使用：

• 至少8个字符
• 包含大小写字母
• 包含数字和特殊字符

3. 局域网隔离

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

4. 定期更新

git pull origin main
go mod tidy

---

📞 获取帮助

遇到问题？

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

常用命令

# 查看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. ✅ 享受音乐！

---

祝您使用愉快！ 🎵✨

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