nfhgw295/embynotice-bot repository overview

⁠Emby Telegram 通知服务 (Emby Notice Bot)

版本：v4.6.1 项目简介：实时监控 Emby 媒体服务器的关键事件（播放、入库、用户操作、元数据更新等），通过 Telegram 机器人发送格式化通知。支持图片防剧透、多聊天 ID、智能集数解析、代理配置和时区自定义。

⁠一、核心特性

1. 全面事件监控：支持播放（开始/停止/暂停）、媒体库更新（新增/删除/元数据刷新）、用户登录/登出等事件，可自定义监控列表。
2. 智能集数解析：准确识别连续集（S01E01-E05）、非连续散集（S01E08,E11-E14）及跨季集数，通知中清晰展示。
3. 多用户/多群组通知：支持向多个 Telegram 聊天（用户/群组）同时发送通知，逗号分隔 TELEGRAM_CHAT_ID 即可。
4. 图片模糊防剧透：通过 ENABLE_SPOILER 控制是否将发送的封面图片设为模糊效果。
5. 元数据更新详情：可显示具体变更的字段（如名称、评分、首映日期等），字段列表可自定义。
6. 灵活网络配置：支持 HTTP/HTTPS 代理，自动判断 Emby 内网地址绕过代理。
7. 高可用性：内置失败重试队列（最多 5 次），缓存去重防止重复发送。
8. 可视化封面图片：自动从 Emby 获取媒体封面（Backdrop/Primary 等），按媒体类型智能选择。
9. 缓存统计与日志：可选 DEBUG 模式，查看缓存命中率、队列状态，便于运维。

⁠二、Docker Compose 配置

创建 docker-compose.yml 文件，内容如下（使用最新稳定镜像 nfhgwy295/embynotice-bot:latest，建议固定具体版本号）：

version: '3.8'

services:
  embynotice-bot:
    image: nfhgw295/embynotice-bot:latest   # 可替换为 v4.6.1
    container_name: embynotice-bot
    network_mode: bridge
    environment:
      # 必填
      - TELEGRAM_BOT_TOKEN=your_bot_token
      - TELEGRAM_CHAT_ID=12345678,87654321   # 多个ID用逗号分隔

      # 推荐填写（用于封面图片）
      - EMBY_SERVER_URL=http://your_emby:8096
      - EMBY_API_KEY=your_emby_api_key

      # 服务监听
      - WEBHOOK_HOST=0.0.0.0
      - WEBHOOK_PORT=8099

      # 监控事件（可选，默认值如下）
      - EMBY_MONITOR_EVENTS=playback.start,playback.stop,playback.pause,user.authenticated,user.logout,library.new,library.deleted,metadata.update

      # 时区与代理（可选）
      - TZ=Asia/Shanghai
      - HTTP_PROXY=http://proxy:port
      - HTTPS_PROXY=https://proxy:port

      # 功能开关（可选）
      - ENABLE_COVERS=True
      - ENABLE_SPOILER=True
      - OVERVIEW_MAX_LENGTH=150
      - DEBUG_MODE=False
      - RATING_DECIMAL_PLACES=1

      # 元数据跟踪字段（可选）
      - METADATA_TRACKED_FIELDS=Name,Overview,OriginalTitle,Tagline,OfficialRating,CommunityRating,Genres,ProductionYear

    ports:
      - "8099:8099"
    restart: unless-stopped

⁠三、使用说明

⁠1. 配置 Emby Webhook

1. 登入 Emby 后台 → 设置 → 通知 → Webhook → 点击 + 添加。
2. 配置参数：
   • 名称：任意（如 Telegram通知）
   • URL：http://通知服务IP:8099/emby-webhook
     • 若服务与 Emby 同一 Docker 网络，可使用容器名：http://embynotice-bot:8099/emby-webhook
   • 事件类型：勾选需要监控的事件（建议全选或与 EMBY_MONITOR_EVENTS 一致）
   • 格式：必须选择 multipart/form-data
3. 点击 保存。

⁠2. 启动服务

docker-compose up -d
docker-compose logs -f   # 查看启动日志

⁠3. 测试

在 Emby 中播放一部电影、新增一个剧集或登录一个用户，几秒后 Telegram 应收到通知。

⁠四、环境变量详解

默认监控事件：

playback.start,playback.stop,playback.pause,user.authenticated,user.logout,library.new,library.deleted,metadata.update

默认跟踪元数据字段：

Name,Overview,OriginalTitle,Tagline,OfficialRating,CustomRating,CriticRating,CommunityRating,IndexNumber,ParentIndexNumber,PremiereDate,ProductionYear,EndDate,RunTimeTicks,Tags,Genres,Studios,ProductionLocations,ProviderIds

⁠五、常见问题排查

⁠1. 未收到任何通知

• 检查日志：docker-compose logs 查看错误信息（Token 无效、网络不通）。
• Emby Webhook 配置：确认 URL、格式（multipart/form-data）、事件类型是否正确。
• 防火墙：确保 8099 端口开放，Emby 能访问该地址。
• 测试端点：容器内执行 curl http://localhost:8099/emby-webhook 应返回 405 Method Not Allowed。

⁠2. 封面图片无法发送

• 确认 EMBY_SERVER_URL 和 EMBY_API_KEY 正确。
• 确认 Emby 中媒体包含图片（Primary/Backdrop）。
• 日志提示“图片过大”会自动降级为文本（限制 10MB）。

⁠3. 代理无效

• 确保代理地址包含协议（http://）。
• 容器内测试：curl -I --proxy http://proxy:port https://api.telegram.org
• 日志显示“代理已启用”表示配置生效；Emby 内网地址会自动绕过代理。

⁠4. 收到重复通知

• 极少出现，缓存去重（TTL 24小时）。如果发生，可能是 Emby 重复推送，日志可看到“重复事件已跳过”。

⁠5. 元数据更新显示乱码

• 检查 METADATA_TRACKED_FIELDS 字段名与 Emby 返回一致（大小写敏感）。

⁠六、升级说明（v4.5.x → v4.6.1）

• 框架变更：升级至 python-telegram-bot 20.x 异步架构，必须更新镜像。
• 新增变量：ENABLE_SPOILER（默认 True，可设为 False 关闭模糊）。
• 多聊天 ID：TELEGRAM_CHAT_ID 支持逗号分隔多个 ID，旧版单个 ID 依然兼容。
• 默认字段：METADATA_TRACKED_FIELDS 保持不变，可按需修改。

升级步骤：

docker-compose pull          # 拉取最新镜像
docker-compose up -d         # 重启容器