概述

EmbyPulse-Pro 是一款专为 Emby 服务器设计的专业级管理工具，提供风险管控、智能运维、用户管理、数据分析等全方位功能。通过 Docker 一键部署，支持本地模式和 API 模式两种运行方式。

快速部署

Docker Compose 一键启动，3 分钟完成部署

风险管控

实时监控并发播放，自动拦截违规账号

智能运维

缺集扫描、追剧日历、自动合集等智能功能

用户管理

积分系统、保号规则、用户画像分析

快速开始

安装 Playback Reporting 插件

在 Emby 服务器中安装官方 Playback Reporting 插件，这是必须的前提条件。

创建配置文件

创建 docker-compose.yml 文件，配置必要的环境变量。

启动服务

运行 docker-compose up -d 启动容器。

访问后台

打开浏览器访问 http://your-ip:10307 进入管理后台。

Docker Compose 部署

docker-compose.yml

version: '3.8'

services:
  emby-pulse:
    image: zeyu8023/embypulse-pro:latest
    container_name: emby-pulse
    restart: unless-stopped
    network_mode: host
    
    volumes:
      - /volume1/docker/emby/data:/emby-data
      - /volume1/docker/emby-pulse/config:/workspace/config
      - /volume1/docker/emby-pulse/data:/workspace/data
    
    environment:
      - TZ=Asia/Shanghai
      - DB_PATH=/emby-data/playback_reporting.db
      
      # 本地账号配置（可选，开启后可独立登录）
      - LOCAL_AUTH_ENABLED=true
      - LOCAL_ADMIN_USERNAME=admin
      - LOCAL_ADMIN_PASSWORD=your_password
      
      # Emby 配置（本地账号和 Emby Host 必填其一）
      # - EMBY_HOST=http://192.168.31.2:8096
      # - EMBY_API_KEY=your_api_key_here
      
      # - FORCE_MIGRATE=1

重要提示

- network_mode: host 使用主机网络，默认后台端口 10307，用户中心端口 10308
- 本地账号和 Emby Host 必须填写其一，否则无法登录后台
- 开启本地账号后，Emby API Key 可在后台设置中配置
- 本地模式需要挂载 Emby 的 Playback Reporting 数据库

环境变量

变量	说明	默认值	必填
`TZ`	时区设置	Asia/Shanghai	推荐
`PORT`	容器内服务端口	10307	可选
`REQUEST_PORT`	用户中心后台端口	10308	可选
`DB_PATH`	Playback Reporting 数据库路径	-	本地模式必填
`LOCAL_AUTH_ENABLED`	开启本地管理账号开启后可用独立账号登录，不依赖 Emby	false	可选
`LOCAL_ADMIN_USERNAME`	本地管理员用户名 ⚠️ 开启本地账号时必填	-	本地账号必填
`LOCAL_ADMIN_PASSWORD`	本地管理员密码 ⚠️ 开启本地账号时必填	-	本地账号必填
`EMBY_HOST`	Emby 服务器地址本地账号和 Emby Host 必填其一	-	条件必填
`EMBY_API_KEY`	Emby API Key 可在后台设置中配置，核心功能依赖	-	核心功能必填
`FORCE_MIGRATE`	强制迁移系统数据库 ⚠️ 仅迁移时填写，完成后务必删除	1	可选

账号登录说明

EmbyPulse-Pro 支持两种登录方式：Emby 管理员账号登录和本地管理员账号登录。可根据实际需求灵活配置。

Emby 账号登录

使用 Emby 服务器的管理员账号密码登录，适合已有 Emby 服务器的场景。

配置要求：

- 必须配置 EMBY_HOST
- 账号密码为 Emby 管理员账号

本地账号登录

使用独立创建的本地管理员账号登录，不依赖 Emby 服务器，适合独立部署场景。

配置要求：

- LOCAL_AUTH_ENABLED=true
- 配置 LOCAL_ADMIN_USERNAME
- 配置 LOCAL_ADMIN_PASSWORD

禁用 Emby 管理员登录

开启本地账号后，可在后台系统设置中禁用 Emby 管理员账号登录，实现独立管理。

启用条件

