Koito 是一款现代、可换肤的自托管听歌统计工具（scrobbler），兼容所有支持自定义 ListenBrainz 地址的客户端。它比同类软件更快，UI 更精致，还能把数据"中转"到你现有的 ListenBrainz 服务，让你可以放心试用。下面这份 Koito Docker 部署教程，带你 5 分钟跑起自己的听歌统计面板。

一、Koito 能做什么？

部署完成后，Koito 首页会展示你的全部听歌数据：

• 📊全时段统计：总收听时长、播放次数、曲库规模
• 🎨活动热力图：按星期/时段展示听歌活跃程度
• 🏆Top 榜单：热门歌手、专辑、歌曲排行榜
• 🎞️Rewind 月度回顾：每月自动生成你的"年度盘点"
• 📂数据导入：支持从 Spotify、Maloja、LastFM、ListenBrainz 一键导入历史数据

二、一键部署：最小化 Docker Compose 配置

只要你的机器上装好了 Docker（含 Compose 插件），整个部署就是一条命令的事。新建compose.yaml，粘贴官方推荐的最小配置（来源：installation.md）：

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

然后执行：

docker compose up -d

等镜像拉取完成，打开浏览器访问http://你的服务器地址:4110，就能看到登录界面了。

💡 所有数据都通过 SQLite 存储在挂载的./koito目录中，备份时只需要备份这一个文件夹，非常省心。

三、首次登录与账号设置

首次启动会默认创建一个用户：

• 用户名：admin
• 密码：changeme

登录后请务必修改密码。之后可以随时修改默认账号、端口、主题等参数，完整配置项参考 configuration.md，最常用的是这几个：

修改后执行docker compose up -d重新加载即可。

四、配置 Scrobble：让播放器自动上报

想让听歌行为自动记录，只需两步：

1️⃣ 获取 API Key：登录 Koito，按\打开设置面板，进入API Keys标签页，复制自动生成的 API Key（这一步在 scrobbler.md 中有详细说明）。

2️⃣ 在播放器中指向 Koito：以 Navidrome 为例，将 scrobble 地址设为{你的Koito地址}/apis/listenbrainz/1，Token 填刚才复制的 API Key。以 Navidrome 为例，还需在 Navidrome 的环境变量中加上：

ND_LISTENBRAINZ_ENABLED=true ND_LISTENBRAINZ_BASEURL=<你的Koito地址>/apis/listenbrainz/1

随后在 Navidrome 个人设置里打开Scrobble to ListenBrainz开关：

保存后，你每听一首歌，数据就会实时进入 Koito。🎧

🔁 小技巧：如果暂时不想完全替换现有 scrobbler，可以开启KOITO_ENABLE_LBZ_RELAY+KOITO_LBZ_RELAY_URL+KOITO_LBZ_RELAY_TOKEN三个环境变量，把 Koito 收到的数据同步转发到你原来的 ListenBrainz 服务，双保险零风险。

五、导入历史听歌数据

从零开始积累有点慢？Koito 支持从 Spotify、Maloja、LastFM、ListenBrainz 导入历史数据。以 Spotify 为例（详见 importing.md）：

1. 在 Spotify 账号隐私页申请"Extended streaming history"数据导出
2. 拿到.json文件后，放入配置目录的import文件夹（即宿主机./koito/import/）
3. 文件名需包含Streaming_History_Audio字样
4. 执行docker compose restart koito，导入自动开始

其他来源同样"丢文件进import文件夹 + 重启"即可，文件名需包含对应关键词（maloja/recenttracks/listenbrainz）。

⏱️ 大数据量导入时，MusicBrainz 匹配按每秒 1 次限速，可能需要较长时间，耐心等待即可。

六、看看效果：Rewind 月度回顾

等数据积累一些后，侧边栏的 Rewind 页面会按月生成漂亮的听歌回顾，包括当月 Top 歌手、Top 专辑、Top 歌曲和各项统计，非常值得每月截一张图留念：

七、常见问题速查

至此，你的自托管听歌统计站已经完整上线了 🎉 更多高级玩法（别名合并、图片替换、编辑管理）可继续探索 docs/src/content/docs/guides/ 下的官方指南。