akari787/xiaomusic-core
akari787
xiaomusic-core 是基于原版 xiaomusic 的独立维护分支
下载次数: 0状态：社区镜像维护者：akari787仓库类型：镜像最近更新：30 天前
让 AI 帮你使用轩辕镜像？ · 展开查看说明 · 点击收起说明
如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。
只需在 AI 对话中先发送下面这句话即可：
请先完整阅读并严格遵守以下文档中的全部规则与要求：
https://xuanyuan.cloud/agents.md
在未充分阅读并理解该文档前，不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。查看 agents.md 用法指南与完整示范。国内用户首推 元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。 若 AI 无法访问外链，可 打开说明文档 复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。
xiaomusic-core
小爱音箱播放控制核心，聚焦自托管部署、认证运行时恢复与来源扩展能力。
1. 项目简介
xiaomusic-core 是基于 https://github.com/hanxi/xiaomusic 的独立维护分支，当前核心维护方向是小爱音箱交互、播放控制与认证运行时基础的稳定性。
2. 特性概览
核心能力
- 统一播放控制：
POST /api/v1/play为唯一正式播放入口，所有播放请求经由统一调度链路执行 - 控制面与状态面分离：命令接口与播放状态观测相互独立，状态通过
GET /api/v1/player/state与 SSE 流获取 - 认证运行时恢复：扫码登录后 auth.json 持久化，短期会话失效时自动从长期态重建，无需频繁重新扫码
来源与扩展
- 来源扩展层：播放能力通过统一的来源扩展层接入，当前支持直链（direct_url）、本地媒体库（local_library）、Jellyfin、站点媒体（site_media）等
工程化能力
- API v1：
/api/v1/*为唯一正式对外接口层，统一 envelope 与结构化错误模型 - WebUI：React + TypeScript 前端，默认后端托管构建产物
- 自托管部署：Docker Hub 镜像分发，配套 hardened compose 与安全默认配置（HTTP_AUTH_HASH、SSRF 防护、日志脱敏）
3. 快速开始
bash# 1. 准备目录 mkdir -p conf music # 2. 拉取镜像 docker pull akari787/xiaomusic-core:stable # 3. 启动容器（使用 HTTP_AUTH_PASSWORD 自动生成哈希） docker run -d --name xiaomusic-core \ -p 58090:8090 \ -v $(pwd)/conf:/app/conf \ -v $(pwd)/music:/app/music \ -e HTTP_AUTH_PASSWORD='your_password' \ akari787/xiaomusic-core:stable # 4. 访问 # http://<HOST>:58090/
说明：
- 若提供
HTTP_AUTH_PASSWORD，容器启动时会自动生成 bcrypt 哈希并用于运行时认证，无需手动生成 - 若希望使用固定哈希，也可直接提供
HTTP_AUTH_HASH（可通过python scripts/generate_password_hash.py生成） - 两者都提供时，优先使用
HTTP_AUTH_HASH - 启动后在设置页完成扫码登录即可使用
4. 文档导航
入口索引（AI 开工必读）
| 文档 | 说明 |
|---|---|
| ARCHITECTURE.md | AI 开工协议入口，含九大边界与约束清单 |
| Architecture 文档地图 | 架构文档索引 |
| Spec 文档地图 | 规范文档索引（规范 > 架构） |
| API v1 规范 | v1 接口契约、白名单、错误模型 |
| AI Review Checklist | 提交前检查清单 |
关键专题文档（按领域）
| 文档 | 说明 |
|---|---|
| 系统总览 | 九大边界、调用规则、文档优先级 |
| 状态权威与约束 | 状态权威归属、禁止跨边界规则 |
| 播放状态快照规范 | 权威状态快照字段模型 |
| SSE 推送协议 | 播放状态主通道、重连、心跳 |
| WebUI 状态机规范 | 前端状态机定义 |
| Runtime 技术规范 | core 层数据模型、错误体系 |
| Relay 术语 | relay/proxy/delivery 术语定义 |
| ADR 目录 | 架构决策记录 |
auth 主线阅读路径
详见 auth spec 子目录入口，包含恢复链路、状态机、singleflight 等文档。
5. Roadmap
- 统一播放入口已收敛到
POST /api/v1/play，旧并行播放入口已移除 -
/api/v1/*已明确为唯一正式对外接口层，接口白名单、错误模型与分级契约已形成文档约束 - 控制面与状态面已拆分，播放器权威状态通过
GET /api/v1/player/state与GET /api/v1/player/stream提供 - 认证运行时恢复链路已建立，长期态 / 短期态分层、auth.json 持久化与 runtime re***d 已落地
- WebUI 主流程已围绕 v1 正式控制面持续收敛
- 核心能力与来源扩展边界仍需继续收敛，减少实现层相互渗透
- 现有来源能力仍需进一步整理为更清晰的插件范式
- 播放稳定性与认证恢复可观测性仍需继续加强
- 自托管部署体验与安全默认配置仍需持续打磨
6. 免责声明与致谢
本项目为非官方项目，与小米公司无关。
感谢 https://github.com/hanxi/xiaomusic 原作者与社区贡献，以及 Jellyfin 等开源生态支持。
许可证：MIT
镜像拉取方式
您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本，请访问 标签列表页面。
轩辕镜像加速拉取命令点我查看更多 xiaomusic-core 镜像标签
docker pull docker.xuanyuan.run/akari787/xiaomusic-core:<标签>
DockerHub 原生拉取命令
docker pull akari787/xiaomusic-core:<标签>
镜像拉取常见问题
功能
错误码
用户好评
来自真实用户的反馈，见证轩辕镜像的优质服务
oldzhang
运维工程师
Linux服务器
5
"Docker访问体验非常流畅，大镜像也能快速完成下载。"