- 必须先开启本地管理员账号
- 禁用 Emby 登录开关仅在本地认证开启时显示
- 禁用后 Emby 管理员账号将无法登录后台

📝 使用流程

开启本地认证：设置环境变量 LOCAL_AUTH_ENABLED=true

创建本地账号：配置用户名和密码环境变量

登录后台：使用本地账号登录管理后台

禁用 Emby 登录：在系统设置 → 账号管理中开启「禁用 Emby 登录」开关

后台账号管理功能

开启本地认证后，可在后台设置页面的「账号管理」卡片中管理本地账号：

✅ 支持的操作

- 创建新的本地账号
- 编辑账号用户名、密码
- 设置账号角色（管理员/子账号）
- 配置子账号权限
- 启用/禁用账号
- 删除账号
- 开启/关闭本地认证
- 禁用 Emby 管理员登录
- 绑定/解绑 TOTP 两步验证

🔐 角色说明

管理员：拥有全部权限，可管理其他账号
子账号：只能修改自己密码，不能管理其他账号
权限控制：子账号可配置19个页面的访问权限
侧边栏：根据权限动态隐藏菜单项
两步验证：本地账号支持 TOTP 安全验证

TOTP 两步验证

本地账号支持 TOTP 两步验证，登录时除了密码，还需要输入验证器应用生成的 6 位动态验证码，大幅提升账号安全性。

支持的验证器应用

验证器	平台
Google Authenticator	iOS / Android
Microsoft Authenticator	iOS / Android / Windows
Authy	iOS / Android
1Password	iOS / Android / macOS / Windows
其他 TOTP 兼容应用	所有平台

🔐 登录流程

输入用户名和密码

系统检测账号启用 TOTP，显示验证码输入框

打开验证器应用获取 6 位动态验证码

输入验证码完成登录

💡 安全提示

- 绑定后请保存密钥，更换手机时可用密钥重新绑定
- 验证码每 30 秒刷新一次
- 允许前后 1 个时间窗口的验证码（防止时钟偏差）
- 建议管理员账号启用两步验证，提升安全性

功能介绍

EmbyPulse-Pro 提供完整的服务器管理解决方案，以下为各功能模块的详细说明。

仪表盘

通过直观的可视化卡片实时监控服务器运行状态。内置 15 个功能卡片，支持右下角卡片配置按钮自由添加，底部下拉调整高度，卡片右上角菜单调整宽度。天气卡片需在设置页配置天气 API；若其他卡片无数据，请检查 Emby API 配置及 Playback Reporting 插件安装状态。

内容排行

综合展示服务器播放热度与观看时长排名。支持自定义排名维度（播放量、总时长），分类筛选（电影、剧集），排除指定媒体类型。数据源自 Playback Reporting 插件。

数据洞察

深度分析服务器播放数据，包含用户画像与成就勋章系统。全景展示：24H 观影生物钟、观影偏好天平、观影频率统计、硬件设备分布、播放软件偏好、最近 100 条流水账。支持用户维度筛选，查看单用户独立数据。数据源自 Playback Reporting 插件。

质量盘点

全量扫描服务器电影画质分布。支持分辨率矩阵、光影与动态范围分析，快速定位低画质影片。数据源自 Emby API，若页面无数据请检查媒体元数据是否正确获取。

缺集管理

全库扫描：智能比对 Emby 现有剧集与 TMDB 全量数据，精准定位已上线但库内缺失集数。

MoviePilot 联动：一键调用 MP 搜索接口，支持根据库内已有版本自动匹配 4K / 1080P / HDR 等基因配型。

底层下载截胡：推送到 MP 下载整季包时，系统自动切入 qBittorrent / Transmission，物理切除非必要文件，实现"只下载缺的那几集"。

状态心跳同步：采用焦点唤醒机制，入库后前端数据零延迟自动核销变色。

下载器配置在右上角菜单。数据通过 Emby API 与 TMDB 对比，因数据复杂性可能有部分剧集不准，请自行排查。支持屏蔽指定媒体库。

去重管理

