1. 私有云音乐服务为什么要折腾在线曲库

本地曲库玩久了都会遇到同一个尴尬：硬盘里躺着几千首无损，想听一首刚在短视频里刷到的歌，翻遍目录也找不到。飞牛音乐这类跑在自家机器上的音乐服务，扫描本地目录、生成曲库、对外提供播放接口，体验其实已经相当顺，问题在于它的世界是封闭的——曲库边界就是你硬盘的边界。我最初只是想给家里的老人机场景补一个"搜一下就能听"的入口，结果一路做到了多歌单聚合加内置大模型点歌，中间踩的坑比预想多得多，索性把整套二开思路完整写一遍。

这篇内容面向三类人：一是已经在用私有云音乐服务、想扩一条在线曲库通道的人；二是有一定 Go / TypeScript 基础、想读懂一个中型二开项目该怎么拆模块的人；三是想在自己的服务里塞一个"能用自然语言点歌"的大模型入口、但不知道从何下手的人。核心关键词就三个：在线曲库、多歌单、内置大模型源。我会从架构选型讲到字段映射，从缓存策略讲到 Prompt 约束，最后给一份能直接对照的排查表。文中所有接口、字段、参数都来自我自己那套跑了大半年的实现，按你的环境改改就能用。

先明确一件事：飞牛音乐本身是一个偏"本地优先"的音乐服务，二开的核心不是推倒重来，而是在它已有的曲库层之上，平行插一层"远程源"。这个定位决定了后面所有的设计取舍——包括为什么我没有直接换一套现成的音乐服务器，而是选择在原项目里做加法。

1.1 本地库的三个天然短板

第一是数量天花板。个人收藏再猛也就几万首，跟任何在线曲库比都是零头。第二是时效性断层，新歌、冷门曲、现场版、翻唱版，本地库基本靠人工搬运，搬运成本高到没人愿意坚持。第三是发现能力缺失，本地库只能"你搜什么它给什么"，它不会告诉你"今晚适合听点什么"。

这三个短板恰好对应三种不同的补法：数量靠接入在线源，时效靠搜索直连，发现能力靠大模型。这也是整个二开方案的三根支柱，后面每一章都对应其中一根。

1.2 二开还是换方案：一次不太纠结的选型

我认真对比过两条路。路线 A 是直接换一套成熟的开源音乐服务器，它天生支持外挂源和插件；路线 B 是在飞牛音乐上做二次开发。最后选 B，理由有三条，都很实在。

一是客户端生态已经绑死了。家里电视、手机、车机上的播放器都是按现有接口适配的，换后端意味着所有终端重配一遍，这个成本我承担不起。二是曲库元数据迁移麻烦，播放次数、评分、自定义标签这些沉淀数据，跨系统迁移基本靠手写脚本，容易丢。三是可控性，飞牛音乐的后端结构不算复杂，曲库、播放列表、流媒体输出这几块边界清晰，插一层适配器的改动量比我预想的小。

提示：二开的前提是你愿意跟着上游版本走。我建议把改动尽量收在独立包和独立配置里，不要就地改核心文件，否则上游一发版你就是一整天的手工合并。

1.3 三层解耦：整个改造的骨架

我把改动拆成三层，层与层之间只通过结构体通信，任何一层替换都不影响其他两层。

这个分层最大的好处是在线源可以无限加。后来我加第三个源的时候，只需要写一个两百行的 Provider 文件加一段配置，聚合层和前端一行没动。这种"扩展成本恒定"的设计，比一开始就把所有源硬编码进搜索结果里要值太多。

2. 在线曲库层：把异构来源压成一套标准结构

在线曲库最难的地方从来不是"能不能搜到"，而是"搜到的东西能不能像本地曲目一样被播放器消费"。不同来源返回的字段名、时长单位、封面地址、音质标记全都不一样，有的给毫秒有的给秒，有的封面是直链有的要拼参数。所以第一件事不是写请求，是定标准。

2.1 数据模型：先定 Track，再谈搜索

我定义了一个内部统一的Track结构，所有源返回的结果必须先转成它，才能进入后续流程。这是整个项目里最值得先做的一件事，没有之一。

