Bubble Emby Admin

Appearance

FAQ ​

1. 没有我想要的功能、发现 Bug，或需要新增功能怎么办？ ​

如果你遇到 Bug，或希望增加新功能，请前往 GitHub Issues 提交反馈。

我会尽快查看并处理你的需求。

2. 怎么配置禁用客户端？ ​

如需根据客户端信息自动禁用账号，可按以下步骤配置：

  1. 在 系统配置 的 客户端黑名单 中添加需要禁用的黑名单规则。
  2. 在 Emby 后台的通知中新增 Webhook 通知，并勾选 用户。
  3. Emby 通知使用的 Webhook 地址 可在本系统的 Emby 设置 的 Webhook 配置 中获取。

配置完成后，命中客户端黑名单规则的账号会被系统自动禁用。

3. 安装后从哪里进入后台？ ​

首次部署时，请先通过 /install 完成安装。

安装完成后，管理员请使用 /admin/login 进入后台；普通用户使用 /login 进入网页用户入口。

/install 只用于首次安装，不用于后续日常管理。

4. 安装口令在哪里看？ ​

首次启动后，后端日志会输出一次性安装口令。

常见查看方式如下：

bash
docker logs -f bubble-emby-admin

或：

bash
docker compose logs -f app

安装页中的 一次性安装口令 字段需要填写该值。安装完成后，该口令不再用于后续登录。

5. 为什么网页注册入口没有了？ ​

网页注册入口是否显示，通常与以下配置有关：

  • 系统配置 中的 开放网页使用 是否已开启
  • 开放用户注册 是否已开启
  • 注册开放方式 当前是否处于可注册时间段，或是否还有剩余额度
  • 是否只开启了 邀请码注册

如果关闭了 开放网页使用，网页登录、网页注册、网页查看线路和网页续费都会不可用。

6. 为什么用户过期了或被禁用了，还是能进入用户中心？ ​

这是系统的默认设计行为。

用户过期、手动禁用或因客户端黑名单被禁用后，默认仍可进入用户中心，用于续费、修改密码和查看账号信息。

7. 忘记密码怎么用？恢复秘钥是什么？ ​

恢复秘钥 是用户自助重置密码所需的凭证，可在网页用户中心或 Telegram Mini App 的设置页生成。

  • 恢复秘钥只会明文展示一次
  • 生成后只会显示状态和尾号，不会再次展示完整内容
  • 如果开启了 开启忘记密码（恢复秘钥），登录页会显示 忘记密码 入口

用户可通过 /forgot-password 使用 用户名 + 恢复秘钥 重置密码。重置成功后，Emby 密码和当前网页密码会同时更新。

8. 什么时候用“同步用户”，什么时候用“恢复用户”？ ​

这两个功能的用途不同：

  • 同步用户：把 Emby 当前仍存在的用户写回本系统，适合首次接入本系统，或需要重新把 Emby 现有用户补齐到本地时使用
  • 恢复用户：把本地数据库里的用户重新恢复到 Emby，适合 Emby 被重置、丢失用户或需要重建账号时使用

如果 Emby 里本来就有历史用户，通常先用 同步用户；如果本地还有数据，但 Emby 侧用户缺失，通常用 恢复用户。

9. 为什么 Emby 用户没有同步到系统里？ ​

常见原因如下：

  • Emby 设置 中的 Emby 地址 或 API Key 配置不正确
  • 系统虽然已经接入 Emby，但还没有在 用户管理 中手动执行 同步用户
  • 需要同步的用户当前并不存在于 Emby 中

首次接入本系统后，如果 Emby 中已经有历史用户，建议先手动执行一次 同步用户。

10. 为什么配置了 Emby Webhook，但还是没有生效？ ​

建议按以下顺序排查：

  1. 确认 Emby 设置 中已开启 启用 Emby Webhook
  2. 确认 Emby 侧实际使用的是本系统生成的 Webhook 地址
  3. 确认 Emby 侧已经新增对应的 Webhook 通知，并勾选了业务所需事件
  4. 如果 Emby 和本系统都运行在 Docker 中，确认 Webhook 地址 中的主机名已替换为容器之间可访问的地址
  5. 结合运行日志确认 Emby 回调是否真正到达系统

很多“已配置但不生效”的问题，实际上是回调地址不可达，或 Emby 侧没有勾选正确的通知事件。

11. 为什么求片没有自动完成？ ​

求片自动完成依赖两套机制共同工作：

  • Emby Webhook 实时回调
  • 系统后台每 10 分钟一次的自动检查

如果内容刚入库但 Emby 还没有完成索引，自动完成可能不会立即发生。即使实时回调没有命中，系统后续仍会通过定时检查补做自动完成。

如果长时间没有自动完成，建议优先检查 Emby Webhook 是否正常，以及运行日志中是否有相关异常。

12. 播放统计为什么没有数据？ ​

播放统计 中的历史统计数据来自 Emby 的 Playback Reporting 插件，实时会话数据来自 Emby 的 /Sessions 接口。

如果你看到播放统计为空，常见原因包括：

  • Emby 没有安装或启用 Playback Reporting 插件
  • 插件里还没有累计到历史播放数据
  • Emby 设置 中的连接配置异常，导致系统无法读取 Emby 数据

如果只是历史统计为空，但实时会话正常，通常说明 /Sessions 可用，但 Playback Reporting 数据还没有准备好。

13. 为什么 Telegram Bot 或 Mini App 用不了？ ​

建议依次检查以下配置：

  • Telegram 基础配置 中的 开启 Telegram 服务 是否已开启
  • Bot Token 是否有效，保存后 Bot 用户名 是否已自动回填
  • 当前更新模式是 Webhook 还是 Long Polling
  • 使用 Webhook 模式时，公网地址 和 Webhook Secret 是否正确，是否已执行 注册 Webhook
  • 服务器无法直接访问 Telegram 时，是否已配置 Telegram HTTP 代理
  • 使用 Mini App 时，是否已开启 Telegram Mini App，并生成了可用的 Mini App 地址

Mini App 无法使用时，往往不是 Mini App 本身的问题，而是 Telegram 基础连接或公网地址配置不完整。

14. 用户怎么绑定 Telegram 账号？ ​

普通用户的绑定入口主要在 Telegram Mini App。

启用 Telegram Mini App 后，打开 允许已有账号登录并绑定当前 Telegram，用户即可通过 Telegram 菜单按钮或 Mini App 地址 进入用户中心，并使用已有网页账号登录完成绑定。

如果同时开启了 允许通过 Mini App 直接注册，没有账号的 Telegram 用户也可以先注册，再直接使用当前 Telegram 身份进入用户中心。

15. 为什么线路已经配置了，用户还是看不到？ ​

建议检查以下几点：

  • 线路本身是否开启了显示
  • 该线路是否设置为仅白名单用户可见
  • 当前用户是否满足对应的白名单条件
  • 系统配置 中的 开放网页使用 是否已关闭

如果关闭了 开放网页使用，网页侧的线路查看入口也会一起关闭。

16. 为什么管理员没有收到通知？ ​

管理员通知需要同时满足以下条件：

  • Telegram 设置中的 通过 Telegram 接收管理员通知 已开启
  • 通知配置 页面中对应的管理员通知事件已开启
  • 管理员本人已经在 个人设置 中完成 Telegram 绑定
  • 管理员本人的 我的通知接收 中开启了对应事件

当前管理员通知渠道仅支持 Telegram。只要以上任一条件不满足，通知都不会实际发送。

Bubble Emby Admin