Koito项目数据导入指南：从各大音乐平台迁移你的听歌历史

前言

对于音乐爱好者来说，个人听歌历史记录是一份珍贵的数字资料。Koito作为一个开源的听歌记录分析平台，提供了从多个主流音乐服务平台导入历史数据的功能。本文将详细介绍如何将你的听歌历史从Spotify、Maloja、LastFM和ListenBrainz等平台迁移到Koito中。

数据导入概览

Koito目前支持从以下来源导入数据：

• Spotify（流媒体历史）
• Maloja（自托管追踪平台）
• LastFM（需使用第三方导出工具）
• ListenBrainz（开源音乐元数据库）

性能注意事项

对于ListenBrainz和LastFM的大规模数据导入，由于MusicBrainz API的请求限制（每秒1次），导入过程可能会非常耗时。如果你希望加快导入速度，可以考虑以下优化方案：

1. 在配置中临时禁用MusicBrainz查询（但会导致无法自动获取艺术家别名信息）
2. 搭建自己的MusicBrainz镜像服务器
3. 在配置中禁用MusicBrainz的速率限制

详细导入指南

1. 从Spotify导入数据

操作步骤：

1. 访问Spotify隐私页面申请导出你的扩展流媒体历史记录
2. 等待Spotify处理你的请求（最长可能需要30天）
3. 收到数据后，将包含Streaming_History_Audio的JSON文件放入Koito配置目录的import文件夹
4. 重启Koito服务，系统将自动开始导入

技术细节：

• Koito通过文件名识别Spotify数据文件，确保文件名包含关键标识
• 导入过程会解析JSON文件中的播放时间、曲目和艺术家信息
• 由于Spotify提供完整数据，导入后所有统计信息都将准确可用

2. 从Maloja导入数据

操作步骤：

1. 登录你的Maloja实例管理页面
2. 在/admin_overview页面找到"Download Data"部分
3. 点击"Export"按钮下载JSON格式的数据文件
4. 将文件放入Koito的import文件夹（建议文件名包含"maloja"）
5. 重启Koito服务开始自动导入

注意事项：

• Maloja导出的数据可能缺少或包含不一致的曲目时长信息
• 这会导致"收听小时数"统计可能不准确
• 后续通过API提交的收听记录将补充这些缺失的时长数据

3. 从LastFM导入数据

准备工作：

由于LastFM官方不直接提供数据导出功能，我们需要先使用第三方工具将数据转换为Koito可识别的格式。

操作步骤：

1. 使用指定的JSON导出工具处理你的LastFM数据
2. 将生成的JSON文件放入Koito的import文件夹
3. 重启Koito服务，系统会自动检测并开始导入

技术限制：

• LastFM导出数据不包含曲目时长信息
• 与Maloja类似，"收听小时数"统计可能不准确
• 缺失的时长数据会随着后续API使用逐渐补充

4. 从ListenBrainz导入数据

操作步骤：

1. 访问ListenBrainz网站的导出工具页面
2. 创建并下载你的数据导出文件（ZIP格式）
3. 将ZIP文件放入Koito的import文件夹
4. 重启Koito服务开始自动导入

特点：

• ListenBrainz作为开源平台，数据格式较为规范
• 导入过程会保留尽可能多的元数据信息
• 对于大规模数据集，导入可能需要较长时间处理

最佳实践建议

1. 分批导入：如果从多个来源导入数据，建议分批进行，便于问题排查
2. 数据验证：导入完成后，检查关键统计数据是否合理
3. 定期备份：导入大量数据后，建议备份Koito数据库
4. 性能优化：对于超大数据集，考虑在低峰期进行导入操作

常见问题解答

Q：导入后为什么某些统计数据不准确？

A：这是因为部分数据源缺少曲目时长信息。随着你继续使用Koito记录收听习惯，这些数据会逐渐完善。

Q：导入过程中断怎么办？

A：Koito的导入机制具有幂等性，重启后会从上次中断的位置继续，不会导致数据重复。

Q：如何确认导入是否成功？

A：检查Koito的日志文件，其中会详细记录导入进度和结果。

通过本文指南，你应该能够顺利将各种来源的音乐收听历史迁移到Koito平台，继续你的音乐探索之旅。如果在导入过程中遇到任何技术问题，建议查阅更详细的日志信息进行排查。