备份与恢复

入口位于“配置中心 → 备份与恢复”，仅主管理员可操作。“创建备份”和“恢复备份”分开展示；每次恢复的上传、预检和恢复前快照合并到一条历史记录，内部步骤可展开。关闭页面不会终止后台任务。

怎么配置

备份、恢复和回退要求业务表及恢复控制表全部使用 InnoDB；存在非事务表或无法确认表引擎时会拒绝操作。

恢复只支持单应用实例。确认同一数据库没有第二个应用实例或外部写入程序后，设置：

backup:
  single_instance_confirmed: true
  directory: data/backup-control
  max_compressed_bytes: 1073741824
  max_uncompressed_bytes: 8589934592
  max_line_bytes: 16777216

备份目录应位于持久磁盘，由服务运行用户独占读写，不能暴露为静态资源目录。默认上限分别为压缩包 1 GiB、解压数据 8 GiB、单条记录 16 MiB；大库恢复还需要数据库事务空间和恢复前快照空间。

成功备份和上传文件默认保留 7 天，失败的暂存数据和临时文件在 24 小时后清理。活跃恢复、等待确认和需要故障处理的回退包不会自动删除。请另外保存下载的备份；本机保留期不能替代异地备份。

怎么备份

类型	保存内容	不保存内容
用户数据备份	用户身份、已有密码认证材料、VIP、白名单、积分和签到防重日期	管理员、配置、订单、流水、用户历史和渠道绑定
完整数据备份（不含日志和文件）	持久业务数据库数据，包括管理员、应用设置、订单、卡密、积分流水和工单元数据	运行日志、通知及后台任务等临时执行状态

两种备份都不包含首页模板文件、图片、工单附件、Emby 媒体库或 Emby Server 配置。完整包包含本应用数据库中的连接和通知设置；目标部署的数据库连接、JWT 配置和文件目录仍保留。备份含认证材料，应按敏感文件保管。

“包含认证材料”不代表每个用户都有可恢复的 Emby 密码。本系统未保存过的密码不能从 Emby 或密码哈希中反推出；这类账号在空 Emby 上恢复时，会在管理员确认执行后生成随机新密码。

1. 选择类型，点击“创建备份任务”。在线导出期间业务可以继续。
2. 等待“已完成”，点击任务查看详情并下载 ZIP。任务列表显示备份类型，再次点击同一任务可收起；文件名包含类型及备份生成时间（UTC）。
3. 将文件复制到受控的备份存储。
4. 定期在相同版本、数据库结构及业务时区的测试环境执行预检和恢复演练。

自动备份

在“创建备份”页启用“自动备份”，选择间隔天数（1–365）、北京时间（精确到分钟）和保留份数（1–100），点击“保存自动备份设置”。默认关闭，预填每 1 天 02:00、保留 7 份。保存后以下方“下次执行时间”为准；首次在下一个指定时间执行，之后按设定天数间隔执行。仅修改保留份数不会重新计算执行周期。

自动备份固定保存完整管理数据到当前服务器，不自动上传到外部存储。成功的自动备份按份数保留，不受手动备份的 7 天过期规则影响。新备份成功后才清理超出数量的旧自动备份；失败不会替换已有成功备份。恢复正在使用的备份暂时保留，可能短暂超过保留份数。

计划在重启后保留，停机错过多次只补执行一次，恢复维护期间暂缓。修改周期或时间、重新启用时，会从下一个指定时间重新安排。关闭自动备份停止后续调度，已创建的任务继续执行；历史文件不会因关闭开关立即删除。

检查是否正常：查看已保存的下次执行时间，到点后在“备份记录”中检查“自动备份”任务及结果。未执行时确认服务正在运行、计划已保存且启用，以及是否仍有备份或恢复任务等待处理；备份失败时查看任务结果并检查服务器剩余磁盘空间。自动计划独立保存，恢复旧数据库备份不会覆盖当前计划。

怎么恢复

