让Navidrome的听歌记录流入Koito：Navidrome+Koito组合完整配置指南

Navidrome 是一款优秀的自托管音乐服务器，但它本身不会把听歌记录送到任何统计平台。而 Koito 是一个现代、可换肤、兼容 ListenBrainz 协议的自建 scrobbler（听歌上报服务）。把两者组合起来，就能让 Navidrome 的每首歌实时流入 Koito，生成漂亮的听歌统计图表。本文将带你从零完成 Navidrome + Koito 组合的完整配置：部署 Koito、获取 API Key、开启 Navidrome 的 ListenBrainz 上报，以及用 Navidrome 作为专辑封面图源。

组合前：先了解工作原理

整个链路非常清晰：

1. 你在 Navidrome 里听歌；
2. Navidrome 把「已播放」事件发送到 Koito 的 ListenBrainz 兼容接口；
3. Koito 接收、解析并入库，同时自动匹配 MusicBrainz 数据；
4. 打开 Koito 网页，就能看到 Top 歌曲、Top 歌手、专辑等统计。

Koito 还额外支持从 Navidrome（Subsonic 协议）拉取专辑封面，让统计页面的图片直接来自你自己的曲库，详见 Navidrome 快速上手文档。

第一步：部署 Koito 实例

官方推荐使用 Docker Compose 部署，最简单快捷。示例配置取自 安装指南：

services: koito: image: gabehf/koito:latest container_name: koito ports: - "4110:4110" volumes: - ./koito:/etc/koito restart: unless-stopped

启动后访问http://<你的IP>:4110，即可看到 Koito 登录页。默认账号密码为admin/changeme，首次登录后记得立即修改。

💡 自v0.2.1起，Koito 默认使用 SQLite 数据库，无需额外配置数据库。

第二步：获取 Koito 的 API Key

Navidrome 需要一个 token 才能把听歌记录发给 Koito，这个 token 就是 Koito 界面里自动生成的 API Key（对应前端组件 ApiKeysModal.tsx）：

1. 登录 Koito，点击右上角设置按钮（或按反引号`）；
2. 切换到API Keys标签页；
3. 复制那个自动生成的 API Key。

⚠️ 注意：如果 Koito 不是通过https://或localhost访问，一键复制按钮可能失效，直接点选密钥文本后用 Ctrl+C 复制即可。

第三步：配置 Navidrome 指向 Koito

在 Navidrome 的部署配置中（compose 文件或环境变量）添加两项设置：

environment: - ND_LISTENBRAINZ_ENABLED=true - ND_LISTENBRAINZ_BASEURL=http://<你的koito地址>:4110/apis/listenbrainz/1

修改后重启 Navidrome 容器使环境变量生效。

第四步：在 Navidrome 里打开上报开关

1. 登录 Navidrome，点击右上角Settings，再进入Personal；
2. 找到Scrobble to ListenBrainz开关并打开（见上图）；
3. 系统会提示输入 ListenBrainz token——粘贴第二步复制的 Koito API Key，保存。

完成后，只要你在 Navidrome 播放歌曲，听歌记录就会开始流入 Koito。稍等片刻打开 Koito 首页，就能看到最近播放记录和不断上涨的统计。

进阶：用 Navidrome 作为封面图源

Koito 支持通过 Subsonic 协议从 Navidrome 拉取专辑封面，配置方式是给 Koito 增加两个环境变量（变量名定义见 cfg.go）：

environment: - KOITO_SUBSONIC_URL=https://navidrome.example.com - KOITO_SUBSONIC_PARAMS=u=<用户名>&t=<token>&s=<salt>

KOITO_SUBSONIC_PARAMS里的u、t、s三个参数获取方法很简单：

1. 浏览器登录 Navidrome，按F12打开开发者工具；
2. 切到Network标签页，在首页找到任意一个getCoverArt请求；
3. 复制 URL 中u=<username>&t=<随机串>&s=<短随机串>这一段，整体填入即可。

⚠️ 两个变量必须同时设置，否则 Koito 会校验失败而拒绝启动；如果改完参数后容器起不来，先去看日志。不想用 Navidrome 提供封面的话，这两个变量可以完全省略，Koito 会自动使用 MusicBrainz 等在线图源。

完整的环境变量说明（包括所有变量都支持的_FILE后缀写法，方便使用 Docker secrets）见 配置参考。

常见问题排查

• Navidrome 开了开关但 Koito 没数据？确认ND_LISTENBRAINZ_BASEURL末尾必须带/apis/listenbrainz/1，且 Navidrome 能访问到 Koito（同一台机器的 compose 里可用服务名互访）。
• Koito 容器启动就退出？十有八九是KOITO_SUBSONIC_URL/KOITO_SUBSONIC_PARAMS校验没通过，检查两个变量是否成对设置、参数是否复制完整。
• 想让数据同时上报到官方 ListenBrainz？Koito 内置转发（relay）能力，设置KOITO_ENABLE_LBZ_RELAY=true、KOITO_LBZ_RELAY_URL和KOITO_LBZ_RELAY_TOKEN三个变量即可，详见 Scrobbler 指南。
• 历史记录？Koito 支持导入 Maloja、ListenBrainz、LastFM、Spotify 的历史数据，参考 数据导入指南。

小结

只需四步——部署 Koito、复制 API Key、配置 Navidrome 环境变量、打开上报开关——你的 Navidrome 听歌记录就会自动汇入 Koito。再顺手配上 Subsonic 图源，统计页面的封面就全部来自你自己的曲库。开始享受属于你自己的听歌数据吧！🎵