深度检测媒体库内重复的剧集和电影，支持智能权重匹配，可一键删除重复资源。提供白名单与屏蔽媒体库功能，支持自定义扫描权重。⚠️ 删除有风险，请仔细核对后再操作。去重删除等效于 Emby 删除媒体功能，会删除本地文件；若配置神医深度删除，将同步删除网盘内容。

播放历史

全站用户详细观影流水，支持当日数据观看统计，清晰展示服务器播放动态。包含用户头像、设备信息展示、IP 归属地精确查询（IPv4/IPv6）。

工单大厅

求片与纠错：支持用户提交电影、剧集、季度等求片请求，统一流转后台处理。

状态追踪：支持待处理、已下载、已入库、已拒绝等完整状态链路。

自动联动：媒体一旦成功入库，可自动完成对应求片工单闭环。

机器人协同：支持通过 Telegram 等渠道触发求片反馈与处理提醒。

用户管理

集中展示用户基础资料、到期时间、备注等关键信息。支持账号续期、到期控制、状态管理与生命周期维护；生成带有效期的注册链接和注册码（7 天、30 天、永久）；用户通过邀请链接自助建号，无需管理员干预。支持账号自动到期锁定、批量续期及强制重置密码，可套用 Emby 用户权限模板，轻松管理用户权限。

消息中心

支持与用户实时沟通。用户可通过用户社区向管理员发送消息，管理员支持后台回复与 TG 机器人回复。提供禁言管理、屏蔽通知灯功能。

积分引擎

支持设定用户签到积分，配置求片消耗积分，配置积分商城。积分商城支持自动发货续期模式和手动发货的其他商品配置。

自动发货续期支持盲盒模式，管理员可自由配置消耗积分、获得天数及盲盒概率，支持用户积分批量调控。

风险管控

实时监控多设备并发播放，自定义阈值，自动识别异常账号。支持警告 / 封禁 / 踢下线等处理策略。VIP 用户可跳过风控检测，完整封禁 / 解封操作日志追溯。

客户端管控

分析全服播放设备，一键阻断异常客户端。

追剧日历

智能联动 Emby 媒体库状态，通过 TMDB 获取每日更新日历，智能比对本地媒体库，支持状态实时更新。

机器人助手

管理员机器人：通过机器人对服务器进行管理和查看通知，绝大多数功能均可通过管理机器人触发通知。

用户机器人：支持用户注册、查看媒体服务器信息等功能。

频道入库通知：将管理员机器人加入频道并赋予管理员权限，后台填入频道信息，开启入库通知即可。

群内互动命令：支持签到、帮助、积分三个命令。将用户机器人拉入群聊，填入频道 ID 即可开启。

任务中心

管理 Emby 计划任务与后台作业，支持接入系统通知。

映迹工坊

多维报表：自动生成日报、周报、月报及年度总结。

内置黑金、赛博、极光、落日等精美视觉主题，支持一键生成长图。用户社区支持生成用户个人数据报表。

数据库模式

API 模式

通过 API 穿透查询，部署最简单

不设置 DB_PATH

适用：极空间、云服务器、无法挂载数据库

本地模式

直接读取数据库文件，性能最高

设置 DB_PATH=/path/to/db

适用：本地 Docker、可挂载 Emby 数据目录

Emby 基础配置

配置项	说明
`emby_host`	Emby 服务器地址
`emby_api_key`	Emby API Key（必填）
`webhook_token`	Webhook 安全令牌
`emby_public_url`	对外访问 Emby 的公网地址

⚠️ Emby API Key 配置指南

必须填写 Emby API Key！

Emby API Key 是系统的核心凭证，缺少此配置将导致大量核心功能无法正常运行。

功能模块数据依赖分析

了解哪些功能依赖 Emby API，哪些可以独立运行：

✓纯本地数据库（不依赖 Emby API）

模块	数据表	说明
播放历史	PlaybackActivity	从 playback.db 读取
质量盘点	insight_ignores	盘点忽略列表
去重管理	dedupe_results, dedupe_whitelist, dedupe_config	去重结果和配置
积分引擎	point_config, point_logs, users_meta	积分配置和记录
风险管控	risk_logs, users_meta	风控记录
邀请码	invitations	邀请码管理
禁言管理	user_mutes, bot_notify_mutes	禁言记录
任务配置	task_config	定时任务