1. 打开“恢复备份”，选择 ZIP；需要重建 Emby 账号时勾选“数据库恢复后，继续恢复 Emby 用户”。
2. 点击“上传并检查备份”。系统自动识别类型、时间和版本；用户包默认仅补充缺失用户，可在预检结果中切换方式并重新检查。上传和预检不会修改业务数据。
3. 在当前页核对新增、覆盖、删除、跳过数量和恢复说明，点击“确认范围并恢复数据库”。系统自动保存恢复前快照，页面持续显示进度。
4. 若影响范围发生变化，核对最新摘要后继续或取消。默认确认期限为 5 分钟，重启不会延长。
5. 登录失效时，使用恢复后的管理员账号重新登录，会返回原恢复步骤；完整恢复须使用备份中的主管理员账号。
6. 若选择继续恢复 Emby，数据库成功后会在同页自动预检。核对账号并点击“确认恢复选中的用户”才会创建账号；没有缺失或冲突账号时自动完成。有冲突时留在结果页人工核对。未勾选的也可在数据库完成页继续恢复 Emby。
7. 查看结果；为随机密码账号下载一次性 CSV，保存后自行交付用户。可重试选中的失败用户。保存地址栏链接，重新打开仍可继续查看。

普通恢复策略	本地独有用户	双方已有用户	备份独有用户
仅补充缺失用户	保留	整个用户跳过	新增
合并并覆盖已有用户	保留	认证、VIP、白名单及积分采用备份	新增
完全替换用户数据	删除	采用备份	新增

积分采用备份值，不会累加。合并保留本地较新的签到防重日期；没有签到历史但存在当天防重日期时，也不能再次领取。

完全替换用户数据会清理用户订单、兑换、续期、积分历史、工单及绑定等记录，普通包不能恢复这些历史。已发放库存和已使用卡密不会重新变成可用。完整包固定以备份覆盖持久业务数据，旧通知和后台任务不会重放。完整包中找不到对应用户的会员等记录会按原样保留并提示数量；商品已删除的已发放库存保留交付记录，不会重建商品或变回可用库存。

恢复期间暂停业务请求及相关后台写入。数据库恢复不会修改 Emby 用户；恢复后原有同步仍可能重新导入 Emby 独有用户，请自行核对远端账号。缺少模板文件时回到默认首页，缺失图片或附件需要另外补回文件，数据库备份不能找回它们。

单独恢复 Emby 用户

数据库恢复结果页可以直接继续；单独操作也可进入“配置中心 → Emby → 从本地恢复用户到 Emby”。

1. 默认勾选“优先使用已保存密码”，点击“重新预检 Emby 用户”。
2. 核对可恢复、已存在、冲突和将生成随机密码的用户。新账号使用当前默认权限模板；普通包不包含原个人媒体库权限。
3. 选择可恢复用户，再点击确认。已有同名账号不会被接管或修改密码。
4. 预检会区分“原密码恢复”和“将生成随机密码”。仅在执行 Emby 用户恢复时，为没有可用密码快照的账号生成安全随机密码；有快照的账号沿用原密码。随机密码会加密保存在任务中，失败重试沿用同一密码，成功后保存到本地密码快照并同步门户密码、使旧门户登录失效。管理员可在恢复结果中一次性下载随机密码 CSV，再自行通知用户。创建失败时不修改本地密码。日常单人、批量密码重置仍保持原行为。
5. 对结果中可重试的失败用户，使用原预检和原任务记录重试。只有记录了本任务创建的确切远端 ID，才会继续处理该账号；创建响应丢失或远端账号变化时必须人工核对。

异步任务页可查看预检及恢复结果，并通过“查看预检 / 重试”返回。保存任务链接后，刷新页面仍可继续查看。旧恢复模式保持原行为，未选择上述选项时请按原密码交付流程操作。

恢复进程中断后，保留原任务及数据库。服务重新启动并回收超时任务后，会跳过已完成重绑的账号，继续未完成账号；不要删除原任务记录后重新创建同名用户。

Emby 整个实例重建了

