krateng/maloja

Maloja

自托管的音乐记录数据库，用于创建个人收听统计数据和图表。您可以完全掌控自己的音乐数据，无需依赖第三方服务，支持自定义标签体系和个性化展示。

!https://raw.githubusercontent.com/krateng/maloja/master/screenshot.png

可查看官方示例实例了解实际效果。

核心功能特性

自托管数据控制

• 完全掌控数据访问权，数据以易解析格式存储，不与任何公共音乐数据库同步，支持自定义标签体系。

灵活的艺术家关联

• 支持关联艺术家（如子团体、合作项目或成员个人作品），随时调整关联关系而不丢失数据，准确反映不同艺术家在收听习惯中的 popularity。

多艺术家曲目处理

• 自动识别并拆分曲目中的合作艺术家（如"featuring"形式），每个艺术家独立计入统计，避免组合形式导致的统计分散。

自定义图片管理

• 支持上传自定义艺术家或曲目图片，自主设计个人首页展示效果，不依赖社区图片资源。

代理记录转发

• 可配置将记录转发至其他服务，无需重复设置客户端，实现数据多平台同步。

标准兼容API

• 支持现有成熟应用或扩展程序记录音乐收听行为，兼容自定义ListenBrainz或GNUFM服务器设置。

手动记录功能

• 针对 vinyl 或背景音乐等无法自动记录的场景，提供网页界面手动提交记录。

简洁实用设计

• 专注核心功能，无社交网络、电台或推荐等附加功能，仅用于追踪长期收听习惯。

使用场景

• 自建音乐服务用户：搭配个人音乐服务器（如Navidrome、Plex），构建完整的个人音乐生态。
• 数据隐私重视者：不将收听数据上传至第三方平台，确保数据隐私和控制权。
• 自定义标签需求者：使用个人化标签体系管理音乐库，不受公共数据库限制。
• 多来源数据整合者：需整合Last.fm、Spotify、ListenBrainz等平台历史记录的用户。

详细使用方法

Docker部署

环境变量说明

基本部署命令

console
docker run -p 42010:42010 -v $PWD/malojadata:/mljdata -e MALOJA_DATA_DIRECTORY=/mljdata krateng/maloja

Linux主机权限配置

获取当前用户的UID和GID：

console
id -u  # 获取UID，如1000
id -g  # 获取GID，如1001

带权限配置的部署命令：

console
docker run -e PUID=1000 -e PGID=1001 -p 42010:42010 -v $PWD/malojadata:/mljdata -e MALOJA_DATA_DIRECTORY=/mljdata krateng/maloja

数据管理

导入历史记录

将以下来源的导出文件放入数据目录的import文件夹即可自动导入：

• Last.fm导出文件（通过ghan64's website生成）
• Spotify官方数据导出文件（在Spotify隐私设置获取）
• ListenBrainz官方导出文件（在ListenBrainz个人资料获取）
• 其他Maloja实例的导出文件

数据持久化

通过-v $PWD/malojadata:/mljdata挂载数据卷，确保容器重启后配置、记录和自定义图片不丢失。

自定义配置

配置文件

核心配置文件为数据目录下的/etc/maloja/settings.ini，支持通过环境变量设置（前缀MALOJA_，如MALOJA_PORT=42010）。详细配置项可参考https://github.com/krateng/maloja/blob/master/settings.md%E3%80%82

自定义图片

• 网页界面：管理员模式下，将图片拖放至艺术家/曲目页面的现有图片上即可上传。
• 文件系统：直接管理数据目录/var/lib/maloja/images下的图片文件，参考该目录下的images.info说明。

规则设置

通过数据目录/etc/maloja/rules下的rules.info文件定义自定义规则，或在服务器/admin_setup页面应用预定义规则。

如何记录音乐收听（Scrobble）

1. API密钥配置：在配置目录的apikeys.yml文件中设置API密钥（建议为每个客户端分配独立密钥），也可通过网页界面管理。

2. 支持的记录方式：

   • 原生支持Maloja API的客户端应用
   • 支持自定义ListenBrainz或GNUFM服务器的客户端（如Plex插件、音乐播放器扩展）
   • 网页界面手动提交：访问服务器/admin_manual页面手动录入收听记录

3. 代理转发：配置服务器将记录转发至Last.fm、ListenBrainz等第三方服务，实现数据同步。

扩展与集成

通过访问服务器/api_explorer页面探索API接口，可基于现有接口开发扩展功能或集成至其他应用。