!强依赖 Emby API（必须配置 API Key）

模块	Emby API 调用	说明
用户管理	/Users, /Users/{id}, /Users/{id}/Policy	用户列表、详情、权限修改
仪表盘	/Users, /Sessions, /Items/Counts	用户、会话、媒体统计
内容排行	/Items, /Users/{id}/Items	媒体详情和观看历史
缺集管理	/Users/{id}/Items, /Shows/{id}/Episodes	剧集扫描
搜索	/Users/{id}/Items, /Shows/{id}/Episodes	媒体搜索
消息中心	/Users/{id}/Images/Primary	用户头像
注册邀请	/Users/New, /Users/{id}/Policy	创建新用户
客户端设备	/Devices, /Sessions	设备列表、会话

◐混合模式（本地 + Emby API）

模块	本地数据	Emby API
用户管理	users_meta（过期、VIP、线路）	用户 Policy、头像
追剧日历	users_meta	TMDB API 获取剧集信息
客户端管控	client_blacklist	/Devices 设备管理

缺少 Emby API Key 的影响

❌ 无法使用的功能

✗Emby 账号登录
✗用户列表与管理
✗仪表盘实时统计
✗内容排行观看数据
✗缺集扫描
✗媒体搜索

✓ 可独立运行的功能

✓播放历史（本地数据库）
✓积分引擎（本地数据库）
✓客户端黑名单（本地）
✓审计日志（本地数据库）
✓邀请码管理（本地数据库）

如何获取 Emby API Key

登录 Emby 后台

打开 Emby 服务器网页界面，使用管理员账号登录。

进入设置页面

点击右上角设置图标 ⚙️，选择「服务器」 → 「API」。

创建 API Key

点击「新增」按钮，输入应用名称（如 "EmbyPulse"），点击保存。

复制 API Key

生成的 API Key 会显示在列表中，点击复制按钮保存。

填写到配置

将 API Key 填入 EmbyPulse-Pro 的系统设置 → 媒体服务器核心 → Emby API Key字段，或环境变量 EMBY_API_KEY。

安全提示

API Key 具有管理员权限，请妥善保管，不要泄露给他人。如发现泄露，请立即在 Emby 后台删除并重新生成。

风控配置

配置项	说明
`risk_max_concurrent`	最大并发数限制
`risk_action`	违规处理方式：warn_only / warn_user / auto_ban
`risk_vip_exempt`	VIP 用户豁免开关

Telegram 配置

配置项	说明
`tg_bot_token`	Telegram Bot Token
`tg_chat_id`	推送目标聊天 ID
`proxy_url`	网络代理（可选）

TMDB 配置

配置项	说明
`tmdb_api_key`	TMDB API Key，用于缺集扫描、合集同步

MoviePilot 配置

配置项	说明
`moviepilot_url`	MoviePilot 服务地址
`moviepilot_token`	MoviePilot API Token

插件系统

EmbyPulse-Pro 提供丰富的插件系统，按需启用扩展功能。

插件名称	功能描述	状态
用户到期提醒	用户到期自动提醒通知	Pro专享
115网盘转存	链接自动转存到115网盘	内置
影巢资源中心	对接影巢资源站	内置
保号规则	播放时长达标检测，自动处理不达标账号	Pro专享
媒体库封面管理	快速更新媒体库封面图	Pro专享
自定义通知模板	自定义通知风格（动漫风、幽默风等）	内置
Emby智能合集	同步 TMDB 热门电影剧集，自动更新合集	Pro专享
观影报告	多维报表生成，精美主题	内置

说明

插件可在后台「系统设置 > 插件管理」中启用或禁用。Pro专享插件需要授权才能使用。

端口说明

端口	服务	说明
`10307`	管理后台	管理员控制面板，配置管理、用户管理等
`10308`	用户中心	用户自助服务，查看播放记录、积分等

端口修改

通过环境变量 PORT 和 REQUEST_PORT 可自定义端口。使用 network_mode: host 时直接访问对应端口。

备份恢复

数据目录

/workspace/config - 配置文件目录
/workspace/data - 数据库文件目录（IP归属地等）

