概述
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 部署
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
- 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 地址
- - 本地模式需要挂载 Emby 的 Playback Reporting 数据库
环境变量
| 变量 | 说明 | 默认值 | 必填 |
|---|---|---|---|
TZ | 时区设置 | Asia/Shanghai | 推荐 |
PORT | 容器内服务端口 | 10307 | 可选 |
REQUEST_PORT | 用户中心后台端口 | 10308 | 可选 |
DB_PATH | Playback Reporting 数据库路径 | - | 本地模式必填 |
FORCE_MIGRATE | 强制迁移系统数据库 | 1 | 可选 |
EMBY_HOST | Emby 服务器地址 | - | 必填 |
EMBY_API_KEY | Emby API Key | - | 选填 |
数据库模式
通过 API 穿透查询，部署最简单
适用：极空间、云服务器、无法挂载数据库
直接读取数据库文件，性能最高
适用：本地 Docker、可挂载 Emby 数据目录
Emby 基础配置
| 配置项 | 说明 |
|---|---|
emby_host | Emby 服务器地址 |
emby_api_key | Emby API Key |
webhook_token | Webhook 安全令牌 |
emby_public_url | 对外访问 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 如何获取？
登录 hdhive.com 后，进入个人设置 > API 管理创建。
为什么无法登录后台？
请检查 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. 播放一些内容后等待几分钟刷新。