type Track struct { UID string // 全局唯一：source + ":" + sourceID 的哈希 Source string // local / provider_a / provider_b / llm SourceID string // 源内 ID，回源取流时用 Title string Artist string Album string Duration int // 统一毫秒 CoverURL string Bitrate int // kbps，未知填 0 Ext string // mp3 / flac / m4a Score float64 }

几个字段的取值我踩过坑。Duration一定要统一成毫秒，我最初偷懒让各源自己带单位，结果排序和"时长相近去重"全部错乱。Bitrate未知时必须填 0 而不是 -1 或 999，否则前端排序会把未知音质的曲目顶到最前面。CoverURL只存原始地址，不做本地化，因为大部分源的封面带防盗链签名，落盘反而会失效，交给前端加referrerpolicy更省事。

注意：UID千万别用自增 ID。在线源的结果是每次搜索动态生成的，自增 ID 会导致同一个曲目每次搜索 ID 都变，收藏和歌单引用全部失效。用source + sourceID的稳定哈希，跨重启也不会漂移。

2.2 搜索适配器：写得糙一点，反而更抗造

每个源的搜索适配器我都控制在 150 行以内，结构完全一致：拼请求、发请求、解析、映射、返回。不搞抽象工厂，不搞泛型，就是五个函数排排坐。这不是偷懒，是刻意的——第三方接口随时会变，适配器越薄，改起来越快。

type Provider interface { Name() string Search(ctx context.Context, kw string, limit int) ([]Track, error) Resolve(ctx context.Context, t Track) (Stream, error) } type Stream struct { URL string Expires time.Time Headers map[string]string }

Resolve单独拆出来的原因很关键：搜索结果里的播放地址往往是临时签名链接，有效期短则几分钟。如果在搜索阶段就把 URL 存进Track，用户点开时大概率已经过期，表现就是"搜得到、点不动"。我的做法是搜索阶段只返回SourceID，真正播放前再调一次Resolve换取新鲜地址。多一次请求，换来的是几乎为零的播放失败率。

适配器内部还有两个小细节值得说。一是超时必须是可控的，我给每个源单独设 4 秒超时，用context.WithTimeout包住，任何一个源卡住都不拖累整体。二是错误要分类，网络错误、鉴权失败、限流、空结果要分开返回，前端才能给出"这个源暂时不可用"还是"确实没这首歌"的不同提示。混成一个 error 的话，排查起来会非常痛苦。

2.3 并发聚合、去重与排序

聚合层做三件事：并发调所有 Provider、合并结果、去重排序。并发用errgroup加信号量控制，同时打到所有源，任何一个失败只记日志不中断整体。

func (a *Aggregator) Search(ctx context.Context, kw string) ([]Track, error) { g, ctx := errgroup.WithContext(ctx) ch := make(chan []Track, len(a.providers)) for _, p := range a.providers { p := p g.Go(func() error { res, err := p.Search(ctx, kw, 20) if err != nil { return nil // 单源失败不影响整体 } ch <- res return nil }) } go func() { _ = g.Wait(); close(ch) }() var all []Track for part := range ch { all = append(all, part...) } return a.rank(dedupe(all)), nil }

去重是这里最容易做糙的地方。只用标题完全相同去重会漏掉一堆，用模糊匹配又会误杀。我最终的策略是归一化后的标题+艺术家主字段相等，且时长差值在 5 秒以内才判定为同一首。归一化包括：全角转半角、去括号内版本标记（live/伴奏/remix）、小写化、去掉常见标点。5 秒的容差是实测出来的——不同源同一首歌的时长差异普遍在 1~3 秒，超过 5 秒基本就是不同版本了。

排序权重我用了四段：源优先级（自建源 > 公有源）、标题匹配度（完全包含 > 分词命中）、音质（有码率信息优先）、时长完整度（时长未知的降权）。把这四个权重做成配置项放在配置文件里，后期调参不用重新编译。

2.4 缓存与限流：让在线源表现得像本地一样

在线源再快也比本地慢，而且调用是有成本的。缓存分两级，策略完全不同：

搜索缓存 TTL 设 10 分钟是个平衡点。太短没意义（用户来回切页面会重复打请求），太长会拿到过期结果（某些源下架很快）。

限流用令牌桶，按源独立配置。我给公有源的默认值是每秒 3 个请求、桶容量 6，允许短时突发但长期不超过阈值。这个数值不是拍脑袋的：连续搜索场景下用户平均每次输入会触发 4~6 次请求（输入防抖 300ms），3 QPS 刚好够用且不会触发对方风控。

提示：限流一定要做在聚合层而不是适配器里。适配器只管发请求，限流统一收口，否则将来加源的时候很容易漏掉，一次批量扫描就能把配额打光。

3. 多歌单体系：从聚合展示到可编辑的完整链路

多歌单这个需求看起来简单，实际上是把"播放列表"从一个附属功能升级成系统的一等公民。本地歌单、在线歌单、大模型生成的歌单，三者的数据来源、更新频率、可编辑程度完全不同，但用户希望它们长得一样、操作一样。

3.1 歌单对象的统一建模

我没有为每种歌单建一张表，而是用一套结构加type字段区分。

{ "id": "pl_7f3a", "name": "深夜通勤", "type": "local", "source": "", "track_uids": ["local:8a2f", "provider_a:19bc"], "revision": 12, "editable": true, "created_at": 1730000000, "updated_at": 1730086400 }

track_uids只存 UID 不存完整曲目信息，这是个重要决定。存完整信息意味着同一个曲目在十个歌单里存十份，元数据一更新就要批量回写；存 UID 则只需要播放时批量解引用，内存和更新成本都低。代价是解引用要做批量查询和缺失兜底——如果某个在线源下架了某首歌，UID 就查不到了，这时不能整单报错，要返回占位对象并在 UI 上标灰。

editable字段用来区分只读源。从外部导入的歌单通常是只读的，只能整体同步或删除，不能单曲增删。UI 层根据这个字段决定是否显示拖拽排序入口。

3.2 多源歌单的同步与去重

外部歌单同步我用的是全量拉取 + 增量比对的笨办法，而不是增量接口。原因很现实：能提供稳定增量接口的源太少，而歌单条目量级通常在几百到几千，全量拉一次的成本完全可以接受。

同步流程是这样的：拉取远端歌单 → 转成Track数组 → 逐条计算 UID → 与本地现有 UID 列表比对 → 生成新增/删除/保留三个集合 → 差异超过阈值时提示用户确认。

去重逻辑和搜索层共用同一套归一化函数，保证"搜索时认为是同一首歌的，加入歌单时也不会重复"。这里有个细节：同一个歌单里允许存在同一首歌的两个不同版本（比如录音室版和现场版），所以去重键要带上时长和专辑，不能只用标题+艺术家。

revision字段是并发控制的核心。每次写操作都要求客户端带上当前 revision，服务端比对不一致就拒绝并返回最新数据。这个乐观锁机制避免了多端同时编辑把对方改动覆盖掉——我最初没做这个，结果手机和网页同时整理歌单，一次冲突就丢了四十多首歌。

3.3 播放队列与歌单的联动

播放队列我设计成一个独立的、可持久化的对象，而不是挂在某个歌单上的临时数组。队列里存的是 UID 列表加当前索引，服务启动时从磁盘恢复。这样做的收益是：重启服务后接着上次的位置继续播，多端切换时队列状态一致。

队列与歌单的联动只做两件事：从歌单播放时，把歌单的 UID 列表整体灌进队列并把索引指向点击的那首；队列播放到末尾时不循环回歌单，除非用户显式开启循环。这个"不隐式联动"的原则很重要，早期版本里我在队列播完时自动回填歌单，结果用户手动加了歌又删了歌，队列莫名其妙变长，体验很差。

跨源播放还有一个隐藏问题：不同源的音量响度差异巨大。解决办法是在Resolve阶段读取一次响度信息（能拿到就存进缓存），播放在前端做一次增益归一化。拿不到响度信息的就按源的默认补偿值处理，我这边公有源统一 -2dB，自建源 0dB，实测下来切换时突兀感小了很多。

4. 内置大模型源：把"点歌"变成一句话的事

这是我整套改造里最花心思的部分，也是最容易被误解的部分。很多人一听"内置大模型"就以为要让模型生成音乐、生成播放列表文本，其实完全不是。在这个系统里，大模型只承担一个职责：把一句自然语言翻译成结构化的检索条件。真正的召回仍然交给搜索引擎，模型不碰数据，只碰意图。

4.1 大模型该干什么、不该干什么

先说清楚边界。该干的是：理解"来点适合雨天开车听的""别放太吵的""找几首九零年代粤语慢歌"这类含情绪、含场景、含模糊约束的请求。不该干的是：凭记忆说出具体歌曲名。后者是幻觉重灾区，模型会吐出根本不存在的歌名和歌手组合，用户点进去全是空。

所以我在整个链路里加了一条硬约束：模型输出的每个曲目标识，必须来自本次检索召回的候选集。模型不许直接生成歌名，它只能从候选列表里选 ID 并排序。这条约束让准确率从"经常出鬼"变成"基本可用"。

具体分工是这样：

4.2 结构化输出：Prompt 与 Schema 双约束

Prompt 我改了十几版，最后稳定下来的结构是"角色 + 任务 + 输出格式 + 约束 + 示例"五段式。关键词是输出必须是合法 JSON，且给出明确的字段类型和取值范围。

你是音乐检索助手。把用户的自然语言需求翻译成检索参数。 只输出 JSON，不要任何解释文字。 字段定义： - keywords: 字符串数组，2到6个，用于搜索引擎的关键词 - mood: 情绪标签，从 [安静, 明亮, 忧郁, 热烈, 怀旧, 冷静] 中选，可多选 - era: 年代区间，格式 "1990-1999"，不确定填 null - language: 语言，从 [国语, 粤语, 英语, 日语, 纯音乐] 中选，可多选 - exclude: 排除项数组，如 ["live", "remix", "伴奏"] - limit: 期望数量，10到50的整数 示例输入：来点适合下雨天一个人待着听的，别太吵 示例输出：{"keywords":["雨","安静","钢琴","氛围"],"mood":["安静","忧郁"],"era":null,"language":[],"exclude":["live"],"limit":20}

配合 Schema 校验（我用的是 JSON Schema 校验库，校验失败直接丢弃重试一次），能挡掉绝大部分脏输出。实测下来，加了 Schema 校验之后，解析失败率从接近两成降到 1% 以下。

这里有个反直觉的经验：不要给模型太多自由度。我一开始想让模型自由发挥，输出"推荐理由"字段，结果它把理由写得天花乱坠，反而把 JSON 弄坏。后来把理由字段砍掉，改由服务端根据命中的标签拼接一句简短说明，稳定性立刻上来了。

4.3 语义检索链路：从一句话到一份歌单

完整链路分四步，每一步都有超时和降级。

第一步，意图解析。调模型，超时设 5 秒。失败则降级为"把用户原句直接当关键词"。

第二步，多路召回。用解析出的keywords分别打本地库（走全文索引）和在线源（走聚合搜索），每路取前 20 条，合并后按 UID 去重。这里的关键词扩写很有用——用户说"雨天"，模型给的关键词是"雨、安静、钢琴、氛围"，四个词分批召回，覆盖面比单查"雨天"宽得多。

第三步，重排。把候选集压缩成紧凑列表（只给 ID、歌名、艺术家、专辑、年份），连同原始需求一起喂给模型，让它返回有序的 ID 列表。候选控制在 40 条以内，超过就分批重排再拼接，避免上下文过长。

第四步，落地。把选中的 UID 写成一个type: "llm"的歌单，editable: true，用户可以继续手动改。歌单名默认用用户原句截断，也可以让用户自己起。

func (s *LLMService) BuildPlaylist(ctx context.Context, sentence string) (*Playlist, error) { ctx, cancel := context.WithTimeout(ctx, 8*time.Second) defer cancel() q, err := s.parseIntent(ctx, sentence) if err != nil { q = &Query{Keywords: []string{sentence}, Limit: 20} // 降级 } cands := s.recall(ctx, q) if len(cands) == 0 { return nil, ErrNoCandidate } picked, err := s.rerank(ctx, sentence, cands) if err != nil { picked = fallbackOrder(cands) // 降级：按召回分数排 } return s.persist(picked), nil }

4.4 成本、延迟与兜底：那些跑起来才会想的事

延迟是最大的体验杀手。两步模型调用叠加，串行下来轻松超过 6 秒。我的做法是意图解析和召回并行不了（有依赖），但召回和重排之间的候选裁剪做得很激进，只传必要字段，把重排这一步的耗时压到 2 秒内。整体 P90 落在 4 秒左右，配合前端"正在为你选歌"的骨架屏，感知上还能接受。

成本取决于你用什么模型。本地部署一个 7B 量化的模型，在带核显的 x86 机器上跑意图解析够用，但重排这种需要理解语义的任务明显吃力。我最终采用的是混合策略：意图解析走本地小模型（快、免费、够用），重排走外部接口（质量高、调用量小）。这样每月调用量控制在几百次，成本几乎可以忽略。

兜底必须做三层：模型超时走关键词直搜；Schema 校验失败重试一次再失败走直搜；召回为空时返回热门推荐并提示"没找到特别匹配的，先听听这些"。这三层兜底让功能在模型挂掉时依然可用，只是退化成普通搜索。

注意：本地跑模型时一定要限制并发。我见过有人把max_concurrent设成 8，结果一次请求把 NAS 的内存打满，整套服务连带崩了。建议初次部署设成 1，观察内存占用后再调到 2。

还有一个容易被忽略的点是结果可解释。大模型选出来的歌，用户凭什么相信？我在歌单详情里加了一行小字，显示"根据关键词：雨、钢琴、安静"，命中标签也做了高亮。有了这行说明，用户对结果的容忍度明显提升，觉得不合适的还能自己删。

5. 部署实操：从改代码到跑起来

这一节讲具体落地。假设你已经把项目源码拉到本地，能正常编译运行，接下来的事情就是把上面三层接进去。

5.1 环境与依赖准备

后端是 Go，版本建议 1.21 以上，因为用到了slices和maps标准库。前端是 TypeScript，构建走常规的包管理器流程。大模型部分我用的是一个兼容通用对话协议的客户端封装，不绑定具体服务，配置里填地址和模型名即可。

# 依赖拉取 go mod tidy # 编译（关闭 CGO，产物可直接扔到设备上） CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \ go build -trimpath -ldflags="-s -w" -o fnmusic ./cmd/server # 前端构建 cd web && npm ci && npm run build

编译产物大约 30MB 出头，静态资源单独放一个目录，前端构建完拷进web/dist即可。我习惯用 systemd 托管，配置文件放/etc/fnmusic/config.yaml，数据目录独立挂载，升级时只替换二进制。

5.2 关键配置项

配置我全部收在一个 YAML 里，敏感值通过环境变量注入，不写进文件。

providers: - name: provider_a enabled: true timeout: 4s qps: 3 burst: 6 priority: 10 - name: provider_b enabled: true timeout: 4s qps: 2 burst: 4 priority: 5 cache: search_ttl: 10m detail_ttl: 30m lru_size: 2000 llm: enabled: true base_url: "${LLM_BASE_URL}" api_key: "${LLM_API_KEY}" intent_model: "local-7b" rerank_model: "remote-large" timeout: 5s max_concurrent: 2 fallback_on_error: true playlist: sync_interval: 30m max_tracks: 5000 conflict_policy: "reject"

几个参数值得单独说。priority决定同源去重时保留哪一条，自建源给高值。lru_size别设太大，2000 条搜索结果大约占 20~40MB 内存，设到 20000 就要小心了。max_tracks是防呆，防止某个源返回异常数据把歌单撑爆。conflict_policy设成reject是乐观锁的严格模式，多端冲突时让用户手动刷新，避免静默覆盖。

5.3 启动验证与压测

启动后按顺序验证四件事，能快速定位问题。

第一，搜索链路。随便搜一个词，看返回的source字段是否覆盖了多个源，耗时是否在 1 秒内。第二，播放链路。点一首在线曲目，看是否真的出声音，注意观察Resolve请求是否成功。第三，歌单链路。建一个歌单，加几首在线曲目，重启服务，看数据是否还在。第四，大模型链路。说一句"来点安静的钢琴"，看是否生成歌单，耗时多少。

压测我用的是一百个并发搜索请求，连续打 60 秒。重点看三个指标：P99 延迟、错误率、内存增长。健康的表现是 P99 在 2 秒内、错误率低于 1%、内存回落到基线。如果内存持续不回落，八成是 LRU 没设上限或者Resolve结果没做清理。

6. 踩坑实录：排查速查表

这部分是我半年里攒下来的真实问题，按现象分类，可以直接对照。

再补三条表格里写不下的经验。

第一条，关于日志。二开项目的日志一定要按trace_id串起来。一次点歌请求会经过聚合层、多个适配器、大模型两次调用，日志分散在七八处。我最初没加 trace_id，排查一个问题要看五六个文件。后来在入口生成一个短 ID 写进 context，所有日志带上它，grep一次就能还原完整链路。

第二条，关于源的健康度。加一个简单的健康检查，每隔几分钟对每个源发一个固定关键词的搜索，连续三次失败就临时禁用并标记，恢复后自动启用。这个机制帮我扛过一次某个源连续几小时不可用的情况，用户完全无感知，因为聚合层只是少了一路结果。

第三条，关于版本升级。二开最大的痛苦是跟上游合并。我的策略是：所有改动放在独立目录internal/extension/下，上游文件只在三个地方动过——路由注册、配置结构体加一个字段、启动流程加一行初始化。这三处改动我都写了注释标记，每次升级顺着注释改一次，十分钟搞定。如果你的改动散落在十几个文件里，升级那天会非常难受。

最后分享一个我自己一直在用的小技巧。整套功能上线后，我给自己留了一个隐藏的调试入口，输入特定关键词会返回完整的链路信息：解析出的意图 JSON、每路召回的条数与耗时、重排前后的顺序对比、最终歌单。这个入口不开放给普通用户，但在我调 Prompt、调权重、调缓存 TTL 的时候，省掉了无数次翻日志的时间。做二开项目，给自己留一双能看进去的眼睛，比多写两百行功能代码更值。