企业官网建设流程全解析

xiaomusic 在线搜索深度指南：MusicFree 插件 与 LX Server 接口双模式配置与实战

【免费下载链接】xiaomusic使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic

xiaomusic 的在线搜索模块让音箱不再依赖本地曲库——OnlineMusicService（xiaomusic/online_music.py）负责搜索、直链解析、歌词查询，JSPluginManager（xiaomusic/js_plugin_manager.py）负责搜索源接入。读完本文你能拿到三样东西：两种接口生态的选型依据、plugins-config.json每个字段的含义与配置路径、以及语音口令不生效、LX 接口连不上时的排错路径。

底层机制拆解：搜索请求怎么走到音箱

一条"在线播放 江南"的语音请求，数据流经过三层：

1. 口令路由：command_handler.py将唤醒词映射到online_play/singer_play/online_playlist_play，参数以歌名|歌手的管道格式传入（见 xiaomusic/command_handler.py）；
2. 业务编排：OnlineMusicService.online_play先调_parse_keyword_with_ai提取歌名歌手（AI 未启用时回退到_parse_keyword_by_dash，按第一个-拆分），再调get_music_list_online发起搜索，最后由search_top_one_play走_search_top_one打分取最优，经push_music_list_play构造_online_play临时歌单推给已绑定音箱；
3. 搜索源执行：入口get_music_list_online按api_type分流——2走_search_all_platform_lx（LX Server 并行请求），1走_search_all_plugins（MusicFree 插件并行搜索，每插件限额limit // 插件数）。聚合结果统一交给optimize_search_results排序，优先级为「歌曲名匹配度 > 歌手名匹配度 > 插件权重」，插件权重由启用列表顺序决定，仅前 9 个插件有效，排名越靠前分越高（最高 9 分）。

双生态核心差异

⚠️ 两生态互斥：back_conf_info.api_type是1/2的硬切换，切换时前端弹确认框，因为插件列表与平台列表配置互不兼容。

LX Server 侧内置了完整的播放保障链：音质优先级LX_QUALITY_PRIORITY = ["master", "flac24bit", "flac", "320k", "192k", "128k"]，解析失败自动降档；原平台解析失败时按"歌名+歌手+时长误差≤5 秒"跨平台换源；播放前先查${base_url}/music/cache/check缓存，未命中再走进度接口 +/music/url异步解析。MusicFree 侧的 Node 子进程带自愈：_monitor_node_process每 5 秒探活，崩溃后在 60 秒窗口内最多自动重启 1 次，超限需人工介入。

后台可视配置：按操作区域逐项说明

后台配置页位于 xiaomusic/static/onlineSearch/setting.html，配套脚本见 setting-backend.js、setting-musicfree.js、setting-lxserver.js。

接口生态区域

MusicFree 插件区域（仅api_type=1可见）

LX Server 区域（仅api_type=2可见）

