yundan21/lastfm-visualize

By yundan21

•Updated 5 months ago

可视化lastfm的播放记录

Image

10K+

Overview Tags

yundan21/lastfm-visualize repository overview

⁠Last.fm Music Dashboard

个人音乐数据可视化平台 — 从 Last.fm 获取播放记录，通过 QQ 音乐/网易云音乐获取封面，以深色现代风格网页展示。

⁠功能一览

模块	功能
播放统计	本周 / 本月 / 本年 / 总计播放次数，支持自定义起始日期
排行榜	艺人 TOP 10 + 歌曲 TOP 20，支持周榜 / 月榜 / 年榜 / 自定义时间
最近播放	网格展示最近播放记录，封面懒加载
时间分析	24 小时热力图 / 星期×小时热力图 / 日期热力图 / 月度对比 / 年度对比
报告中心	日报 / 周报 / 月报 / 年报自动生成，网页浏览 + 图片导出 + 手动发送 Telegram
封面系统	自动匹配 QQ 音乐 / 网易云封面，支持手动搜索替换、本地上传、裁剪
Telegram 推送	定时推送报告 + 手动发送，支持 HTTP 代理
同步管理	首次全量同步 + 增量同步，后台异步执行，实时进度显示

⁠快速部署

⁠前置条件

Docker⁠ + Docker Compose⁠
Last.fm API Key⁠（免费申请）

⁠部署步骤

⁠1. 准备目录

mkdir -p ~/lastfm && cd ~/lastfm

⁠2. 创建 `.env` 文件

# Last.fm API（必需）
LASTFM_API_KEY=你的API_KEY
LASTFM_SHARED_SECRET=你的共享密钥

# Telegram 推送（可选）
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

# 全局代理（可选，Last.fm + Telegram 统一走代理）
PROXY_URL=http://127.0.0.1:7890

Last.fm API Key 前往 https://www.last.fm/api/account/create⁠ 申请。

⁠3. 创建 `docker-compose.yml`

services:
  app:
    image: yundan21/lastfm-visualize:3.19.0
    container_name: lastfm-visualize
    ports:
      - "3001:3001"
    environment:
      # 时区设置
      - TZ=Asia/Shanghai
      # Last.fm API（必需）
      - LASTFM_API_KEY=${LASTFM_API_KEY}
      - LASTFM_SHARED_SECRET=${LASTFM_SHARED_SECRET}
      # Telegram 推送兜底（可选，优先级低于 config/telegram.json）
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - TELEGRAM_CHAT_ID=${TELEGRAM_CHAT_ID}
      # 全局代理（Last.fm API + Telegram）
      - PROXY_URL=${PROXY_URL}
    volumes:
      - ./data:/app/data
      - ./config:/app/config
      - ./logs:/app/logs
    restart: unless-stopped

保证 .env与 docker-compose.yml同一目录

⁠4. 启动

docker compose up -d

首次启动会自动触发全量同步，访问 http://<IP>:3001 完成 Last.fm 授权后即可看到数据。

⁠更新版本

# 修改 docker-compose.yml 中的 image tag
docker compose pull
docker compose up -d
docker image prune -f

⁠配置说明

⁠环境变量

变量	必需	说明
`LASTFM_API_KEY`	是	Last.fm API Key
`LASTFM_SHARED_SECRET`	是	Last.fm 共享密钥
`TELEGRAM_BOT_TOKEN`	否	Telegram Bot Token，也可在前端设置页配置
`TELEGRAM_CHAT_ID`	否	Telegram 聊天 ID
`PROXY_URL`	否	全局代理地址，格式 `http://host:port`

⁠数据目录

容器通过 volume 挂载以下目录到宿主机：

宿主机路径	容器路径	内容
`./data`	`/app/data`	播放记录、封面缓存、报告、session
`./config`	`/app/config`	Telegram 等运行时配置（JSON）
`./logs`	`/app/logs`	应用日志文件（按天滚动）

⁠使用指南

⁠首次使用

访问 http://<IP>:3001
点击授权按钮，跳转到 Last.fm 登录并授权
授权完成后自动开始全量同步（后台异步进行，页面不会阻塞）
同步期间可以看到实时进度，同步完成后数据自动展示

⁠播放统计 & 排行榜

顶部统计卡片显示本周 / 本月 / 本年 / 总计播放次数
艺人排行榜和歌曲排行默认显示周榜，可切换月榜 / 年榜
点击日期选择器可指定自定义起始日期，系统将自动计算对应时间范围

⁠时间分析

进入时间分析页面：

视图	说明
日热力图	选择任意日期，查看 24 小时播放分布
周热力图	以起始日期为基准的 7 天 × 24 小时热力图
年热力图	按月份/日期展示全年分布，可滚动浏览
月度对比	选择年份，并排对比各月播放量
年度对比	选择两个年份，对比每日趋势

⁠报告中心

自动生成： 系统按默认计划自动生成报告（日报 08:00、周报周一 09:00、月报 1 号 10:00、年报 1/1 11:00）
手动生成： 点击「生成当前报告」按钮，自动计算当前时期并生成
浏览历史： 在「浏览历史」面板中选择任意历史时期
导出图片： 点击「导出图片」下载 480×320 的深色背景报告卡片
发送到 Telegram： 点击按钮将报告图片推送到指定聊天

⁠封面管理

⁠自动匹配

封面通过 QQ 音乐和网易云音乐并行搜索，精确匹配优先，无精确匹配则取置信度最高。

⁠手动修正

将鼠标悬停在封面图片上，点击右上角编辑按钮：

在线搜索 — 输入关键词搜索，选择正确的封面
本地上传 — 从电脑上传图片
裁剪 — 上传图片后可拖动裁剪区域

手动修正的封面不会被自动匹配覆盖。

⁠Telegram 推送设置

进入设置页面：

填写 Bot Token 和 Chat ID（也可写入 .env 作为兜底）
可选配置代理地址（http://host:port）
点击「测试连接」验证配置
编辑四个报告类型的 cron 表达式，修改推送时间

⁠故障排查

⁠常见问题

问题	解决方法
授权后无数据	检查 `LASTFM_API_KEY` 和 `LASTFM_SHARED_SECRET` 是否正确
封面不显示	检查网络能否访问 QQ 音乐 / 网易云 API，或手动修正封面
Telegram 推送失败	确认 Bot Token / Chat ID 正确，如有代理检查 `PROXY_URL` 格式是否为 `http://host:port`
日志查看	`docker compose logs -f` 或查看 `logs/app-YYYY-MM-DD.log`

⁠代理配置

如果需要通过代理访问 Last.fm 或 Telegram，设置 PROXY_URL 环境变量：

PROXY_URL=http://127.0.0.1:7890

⁠日志

容器日志：docker compose logs -f
文件日志：logs/app-YYYY-MM-DD.log（按天滚动）

⁠技术栈

前端： React 18 + TypeScript + Tailwind CSS + shadcn/ui
后端： Node.js 20 + Express
部署： Docker Compose
数据存储： 本地 JSON 文件（播放记录）+ SQLite（封面缓存）

Tag summary

Recent tags

Content type