foxxmd/maloja

Maloja

![]([] ![]([]

镜像概述和主要用途

Maloja是一个简单的自托管音乐记录数据库，旨在创建个人收听统计。它摒弃了推荐、社交网络等额外功能，专注于纯粹的收听历史追踪与分析。用户可通过网页界面查看个人音乐收听数据，支持自定义标签 schema 和多艺术家标记，确保协作作品的所有参与者都能在统计中得到体现。

可访问官方示例页面查看实际效果。

重要提示：2.0版本更新后，Maloja已重构为Python包，旧更新脚本不再适用。若仍使用1.x版本，请参见更新部分。

核心功能和特性

• 自托管数据：数据完全由用户掌控，以易解析格式存储，确保永久访问权
• 自定义标签：支持个人化标签 schema，可将关联艺术家分组统计
• 多艺术家支持：允许单首曲目关联多个艺术家，准确反映协作作品的收听贡献
• 自定义媒体资源：可上传自定义艺术家或曲目图片
• 轻量级设计：无多余功能，专注于收听历史记录与统计分析
• 多API支持：提供原生API和标准兼容API（GNU FM、ListenBrainz），支持多种记录方式

使用场景和适用范围

• 希望掌控个人音乐收听数据的用户
• 需要自定义音乐标签和艺术家分组的音乐爱好者
• 希望准确统计协作音乐作品收听情况的用户
• 寻求轻量级、无社交功能的音乐统计工具的自托管爱好者

详细使用方法和配置说明

环境要求

• 推荐系统：Alpine Linux（问题支持最佳）
• 内存需求：2-4 GB RAM

安装方法

新安装

1. 确保安装Python 3.5或更高版本。基础依赖包可通过Alpine或Ubuntu的shell脚本安装（项目提供）。

2. 若需显示媒体图片，需获取以下免费API密钥：

   • Last.fm
   • Fanart.tv（需项目密钥，非个人密钥）

3. 通过pip安装Maloja：

   bash
   pip install malojaserver  # 必要时使用pip3确保Python 3版本
   

4. （推荐）通过反向代理实现SSL加密，确保代理至IPv6地址（除非修改设置为IPv4）。容器部署需暴露32400端口（或自定义端口）。

5. （推荐）设置cron任务管理服务：

   bash
   @reboot sleep 15 && maloja start  # 重启后自动启动
   42 0 * * 2 maloja restart        # 每周二0:42重启服务
   

更新

• 1.x版本升级：按上述新安装步骤安装包，然后手动将用户数据复制到~/.local/share/maloja目录
• 2.0+版本升级：直接运行maloja update或使用pip更新机制：pip install --upgrade malojaserver

Docker部署

项目包含Dockerfile，也可使用FoxxMD提供的非官方Dockerhub仓库：

bash
# 基本运行命令
docker run -d -p 32400:32400 -v ~/.local/share/maloja:/app/maloja_data foxxmd/maloja

# 自定义端口和环境变量示例
docker run -d \
  -p 8080:32400 \
  -v /path/to/maloja/data:/app/maloja_data \
  -e MALOJA_SKIP_SETUP=true \
  -e MALOJA_PORT=32400 \
  foxxmd/maloja

基本控制

通过命令行管理服务：

bash
maloja start    # 启动服务
maloja stop     # 停止服务
maloja restart  # 重启服务
maloja debug    # 前台运行服务（用于调试）

数据管理

数据导入

1. 使用benfoxall的工具导出Last.fm历史记录（CSV格式）
2. 导入数据：

   bash
   maloja import /path/to/exported.csv
   

数据备份

bash
maloja backup          # 完整备份（包含媒体资源等）
maloja backup -l minimal  # 最小备份（仅核心数据）

数据库修复

当添加新规则后，修复数据库：

bash
maloja fix

自定义配置

设置管理

• 配置文件位置：~/.local/share/maloja/settings
  • default.ini：默认设置参考
  • settings.ini：用户自定义设置（覆盖默认值）
• 环境变量：所有设置可通过MALOJA_前缀的环境变量设置（如MALOJA_SKIP_SETUP）

自定义图片

• 网页界面：启用管理员模式后，可直接将图片拖放至艺术家/曲目页面的现有图片上
• 文件系统：通过~/.local/share/maloja/images目录下的images.info文件管理

规则配置

• 规则文件：~/.local/share/maloja/rules目录下的rules.info
• 预定义规则：可通过服务器/setup页面应用

音乐记录方法

需在~/.local/share/maloja/clients/authenticated_machines.tsv文件中配置API密钥。

原生API

• 浏览器扩展：支持Chromium系浏览器（Plex Web、Spotify、Bandcamp等），可从Chrome应用商店获取，需在扩展设置中输入Maloja首次启动生成的随机密钥
• 自定义实现：通过POST请求至/api/newscrobble，参数包括artist、title和key（支持form-data或json格式）

标准兼容API

支持audioscrobbler (GNU FM)和ListenBrainz协议（实验性），配置如下：

已测试兼容Android应用：Pano Scrobbler、Simple Last.fm Scrobbler。建议为每个记录工具配置独立API密钥。

手动记录

通过访问Maloja服务器的/manual页面手动提交收听记录。

扩展开发

如需基于Maloja开发扩展功能，可访问/api_explorer查看API文档。