实例管理
约 2695 字大约 9 分钟
2025-04-18
对应前端侧边栏 开服 → 实例管理，集中管理每个 Emby 实例的 Bot 配置、入库通知、运营模式、生命周期任务、权限模板、媒体库管控和求片系统。
为什么需要实例管理
在多实例部署场景中（如一台 Emby 做国产剧、另一台做欧美剧），每个实例需要独立的 Bot、运营策略和媒体库屏蔽规则。实例管理将这些配置从原来的 302 配置中拆分出来，以可折叠卡片的形式集中管理，避免来回切换页面。
页面结构
页面以可折叠卡片形式展示所有 Emby 实例。每张卡片头部显示实例名称、Bot 运行状态、运营模式，点击头部可展开/收起。
实例来源
实例列表来自 Emby 助手 中创建的 302 配置。如果页面提示「暂无实例」，请先在 Emby 助手中创建实例。
Bot 配置
每个实例拥有独立的 Telegram Bot，用于用户交互、通知推送和管理操作。
| 配置项 | 说明 |
|---|---|
| Bot Token | 从 @BotFather 获取的该实例专属 Token |
| 管理员 TG 账号 | 该实例的 Bot 管理员，接收通知并可使用管理员命令 |
| TG 群组 ID | 关联的 TG 群组，用于退群检测等功能，留空不启用 |
| 自定义欢迎消息 | 支持 {name} 占位符，留空使用默认欢迎语 |
| 封面图 | Bot 发送消息时的封面图片，支持 jpg/png/gif/webp |
配置步骤
创建 Bot
在 Telegram 中找到 @BotFather，发送
/newbot创建 Bot，获取 Token填写 Token
将 Token 粘贴到 Bot Token 输入框，点击右侧「测试」按钮确认连接正常
配置管理员
在「管理员 TG 账号」搜索框中搜索并添加管理员的 TG 用户名或昵称
关联群组（可选）
如需启用退群检测，在「TG 群组 ID」中搜索并选择关联的 TG 群组
保存并启动
点击卡片底部「保存」按钮，然后点击卡片头部的「启动 Bot」按钮
Bot 启停
每张卡片头部有「启动 Bot / 停止 Bot」按钮，可独立控制每个实例的 Bot 运行状态，无需重启整个服务。
生命周期任务
实例管理页顶部提供 生命周期任务 区域，用来处理到期用户和长期不活跃用户。
| 任务 | 说明 |
|---|---|
| 到期扫描 | 全局执行并按实例汇总通知。到期用户进入禁用状态，并在保留期结束后删除本地记录、远端 Emby 用户和自备 115 配置 |
| 活跃度检测 | 仅签到模式实例显示。按实例配置不活跃天数、Cron、开关，并支持立即执行 |
默认时间
新版默认到期扫描为每天 08:30，签到模式活跃度检测默认为每天 09:00。旧默认值会自动迁移，自定义 Cron 不受影响。
用户在生命周期保留期内可通过邀请码、续期、积分续期或管理员启用恢复账号，恢复后会自动清除预约删除计划。
运营模式与签到积分
每个实例可独立选择运营模式，签到模式下用户通过每日签到获得积分并兑换各类权益。
运营模式
| 模式 | 说明 |
|---|---|
| 标准模式 | 管理员手动管理用户到期、续期等操作 |
| 签到模式 | 用户可通过 /checkin 每日签到获取积分，用积分兑换白名单、续期、解封、邀请码等权益 |
重要
活跃度检测是签到模式专用能力。标准模式实例不会显示活跃度检测命令、按钮和 Bot 菜单入口。
签到积分配置（仅签到模式）
选择签到模式后，展开以下配置项：
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 启用签到 | 关 | 开启后用户可使用 /checkin 命令每日签到 |
| 签到最少积分 | 1 | 每次签到获取的最少积分 |
| 签到最多积分 | 10 | 每次签到获取的最多积分（实际值在最少~最多之间随机） |
| 白名单兑换积分 | 1000 | 用户使用 /exchange 兑换白名单身份所需积分 |
| 解封兑换积分 | 500 | 被封禁用户兑换解封所需积分 |
| 邀请码兑换积分 | 100 | 用户生成一个邀请码所需积分 |
| 兑换续期积分 | 300 | 用户主动兑换续期所需积分，填 0 关闭此功能 |
| 兑换续期天数 | 30 | 每次兑换续期增加的天数 |
积分自动续费
自动续费逻辑
开启后，到期扫描任务在检测到用户到期时，会优先检查用户积分余额。如果积分充足，自动扣除积分并续期，而不是直接禁用用户。续费成功后自动通知用户。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 启用自动续费 | 关 | 开关 |
| 自动续费积分 | 300 | 每次自动续费扣除的积分 |
| 自动续费天数 | 30 | 每次自动续费增加的天数 |
活跃度检测
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 启用活跃度检测 | 关 | 开启后管理员可使用 /low_activity 命令检测不活跃用户 |
| 不活跃天数 | 30 | 超过此天数未播放的用户视为不活跃 |
| 定时 Cron | 0 9 * * * | 自动检测执行时间 |
典型配置场景
小型私服推荐配置
- 运营模式：签到模式
- 签到积分：1 ~ 10
- 白名单兑换：1000 积分（约 100 天签到）
- 兑换续期：300 积分 / 30 天
- 自动续费：开启，300 积分 / 30 天
这样用户每天签到积累积分，到期时如果有足够积分会自动续费，不需要管理员手动操作。
权限模板
权限模板用于预设一组 Emby 用户策略，新建、导入、邀请码注册和批量覆盖都可以套用模板。
| 模板配置 | 说明 |
|---|---|
| 模板名称/描述 | 管理员自定义，便于区分用户档位 |
| 默认模板 | 新建用户、同步导入和 CSV 导入时默认使用 |
| 网盘模式 | 共享自动均衡、自备网盘、原生播放等 |
| 允许模式 | 用户是否允许在共享/自备之间切换 |
| 设备上限 | 用户设备数限制 |
| Emby Policy | 远程访问、播放、转码、下载、设备、字幕、家长控制等 Emby 原生策略 |
| 媒体库权限 | 默认媒体库访问策略 |
升级兼容
旧版「模板用户 ID」机制已被权限模板取代。升级后系统会为每个实例创建默认权限模板，已有用户自动关联。
管理员可在 Emby 用户 页面批量套用权限模板，并选择只覆盖 Emby 权限、模式与设备数、媒体库权限中的部分范围。
同步导入默认值
控制从 Emby 导入用户或定时同步新增用户时，默认设置的到期时间和白名单状态。
| 配置项 | 说明 |
|---|---|
| 默认时长 | 永久 / 天卡(1天) / 周卡(7天) / 月卡(30天) / 年卡(365天) |
| 白名单 | 仅在默认时长为「永久」时可勾选；勾选后新导入用户直接为白名单身份 |
有到期时间时不可设白名单，因为白名单用户不受到期扫描影响，二者互斥。
媒体库管控
新版媒体库管控从「管理员统一屏蔽」升级为 默认隐藏 + 用户自选 + 强制隐藏。
| 配置项 | 说明 |
|---|---|
| 启用媒体库管控 | 总开关 |
| 默认隐藏的媒体库 | 普通用户可在「我的媒体库」或 TG Bot 中自行开启/关闭 |
| 强制隐藏的媒体库 | 普通用户始终不可见，用户自己也无法开启 |
| 从 Emby 拉取媒体库 | 自动读取实例媒体库列表，避免手输名称 |
| 手动输入媒体库名称 | 适合无法拉取或临时补充的场景 |
Emby 管理员账号始终拥有全部媒体库权限，不受默认隐藏池和强制隐藏池限制。
配置步骤
开启管控
打开「启用媒体库管控」开关
选择默认隐藏库
点击「从 Emby 拉取媒体库」，勾选希望用户默认看不到、但可自行开启的媒体库
选择强制隐藏库
勾选任何普通用户都不能访问的媒体库
保存配置
系统会清理孤儿数据，释放移出管控池的库，再重放新策略
配置变更后自动全量同步
保存配置时系统会自动同步所有用户的媒体库权限，如果用户数量较多可能需要几分钟。
用户可在 用户面板 → 我的媒体库 或 Emby Bot 的媒体库菜单中自助调整默认隐藏库的可见性。管理员也可在 Emby 用户 页面代用户调整。
求片系统
允许用户通过 Bot 或用户面板搜索 TMDB 并提交求片请求，管理员可在后台处理。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 启用求片 | 关 | 总开关 |
| 电影求片限制 | 每 7 天最多 3 次 | 限制周期内每用户最多提交的电影求片次数，填 0 不限制 |
| 剧集求片限制 | 每 7 天最多 3 次 | 限制周期内每用户最多提交的剧集求片次数，填 0 不限制 |
自动找片
开启后，系统会定时处理新片、缺集、异常和 MoviePilot 订阅请求。推荐先使用源码默认的每 10 分钟执行一次，只开启 HDHive 来源，并固定一个内置 115 账号及 /求片 目录。这样出错时更容易知道资源去了哪里。
MoviePilot 订阅
开启后会生成这个实例专用的订阅地址，供支持 MoviePilot v2 协议的播放器使用。可以选择“成功后通知实例群组”。重新生成 Token 会让旧地址立刻失效，只有泄露或需要撤销访问时才操作。