zeyu8023/emby-stats repository overview

⁠🎬 EmbyPulse (映迹)

⁠Emby 服务器的高级伴侣：数据洞察、报表生成与自动化助手

⁠

功能特性⁠ • 快速部署⁠ • 系统配置⁠ • 预览截图⁠

⁠📖 项目简介

EmbyPulse (映迹) 是一个专为 Emby Media Server 打造的现代化综合管理面板。它填补了原生后台在数据可视化和自动化运维方面的空白，为服主提供了一个美观、直观且功能强大的“第二控制台”。

无论您是想通过精美的图表了解用户的观影习惯，还是需要自动生成类似“网易云音乐”风格的观影周报，亦或是通过 Telegram 机器人实现全自动化的入库与播放通知，EmbyPulse 都能完美满足。

⁠✨ 功能特性

⁠📅 追剧日历 (TV Calendar) [NEW]

• 本周热播：自动同步 TMDB 数据，直观展示本周（上周/下周）的剧集更新排期。
• 状态红绿灯：智能比对 Emby 库内文件。
  • 🟢 已入库：点击直接跳转 Emby 播放。
  • 🔴 缺失：剧集已出但库内没有，点击自动复制剧集信息（S01E05）方便补货。
• 灵活配置：前端可自定义缓存时间（1小时/1天/7天），兼顾性能与数据时效性。

⁠🎟️ 邀请与用户管理 (User System) [NEW]

• 邀请注册：
  • 邀请码生成：一键生成专属注册链接，支持设置有效期（如 7天、30天、永久）。
  • 自助注册页：用户凭链接自助设置用户名和密码，无需管理员手动建号。
• 生命周期管理：
  • 自动过期：支持设置账号有效期，到期后系统自动禁用账号，省去人工维护成本。
  • 全能编辑：支持在后台修改用户有效期、封禁/解禁账号，以及强制重置用户密码。

⁠📊 全景仪表盘 (Dashboard)

• 实时监控：直观展示当前并发播放数、转码任务状态、实时带宽消耗。
• 数据大屏：一览媒体库总量（电影/剧集/集数）、历史播放总数、活跃用户数及总播放时长。
• 趋势分析：基于 ECharts 的交互式图表，支持按日、周、月查看服务器热度趋势。

⁠🕵️ 数据洞察 (Insights)

• 用户画像：分析特定用户的观影偏好，生成趣味勋章（如：修仙党、周末狂欢、Emby肝帝）。
• 行为分析：提供 24 小时观影时间分布热力图及客户端设备分布统计。
• 质量盘点：深度扫描媒体库，统计 4K/HDR/杜比视界占比，自动列出低画质（SD/480P）资源以便洗版。

⁠🎨 映迹工坊 (Report Generator)

• 精美报表：自动生成精美的观影报告（日报、周报、月报、年报），支持生成长图。
• 多主题切换：内置黑金、赛博、极光、落日等多种配色主题，满足不同审美。
• 一键推送：支持将生成的报表图片直接推送到 Telegram 频道或群组，增强社区活跃度。

⁠🤖 机器人助手 (Bot)

• Telegram 集成：无缝对接 TG 机器人，支持指令交互。
• 实时通知：
  • 入库通知：新资源入库时，自动发送包含海报、评分和简介的精美通知。
  • 播放通知：实时推送用户开始/停止播放的状态消息。
• 便捷指令：支持 /search (搜索资源), /stats (今日统计), /check (系统健康) 等常用指令。

⁠🛠️ 管理与运维

• 任务中心：可视化管理 Emby 的计划任务，支持手动触发、状态监控及插件任务自动分组。
• 用户管理：直观的用户列表，支持批量设置账号有效期、一键禁用/启用或删除违规用户。
• 系统设置：全图形化配置，支持在线修改 Emby 连接、TMDB API（用于动态壁纸）、Webhook 安全令牌等。

⁠🚀 快速部署

推荐使用 Docker Compose 进行一键部署，仅需几分钟即可完成。

⁠1. 前置条件

• 服务器已安装 Docker 和 Docker Compose。
• 已拥有一个运行中的 Emby Server。
• [重要] Emby 需安装 "Playback Reporting" 插件（官方插件中心即可下载），用于记录历史播放数据。

⁠2. 创建目录与配置

在服务器上创建项目目录：

mkdir -p emby-pulse/config emby-pulse/static/img
cd emby-pulse

创建 `docker-compose.yml` 文件：
```yaml
version: '3.8'

services:
  emby-pulse:
    # 1. 使用远程镜像 (确保您GitHub Actions已经构建完成并推送了新镜像)
    image: zeyu8023/emby-stats:latest
    container_name: emby-pulse
    restart: unless-stopped
    network_mode: host
    
    volumes:
      # --- 数据与配置 ---
      - /volume1/docker/emby/data:/emby-data
      - ./config:/app/config  
    
    environment:
      - TZ=Asia/Shanghai
      - DB_PATH=/emby-data/playback_reporting.db
      # 下面这两个如果 config.json 里存了，这里其实可以删掉，保留也没事作为兜底
      - EMBY_HOST=http://192.168.31.2:8096
      - EMBY_API_KEY=xxxxxxxxxxxxxxxxx

⁠3. 启动服务

docker-compose up -d

启动成功后，访问 http://您的IP:10307 即可进入登录页面。

⁠⚙️ 系统配置

首次登录后，请点击侧边栏的 "系统设置" 完成基础对接：

1. API 设置：
   • 在 Emby 后台生成一个 API Key，填入设置页面的 "Emby API Key" 栏。
2. Webhook 配置 (启用实时通知)：
   • 在 EmbyPulse 设置页设置一个 Token (例如 embypulse)。
   • 在 Emby 后台 -> Webhooks -> 添加 Webhook：
     • URL: http://IP:10307/api/v1/webhook?token=embypulse
     • 事件勾选: Playback Start, Playback Stop, New Media Added。
3. 机器人设置 (可选)：
   • 填入 Telegram Bot Token 和 Chat ID，即可开启消息推送功能。

⁠📄 许可证

本项目基于 MIT 许可证开源。