备份与恢复

最重要的是备份安装目录中的 data。它保存账户登录状态、密钥、设置和本地运行文件。媒体文件是否备份，请按自己的硬盘或网盘方案安排。

日常可从页面下载完整安装包；升级前可停机复制整个 data 目录。两种方式都需要另存媒体文件与部署说明。先看下面的备份范围，再选择恢复方式。

定期备份

1. 暂停正在自动运行的任务。

2. 按原安装方式停止 Mediora：Compose 执行 docker compose stop mediora，命令方式执行 docker stop -t 180 mediora，绿联手动容器在 Docker 界面关闭。先等待在途写入结束，不强制停止。

3. 复制整个 data 目录到其他硬盘、NAS 或可信的备份位置。

4. 记录当前实际使用的版本镜像或摘要，与这份完整数据目录配对保存。

5. 保存部署配置：Compose 文件、完整创建命令，或绿联容器的镜像、目录、端口与环境参数。配置中的凭据要妥善保管。

6. 启动原容器：Compose 使用 docker compose start mediora，命令方式使用 docker start mediora，绿联手动容器在界面启动。备份不需要新建容器。

不要只复制正在使用的数据库主文件。完整目录还包括安装身份、会话密钥、存储配置密钥和恢复材料，缺少配套密钥时无法解开已有存储配置。定期在独立目录和对应版本镜像中实际验证恢复。

各种备份分别包含什么

备份	包含	仍需另外保留
停机复制整个 data	该安装的数据、身份、密钥、归档及其中的运行材料。	镜像标签或摘要、Compose / 创建命令 / 绿联容器参数、媒体及外部写入结果。
完整安装包 .mediora.tar.gz	数据库快照、配套身份和密钥、应用配置、历史归档及可读取的部署文件。	Docker 镜像、媒体、包中未包含的宿主机部署参数和外部写入结果。
旧 .db / .db.gz 或仅导出数据库快照	数据库快照中的设置、任务和记录。	配套安装身份和密钥、独立归档文件及数据库外的材料。
影音优化结果备份	某个视频准备好的播放信息。	影片本身、Mediora 和媒体服务器完整数据。
同步复制的媒体	同步范围内实际复制到目标的文件。	Mediora 配置和历史；开启同步删除后也不等同于可找回旧版本的备份。

备份应放在独立位置。把原数据旁边的文件夹当作唯一备份，无法抵御同一磁盘或账号故障。涉及数据库和密钥的副本与含凭据的部署配置都应妥善保管。

恢复备份

恢复前先停止 Mediora，把成对的完整 data 备份放到独立目录，使用对应版本镜像演练。核对登录、存储和任务后，再在维护窗口切换。结构、密钥和安装身份不匹配时会被拒绝；不会为未知旧结构自动补表。跨不兼容的已发布版本仍按 changelog 使用新的空数据目录。

恢复会覆盖当前的设置和任务记录。先把当前 data 目录另存一份，避免需要回退时没有副本。

恢复演练不要与正式实例同时操作相同网盘、下载目录或媒体库。先隔离外部写入和自动触发，核对文件实际状态，再逐项恢复计划。数据库回退不能撤销备份点之后已经发生的外部操作。

正式版数据升级

1.1.1 支持对 1.0.0 / 1.0.1 / 1.0.2 / 1.0.3 / 1.0.4 / 1.1.0 已发布完整结构的启动升级。它根据实际数据库结构识别，不能仅改版本标记或给旧开发库补列来满足要求；旧预发布版和未经验证的开发库不在兼容范围内。

1. 停止旧实例，备份完整 data，记录旧镜像并确认有足够空间容纳数据库备份、副本和归档转换。
2. 先在独立副本和隔离环境验证。需要实际切换时，在维护窗口使用 1.1.1 镜像启动，保留原目录与冷备份。
3. 查看启动日志。系统先在 data/database-upgrades/upgrade-*/original.db 保存一致的旧数据库快照，在副本升级并完整校验后才替换主库。已有归档会随命名资料一起转换；从 1.0.0 / 1.0.1 升级会保留原月份归档，并将转换后的归档放入独立代次。
4. 启动成功后，核对账户、存储、命名规则、任务、历史及归档。升级至 1.1.1 会取消旧版未完成的媒体整理执行，停止受影响的整理自动计划，以及引用整理任务的活动工作流；历史和未决写入证据保留。从 1.0.0 / 1.0.1 升级还会取消其他未结束的媒体运行和工作流。先核对实际文件，再重新运行或启用计划；不能依据旧任务仍在列表中就判断它会自动继续。
5. 升级失败时保留完整目录、备份和错误提示。不要删除数据库、密钥或安装身份来“修复启动”；回退仍恢复旧镜像和完整旧数据目录。

升级过程中的 original.db 是数据库快照，不是完整安装备份，不能单独作为回退材料。升级适用范围见更新日志，实际切换前仍需用自己的完整数据副本验证。

升级后，媒体整理、媒体刮削和生成 STRM 统一采用“就绪即处理”，已有任务后续运行及历史重试也会采用新策略。处理条件和扫描失败的影响见任务运行与结果核对。

从页面导出数据

在“系统 → 数据维护 → 备份恢复”点击“导出完整备份”，下载 .mediora.tar.gz 安装包。手动维护、日／周／月定时备份及导入前安全备份也采用此格式。包内保存数据库、配套身份和密钥、应用配置与历史归档；媒体、Docker 镜像、日志、缓存、临时文件和旧备份另行保留。

要一并保存 Compose、环境文件等部署材料，将 Mediora 自己的部署目录只读挂载到 /run/mediora-deployment；例如在当前服务的 volumes 中追加 - /实际/Mediora部署目录:/run/mediora-deployment:ro，再重新创建容器。使用其他容器内路径时设置 MEDIORA_DEPLOYMENT_DIR。部署文件及其引用材料应放在该目录内，不能依赖目录外的链接或外置配置。页面会列出实际包含的部署文件；未挂载时仍保存应用数据和容器内生效参数，恢复时需要重新建立宿主机端口、媒体卷等配置。

备份含访问凭据，应妥善保管。需要旧格式时，可在“完整安装恢复说明”中点击“仅导出数据库快照”。普通 .db 和压缩 .db.gz 仍可通过“导入备份”恢复当前安装的数据库；它们不代替配套密钥和其他安装材料，不能把别的安装数据库导入当前身份。

数据库恢复会撤销旧的页面和 Agent 授权，恢复后需要重新登录。数据库回滚不会撤回已经发生的媒体改名、覆盖、删除或外部同步，恢复演练时应另外核对外部文件。

页面导入只接受当前结构的备份，不负责把任意旧备份升级。已支持的旧正式版备份，应先在对应旧镜像与配套安装材料中恢复，再按启动升级流程验证；不要直接导入新实例。存在活动作业或待核实写入时，按页面保护提示先处理原操作，不删除保护记录绕过导入限制。

从完整安装包恢复

完整安装包使用镜像内的恢复工具，恢复到新的空安装目录，不通过正在运行的数据库导入入口覆盖原安装。先停止旧容器并保留原目录、源备份和原镜像，准备独立备份目录及新的空恢复目录。

下面以 1.1.1 生成的备份为例。使用生成备份时的同版本镜像，将宿主机目录、UID/GID 和文件名替换为实际值。先准备新的空恢复目录，并确认所选用户有写入权限；目录中已有部署文件、data 或其他内容时，工具会拒绝恢复：

docker run --rm \
  -e PUID=1000 -e PGID=1000 \
  -v /srv/mediora-backups:/backup:ro \
  -v /srv/mediora-restored:/restore \
  anoiv/mediora:1.1.1 \
  node dist/scripts/restoreInstallationBackup.js \
  /backup/备份.mediora.tar.gz /restore

恢复工具校验文件摘要、数据库与密钥配套关系，写入部署文件和 data，并生成 restore-info/RESTORE.txt、环境参数及 Compose 覆盖文件。先阅读该说明，核对镜像、端口、目录权限和媒体挂载；有原 Compose 时，按说明组合原文件与 restore-info/compose.override.json 启动。NAS 图形界面创建的容器按保存的部署参数重建。

本例恢复后，应用数据位于 /srv/mediora-restored/data，而不是恢复目录的顶层。重建 Mediora 时，应将这个 data 子目录映射到 /app/data，不要把 /srv/mediora-restored 整体误挂成应用数据目录。

工具不恢复媒体和 Docker 镜像，也不会覆盖已有安装目录。只启动一份 Mediora，恢复后重新登录并重新授权智能体；需要升级时，先核对同版本恢复正常，再沿用完整目录升级。

重要提醒

• 不要让两份 Mediora 同时使用同一个 data 目录。
• 不要在恢复过程中同时运行会移动、删除或同步文件的任务。
• 更换电脑或硬盘前，先完成一次完整备份。

容易搞错的地方

容易搞错	实际情况
只备份 docker-compose.yml	设置、任务、历史都在 data 目录里；只备份编排文件等于没备份。
以为备份里包含影片	完整安装包不包含媒体正文；媒体目录中的影音优化随片备份也要随媒体另行保存。停机复制 data 时，保留的是该目录内的实际材料。
把备份放回同一块硬盘	硬盘损坏时备份一起没。应至少另外保留一份跨设备或跨磁盘副本。
恢复前先启动新容器	恢复工具不会覆盖已有安装目录；已有安装目录会让恢复失败或产生第二份数据。
两份 Mediora 共用同一个 data	会造成数据互相覆盖，任何情况下都不要这么做。
恢复后容器启动报 EACCES 就改成 root 跑	这是目录权限问题，改回 root 会掩盖问题并让后续任务以错误身份写文件。
边恢复边跑任务	恢复过程中不要运行会移动、删除或同步文件的任务。
以为恢复后不用重新登录	需要重新登录，智能体授权也要重新授权。
只看“每日保留份数”判断哪些备份能删	启动升级产生的备份有单独策略，不能按普通自动备份推断。

最佳实践

备份三件事： data 目录 + docker-compose.yml + 一份记录着端口、挂载路径和 PUID/PGID 的说明。

备份策略：

项目	建议
频率	每周一次，另在升级或改关键配置前手动备份一次
保留	至少 2 份，且有一份放在另一台设备或网盘
验证	重要配置变更后做恢复演练；能解压、大小正常只能作为初步检查

验证备份是否可用的低成本方法： 在独立空目录里用同版本恢复工具演练，阅读 RESTORE.txt，核对数据目录、端口和媒体挂载，再检查能否登录、读取配置与历史。启动演练实例前先隔离正式存储、下载器和自动触发，避免恢复出的计划再次修改真实媒体。能生成说明文件或启动容器，不等于已完成全部恢复验证。

恢复顺序： 停旧容器并保留原目录 → 准备同版本镜像和新空目录 → 运行恢复工具 → 阅读 RESTORE.txt → 核对 data 子目录、挂载和端口 → 隔离自动触发后启动 → 登录并检查配置、历史和实际文件。