企业官网建设流程全解析

Koito是一款可自托管、主题化的 ListenBrainz 兼容 scrobbler，内置强大的历史数据导入功能，支持 Spotify、LastFM、ListenBrainz、Maloja 四大平台的一键数据搬家。你只需把官方导出的文件丢进import文件夹，重启服务即可自动识别并灌入历史听歌数据，零代码、零配置门槛，几分钟完成从 Spotify 或 LastFM 到私有音乐统计面板的完整迁移。

一、Koito 是什么？为什么值得导入历史数据

Koito 的核心定位：把散落在各平台的"听歌足迹"收进你自己的数据库，用漂亮的界面呈现 Top 艺术家、Top 专辑、活动热力图、月度 Rewind 等统计。但一个全新的 Koito 实例只有"从装它那一刻"开始的数据——导入历史数据才能让统计真正有意义。

官方文档明确了四种导入源（见 docs/src/content/docs/guides/importing.md）：

💡 额外彩蛋：把 Koito 自己导出的koito_export.json丢进 import 目录，还能实现Koito 实例之间的数据迁移（识别关键词koito），见 internal/importer/koito.go。

二、导入机制详解：一个文件夹 + 一次重启

Koito 的导入器设计得极其"懒人友好"。理解下面三点，任何平台的导入都一通百通：

1. 放置文件：把导出文件放进配置目录下的import/文件夹（默认配置目录为/etc/koito，Docker 部署时即你挂载的./koito卷）；
2. 文件名决定类型：Koito 通过文件名包含的关键词判断数据源，检测逻辑在 engine/engine.go 中，按Streaming_History_Audio→maloja→recenttracks→listenbrainz→koito的顺序匹配，命名不对就不会被识别；
3. 重启触发：重启 Koito 后自动开始导入，完成后文件会被移入import_complete/文件夹（逻辑见 internal/importer/importer.go），不会重复导入。

最简 Docker Compose 启动方式（完整列表见 docs/src/content/docs/reference/configuration.md）：

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

三、四大平台逐个搬：导出 → 放置 → 重启

1️⃣ Spotify：申请扩展流媒体历史

1. 登录 Spotify 官方隐私中心（账户设置 → 隐私 → 下载你的数据 / Download your data），勾选Extended streaming history（账户创建以来的全部流媒体历史）并发起申请；
2. Spotify 官方标注最长可能需要30 天准备（实际通常几天内邮箱即收到）；
3. 解压下载包，找到文件名含Streaming_History_Audio的.json文件，放入koito/import/；
4. 重启 Koito，日志出现Beginning spotify import即开始。

⚠️ 两个细节（实现见 internal/importer/spotify.go）：

• 只有reason_end = trackdone的完整播放会被计入，中途切歌不算；
• Spotify 数据自带播放时长，所以导入后的"Hours Listened（收听时长）"统计是准确的。

2️⃣ LastFM：用 ghan.nl 导出工具生成 JSON

1. 打开 LastFM 社区导出工具lastfm.ghan.nl/export，输入你的用户名，选择JSON格式生成导出文件（文件名形如recenttracks-用户名-时间戳.json，关键词正好是recenttracks）；
2. 将该.json文件放入koito/import/；
3. 重启 Koito，自动识别为 LastFM 导入并开始写入（解析逻辑见 internal/importer/lastfm.go）。

⚠️ LastFM 的导出不含歌曲时长，导入后"收听时长"统计会偏低；后续通过 API 正常 scrobble 时会逐步补全（官方文档原话）。

3️⃣ ListenBrainz：官网一键导出 ZIP

1. 登录 ListenBrainz 官网 → 设置（Settings）→ 导出（Export），提交导出请求，稍后邮箱会收到.zip下载链接；
2. 直接把.zip压缩包（无需解压，文件名含listenbrainz，如listenbrainz_用户名_时间戳.zip）放入koito/import/；
3. 重启 Koito 即可，导入器会自动遍历 zip 内的listens/*.jsonl文件逐条解析（见 internal/importer/listenbrainz.go）。

4️⃣ Maloja：管理页 Export 按钮

如果你之前用的是 Maloja：打开 Maloja 实例的/admin_overview页面 → Download Data → 点击Export，把生成的.json文件放入import/（文件名含maloja）后重启即可。Maloja 数据可能缺失时长信息，且其歌手排序习惯（"feat • 主唱"）会被 Koito 自动纠正为"主唱, feat"，见 internal/importer/maloja.go。

四、进阶配置：让大体积导入更快更稳

历史数据动辄几万条，默认行为有两个"慢点"，可用环境变量精准调优：

🔍 为什么慢？ListenBrainz 和 LastFM 导入会为每首歌查询 MusicBrainz 做 MBID 匹配，官方限流为每秒 1 次请求，这是文档中明确提示的"大数据量会很慢"的根源。

导入窗口判断逻辑见 internal/importer/importer.go，完整参数含义见 internal/cfg/cfg.go。

五、导入完成后：验证你的数据新家

重启后打开http://你的主机:4110，按这个顺序验收：

• 首页 All Time Stats：总分钟数、总播放数、曲目/专辑/艺术家数量应当与源平台量级一致；
• Top Artists / Top Albums / Top Tracks：核对你最熟悉的几首歌的排名；
• Rewind 月度回顾：翻到导入数据覆盖的月份，检查月度 Top 是否正确。

常见问题排查

六、小结

Koito 的"文件即配置"式导入器，把Spotify、LastFM、ListenBrainz、Maloja四大平台的历史数据统一收敛到import/目录 + 重启的极简流程里，配合时间窗口过滤与 MusicBrainz 开关，无论是全量搬家还是只搬最近一年都从容可控。数据落地后，你得到的是一套完全属于自己、可主题化、可离线查看的私人听歌统计面板 🎧。

关键源码与文档索引

• 官方导入指南：docs/src/content/docs/guides/importing.md
• 配置参数参考：docs/src/content/docs/reference/configuration.md
• 导入调度（文件名识别）：engine/engine.go
• Spotify 导入器：internal/importer/spotify.go
• LastFM 导入器：internal/importer/lastfm.go
• ListenBrainz 导入器：internal/importer/listenbrainz.go
• Maloja 导入器：internal/importer/maloja.go