高级设置模态框（GET/POST /api/advanced-config/*）

配置文件字段速查：plugins-config.json

配置持久化在运行时目录的conf/plugins-config.json（首次启动由模板 xiaomusic/plugins-config-example.json 生成），插件元数据与文件分别落在该目录的plugins-config.json与js_plugins/下。完整结构：

{ "account": "", "password": "", "auto_add_song": true, "aiapi_info": {"enabled": false, "api_key": ""}, "back_conf_info": { "api_type": 1, "api_options": [ {"name": "MusicFree插件", "type": 1}, {"name": "LXServer接口", "type": 2} ] } }

lx_server_info与music_free_info两个生态节点：

"lx_server_info": { "base_url": "", "x-user-name": "", "x-user-token": "", "auto_convert": false, "platforms": {"tx": "小秋音乐", "kg": "小枸音乐", "kw": "小蜗音乐", "wy": "小芸音乐", "mg": "小蜜音乐"}, "box_play_platform": "all" }, "music_free_info": { "enabled_plugins": [], "plugin_source": {"source_url": ""}, "plugins_info": [], "box_play_platform": "all" }, "voice_playlist_strategy": {"desc": "语音搜单策略", "value": "default"}

⚠️ 涉及配置结构重构的版本升级（如 V1.1.1），旧用户需手动删除conf/plugins-config.json后重启服务，在网页端重新配置。

操作手册：从选型到语音点歌

第一步：选型与生态切换

• 前置条件：已部署 xiaomusic 并可访问后台；MusicFree 路径需有可用的.js插件或订阅源地址，LX 路径需已部署 LX Sync Server；
• 操作动作：后台「接口生态」区域点选目标生态，确认弹窗后保存（POST /api/back-conf/update）；
• 预期反馈：对应配置区（插件列表 / LX 地址表单）切换显示；
• 异常第一反应：确认conf/plugins-config.json中api_type已落盘；若两个配置区同时显示或都不显示，删除配置文件重启重建。

第二步：配置搜索源

MusicFree 路径：填订阅源地址 → 点「更新订阅」（POST /api/plugin-source/refresh，系统校验响应含plugins数组后批量下载）→ 在插件列表中启用 1-3 个可靠插件（注意权重排序）。手动上传仅限.js文件，且ALL.js/all.js/OpenAPI.js/OPENAPI.js为保留名会被 409 拒绝，同名插件重复上传同样 409（POST /api/js-plugins/upload）。在线导入走POST /api/js-plugins/import-online，地址必须http(s)://开头。

LX Server 路径：填base_url→ 点「接口测试」（GET /api/lxServer/test，后端请求${base_url}/music/config并校验player.enableAuth、user.enablePublicRestriction字段判定合法性）→ 按需配鉴权头 → 增删platforms参与聚合。

• 预期反馈：接口测试返回success: true；插件启用后列表状态变绿；
• 异常第一反应：测试失败先查地址是否带/api后缀、服务是否同机可达；插件启用失败查日志中 Node 进程是否存活（60 秒窗口内重启超限会停止自愈）。

第三步：网页搜索与双通道播放

• 前置条件：搜索源已就绪；推音箱播放还要求已在「小爱音箱设置面板」完成绑定；
• 操作动作：搜索页输入歌名 - 歌手（_parse_keyword_by_dash按首个-拆分提升精度），翻页浏览（每页 20 条）；
• 预期反馈：结果带标题、艺术家、专辑、时长、音质与来源平台标签；
• 异常第一反应：某平台结果缺失看该插件/平台是否启用；B 站类源推音箱失败时改用网页端播放（该源音频流可能不被音箱解码支持）。

第四步：开通语音口令

• 前置条件：在「允许唤醒的命令」中加入,singer_play,online_play,——漏配是最常见的不生效原因；
• 操作动作：在线播放 林俊杰 江南或播放歌手 周杰伦；
• 预期反馈：online_play经_search_top_one打分（歌名完全匹配 +90、开头 +70、结尾 +50、包含 +30；歌手匹配按 +9/+7/+5/+3 递减）取最高分播放；singer_play生成_online_歌手名歌单顺序播放；
• 异常第一反应：音箱无响应先核对命令列表；"没找到歌曲"则看box_play_platform是否指到了无结果的单一平台，改all聚合。

进阶能力：AI 口令提取与定时转换

AI 智能口令提取：默认关闭。启用条件为aiapi_info.enabled=true且api_key非空；_parse_keyword_with_ai调用 xiaomusic/utils/openai_utils.py 的analyze_music_command解析模糊指令（如"那首关于秋天的歌"）。接口地址留空默认阿里百炼，模型默认qwen-flash。回退机制：AI 不可用或解析失败时自动退回歌名-歌手的-拆分，功能不中断。

⚠️ 所接大模型必须兼容 OpenAI API 规范，非 OpenAI 协议接口无法使用。

LX 歌单自动转换：auto_convert=true后由js_plugin_manager的_auto_convert_loop每 30 秒拉取 LX 歌单并转换为_online_lx_前缀的 XM 歌单写入曲库；转换出的歌单只有生态切回 LX Server 时才可正常解析播放。手动操作可用GET /api/lxServer/userList、GET /api/lxServer/pullPlaylist、GET /api/lxServer/convertPlaylist（支持playlists参数指定歌单名）。

语音搜单策略：online_playlist_play口令搜到多个歌单时按voice_playlist_strategy.value选取——default取首条、max_songs歌曲数最多、max_plays播放量最高、random随机，选定后经pick_best_playlist拉全量歌曲推给音箱。

后台密码锁（V1.1.2+）：password置非空即启用，进后台时GET /api/password/check返回required: true触发密码框，POST /api/password/verify校验通过方可进入；置空即关闭。

避坑清单

1. LX Music Sync Server v1.8.2+ 增加了 Token 限制，会导致 xiaomusic 接口调用异常——暂不要升级该版本，等待 onlineSearch 适配（V1.1.2 文档说明）。
2. 权重只看前 9 个插件：启用列表超过 9 项时，第 10 个起对聚合搜索权重无贡献，但插件本身仍会被请求。
3. SSRF 防护会拦截内网直链：_make_request_with_validation拒绝内网、回环、链路本地、多播地址，本地测试用公网可达地址或代理。
4. 自动追加只认「全部播放」模式：auto_add_song在随机/单曲循环下无效；该开关早期版本未暴露到前端，需改conf/plugins-config.json的auto_add_song字段。
5. 相对地址已自动归一化：LX Server 返回的相对路径会拼base_url，勿在base_url末尾多加/api之外的路径段导致 404。
6. 保留插件名：ALL/all/OpenAPI/OPENAPI四个名字被系统占用，上传或在线导入均会被拒。

📌 平台歌单同步到音箱的完整方案讨论见 docs/issues/807.md。

源码导航

选型确定后，按「生态切换 → 搜索源配置 → 口令白名单 → 播放通道」四步走一遍，语音点歌、聚合搜索与无限连播即全链路可用；出问题时优先对照api_type落盘值、唤醒命令列表与 LX 版本这三处。

【免费下载链接】xiaomusic使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic