You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/docs/PORTABLE_VM_BACKUPS.md

78 lines
14 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 可移植虚拟机备份、云快照与新实例恢复
管理员可在虚拟机管理页为面板创建的云镜像实例生成一个完整系统盘备份,并把该备份直接上传到后台已验证的 S3 兼容对象存储。恢复不会修改或替换源实例,而是在选定的合格宿主机上创建一个独立实例;目标可以是原宿主机,也可以是其他宿主机。
虚拟机管理页顶部的“备份库”以备份目录自身为管理边界。即使源实例已按到期规则删除,超级管理员仍可从备份库恢复或删除对象;只读管理员只能查看。目录固定分页,浏览器响应不包含对象键、预签名 URL 或长期凭据。
## 备份边界
- 当前只支持一个面板托管、可写、无 backing chain 的 `vda` qcow2 系统盘;额外数据盘、LUN、外部快照链或正在 pivot/mirror 的磁盘会被拒绝。
- 管理员普通云备份默认使用“自动(优先文件系统一致)”。运行中实例通过 libvirt full push backup 生成完整对象:QEMU Guest Agent 可用时执行文件系统冻结,确认 QGA 不可用时自动降级为崩溃一致性;管理员也可显式选择“强制崩溃一致”跳过 QGA。关机实例从稳定的系统卷生成完整副本,但仍按崩溃一致性报告,因为 Agent 无法证明上一次关机经过来宾系统协调。
- S3 长期凭据只在 PHP 控制面解密。Agent 只得到单对象、单方法、最长七天有效的预签名传输能力,不接收 Access Key 或 Secret Key。
- 对象内容是原 qcow2 数据。传输强制 HTTPS,但当前版本不额外执行客户端加密;生产 Bucket 应启用服务端加密、版本控制、最小权限和不完整 multipart 生命周期清理。
- 系统盘内容保持不变,因此来宾系统数据、账户、SSH host key 和应用配置也保持不变。它是从备份创建新实例,不是重装一个空白操作系统。
## 用户自动备份与计费
用户在部署时购买自动备份时,首个服务周期与实例账单一并结算。运行中的实例也可以在实例设置中开启:当前服务周期按剩余秒数向上取整计费,已经提前购买但尚未包含备份的后续服务周期按每期完整价格结算。余额扣款、已支付审计账单、订阅和每个服务周期的不可变权益记录在同一事务内完成;同一个幂等请求不会重复扣款。
调度只在订阅已开启且计划执行时间落入已支付权益时运行,并在创建备份的事务内再次核对。用户可以选择每天或每周在 UTC 00:00 执行,保留上限为两份。关闭会立即停止新自动备份并从下一张续费账单移除备份费用,不退还当前周期费用,也不删除当前已付权益或已有备份;同一已付周期重新开启不重复收费。续费成功后会为新服务周期写入独立权益,历史部署快照不作为当前计费授权。
用户只能在源实例的设置页把自动备份恢复到原实例;全局“云备份”页面不再直接创建实例,只能把仍处恢复期限内的可用备份保存为云快照。实例一到期便停止调度新自动备份,并隐藏和拒绝“恢复原实例”;三天宽限只负责保留已有对象和允许转为云快照。续费产生新的有效服务期后,自动调度与恢复原实例资格才重新开启。自动备份当前仍是完整系统盘对象,不是增量链。
## 用户云快照
云快照是从一份自动备份转换出的长期部署来源。转换只在数据库中转移不可变对象的业务归属,不复制或重新上传 qcow2;转换成功后,该 backing backup 不再出现在自动备份列表,也不会被保留份数轮换或权益到期清理。每个用户最多保留两份云快照,只有用户手动删除后才会释放其对象存储数据。
用户不能把普通云备份编号直接提交到开通接口。从云快照创建实例必须使用本人名下的公开快照键;生成账单和余额付款时都会重新锁定快照与 backing backup,并核对对象键、大小、虚拟容量、SHA-256 和冻结存储身份。未支付或正在交付的订单,以及效果未知或最终化异常的任务,会阻止删除云快照;安全终态订单不会永久占用删除围栏。
云快照可以重复用于创建新的付费实例。新实例使用用户当次选择的销售方案,系统盘容量不得小于快照虚拟容量,并获得新的 UUID、MAC、公网 IP、订单、服务期和流量周期;它不继承源实例的订单、到期时间、续费价格或流量用量。
云快照开通时以备份系统盘中的实际密码为准,不重新注入备份时面板保存的历史密码。由于面板无法确认用户是否已在来宾系统内手工改密,新实例不显示可能失效的历史密码。已转为云快照的 backing backup 也不计入滚动自动备份的保留数,不会阻止后续自动备份。
## 恢复为新实例
恢复目标必须满足以下条件:
- 已启用且 Agent、存储配置均就绪,目标资源池线路拥有当前 Agent 代次已验证的活动网络接入;目标可以是原宿主机或其他宿主机;
- CPU、内存、磁盘和带宽容量足够,并且同一 active、verified 网络接入下分别有一个未分配的公网 IPv4 与 IPv6;
- 目标宿主机没有同名实例。
控制面先在同一数据库事务内锁定目标宿主机与资源池线路,冻结该线路当前 Agent 已验证的网络接入,并原子预留目标容量及同一接入下全新的 IPv4+IPv6,再派发恢复。两族地址、地址池、网络接入和 claim-set 摘要作为同一不可变目标身份保存。Agent 校验下载对象的精确字节数和 SHA-256,创建新的 UUID、MAC、seed、NVRAM、网络过滤器和流量状态,把两族地址及默认路由写入 cloud-init 网络配置,并建立新的 IPv4/IPv6 防伪身份。它不会复用源地址,也不会复制原 Domain XML。
管理员从普通备份执行“独立恢复”时,恢复实例保留备份时冻结的 CPU、内存、系统盘、带宽及系统兼容元数据,归属原用户,但不继承订单、账单、套餐、服务期、到期时间或流量周期;后台将其标记为免计费实例。用户从云快照创建实例则走正常付费开通流程,使用当次选择的套餐规格和独立服务周期。
## 维护迁移
维护迁移是独立恢复之外的管理员流程,只允许选择同一资源池内的其他宿主机。它使用独立的 `PeerMigration V3` 冷迁移协议,不经过面板、Gateway 或对象存储传输磁盘,也不改变普通云备份的单系统盘格式。控制面先冻结当前全部已就绪快照目录,并按系统盘加全部快照容量锁定目标资源和同一接入下全新的公网 IPv4+IPv6;任何未就绪、目录漂移、单族地址不足或不完整回执都会阻止切换。
源 Agent 先把原运行状态和 autostart 写入本地持久恢复意图,再正常关闭实例并禁用 autostart。实例完全停机后,Agent 对稳定系统盘和全部快照卷计算大小、虚拟容量和 SHA-256,发布一个不含宿主机路径的短期只读清单。每台 Agent 首次启动时在私有状态目录自动生成并持久化独立 TLS 1.3 身份;面板通过已认证控制通道把源身份的精确 SHA-256 锁定值交给目标。目标只能用该锁定身份和控制面生成的 32 字节随机票据读取本次迁移,票据不进入 URL,清单和每个工件都不能泄露本机路径。
目标 Agent 主动从源 Agent 的 HTTPS 地址目录拉取数据,优先选择目标本机同网段的地址,再回退公网地址;因此当前可使用公网,后续增加物理内网地址时无需改面板配置。传输使用固定 8 MiB HTTP Range 分块、`.partial` 断点续传和完整 SHA-256 校验。暂存目录由 Agent 自动派生为第一个 `storage_path_roots` 下的 `.peer-migration-staging`,不会落入 Agent Journal 所在目录。导入完成并重建全部快照元数据后,目标只定义关机且禁用 autostart 的 Domain。控制面确认新 UUID、新公网 IPv4+IPv6、系统盘摘要、每个快照回执和资源预留后,才在一个数据库事务内切换原 `cloud_instances` 记录及快照宿主机归属。迁移不会创建第二份账单实例,也不会改动原订单、套餐、服务期、到期时间、续费参数或当前流量周期。
目标使用已冻结的目标资源池线路、该线路当前 Agent 已验证的网络接入和新公网 IPv4+IPv6,并同时建立两族防伪身份。原累计流量作为新 Agent 计数器世代的基数继续单调累计,不能因宿主机和 UUID 改变而清零或重复计费。迁移不重新注入主机名、密码或 SSH 公钥,来宾磁盘中的当前值保持不变;面板保存的 `guest_hostname` 只随实例规格元数据迁移。目标保持源实例的服务状态、网络状态和电源状态;源网络已因流量或到期被限制时,目标持久网卡从定义开始就是 `link down`。
目标在整个恢复和防火墙阶段保持关机。若实例启用了用户防火墙,控制面必须先在关机目标上重新应用并确认同一策略;没有策略或策略已禁用时也必须完成恢复终结。只有这些步骤完成后,独立的目标激活任务才恢复原 autostart 和运行/关机状态,随后才允许进入源副本清理。因此目标不会在用户防火墙生效前短暂联网启动。
管理员可在开始时选择两种源副本策略:
- “目标验证后自动清理”会在目标恢复及防火墙收敛后删除源 Domain 和面板托管磁盘,只有 Agent 同时确认 Domain 与全部托管产物均不存在时,才释放原公网 IPv4、IPv6 和源容量。
- “保留源副本”会保持源 Domain 关机且禁用 autostart,并通过独立 source-debt 账本继续锁定原公网 IPv4、IPv6 和源容量;管理员稍后可从同一页面显式发起清理。
- 在源副本清理或异常核对完成前,面板会阻止普通实例变更和套餐升级;到期策略仍可断网,但不会只删除目标实例而遗留源副本。
任何派发后的超时、断连或回执丢失都进入原 operation 的只读核对,系统不会重放源停机、目标创建或源删除,也不会提前释放资源。传输明确失败且目标创建被证明没有发生时,管理员可以“重试传输”并从已有分块继续,或“中止传输”恢复源机原电源/autostart 状态并释放目标预留。防火墙、目标激活和源回滚的确定失败分别提供同阶段重试;源清理失败回到 `source_retained`,允许再次显式清理。只有不确定效果仍由任务安全核对栅栏阻止重放,因此业务状态不会依靠一个无出口的永久软件锁。
迁移控制面以一份可执行阶段注册表定义源准备、传输、账本切换、防火墙、激活、源清理和回滚。任务字段、完成处理、不确定结果的核对动作、人工恢复动作和管理员页面进度都从该注册表生成;恢复接口在数据库锁内重新使用同一判定,不能只信任页面按钮。资源预留、订单归属和公网 IP 的最终结算由独立模块执行,只有阶段结果得到明确证明后才能调用。后台显示持久化的阶段步骤及完成、跳过、待处理状态;当前 PeerMigration V3 没有持久化字节遥测,因此传输阶段不显示伪造的百分比。
PeerMigration 不创建 `vm-migrations/` 对象,也不持有 S3 凭据。目标成功导入后立即删除本地分块暂存;中断或主机崩溃留下的暂存目录按票据最长寿命进行有界过期回收。普通云备份继续使用 `vm-backups/` 且不携带快照,二者的目录、保留和删除规则互不复用。
## 失败与不确定效果
备份和恢复均为异步 HeavyIO 操作,单次宿主机 worker 最长可运行 24 小时。控制面只会派发一次同一 operation ID:超时、断连或回执丢失均视为效果未知,并通过 Agent Journal 查询原操作,不会重新执行备份或创建第二台 VM。
普通云备份使用独立 `vbackup-*` 工作区卷,不把临时副本加入用户快照目录。因此即使远端对象已经完整提交后本地删除暂时失败,维护迁移仍只读取正式快照,不会被该残留阻断。Agent 会保留对象大小、SHA-256 和一致性结果,把备份标记为可恢复并单独提示本地工作区待清理;该提示不会触发重新上传或删除远端对象。超级管理员的“核对并清理临时工作区”会先读取原成功 operation 的最新计划,再以新的 operation ID 执行精确清理;计划摘要、卷身份、引用关系或活动作业任一变化都会拒绝执行。实例已经迁移或源 Domain 已删除时,清理仍绑定备份冻结的源宿主机和 UUID,只能在确认卷未被任何 Domain 引用后删除;若卷已经随源实例清理消失,则只确认缺席并解除提示。旧版本留下的 `vsnap-*` 临时卷和对应 metadata 也只能通过同一证据绑定入口清理。
恢复失败时,只有 Agent 明确证明新 Domain、所有 UUID 所属卷、seed、NVRAM、网络过滤器和流量状态均不存在,控制面才能释放容量与公网 IP。只要清理结果不确定,资源保持锁定等待人工核对。
备份对象删除也遵守同一原则:首次删除前保存对象的大小、ETag 和可用的 `version_id`;版本控制 Bucket 的 HEAD 与 DELETE 都精确绑定该版本。DELETE 响应未知后不会重放原请求,而是等待两次间隔至少 60 秒、且大小/ETag/版本完全一致的 HEAD 证据,再以新的操作标识创建一个删除代次。每个自动清理周期最多三次,达到上限转为 `delete_attention`,由超级管理员在“对象存储 -> 对象清理异常”核查并手动恢复新的受控周期。删除意图一旦建立便不再占用用户自动备份保留份数;仍存在的远端数据单独计入对象清理债务。生产 Bucket 还必须配置终止未完成 multipart、清理非当前版本和过期删除标记的生命周期规则,但不得提前删除仍被目录引用的当前版本。