hanxi/mimusic repository overview

⁠🎵 MiMusic 快速使用指南

🎵 面向个人用户的自托管音乐服务器 — 仅管理你合法拥有的音乐

🏠 GitHub⁠ • 📥 下载⁠ • 📖 文档⁠ • 💬 问题反馈⁠ • 👥 微信群⁠ • 📸 截图⁠

⁠✨ 核心功能

• 🎵 本地音乐管理 — 扫描本地目录，自动提取 MP3/FLAC/WAV/APE/OGG/M4A 等格式的封面和元数据
• 🧩 JS 插件体系 — 基于 QuickJS 沙箱运行，支持权限模型、健康检查、热更新，可自由扩展音源 / 元数据 / 设备控制等能力
• 📱 跨平台客户端 — Flutter 客户端支持 Android、iOS、macOS、Windows、Linux、Web 六端
• 🌐 Web 界面 — 完整版内置 Web 前端，开箱即用
• 🔑 JWT 认证 — 双 Token 机制（Access Token + Refresh Token），支持多设备管理
• 📡 网络歌曲 & 电台 — 支持添加你已合法获取的网络音频 URL 与电台
• 🔁 歌单转本地 — 把你已合法持有的网络音频 URL 离线落盘到本地音乐库，按歌单分目录、可读文件名命名，转换后回写元数据 / 封面 / 歌词。⚠️ 仅限本人合法持有使用权的内容；下载未授权的版权资源属于侵权，由使用者自行承担责任
• 🔌 完整 REST API — 内置 Swagger 文档，方便集成和二次开发
• ⚡ 轻量高效 — Go 编写，CGO-free，无外部依赖，适合 NAS / 树莓派等低功耗设备

⁠⚖️ 版权与免责声明

MiMusic 是一款面向个人用户的自托管工具，定位为帮助用户管理自己合法拥有的音乐文件。在使用本项目前，请务必阅读并理解以下条款：

• 🚫 不提供任何音乐内容 — MiMusic 本身不内置、不分发、不存储任何受版权保护的音乐资源，仅是一个供你管理本地音乐库的开源软件
• ✅ 请仅管理合法来源的音乐 — 用户应仅使用 MiMusic 管理自己合法获得的音乐文件，包括但不限于：
  • 自行购买并下载的数字音乐
  • 从实体唱片转录的个人备份
  • 自己创作或录制的作品
  • 公有领域（Public Domain）作品
  • 明确以 CC（Creative Commons）等开源协议授权的作品
• 🔌 第三方插件免责 — JS 插件由第三方社区维护，主仓库不预置、不分发任何第三方音源插件成品。插件接入的任何网络音源、元数据、歌词内容版权均归原权利人所有。使用网络音源、歌单转本地等功能下载或转存内容时，用户须自行承担版权合规责任，并遵守所在国家 / 地区的法律法规
• 🏠 仅供个人非商业使用 — 严禁将本项目用于商业用途、对外公开分发版权内容，或搭建面向不特定多数人的公共服务
• ⚠️ 责任自担 — 因不当使用本项目（包括但不限于侵犯第三方版权）所引发的任何法律责任、纠纷或损失，均由使用者本人承担，本项目作者及贡献者不承担任何责任
• ™️ 商标声明 — 本项目及内置插件中提到的所有品牌、协议、产品名称（包括但不限于「MIoT」「Bluetooth」「Android」「iOS」「macOS」「Windows」「Docker」等）均归各自商标权人所有。相关名称的出现仅出于互操作和指示性合理使用目的，MiMusic 与上述商标持有人无任何关联，也未获得任何形式的授权或背书。详见 NOTICE⁠
• 🔒 隐私 — MiMusic 服务端不内置任何遥测，所有数据保存在你本地。详见 PRIVACY.md⁠

⁠📋 版本说明

MiMusic 提供两种版本，满足不同使用场景：

⁠🖥️ 平台支持

⁠📦 二进制文件

⁠🌟 完整版（推荐）

包含 Web 前端，开箱即用：

⁠📦 精简版（Lite）

不包含 Web 前端，体积更小：

⁠🐳 Docker 镜像

⁠🌟 完整版（推荐）

⁠📦 精简版（Lite）

⁠📱 Flutter 客户端

除了 Web 界面，MiMusic 还提供功能更强大的跨平台 Flutter 客户端，支持后台播放、本地缓存、媒体控制（耳机/锁屏/通知栏）等服务端 Web 界面无法实现的能力，覆盖 iOS、Android、macOS、Windows、Linux 和 Web 六端。

🔗 GitHub 仓库：mimusic-org/mimusic-player⁠ 📥 下载：GitHub Releases⁠

⁠🚀 快速开始

⁠📦 方式一：直接运行二进制文件

⁠🐧 Linux / 🍎 macOS

# 1️⃣ 下载对应平台的二进制文件（推荐完整版）
# 例如 Linux x86_64 完整版:
wget https://github.com/mimusic-org/mimusic/releases/latest/download/mimusic-linux-amd64-full
mv mimusic-linux-amd64-full mimusic

# 2️⃣ 添加执行权限
chmod +x mimusic

# 3️⃣ 创建必要目录
mkdir -p music data

# 4️⃣ 启动（推荐通过环境变量传入凭证，避免出现在 shell history / 进程列表中）
ADMIN_USERNAME=admin ADMIN_PASSWORD='your_strong_password' ./mimusic

⁠🪟 Windows

# 1️⃣ 下载对应平台的二进制文件（推荐完整版），并重命名为 mimusic.exe
# 例如 Windows x86_64 完整版: mimusic-windows-amd64-full.exe

# 2️⃣ 创建必要目录
mkdir music
mkdir data

