企业官网建设流程全解析

Koito 是一款现代、可换主题的自托管 Scrobbler（听歌打点服务），兼容 ListenBrainz 协议，能让你把听歌历史、播放统计和音乐数据完整掌握在自己手里。无论你的音乐播放器是否支持自定义 ListenBrainz 地址，都可以把打点数据导入 Koito，获得漂亮的收听统计面板，还能中继（relay）到你原有的打点服务，做到"先试水、不折腾"。本文将带你从零开始，用不到 10 分钟完成安装、接入播放器和数据导入。

为什么听歌数据应该自己掌握？

你可能正使用 Maloja、ListenBrainz 或 Last.fm 记录每天听了什么歌。这些服务很好，但有几个共同问题：

• 📦数据不在自己手里：账号停服、政策变化时，你几年的听歌记录说没就没；
• 🔒隐私交给第三方：每天听什么歌是很私密的习惯画像；
• 🎨界面和主题有限：想换一种风格、想自定义统计维度，基本无解。

自托管 Scrobbler 就是解法：服务跑在你自己的服务器上，数据存在你自己的 SQLite 数据库里（见 db/migrations_sqlite/001_initial_schema.sql），想备份随时备份，想删除随时删除。

Koito 能做什么？核心功能一览

Koito 用 Go 编写后端（cmd/api/main.go）、React 编写前端（client/），主打"快、美、能迁移"：

• ⚡高性能：比同类自托管软件更快，单容器即可运行；
• 🎯兼容一切 ListenBrainz 打点源：Navidrome、Maloja 客户端、自制插件……任何能填"自定义 ListenBrainz URL + Token"的程序都能接入；
• 🚚一键中继：可以同时把数据转发到你原有的 ListenBrainz 服务器，平滑过渡零风险；
• 📥历史数据导入：支持从 Spotify、Maloja、LastFM、ListenBrainz 一键导入（导入逻辑在 internal/importer/）；
• 🖌️12 套内置主题 + 自定义主题：界面可深度换肤；
• 🔧数据可编辑：改名（aliases）、换封面、合并重复条目，数据质量自己说了算。

Docker 三步快速安装 Koito

最推荐的方式是 Docker 部署，整个安装只需一份 Compose 文件。在服务器上创建compose.yaml：

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，登录后请务必第一时间修改密码。

不想用 Docker 也可以从源码编译（需要先安装make、yarn、libvips-dev）：

git clone https://gitcode.com/gh_mirrors/ko/Koito && cd Koito make build && ./koito

完整步骤参考 安装指南，编译脚本见 Makefile。

最快接入方式：5 分钟连上 Navidrome

如果你用 Navidrome（或任何 Subsonic 兼容服务器），接入流程非常短：

1. 打开 Navidrome 的 ListenBrainz 打点：设置环境变量ND_LISTENBRAINZ_ENABLED=true和ND_LISTENBRAINZ_BASEURL=<你的Koito地址>/apis/listenbrainz/1；
2. 在 Navidrome 界面打开开关：进入Settings → Personal，把 "Scrobble to ListenBrainz" 打开（如图所示）；

3. 填入 Koito 的 API Key：在 Koito 中点击设置按钮（或按\`键）→API Keys选项卡，复制自动生成的 API key，粘贴到 Navidrome 的 Token 输入框保存。

之后你每播放一首歌，Navidrome 就会自动把打点发给 Koito。更多细节见 Navidrome 快速上手 和 Scrobbler 配置指南。

把过去的听歌历史导入 Koito

只有"从今天开始"的记录太可惜。Koito 支持从四个来源导入历史数据，操作方式都是"导出文件 → 丢进 import 文件夹 → 重启容器"，自动识别、自动入库（详见 数据导入指南）：

以 Spotify 为例：先到 Spotify 账号隐私页面申请"完整流媒体历史"（Extended streaming history）导出，勾选后等待生成：

拿到.json文件后放进./koito/import/目录，重启 Koito，历史数据就会自动开始入库。注意：ListenBrainz 和 LastFM 的大体量导入会受 MusicBrainz 限流（每秒 1 次）影响而较慢，可在导入期间通过配置临时关闭 MusicBrainz 加速（参见 配置参考）。

让数据更干净：别名、换图与合并

自托管的最大好处是数据可以"精修"。登录 Koito 后，在任意歌手/专辑/歌曲页右上角都有编辑入口（编辑功能源码位于 client/app/components/modals/EditModal/）：

• Alias Manager（别名管理）：为条目添加别名并设为"主名称"，非拉丁文字母的歌曲（如日文、韩文标题）也能轻松搜索和匹配，这是打点归一的关键；

• 更换封面图：直接把本地图片拖拽到页面上即可替换，也可以填入图片 URL 让 Koito 抓取；
• 合并重复条目：同一首歌的日文版和罗马音版？搜索目标条目后一键 Merge，所有子项（专辑、歌曲、打点记录）会自动归并，且支持"反向合并"；

• 删除条目：不需要的记录可直接删除（不可逆，操作前确认好）。

完整教程见 数据编辑指南。

不想放弃现有服务？用中继平滑过渡

担心换掉现有打点服务有风险？Koito 支持中继（relay）：所有发往 Koito 的打点会原样转发给你指定的 ListenBrainz 兼容服务器，等于双写、零损失。只需在 Compose 中增加三个环境变量并重启：

environment: - KOITO_ENABLE_LBZ_RELAY=true - KOITO_LBZ_RELAY_URL=<你的目标服务器ListenBrainz端点完整路径> - KOITO_LBZ_RELAY_TOKEN=<目标服务器的用户token>

这也是作者本人在整个开发期使用的方案，可以放心参考。

常见问题速查

• 默认端口是多少？默认监听4110，可通过KOITO_LISTEN_PORT修改；
• 怎么换主题？环境变量KOITO_DEFAULT_THEME设置默认主题（如black），用户也可在界面右下角切换；
• 要不要公开统计？设置KOITO_LOGIN_GATE=true可要求登录后才显示任何数据；
• 封面图从哪来？Koito 会自动从 Deezer、Cover Art Archive、Subsonic 音乐服务器等来源抓取图片并缓存，可用KOITO_DISABLE_DEEZER等变量关闭指定来源。

全部配置项请参考 配置参考文档 与 README。

小结

Koito 把"自己的听歌数据自己做主"这件事变得非常轻：一个 Docker 容器、一个 Compose 文件，就拥有了自托管的打点服务、精美的收听统计、历史数据导入和灵活的转发能力。装好后，你听过的每一首歌，都真正属于你自己了 🎧