1. 部署相同应用版本并初始化新数据库，设置单实例恢复。保留独立下载的完整备份。
2. 上传完整备份并恢复数据库，再用备份中的主管理员账号登录。
3. 在 Emby 设置中重新填写新实例地址和 API Key，并测试连接。完整数据库恢复会带回旧连接配置，所以应在数据库恢复之后确认新配置。
4. 先在新 Emby 配置媒体库，再核对本应用的默认权限模板。新实例的媒体库 ID 可能变化，旧的指定媒体库权限需要重新选择；用户重建成功不代表媒体文件和媒体库已恢复。
5. 执行 Emby 用户预检。有可用快照的沿用原密码；没有可用快照的在确认恢复时生成随机新密码。同名冲突应人工核对，不能直接接管。
6. 核对用户数、会员期限、白名单、积分及默认权限，分别抽查有效会员登录、过期会员禁用和实际播放。再次预检应显示已存在，不能再创建一批重复账号。

已验证同一应用结构下 MySQL 5.7 到 MySQL 8 的真实备份导入。校验兼容整数显示宽度和已知旧表改名遗留的重复普通索引；字段类型、唯一约束等实质差异仍会拒绝恢复，这不代表任意数据库版本或任意结构都兼容。

失败了怎么办

先保留数据库和 data/backup-control 目录，不要清空恢复控制表、删除回退包或反复提交恢复。

提示	处理方式
BACKUP_TRANSACTIONAL_TABLE_REQUIRED	请数据库管理员检查当前库的表引擎和元数据读取权限，确认全部业务表及恢复控制表使用 InnoDB 后再重试
来源不同或无法确认	核对当前 Emby 来源。补充和合并要求来源一致；完全替换需自行处理远端账号
用户身份冲突	核对同名不同 ID、同 ID 不同名及重复记录，修正来源后重新备份或预检
版本、结构或时区不一致	使用相同应用版本和数据库结构，统一业务时区后重试
文件损坏、超限或过期	重新上传有效包，或按实际容量调整部署限制
等待再次确认	核对最新范围后确认；也可取消。超时会取消并解除维护，不开始数据导入
需要恢复处理	保持维护，先检查数据库连接与磁盘，再点击“完成恢复”；提交已确认且配置可加载时才会开放业务
需要回退	在原恢复任务中使用“回滚到恢复前”；仅在原恢复已提交且业务一直处于维护时允许

提交结果不明确时，系统不会自动重复导入。连接恢复后，可停止并用同一配置重新启动服务，让系统重新核对提交凭据。仍无法确认时继续保留维护和原文件，不能手工宣称恢复成功。

回退失败且未提交时，原恢复数据仍在，维护状态保留；回到原恢复任务继续处理。恢复已经成功并开放业务后，不提供直接回退，以免覆盖其后的业务变化。

网页无法登录时的本机回退

停止所有应用实例，使用相同配置、相同持久目录和相同操作系统用户执行服务端程序：

CONFIG=/实际路径/config.yaml server restore-rollback --task-id <原恢复任务ID>

任务 ID 可从任务详情或保存的任务链接取得。命令不依赖管理网页，不接受外部 SQL 或任意备份路径；常驻服务仍持有目录锁时会拒绝执行。输出 restore rollback: rolled_back 后，按原方式启动服务并验证原管理员登录和业务数据。

本机命令也必须确认原恢复的提交结果。若提示结果仍无法确认，保留数据库、目录及维护状态，先排查数据库连接或文件缺失，不要绕过检查。

备份结果通知

在 配置中心 → 通知 → 通知开关 中，分别设置“备份成功通知”和“备份失败通知”。默认开启失败提醒，成功提醒可按需开启，适用于手动和自动备份。

接收渠道沿用 Telegram、企业微信设置。管理员在 个人设置 → 我的通知接收 中选择对应事件；企业微信群聊在目标配置中勾选“备份成功”或“备份失败”。

可以开启成功通知后手动执行一次备份，检查是否收到消息。收不到时，在通知页面检查 投递记录，并确认渠道、接收目标和事件开关均已启用。