# 3️⃣ 设置环境变量并启动（PowerShell）
$env:ADMIN_USERNAME = "admin"
$env:ADMIN_PASSWORD = "your_strong_password"
.\mimusic.exe

⁠🐳 方式二：Docker 部署

⁠🌐 从 Docker Hub 拉取（推荐）

# 🌟 完整版（推荐，包含 Web 前端）
docker pull hanxi/mimusic:full
# 或指定版本: docker pull hanxi/mimusic:1.4.1-full

# 📦 精简版（不含 Web 前端，需搭配 Flutter 客户端使用）
docker pull hanxi/mimusic:latest
# 或指定版本: docker pull hanxi/mimusic:1.4.1

# 运行容器（以完整版为例）
docker run -d \
  --name mimusic \
  -p 58091:58091 \
  -v /path/to/music:/app/music \
  -v /path/to/data:/app/data \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD='your_strong_password' \
  hanxi/mimusic:full

⁠📥 从 Release 离线导入镜像

适合无法直接访问 Docker Hub 的环境：

# 1️⃣ 下载对应平台的 Docker 镜像 tar 文件（推荐完整版）
wget https://github.com/mimusic-org/mimusic/releases/latest/download/mimusic-docker-linux-amd64-full.tar

# 2️⃣ 导入镜像
docker load -i mimusic-docker-linux-amd64-full.tar

# 3️⃣ 查看导入的镜像标签
docker images | grep mimusic

# 4️⃣ 使用上一节的 docker run 命令启动即可（注意替换为导入的镜像标签）

⁠🐙 Docker Compose 部署（推荐）

使用 Docker Compose 可以更方便地管理容器配置：

version: '3.8'

services:
  mimusic:
    image: hanxi/mimusic:full
    container_name: mimusic
    restart: always
    ports:
      - "58091:58091"
    volumes:
      - /path/to/music:/app/music
      - /path/to/data:/app/data
    environment:
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=your_strong_password
      - LISTEN_PORT=58091

将上述内容保存为 docker-compose.yml 文件，然后运行：

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

⁠📋 使用流程

⁠1️⃣ 启动服务

服务启动后，访问 http://localhost:58091 即可打开 Web 界面（仅完整版内置；精简版请使用 Flutter 客户端⁠ 连接）。

⁠2️⃣ 登录系统

使用配置的管理员账号密码登录。

⁠3️⃣ 配置音乐目录

首次登录后，进入「设置」页面配置音乐文件目录（music_path）。Docker 部署时通常配置为 /app/music。

⁠4️⃣ 扫描音乐

在 Web 界面中点击"扫描"按钮，系统会自动扫描音乐目录中的音频文件并提取元数据。

⁠5️⃣ 播放音乐

扫描完成后，即可在界面中浏览和播放音乐。

⁠⚙️ 配置说明

MiMusic 仅依赖少量启动期配置（凭证、端口、数据库路径）通过环境变量或命令行参数指定，其余业务配置（音乐目录、扫描规则、封面存储等）都保存在数据库 config 表中，启动后通过 Web 界面管理。

⁠🌍 环境变量

⁠💻 命令行参数

# 查看帮助
./mimusic -help

# 指定端口
./mimusic -port 8080

# 指定数据库文件路径
./mimusic -db data/mimusic.db

# 指定管理员账号（不推荐，密码会出现在 shell history 和 ps 进程列表中）
./mimusic -username admin -password your_password

⁠💻 系统要求

⁠✅ 校验文件完整性

每个 Release 都包含 checksums.txt 文件，用于验证下载文件的完整性：

# 下载校验和文件
wget https://github.com/mimusic-org/mimusic/releases/latest/download/checksums.txt

# 验证文件
sha256sum -c checksums.txt

⁠📌 版本检查

# 查看版本信息（含 Git Commit / 构建时间 / 构建类型）
./mimusic -version

# 查看完整帮助
./mimusic -help

# 通过 API 检查版本
curl http://localhost:58091/api/v1/version

输出示例：

MiMusic Version: 1.4.1
Git Commit: c8f3171
Build Time: 2026-05-28_13:46:11
Build Type: lite

⁠🔌 插件系统

MiMusic 内置 JS 插件引擎，插件运行在 QuickJS 沙箱中，支持权限模型、健康检查与热更新，可自由扩展音源 / 元数据 / 设备控制等能力。

⁠🎯 插件获取

社区维护的预构建插件集中在 mimusic-org/jsplugins⁠ 仓库，下载 .jsplugin.zip 后在 MiMusic 客户端的「插件管理」页上传即可启用。

⁠🛠️ 插件开发

如需开发自定义插件，请参考以下资源：

• 开发工具链: mimusic-org/plugin-toolchain⁠ — @mimusic/plugin-sdk + @mimusic/plugin-builder + 脚手架
• 快速开始: pnpm create mimusic-plugin <name>，详见 JS 插件开发指南⁠

⁠📖 API 文档

完整的 API 文档（Swagger/OpenAPI 格式）可在以下地址查看：

• Swagger API 文档: swagger.json⁠
• Swagger UI 在线查看: petstore.swagger.io⁠
• 本地查看: 启动服务后访问 http://localhost:58091/swagger/index.html

⁠主要接口概览

⁠❓ 常见问题

遇到问题？请查看 常见问题与解决方案⁠ 💬

⁠🛠️ 技术支持

• GitHub: mimusic-org/mimusic⁠
• Issues: 问题与反馈⁠
• 💬 加入微信群交流：微信群二维码⁠
• 🐧 QQ群: 979995241

⁠📝 更新日志

详细的版本更新记录请查看 CHANGELOG.md⁠。

⁠📄 许可证

本项目基于 Apache-2.0 License⁠ 开源。