From 9640f94ffb254fb0967afd8bd1b0ea2323e76a76 Mon Sep 17 00:00:00 2001 From: codex Date: Sun, 8 Nov 2026 02:01:25 +0800 Subject: [PATCH] feat(backup): show deferred schedule status --- docs/DEPLOYMENT.md | 4 +-- docs/SERVICE_COMPENSATION.md | 4 +-- web/app/Services/Cloud/CloudBackupService.php | 3 +- web/public/cloud/detail.js | 28 +++++++++++++++++++ .../entries/detail-reinstall.entries.php | 13 +++++++++ web/resources/views/venix/layout_assets.tpl | 2 +- web/tests/CloudAssetVersionContractTest.php | 2 +- web/tests/CloudFreshSchemaContractTest.php | 11 ++++++-- web/tests/CloudUserBackupUiContractTest.php | 17 +++++++++++ web/tests/UserCopyManifestContractTest.php | 2 +- 10 files changed, 76 insertions(+), 10 deletions(-) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index b4c3eabc..01c46f31 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -160,7 +160,7 @@ libvirt 的持久 pool 定义就是 Agent 后续使用的映射,不另写存 公网网络接入在宿主机的“网络接入”中按资源池线路独立配置,可使用 `bridge:br0`、其他 Linux 网桥或 `network:default` 这样的 libvirt network。名称以字母或数字开头,后续只能包含字母、数字、点、下划线和短横线,bridge 名称为 1~15 字符,libvirt network 名称为 1~64 字符。宿主机上的公网网桥或 libvirt network 必须由运维预先准备。Agent 只发现、验证和使用现有公网网络,不创建公网网桥、不启动 libvirt network,也不修改公网地址、上游网关或挂载。`cloud_hosts.default_network` 仅保留为兼容展示值,不参与 Agent 就绪、调度、恢复、迁移或换 IP 决策;真正的运行时权威是资源池线路、当前 Agent 代次已验证的网络接入,以及绑定该接入的公网地址池。VPC 使用下述独立的 Agent 受管 bridge 和 L3 路由,不改变这一公网边界。 -当前完整 schema 版本为 `go-agent-wss-v38-backup-publication-preparation`。每个资源预留的当前公网权威只来自 `cloud_resource_reservation_ips.active_claim = 1` 的一组 IPv4+IPv6 精确声明;两族允许具有各自的 generation 和 operation ID,但必须绑定同一资源预留和网络接入,并各自与具体 IP、地址池、宿主机、实例状态双向一致。`cloud_resource_reservations` 中旧的单地址列只保留审计形态,不参与当前地址读取、释放或管理员投影。释放时历史声明保留并把 `active_claim` 置空,具体 IP 同时清空 claim、operation、reservation 和 instance 归属。普通换 IP、独立恢复和维护迁移分别只允许 transition ledger、restore attempt 与 migration source debt 所有的完整双栈流程;旧 `CloudPlacementService` 单地址恢复、旧换 IP writer,以及缺少或损坏冻结身份的任务仍会在派发 CAS 前拒绝,不能绕过新账本。 +当前完整 schema 版本为 `go-agent-wss-v41-backup-attempts`。自动备份订阅通过独立的延期字段保留原逻辑执行时隙;只有已确认未应用且可安全重试的救援或磁盘切换竞态,才会退休空白制品并以递增的 `schedule_attempt` 建立新代次。每个资源预留的当前公网权威只来自 `cloud_resource_reservation_ips.active_claim = 1` 的一组 IPv4+IPv6 精确声明;两族允许具有各自的 generation 和 operation ID,但必须绑定同一资源预留和网络接入,并各自与具体 IP、地址池、宿主机、实例状态双向一致。`cloud_resource_reservations` 中旧的单地址列只保留审计形态,不参与当前地址读取、释放或管理员投影。释放时历史声明保留并把 `active_claim` 置空,具体 IP 同时清空 claim、operation、reservation 和 instance 归属。普通换 IP、独立恢复和维护迁移分别只允许 transition ledger、restore attempt 与 migration source debt 所有的完整双栈流程;旧 `CloudPlacementService` 单地址恢复、旧换 IP writer,以及缺少或损坏冻结身份的任务仍会在派发 CAS 前拒绝,不能绕过新账本。 Agent 的 capabilities 响应仍使用 `network_selectors` 字段,但它是自动发现的当前可用 `bridge:<名称>` / `network:<名称>` 列表,排序去重且最多 64 项,不再来自配置文件。Linux 网桥必须有 sysfs bridge 目录且接口为 UP;libvirt network 必须处于 active 状态。完整 Agent 测试保存当前代次的候选列表,但不要求某个宿主机全局默认值必须存在。管理员只能从该代次已测试列表创建网络接入,并必须对每个接入执行精确验证;创建、恢复、迁移、重装和换 IP 会在锁内再次核对本次资源池线路、接入、公网池与 Agent 代次。修改兼容 `default_network` 不会撤销 Agent 就绪结果,修改或失效真实网络接入则由接入自身的验证状态阻止运行时使用。 @@ -258,7 +258,7 @@ systemctl enable --now virt-cloud-worker.service \ `virt-cloud-storage-health-worker.service` 与副本复制 worker 彻底隔离:它每次只领取一个到期后端,在数据库事务外执行最长 15 秒的 `HeadBucket`,并且只能按领取时冻结的配置版本结算。成功只恢复健康证据,不会把人工设置的 `read_only`、`draining` 或 `disabled` 改回 `active`;失败使正在 `active` 的后端转为 `read_only`、按 60 秒到 1 小时退避,新写入随即停止选择它。这个 worker 不执行 PUT、COPY、DELETE 或 Abort,也不把凭据写入心跳、日志或命令行。 -实例补偿的批次、明细和收件人账本已包含在当前 v38 完整 schema 中。`php xcat cloudInit` 只能为全新空数据库创建和验证当前全部结构,不能冒充既有数据库的增量升级。既有安装发布前必须备份数据库,使用经过审核的一次性迁移落地完整 v38 结构并核对 schema 指纹;升级成功后删除迁移脚本。然后按本节重启普通、通知及对象存储 workers。补偿本身不调用 Agent/Gateway,因此仅补偿功能不要求更新或重新编译宿主机 Agent 和面板 Gateway。完整语义见 [`SERVICE_COMPENSATION.md`](SERVICE_COMPENSATION.md)。 +实例补偿的批次、明细和收件人账本已包含在当前 v41 完整 schema 中。`php xcat cloudInit` 只能为全新空数据库创建和验证当前全部结构,不能冒充既有数据库的增量升级。既有安装发布前必须备份数据库,使用经过审核的一次性迁移落地完整 v41 结构并核对 schema 指纹;升级成功后删除迁移脚本。然后按本节重启普通、通知及对象存储 workers。补偿本身不调用 Agent/Gateway,因此仅补偿功能不要求更新或重新编译宿主机 Agent 和面板 Gateway。完整语义见 [`SERVICE_COMPENSATION.md`](SERVICE_COMPENSATION.md)。 共享流量池必须严格按 `disabled -> shadow -> enforced` 上线,并在强制执行前通过全部账本、采样和网络策略门禁。现有数据库不能使用 `php xcat cloudInit` 冒充增量升级,旧服务周期也不能通过 SQL 回填到流量池;完整步骤、验收项和故障处置见 [`TRAFFIC_POOL_ROLLOUT.md`](TRAFFIC_POOL_ROLLOUT.md)。 diff --git a/docs/SERVICE_COMPENSATION.md b/docs/SERVICE_COMPENSATION.md index e7bc44d8..c2f6311c 100644 --- a/docs/SERVICE_COMPENSATION.md +++ b/docs/SERVICE_COMPENSATION.md @@ -47,14 +47,14 @@ ## 部署 -全新数据库必须由当前 `CloudSetup` 创建并验证 `go-agent-wss-v38-backup-publication-preparation` 完整 schema;其中补偿模块包括: +全新数据库必须由当前 `CloudSetup` 创建并验证 `go-agent-wss-v41-backup-attempts` 完整 schema;其中补偿模块包括: - `cloud_service_compensations`; - `cloud_service_compensation_items`; - `cloud_service_compensation_recipients`; - 对应唯一键、领取索引、CHECK 和外键。 -`php xcat cloudInit` 只用于空数据库,不能作为既有数据库的增量升级工具。既有安装必须先备份数据库,再用经过审核的一次性迁移把当前 v38 结构完整落地,核对 schema 指纹后删除迁移脚本。只更新 PHP 而没有升级数据库会明确失败,不能在生产代码中忽略缺表。 +`php xcat cloudInit` 只用于空数据库,不能作为既有数据库的增量升级工具。既有安装必须先备份数据库,再用经过审核的一次性迁移把当前 v41 结构完整落地,核对 schema 指纹后删除迁移脚本。只更新 PHP 而没有升级数据库会明确失败,不能在生产代码中忽略缺表。 发布后需要重启普通 worker 和 `virt-cloud-notification-worker.service` 使其加载新 PHP 代码。功能不调用 Agent/Gateway,也不改变宿主机协议,因此不需要编译或更新 Agent、Gateway AMD64 二进制。 diff --git a/web/app/Services/Cloud/CloudBackupService.php b/web/app/Services/Cloud/CloudBackupService.php index fc0b03a6..3c7913e0 100644 --- a/web/app/Services/Cloud/CloudBackupService.php +++ b/web/app/Services/Cloud/CloudBackupService.php @@ -29,6 +29,7 @@ final class CloudBackupService ]; private const TRANSFER_URL_SECONDS = 604800; private const GIB = 1073741824; + private const MAX_SCHEDULE_ATTEMPT = 4294967295; /** * Global administrator backup catalog. It is intentionally keyed by the @@ -1956,7 +1957,7 @@ final class CloudBackupService if ((string) $latest->state === 'deleted') { if ((string) $latest->error_code !== 'automatic_transient_retried' - || $expected >= 4294967295) { + || $expected >= self::MAX_SCHEDULE_ATTEMPT) { throw new CloudError( '自动备份计划存在不可重用的已删除代次', 409 diff --git a/web/public/cloud/detail.js b/web/public/cloud/detail.js index 2af16426..ba227c70 100644 --- a/web/public/cloud/detail.js +++ b/web/public/cloud/detail.js @@ -1431,6 +1431,31 @@ function automaticBackupEnabled(payload = automaticBackupPayload) { return billing?.subscription_enabled === true || subscription?.enabled === true; } +const AUTOMATIC_BACKUP_DEFER_REASON_KEYS = Object.freeze({ + migration_active: 'instance_detail.backup.defer.reason.migration_active', + instance_mutation_active: 'instance_detail.backup.defer.reason.instance_mutation_active', + backup_rescue_active: 'instance_detail.backup.defer.reason.backup_rescue_active', + backup_disk_transition_active: 'instance_detail.backup.defer.reason.backup_disk_transition_active', + domain_job_active: 'instance_detail.backup.defer.reason.domain_job_active', + backup_readiness_unavailable: 'instance_detail.backup.defer.reason.backup_readiness_unavailable', + scheduler_unavailable: 'instance_detail.backup.defer.reason.scheduler_unavailable', +}); + +function automaticBackupDeferral(payload = automaticBackupPayload) { + const subscription = automaticBackupSubscription(payload); + const deferredUntil = Number(subscription?.deferred_until); + if (subscription?.deferred !== true + && (!Number.isFinite(deferredUntil) || deferredUntil <= 0)) return null; + const reasonKey = AUTOMATIC_BACKUP_DEFER_REASON_KEYS[ + String(subscription?.defer_reason || '') + ] || 'instance_detail.backup.defer.reason.backup_readiness_unavailable'; + return { + reason: t(reasonKey), + scheduled: snapshotTime(subscription?.next_run_at), + retry: snapshotTime(deferredUntil), + }; +} + function automaticBackupAmount(value) { const amount = typeof value === 'string' ? value.trim() : String(value ?? '').trim(); return /^(?:0|[1-9][0-9]{0,9})\.[0-9]{2}$/.test(amount) ? amount : ''; @@ -1631,6 +1656,7 @@ function renderAutomaticBackup(vmId, payload = automaticBackupPayload) { const schedule = automaticBackupSchedule(payload); const purchased = automaticBackupPurchased(payload); const enabled = automaticBackupEnabled(payload); + const deferral = automaticBackupDeferral(payload); const canConfigure = payload?.can_configure !== false && automaticBackupSubscription(payload)?.can_configure !== false; const scheduleAllowed = purchased && enabled && canConfigure @@ -1656,6 +1682,8 @@ function renderAutomaticBackup(vmId, payload = automaticBackupPayload) { automaticBackupStatus(t('instance_detail.backup.error.service_not_modifiable'), 'warning'); } else if (!enabled) { automaticBackupStatus(t('instance_detail.backup.notice.disabled_entitlement_retained'), 'warning'); + } else if (deferral) { + automaticBackupStatus(t('instance_detail.backup.defer.status', deferral), 'warning'); } else { automaticBackupStatus(t('instance_detail.backup.notice.enabled_schedule_editable'), 'success'); } diff --git a/web/resources/user-copy/entries/detail-reinstall.entries.php b/web/resources/user-copy/entries/detail-reinstall.entries.php index 3b28db3d..7e03854a 100644 --- a/web/resources/user-copy/entries/detail-reinstall.entries.php +++ b/web/resources/user-copy/entries/detail-reinstall.entries.php @@ -469,6 +469,14 @@ foreach ([ 'instance_detail.backup.enable_price' => '本期启用 {activation};下个完整周期 {renewal}', 'instance_detail.backup.entitlement_retained' => '当前已付备份权益保留至 {time}。', 'instance_detail.backup.restore_confirm' => '确认使用“{name}”覆盖当前实例系统盘?此操作不会回滚账单、服务周期或公网 IP。', + 'instance_detail.backup.defer.status' => '自动备份暂时延期:{reason}。原计划时间:{scheduled};系统将在 {retry} 重新核对。', + 'instance_detail.backup.defer.reason.migration_active' => '实例正在维护迁移', + 'instance_detail.backup.defer.reason.instance_mutation_active' => '实例正在执行其他操作', + 'instance_detail.backup.defer.reason.backup_rescue_active' => '实例处于救援模式', + 'instance_detail.backup.defer.reason.backup_disk_transition_active' => '实例正在切换或清理系统盘', + 'instance_detail.backup.defer.reason.domain_job_active' => '虚拟化层正在执行磁盘任务', + 'instance_detail.backup.defer.reason.backup_readiness_unavailable' => '宿主机备份状态暂不可核对', + 'instance_detail.backup.defer.reason.scheduler_unavailable' => '自动备份调度暂时不可用', 'instance_detail.firewall.apply_failed' => '新策略应用失败{detail};上一份已确认策略仍然生效,可修正规则后重试。', 'instance_detail.firewall.rule_duplicate' => '第 {index} 条规则与前面的规则重复。', 'instance_detail.firewall.rule_limit' => '每台实例最多允许 {limit} 条规则。', @@ -625,6 +633,11 @@ foreach ([ 'instance_detail.backup.enable_price' => ['activation' => 'string', 'renewal' => 'string'], 'instance_detail.backup.entitlement_retained' => ['time' => 'string'], 'instance_detail.backup.restore_confirm' => ['name' => 'string'], + 'instance_detail.backup.defer.status' => [ + 'reason' => 'string', + 'scheduled' => 'string', + 'retry' => 'string', + ], 'instance_detail.firewall.apply_failed' => ['detail' => 'string'], 'instance_detail.firewall.rule_duplicate' => ['index' => 'integer'], 'instance_detail.firewall.rule_limit' => ['limit' => 'integer'], diff --git a/web/resources/views/venix/layout_assets.tpl b/web/resources/views/venix/layout_assets.tpl index a5f29608..d8c8ef04 100644 --- a/web/resources/views/venix/layout_assets.tpl +++ b/web/resources/views/venix/layout_assets.tpl @@ -1,2 +1,2 @@ {* Shared Venix CSS/JS cache key. Increment whenever a shared browser asset changes. *} -{assign var=venix_asset_version value='2026110715' scope='global'} +{assign var=venix_asset_version value='2026110801' scope='global'} diff --git a/web/tests/CloudAssetVersionContractTest.php b/web/tests/CloudAssetVersionContractTest.php index 9dd97036..b0619203 100644 --- a/web/tests/CloudAssetVersionContractTest.php +++ b/web/tests/CloudAssetVersionContractTest.php @@ -15,7 +15,7 @@ $assert = static function (bool $condition, string $message): void { }; $assert(is_string($assets) - && str_contains($assets, "venix_asset_version value='2026110715'") + && str_contains($assets, "venix_asset_version value='2026110801'") && is_string($cloudShell) && str_contains($cloudShell, '/cloud/app.js?v={$venix_asset_version}'), 'The cloud application entry must use the shared Venix asset version.'); diff --git a/web/tests/CloudFreshSchemaContractTest.php b/web/tests/CloudFreshSchemaContractTest.php index 6ef8d924..72d952d1 100644 --- a/web/tests/CloudFreshSchemaContractTest.php +++ b/web/tests/CloudFreshSchemaContractTest.php @@ -4,7 +4,12 @@ $root = dirname(__DIR__); $schema = file_get_contents($root . '/sql/cloud.sql'); $baseSchema = file_get_contents($root . '/sql/ss.sql'); $setup = file_get_contents($root . '/app/Command/CloudSetup.php'); -if (!is_string($schema) || !is_string($baseSchema) || !is_string($setup)) { +$deployment = file_get_contents(dirname($root) . '/docs/DEPLOYMENT.md'); +$compensation = file_get_contents( + dirname($root) . '/docs/SERVICE_COMPENSATION.md' +); +if (!is_string($schema) || !is_string($baseSchema) || !is_string($setup) + || !is_string($deployment) || !is_string($compensation)) { throw new RuntimeException('Fresh schema files are unreadable.'); } @@ -23,7 +28,9 @@ $assert(!preg_match('/\bengine_[A-Za-z0-9_]*\b/', $schema), 'cloud.sql retained an engine-prefixed identifier.'); $assert(str_contains($setup, "SCHEMA_VERSION = 'go-agent-wss-v41-backup-attempts'") - && !str_contains($setup, "SCHEMA_VERSION = 'go-v1'"), + && !str_contains($setup, "SCHEMA_VERSION = 'go-v1'") + && str_contains($deployment, '`go-agent-wss-v41-backup-attempts`') + && str_contains($compensation, '`go-agent-wss-v41-backup-attempts`'), 'Outbound Agent schema must reject the incompatible earlier Go database.'); $assert(str_contains($schema, "timezone VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT 'UTC'") diff --git a/web/tests/CloudUserBackupUiContractTest.php b/web/tests/CloudUserBackupUiContractTest.php index a8644f46..9eb41cb8 100644 --- a/web/tests/CloudUserBackupUiContractTest.php +++ b/web/tests/CloudUserBackupUiContractTest.php @@ -75,6 +75,23 @@ $assert(str_contains($detailScript, "t('instance_detail.backup.notice.schedule_utc_midnight')") && !str_contains($detailScript, 'PT 00:00'), 'Automatic-backup runtime copy must use UTC.'); +$assert(str_contains($detailScript, 'function automaticBackupDeferral(') + && str_contains($detailScript, 'subscription?.next_run_at') + && str_contains($detailScript, 'subscription?.deferred_until') + && str_contains($detailScript, 'subscription?.defer_reason') + && str_contains($detailScript, "migration_active: 'instance_detail.backup.defer.reason.migration_active'") + && str_contains($detailScript, "instance_mutation_active: 'instance_detail.backup.defer.reason.instance_mutation_active'") + && str_contains($detailScript, "backup_rescue_active: 'instance_detail.backup.defer.reason.backup_rescue_active'") + && str_contains($detailScript, "backup_disk_transition_active: 'instance_detail.backup.defer.reason.backup_disk_transition_active'") + && str_contains($detailScript, "domain_job_active: 'instance_detail.backup.defer.reason.domain_job_active'") + && str_contains($detailScript, "backup_readiness_unavailable: 'instance_detail.backup.defer.reason.backup_readiness_unavailable'") + && str_contains($detailScript, "scheduler_unavailable: 'instance_detail.backup.defer.reason.scheduler_unavailable'") + && str_contains($detailScript, 'scheduled: snapshotTime(subscription?.next_run_at)') + && str_contains($detailScript, 'retry: snapshotTime(deferredUntil)') + && str_contains($detailScript, + "automaticBackupStatus(t('instance_detail.backup.defer.status', deferral), 'warning')") + && !str_contains($detailScript, 'defer_count'), + 'Automatic-backup deferrals must show a browser-local warning without exposing internal codes or retry counters.'); $assert(str_contains($detailScript, "`/api/v1/vms/\${encodeURIComponent(vmId)}/automatic-backup`") && str_contains($detailScript, diff --git a/web/tests/UserCopyManifestContractTest.php b/web/tests/UserCopyManifestContractTest.php index 0923e6f4..34502dc0 100644 --- a/web/tests/UserCopyManifestContractTest.php +++ b/web/tests/UserCopyManifestContractTest.php @@ -47,7 +47,7 @@ $assert($surfaceCounts === [ 'admin' => 112, 'dialog' => 56, 'feedback' => 610, - 'page' => 1462, + 'page' => 1470, 'shared' => 38, 'task' => 53, ],