Music Together

在线多人同步听歌平台 -- 创建房间，邀请朋友，一起实时听同一首歌。

English

截图

桌面端

移动端

歌词展示对比

功能特性

• 实时同步播放 -- 基于 NTP 时钟同步 + 定时执行，延迟极低
• 多平台音源 -- 支持网易云音乐、QQ 音乐、酷狗音乐搜索与播放
• Apple Music 风格歌词 -- 逐词高亮动画歌词，桌面端/移动端自适应
• VIP 歌曲支持 -- 平台账号登录贡献 Cookie，解锁 VIP 曲目（房间级作用域）
• 权限管理 (RBAC) -- 房主 > 管理员 > 普通成员，细粒度权限控制
• 临时管理员转移 -- 非空房间始终保留至少一个具备管理能力的在线用户
• 投票系统 -- 普通成员通过投票控制切歌、暂停等操作
• 播放模式 -- 顺序播放、单曲循环、列表循环、随机播放
• 实时聊天 -- 房间内文字聊天，支持系统消息
• 移动端适配 -- 响应式设计，横竖屏自动切换布局

快速开始

环境要求

• Node.js >= 24.15.0
• pnpm >= 10

生产部署必须设置至少 32 字符的随机 IDENTITY_SECRET；本地开发可使用默认开发配置。

安装与开发

git clone https://github.com/Yueby/music-together.git
cd music-together
pnpm install
pnpm dev

提交代码前可运行：

pnpm test
pnpm --filter @music-together/client typecheck
pnpm --filter @music-together/client lint
pnpm build

前端: http://localhost:5173 | 后端: http://localhost:3001

部署

Docker 单镜像部署：

docker run -d --name music-together --restart unless-stopped \
  -p 3001:3001 \
  -e IDENTITY_SECRET='<至少32字符的随机密钥>' \
  ghcr.io/yueby/music-together:latest

如果宿主机 3001 端口已被占用，修改 -p 宿主机端口:容器端口 左侧端口即可，例如 -p 8080:3001。

默认自动模式下，前端会按当前访问地址自动连接后端；服务端默认开放所有来源访问，并根据当前请求协议自动决定 cookie 是否带 Secure。

需要显式限制来源时，再配置 CLIENT_URL：

docker run -d --name music-together --restart unless-stopped \
  -p 3001:3001 \
  -e IDENTITY_SECRET='<至少32字符的随机密钥>' \
  -e CLIENT_URL=https://music.example.com \
  ghcr.io/yueby/music-together:latest

CLIENT_URL 现在主要用于显式白名单模式或前后端分离部署；默认自动模式下通常不再需要手动设置。

如果你通过 Nginx / Caddy / 1Panel / Lucky 等反向代理暴露 HTTPS，请确保代理正确透传 X-Forwarded-Proto，否则服务端无法自动判断应该下发 Secure cookie。

push 到 main 后 GitHub Actions 自动构建镜像。详见 架构文档。

项目结构

packages/
  client/   -- 前端 React 应用
  server/   -- 后端 Node.js 服务
  shared/   -- 共享类型、常量与权限定义

致谢

协议

AGPL-3.0