企业官网建设流程全解析

xiaomusic 在线搜索完整指南：2 种接口生态、3 个语音口令与配置字段全解析

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

家里的小爱音箱绑好之后，你很快会碰到一个真实需求：想听一首不在本地曲库里的歌，或者只想"动口不动手"直接点播周杰伦。xiaomusic 的在线搜索模块就是为这个场景准备的——它不依赖本地文件，直接通过你配置的接口生态去搜互联网音乐，把命中的歌曲推送到音箱播放，或直接在网页里在线试听。本文带你走完「选生态 → 填配置 → 配语音口令 → 排错」的完整路径，每个结论都能在源码里找到出处。

在线搜索到底能干啥：一张表看懂能力边界

在线搜索的所有业务都集中在 xiaomusic/online_music.py 的OnlineMusicService里：搜歌、搜歌单、解析播放直链、查歌词。搜索源则由 xiaomusic/js_plugin_manager.py 的JSPluginManager管理。它对外提供 4 类动作：

搜索结果推送到音箱后，就是下面这张图里「播放列表」中的一条歌曲，支持切歌、播放模式切换等操作：

💡 推送功能有前置条件：必须先在「小爱音箱设置面板」完成音箱绑定，否则搜索能成功但没设备可推。

两种接口生态怎么选：先读这张对比表

后台「接口生态」区域是二选一的，同一时间只有一种生效。配置项back_conf_info.api_type取值1= MusicFree 插件、2= LX Server 接口，见 xiaomusic/plugins-config-example.json；请求入口为POST /api/back-conf/update（xiaomusic/api/routers/plugin.py）。切换时前端会弹确认框，因为两套配置字段（插件列表 vs 平台列表）互不兼容。

我的建议：如果你没有任何现成的 LX Sync Server 实例，选 MusicFree 插件版——它开箱即可订阅官方插件市场，不依赖额外服务；如果你已经在跑 LX Sync Server，直接选接口版，配置成本最低且播放保障（换源、缓存、音质降级）由服务端兜底。

方案一：30 秒接入 MusicFree 插件版

一句话原理：JSPluginManager启动一个 Node.js 子进程作为插件沙箱，Python 端通过 stdin/stdout 发 JSON 消息驱动插件完成搜索和取链。

界面操作：

1. 后台配置页「接口生态」选MusicFree插件（即api_type = 1）；
2. 「插件源配置」区域填入订阅地址，点「更新订阅」，系统请求订阅源 JSON，校验包含plugins数组后批量下载插件；
3. 在插件列表里启用/禁用/卸载插件；也可以手动上传.js文件，或粘贴http(s)://地址在线导入单个插件；
4. 启用列表的顺序决定搜索权重：前 9 个插件有效，排第 1 的权重 9 分，排第 9 的权重 1 分。

关键参数（对应conf/plugins-config.json的music_free_info节点）：

上传限制（见upload_js_plugin，xiaomusic/api/routers/plugin.py）：只收.js文件，文件名不能是保留字段ALL / all / OpenAPI / OPENAPI，同名插件不可重复上传。

（进阶）源码级实现：

• 子进程启动：JSPluginManager._start_node_process（xiaomusic/js_plugin_manager.py）执行node --max-old-space-size=128 js_plugin_runner.js，内存上限压到 128MB；另有监控线程，进程挂掉后按重启窗口自动拉起（60 秒窗口内最多重启 1 次）；
• 插件文件存放在conf/js_plugins/目录，元数据写plugins-config.json的music_free_info；
• 聚合搜索：_search_all_plugins（xiaomusic/online_music.py）并行调用所有启用插件，每插件限额按limit // 插件数分配；
• 排序：optimize_search_results里歌名完全匹配 +400 / 开头匹配 +300 / 包含 +200，歌手完全匹配 +1000 / 开头 +800 / 包含 +600，最后加平台权重分。所以「歌手名匹配度」的实际优先级高于「歌曲名匹配度」，再才是插件权重。

方案二：填一个地址接入 LX Server 接口版

一句话原理：把搜索、解析、缓存全部委托给你自建的 LX Sync Server，xiaomusic 只做请求编排和失败降级。

界面操作：

1. 「接口生态」选LXServer接口（api_type = 2）；
2. 填入 API 地址，占位示例http://127.0.0.1:9527/api；
3. V1.1.2+ 点「接口测试」按钮，后端请求${base_url}/music/config并校验返回的player.enableAuth、user.enablePublicRestriction字段来判定是否为合法 LX Server（test_lx_server）；
4. V1.1.3+ 可填x-user-name与x-user-token，请求时自动附加这两个鉴权头；
5. 平台管理区域添加/删除平台（如tx小秋音乐、kg小枸音乐），搜索时并行请求所有已配置平台再合并排序（_search_all_platform_lx）。

最小可运行配置（conf/plugins-config.json，LX 生态只关心这几个字段）：

{ "back_conf_info": { "api_type": 2 }, "lx_server_info": { "base_url": "http://127.0.0.1:9527/api", "x-user-name": "", "x-user-token": "", "auto_convert": false, "platforms": { "tx": "小秋音乐", "kg": "小枸音乐" }, "box_play_platform": "all" } }

（进阶）播放保障机制（均在 xiaomusic/online_music.py）：

• 音质优先级链LX_QUALITY_PRIORITY = ["master", "flac24bit", "flac", "320k", "192k", "128k"]，解析失败自动降一档重试；
• 原平台解析失败时，按「歌名 + 歌手 + 时长误差 ≤ 5 秒」跨平台找同歌曲自动换源；
• 播放前先查${base_url}/music/cache/check，命中缓存直接返回，未命中再走 SSE 进度 +${base_url}/music/url异步解析；
• 返回的相对路径会自动拼上base_url归一化为完整 URL。

⚠️版本兼容提醒：LX Music Sync Server v1.8.2 之后接口增加了 Token 限制，如需使用请暂时不要升级到该版本，等待 onlineSearch 新版适配。

进阶：语音口令与 AI 提取的组合技

三个语音口令，对应后端online_play、singer_play、online_playlist_play：

前置配置：在「允许唤醒的命令」列表中加入singer_play和online_play，否则口令不生效。

online_play的打分逻辑在_search_top_one：歌名完全匹配 +90、开头 +70、结尾 +50、包含 +30；歌手名匹配按 +9/+7/+5/+3 递减，取最高分那首播放。

AI 智能口令提取（默认关闭）：模糊指令如「我想听那首关于秋天的歌」靠传统分割很难命中。开启后，_parse_keyword_with_ai读取aiapi_info配置，当enabled=true且api_key非空时调用 xiaomusic/utils/openai_utils.py 的analyze_music_command提取「歌名 + 歌手」；AI 不可用或解析失败时自动回退到_parse_keyword_by_dash的歌名-歌手分割，功能不中断。接口地址留空默认走阿里百炼，模型默认qwen-flash，只兼容 OpenAI API 规范。

两个进阶开关：

• auto_add_song（顶层字段，默认true）：播放到歌单末尾时自动搜同歌手歌曲追加，仅「全部播放」模式生效；
• voice_playlist_strategy：语音搜歌单的选单策略，default（首条）/max_songs（歌曲最多）/max_plays（播放最多）/random（随机），由pick_best_playlist执行；
• LX 生态专属auto_convert：开启后每 30 秒自动把 LX 歌单转成 XM 歌单（_auto_convert_interval = 30），转换歌单用_online_lx_前缀命名。

排错与避坑：从现象到根因

现象：语音口令说了没反应原因：「允许唤醒的命令」列表缺singer_play/online_play。 解决：在后台唤醒命令选项中补上这两项，无需重启服务。

现象：切换接口生态后搜索报「插件不存在」或「base_url 为空」原因：两套生态配置互不兼容，切换api_type后另一侧字段是空的。 解决：切到哪边就完整配哪边（插件启用列表 or LX 地址 + 平台），确认切换时弹出的提示后再保存。

现象：LX Server 接口测试失败原因：地址不是合法 LX Server，或服务端已升级 v1.8.2+ 触发了 Token 限制。 解决：核对${base_url}/music/config是否返回player.enableAuth字段；确认服务端版本低于 v1.8.2，或等新版适配。

现象：MusicFree 部分歌曲推送到音箱播不了，网页端却能听原因：个别插件（如 B 站源）返回的音频流格式不被小爱音箱支持。 解决：这类资源改用网页端在线播放；或把该插件移出启用列表前 9 位。

现象：升级后在线搜索配置全丢了原因：V1.1.1 重构变更了配置文件结构。 解决：删除conf/plugins-config.json后重启服务，在网页端重新配置。

现象：忘记密码进不了后台原因：password字段非空即启用密码锁。 解决：直接编辑conf/plugins-config.json重置密码；把该字段置空即关闭密码锁。

⚠️安全提示：在线播放直链会经过_make_request_with_validation的 SSRF 防护（xiaomusic/online_music.py），解析到内网、回环、链路本地、多播等地址的 URL 会被拒绝代理，只放行 http/https 公网地址。自定义插件返回内网地址时播放会失败，这是预期行为。

延伸阅读：源码与配置索引

• 在线搜索核心业务（搜索、聚合、直链解析、AI 提取、SSRF 防护）：xiaomusic/online_music.py
• 插件沙箱与 LX 接口管理（Node 子进程、订阅更新、自动转换定时任务、结果排序）：xiaomusic/js_plugin_manager.py
• 全部在线搜索 REST 接口（订阅更新、插件上传、接口测试、生态切换、密码校验）：xiaomusic/api/routers/plugin.py
• 前端搜索页与后台配置页：xiaomusic/static/onlineSearch/index.html、xiaomusic/static/onlineSearch/setting.html 及配套setting-backend.js、setting-musicfree.js、setting-lxserver.js
• 配置文件模板（首次启动复制到conf/plugins-config.json）：xiaomusic/plugins-config-example.json
• AI 口令提取封装：xiaomusic/utils/openai_utils.py

按「先定生态、再配源、后开口令」的顺序走一遍，你就能在小爱音箱上实现语音点歌、聚合搜索、无限连播的完整在线音乐体验。

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