备份方法

docker exec emby-pulse tar -czvf /tmp/backup.tar.gz /workspace/config /workspace/data
docker cp emby-pulse:/tmp/backup.tar.gz ./embypulse-backup-$(date +%Y%m%d).tar.gz

恢复方法

docker cp ./embypulse-backup.tar.gz emby-pulse:/tmp/
docker exec emby-pulse tar -xzvf /tmp/embypulse-backup.tar.gz -C /

安全建议

访问控制

1. 使用反向代理（Nginx/Caddy）配置 HTTPS
2. 配置防火墙限制访问 IP 范围
3. 修改默认端口避免扫描
4. 定期更换 Emby API Key

密钥管理

1. 不要将 API Key 硬编码在配置文件中
2. 使用环境变量或 Docker Secrets 管理敏感信息
3. 定期轮换 Telegram Bot Token
4. Webhook Token 使用强随机字符串

监控审计

1. 定期检查风控执法记录
2. 监控异常登录行为
3. 关注 Telegram 告警通知
4. 定期审查用户权限

免责声明

使用须知

•本地部署优先：本项目建议在本地网络环境中部署使用，以确保数据安全和服务稳定。
•公网风险提示：如需将服务暴露至公网访问，请充分评估潜在安全风险。公网暴露可能导致恶意攻击、数据泄露等问题，请谨慎操作。
•安全防护措施：若必须公网部署，请务必采取以下安全措施：
1.设置强密码，避免使用默认密码或弱密码
2.使用反向代理（如 Nginx、Caddy）配置 HTTPS 加密传输
3.接入CDN 服务隐藏真实服务器 IP，提供额外防护层
4.配置防火墙规则限制访问来源
5.定期更新版本修复安全漏洞
•责任声明：因使用不当或安全配置缺失导致的任何损失，开发者不承担相关责任。请使用者自行承担风险。

常见问题

是否必须安装 Playback Reporting 插件？

是的。无论使用本地模式还是 API 模式，Emby 都必须安装此官方插件以生成播放历史数据。

API 模式和本地模式的区别？

本地模式：直接读取数据库文件，性能最高，需要挂载数据库路径。API 模式：通过 API 穿透查询，部署最简单，无需挂载数据库。

Pro 版与普通版的区别？

Pro 版独占风险管控、积分系统、智能合集、保号规则、Telegram机器人、注册码管理等功能。

影巢 API Key 如何获取？

为什么无法登录后台？

请检查 EMBY_HOST 是否配置正确，确保地址可访问。账号密码为 Emby 管理员账号密码。

TMDB API 配置无效？

1. 确认 TMDB API Key 是否正确填写；2. 检查网络是否能访问 api.themoviedb.org；3. 如在国内服务器，需配置代理 TMDB_PROXY；4. 验证 API Key 是否有效，可在 TMDB 官网测试。

Telegram Bot 无法连接？

1. 确认 Bot Token 格式正确（数字:字母数字组合）；2. 检查 Chat ID 是否正确；3. 如在国内服务器，需配置代理 proxy_url；4. 先用浏览器测试 api.telegram.org 是否可访问。

MoviePilot 连接失败？

1. 确认 MoviePilot 服务地址正确（包含端口号）；2. 检查 API Token 是否有效；3. 确保网络可达 MoviePilot 服务；4. 查看 EmbyPulse 日志获取详细错误信息。

代理配置无效？

代理地址格式应为：http://ip:port 或 socks5://ip:port。确认代理服务已启动且端口正确。如使用 Clash 等工具，确保开启了允许局域网连接。

数据库迁移失败？

1. 首次部署可设置 FORCE_MIGRATE=1 强制迁移；2. 检查 /workspace/data 目录权限是否正确；3. 查看容器日志：docker logs emby-pulse；4. 确保挂载目录存在且有写入权限。

播放数据不显示？

1. 确认 Emby 已安装 Playback Reporting 插件；2. 检查插件是否已启用且有数据记录；3. 本地模式确认 DB_PATH 路径正确；4. API 模式确认 Emby API Key 有效；5. 播放一些内容后等待几分钟刷新。