['min_range' => 1]]); $currency = strtoupper((string) ($spec['currency'] ?? '')); if ($version === false || $currency !== 'USD' || (int) $instance->offer_id < 1) { throw new CloudError('实例缺少可信的自动备份计费快照', 409); } return $instance->getConnection()->transaction(function () use ( $instance, $price, $version, $currency ): CloudBackupSubscription { $locked = CloudInstance::where('id', (int) $instance->id) ->lockForUpdate()->first(); if ($locked === null || (string) $locked->status === 'deleted' || (int) $locked->user_id !== (int) $instance->user_id) { throw new CloudError('虚拟机不存在', 404); } $subscription = CloudBackupSubscription::where( 'instance_id', (int) $locked->id )->lockForUpdate()->first(); if ($subscription !== null) { if ((int) $subscription->user_id !== (int) $locked->user_id || (int) $subscription->offer_id !== (int) $locked->offer_id || CloudMoney::cents((string) $subscription->price) !== CloudMoney::cents($price) || strtoupper((string) $subscription->currency) !== $currency || (int) $subscription->price_version !== (int) $version) { throw new CloudError('自动备份订阅与实例计费账本不一致', 409); } return $subscription; } $now = time(); $subscription = new CloudBackupSubscription(); $subscription->instance_id = (int) $locked->id; $subscription->user_id = (int) $locked->user_id; $subscription->offer_id = (int) $locked->offer_id; $subscription->enabled = true; $subscription->renew_next_period = true; $subscription->frequency = 'daily'; $subscription->weekday = 0; $subscription->retention_count = self::MAX_RETENTION; $subscription->timezone = self::TIMEZONE; $subscription->price = $price; $subscription->currency = $currency; $subscription->price_version = (int) $version; $subscription->state_revision = 1; $subscription->next_run_at = self::nextRunAt( $now, 'daily', 0 ); $subscription->last_scheduled_at = null; $subscription->last_backup_id = null; $subscription->created_at = $subscription->updated_at = $now; $subscription->save(); return $subscription; }, 3); } public static function settings(CloudInstance $instance, array $actor): array { self::assertOwner($instance, $actor); $subscription = CloudBackupSubscription::where( 'instance_id', (int) $instance->id )->first(); $entitled = self::entitled($instance, $subscription, time()); if ($entitled && $subscription === null) { throw new CloudError('自动备份权益缺少订阅账本,请联系管理员', 409); } if ($subscription !== null && (int) $subscription->user_id !== (int) $instance->user_id) { throw new CloudError('自动备份订阅归属不一致', 409); } return [ 'instance_id' => (string) $instance->id, 'entitled' => $entitled, 'subscription' => $subscription === null ? null : self::displaySubscription($subscription), 'timezone' => self::TIMEZONE, 'run_at' => self::RUN_AT, 'max_retention' => self::MAX_RETENTION, 'backups' => self::backupsForInstance($instance), ]; } /** Keep the next-cycle backup fee aligned with a completed plan upgrade. */ public static function refreshPriceAfterUpgradeLocked( CloudInstance $instance, CloudOffer $offer ): void { $subscription = CloudBackupSubscription::where( 'instance_id', (int) $instance->id )->lockForUpdate()->first(); if ($subscription === null) { return; } if ((int) $offer->id !== (int) $instance->offer_id || (int) $subscription->user_id !== (int) $instance->user_id || strtoupper((string) $offer->currency) !== 'USD') { throw new CloudError('升级后的自动备份价格账本不一致', 409); } $price = self::moneySnapshot($offer->backup_price); $subscription->offer_id = (int) $offer->id; $subscription->price = $price; $subscription->price_version = (int) $offer->price_version; $subscription->updated_at = time(); $subscription->save(); } public static function update(CloudInstance $instance, array $actor, array $input): array { self::assertOwner($instance, $actor); CloudInput::only($input, [ 'frequency', 'weekday', 'retention_count', ]); $frequency = $input['frequency'] ?? null; if (!is_string($frequency) || !in_array($frequency, ['daily', 'weekly'], true)) { throw new CloudError('备份频率仅支持每天或每周'); } $retention = filter_var($input['retention_count'] ?? null, FILTER_VALIDATE_INT); if ($retention === false || !in_array((int) $retention, [1, 2], true)) { throw new CloudError('自动备份最多可保留两份'); } $weekday = $input['weekday'] ?? 0; if ($frequency === 'weekly') { $weekday = filter_var($weekday, FILTER_VALIDATE_INT); if ($weekday === false || (int) $weekday < 0 || (int) $weekday > 6) { throw new CloudError('每周备份日必须为 0 至 6'); } } elseif (array_key_exists('weekday', $input)) { $weekday = filter_var($weekday, FILTER_VALIDATE_INT); if ($weekday === false || (int) $weekday < 0 || (int) $weekday > 6) { throw new CloudError('备份日必须为 0 至 6'); } } $now = time(); $subscription = $instance->getConnection()->transaction( function () use ( $instance, $frequency, $weekday, $retention, $now ): CloudBackupSubscription { $locked = CloudBackupSubscription::where( 'instance_id', (int) $instance->id )->lockForUpdate()->first(); if ($locked === null || (int) $locked->user_id !== (int) $instance->user_id) { throw new CloudError('自动备份订阅尚未激活,请联系管理员', 409); } if (!(bool) $locked->enabled || !CloudBackupPeriodEntitlement::where( 'subscription_id', (int) $locked->id )->where('instance_id', (int) $instance->id) ->where('user_id', (int) $instance->user_id) ->where('starts_at', '<=', $now) ->where('ends_at', '>', $now) ->lockForUpdate()->exists()) { throw new CloudError('该实例当前没有已启用的自动备份权益', 409); } $changedSchedule = (string) $locked->frequency !== $frequency || (int) $locked->weekday !== (int) $weekday; $locked->frequency = $frequency; $locked->weekday = (int) $weekday; $locked->retention_count = (int) $retention; $locked->timezone = self::TIMEZONE; if ($changedSchedule) { $locked->next_run_at = self::nextRunAt( $now, $frequency, (int) $weekday ); } $locked->updated_at = $now; $locked->save(); return $locked; }, 3 ); return [ 'instance_id' => (string) $instance->id, 'entitled' => true, 'subscription' => self::displaySubscription($subscription), 'timezone' => self::TIMEZONE, 'run_at' => self::RUN_AT, 'max_retention' => self::MAX_RETENTION, 'backups' => self::backupsForInstance($instance), ]; } public static function library(array $actor, array $input): array { CloudInput::only($input, ['page', 'per_page']); $userId = (int) ($actor['user_id'] ?? 0); if ($userId < 1) { throw new CloudError('请先登录', 401); } $page = self::positiveInteger($input['page'] ?? 1, 1, 1000000); $perPage = self::positiveInteger($input['per_page'] ?? 20, 1, 50); if (!in_array($perPage, [20, 50], true)) { throw new CloudError('备份库每页条数仅支持 20 或 50'); } $query = CloudInstanceBackup::where('user_id', $userId) ->where('purpose', 'portable')->where('source', 'automatic') ->where('state', '<>', 'deleted'); self::withoutDeploymentSnapshots($query); $total = (int) (clone $query)->count('id'); $pages = max(1, (int) ceil($total / $perPage)); $page = min($page, $pages); $rows = $query->orderByDesc('id') ->offset(($page - 1) * $perPage)->limit($perPage)->get(); $instances = []; $ids = array_values(array_unique(array_map( static fn (CloudInstanceBackup $backup): int => (int) $backup->source_instance_id, $rows->all() ))); if ($ids !== []) { foreach (CloudInstance::whereIn('id', $ids)->get([ 'id', 'name', 'status', 'service_status', 'expires_at', 'user_id', ]) as $instance) { $instances[(int) $instance->id] = $instance; } } $items = []; foreach ($rows as $backup) { $items[] = self::displayBackup( $backup, $instances[(int) $backup->source_instance_id] ?? null ); } $from = $total === 0 ? 0 : (($page - 1) * $perPage) + 1; return [ 'items' => $items, 'pagination' => [ 'page' => $page, 'per_page' => $perPage, 'total' => $total, 'total_pages' => $pages, 'from' => $from, 'to' => $from === 0 ? 0 : $from + count($items) - 1, ], ]; } /** Queue at most $limit due backups; one bad subscription cannot starve later rows. */ public static function scheduleDue(int $limit = 10, ?int $now = null): int { $limit = max(1, min(50, $limit)); $now ??= time(); $ids = CloudBackupSubscription::where('enabled', 1) ->where('next_run_at', '>', 0) ->where('next_run_at', '<=', $now)->orderBy('next_run_at') ->orderBy('id')->limit($limit)->pluck('id')->all(); $queued = 0; foreach ($ids as $id) { try { if (self::scheduleOne((int) $id, $now)) { $queued++; } } catch (\Throwable $error) { if (self::pauseIfInstanceExpired((int) $id, $now)) { continue; } if (self::deferIfMigrationOpen((int) $id, $now)) { continue; } // Creation owns a durable intent before object-storage // preparation begins. Keep that exact scheduled slot stable // while the preparation worker reconciles it; moving // next_run_at here would change the idempotency key and create // a second backup for the same logical run. if (self::hasPendingCreateIntent((int) $id, $now)) { continue; } CloudBackupSubscription::where('id', (int) $id) ->where('enabled', 1) ->where('next_run_at', '<=', $now) ->update([ 'next_run_at' => $now + self::RETRY_SECONDS, 'updated_at' => time(), ]); error_log('cloud automatic backup schedule unavailable: ' . get_class($error)); } } return $queued; } /** * Return true only while the subscription's current slot is already * represented by a durable, pre-Agent backup intent. The subscription row * is locked so a concurrent successful preparation either advances the * slot first or observes this unchanged slot; it can never be rewritten to * a different retry timestamp between the check and the decision. */ private static function hasPendingCreateIntent( int $subscriptionId, int $now ): bool { $probe = CloudBackupSubscription::find($subscriptionId); if (!$probe instanceof CloudBackupSubscription) { return false; } return $probe->getConnection()->transaction(function () use ( $subscriptionId, $now ): bool { $subscription = CloudBackupSubscription::where( 'id', $subscriptionId )->lockForUpdate()->first(); if (!$subscription instanceof CloudBackupSubscription || !(bool) $subscription->enabled || (int) $subscription->next_run_at < 1 || (int) $subscription->next_run_at > $now) { return false; } $scheduledFor = (int) $subscription->next_run_at; $requestKey = 'automatic-backup-' . $subscriptionId . '-' . $scheduledFor; return CloudInstanceBackup::where( 'subscription_id', $subscriptionId )->where('scheduled_for', $scheduledFor) ->where('source', 'automatic') // `uncertain` with no Agent job is the operator-attention // form of this same pre-dispatch intent. It must keep the // original slot frozen until an administrator reopens it. ->whereIn('state', ['creating', 'uncertain']) ->whereNotNull('storage_artifact_id') ->whereNull('active_job_id') ->where('create_request_actor_id', (int) $subscription->user_id) ->where('create_request_idempotency_key', $requestKey) ->exists(); }, 3); } /** * Prune at most $limit fresh retention candidates plus a separate bounded * cleanup-debt batch, so stuck remote objects cannot starve new rotation. */ public static function pruneRetention(int $limit = 10, ?int $now = null, ?CloudObjectStorageS3Client $client = null): int { $limit = max(1, min(50, $limit)); $now ??= time(); $actorFor = static fn (int $userId): array => [ 'user_id' => $userId, 'is_admin' => true, 'is_super_admin' => true, 'can_manage' => true, 'session_id' => 'automatic-backup-retention', ]; $processed = 0; $removed = 0; // Cleanup debt has its own budget and due index. It never consumes the // fresh retention budget and attention-required rows wait for an // explicit administrator action instead of monopolising every batch. $debtLimit = max(1, min(10, intdiv($limit + 1, 2))); $pending = CloudInstanceBackup::where('purpose', 'portable') ->whereIn('state', ['deleting', 'delete_uncertain']) ->where('delete_next_check_at', '<=', $now) ->orderBy('delete_next_check_at')->orderBy('id'); $pending = $pending->limit($debtLimit)->get(); foreach ($pending as $backup) { try { $result = CloudBackupService::delete( $backup, $actorFor((int) $backup->user_id), $client ); if (($result['deleted'] ?? false) === true) { $removed++; } } catch (\Throwable $error) { error_log('cloud automatic backup retention unavailable: ' . get_class($error)); } } // A disabled plan keeps its already-paid recovery rights. Only after // the latest immutable entitlement has ended plus the three-day grace // may the retained object be removed. A later paid entitlement keeps // every retained backup available and excludes the subscription here. $cutoff = $now - self::RECOVERY_GRACE_SECONDS; $expiryGuard = static function ( CloudInstanceBackup $locked ) use ($cutoff): void { $subscription = CloudBackupSubscription::where( 'id', (int) $locked->subscription_id )->lockForUpdate()->first(); if ($subscription === null || CloudBackupPeriodEntitlement::where( 'subscription_id', (int) $subscription->id )->where('ends_at', '>', $cutoff)->exists()) { throw new CloudError( '自动备份权益已续期,跳过到期清理', 409 ); } }; $expired = CloudInstanceBackup::where('source', 'automatic') ->where('purpose', 'portable') ->whereIn('state', ['ready', 'failed']) ->whereNotNull('subscription_id') ->whereExists(static function ($query): void { $query->selectRaw('1') ->from('cloud_backup_period_entitlements') ->whereColumn( 'cloud_backup_period_entitlements.subscription_id', 'cloud_instance_backups.subscription_id' ); })->whereNotExists(static function ($query) use ($cutoff): void { $query->selectRaw('1') ->from('cloud_backup_period_entitlements') ->whereColumn( 'cloud_backup_period_entitlements.subscription_id', 'cloud_instance_backups.subscription_id' )->where('cloud_backup_period_entitlements.ends_at', '>', $cutoff); }); self::withoutDeploymentSnapshots($expired); $expired = $expired->orderBy('id') ->limit($limit - $processed)->get(); foreach ($expired as $backup) { try { $result = CloudBackupService::delete( $backup, $actorFor((int) $backup->user_id), $client, $expiryGuard ); if (($result['deleted'] ?? false) === true) { $removed++; } } catch (\Throwable $error) { error_log('cloud automatic backup expiry cleanup unavailable: ' . get_class($error)); } $processed++; } if ($processed >= $limit) { return $removed; } $subscriptions = CloudBackupSubscription::whereRaw( '(SELECT COUNT(*) FROM cloud_instance_backups ' . 'WHERE cloud_instance_backups.subscription_id = ' . 'cloud_backup_subscriptions.id ' . "AND cloud_instance_backups.source = 'automatic' " . "AND cloud_instance_backups.purpose = 'portable' " . "AND cloud_instance_backups.state = 'ready' " . 'AND NOT EXISTS (SELECT 1 FROM cloud_deployment_snapshots ' . 'WHERE cloud_deployment_snapshots.backup_id = ' . 'cloud_instance_backups.id ' . "AND cloud_deployment_snapshots.state <> 'deleted')) " . '> cloud_backup_subscriptions.retention_count' )->orderBy('id')->limit($limit - $processed)->get(); foreach ($subscriptions as $subscription) { if ($processed >= $limit) { break; } $ready = CloudInstanceBackup::where( 'subscription_id', (int) $subscription->id )->where('source', 'automatic')->where('purpose', 'portable') ->where('state', 'ready'); self::withoutDeploymentSnapshots($ready); $ready = $ready->orderBy('scheduled_for')->orderBy('id')->get(); $excess = max(0, $ready->count() - min(self::MAX_RETENTION, max(1, (int) $subscription->retention_count))); foreach ($ready->take($excess) as $backup) { if ($processed >= $limit) { break 2; } try { $result = CloudBackupService::delete( $backup, $actorFor((int) $subscription->user_id), $client ); if (($result['deleted'] ?? false) === true) { $removed++; } } catch (\Throwable $error) { error_log('cloud automatic backup retention unavailable: ' . get_class($error)); } $processed++; } } return $removed; } /** First UTC midnight strictly after $after. Weekday uses PHP w: 0=Sunday. */ public static function nextRunAt(int $after, string $frequency, int $weekday): int { if (!in_array($frequency, ['daily', 'weekly'], true) || $weekday < 0 || $weekday > 6) { throw new \InvalidArgumentException('Invalid automatic backup schedule'); } $zone = new \DateTimeZone(self::TIMEZONE); $local = (new \DateTimeImmutable('@' . max(0, $after))) ->setTimezone($zone); $candidate = $local->setTime(0, 0, 0); if ($candidate->getTimestamp() <= $after) { $candidate = $candidate->modify('+1 day'); } if ($frequency === 'weekly') { while ((int) $candidate->format('w') !== $weekday) { $candidate = $candidate->modify('+1 day'); } } return $candidate->getTimestamp(); } public static function advanceAfterScheduled( CloudBackupSubscription $subscription, int $scheduledFor, int $backupId ): void { $lastScheduled = max( 0, (int) ($subscription->last_scheduled_at ?? 0) ); if ($scheduledFor > $lastScheduled) { $subscription->last_scheduled_at = $scheduledFor; $subscription->last_backup_id = $backupId; } elseif ($scheduledFor === $lastScheduled) { $lastBackupId = (int) ($subscription->last_backup_id ?? 0); if ($lastBackupId !== 0 && $lastBackupId !== $backupId) { throw new CloudError('自动备份计划时间已绑定其他备份', 409); } if ($lastBackupId === 0) { $subscription->last_backup_id = $backupId; } } // A user may have changed frequency/weekday while object storage was // being prepared. Only advance the exact still-current slot; an older // intent may record its completion monotonically but must never // overwrite the newly selected schedule. if ($scheduledFor >= $lastScheduled && (int) $subscription->next_run_at === $scheduledFor) { $subscription->next_run_at = self::nextRunAt( max(time(), $scheduledFor), (string) $subscription->frequency, (int) $subscription->weekday ); } $subscription->updated_at = time(); $subscription->save(); } private static function scheduleOne(int $subscriptionId, int $now): bool { $subscription = CloudBackupSubscription::find($subscriptionId); if ($subscription === null || !(bool) $subscription->enabled || (int) $subscription->next_run_at > $now) { return false; } $instance = CloudInstance::find((int) $subscription->instance_id); if ($instance === null || self::shouldPauseForInstanceExpiry($instance, $now)) { self::pauseIfInstanceExpired($subscriptionId, $now); return false; } if ((string) $instance->status !== 'active' || (string) $instance->service_status !== 'active' || (int) $instance->user_id !== (int) $subscription->user_id) { throw new CloudError('实例当前不可创建自动备份', 409); } if (self::deferIfMigrationOpen($subscriptionId, $now)) { return false; } $scheduledFor = (int) $subscription->next_run_at; if (!CloudBackupPeriodEntitlement::where( 'subscription_id', (int) $subscription->id )->where('instance_id', (int) $instance->id) ->where('user_id', (int) $instance->user_id) ->where('starts_at', '<=', $scheduledFor) ->where('ends_at', '>', $scheduledFor)->exists()) { throw new CloudError('自动备份执行时间不在已付权益周期内', 409); } $actor = [ 'user_id' => (int) $instance->user_id, 'is_admin' => false, 'is_super_admin' => false, 'can_manage' => true, 'session_id' => 'automatic-backup-scheduler', 'request_idempotency_key' => 'automatic-backup-' . (int) $subscription->id . '-' . $scheduledFor, ]; $queued = CloudBackupService::createAutomatic( $instance, $subscription, $actor, $scheduledFor ); return $queued['job'] instanceof CloudJob; } /** Instance expiry is a billing pause, not a retryable scheduler error. */ public static function shouldPauseForInstanceExpiry( CloudInstance $instance, int $now ): bool { return (string) $instance->status === 'deleted' || ($instance->expires_at !== null && (int) $instance->expires_at <= $now) || in_array((string) $instance->service_status, [ 'expired_grace', 'suspending_expired', 'suspend_failed', 'suspended_expired', 'purge_stopping', 'purge_stop_failed', 'purge_force_required', 'purge_deleting', 'purge_failed', ], true); } /** * Match renewal lock order (instance then subscription), then re-check the * expiry predicate before parking the schedule. This prevents a stale * scheduler read from disabling a subscription after renewal commits. */ private static function pauseIfInstanceExpired( int $subscriptionId, int $now ): bool { $probe = CloudBackupSubscription::find($subscriptionId); if ($probe === null) { return false; } return $probe->getConnection()->transaction(function () use ( $subscriptionId, $probe, $now ): bool { $instance = CloudInstance::where( 'id', (int) $probe->instance_id )->lockForUpdate()->first(); $subscription = CloudBackupSubscription::where( 'id', $subscriptionId )->lockForUpdate()->first(); if ($subscription === null || (int) $subscription->instance_id !== (int) $probe->instance_id) { return false; } if ($instance !== null && !self::shouldPauseForInstanceExpiry($instance, $now)) { return false; } if ((bool) $subscription->enabled || (int) $subscription->next_run_at !== 0) { $subscription->enabled = false; $subscription->next_run_at = 0; self::advanceStateRevision($subscription); $subscription->updated_at = $now; $subscription->save(); } return true; }, 3); } /** * An open maintenance migration is a temporary instance mutation fence, * not an automatic-backup failure. Serialize with migration start through * the instance row, then move only the due slot by the bounded retry delay. */ private static function deferIfMigrationOpen( int $subscriptionId, int $now ): bool { $probe = CloudBackupSubscription::find($subscriptionId); if ($probe === null) { return false; } return $probe->getConnection()->transaction(function () use ( $subscriptionId, $probe, $now ): bool { $instance = CloudInstance::where( 'id', (int) $probe->instance_id )->lockForUpdate()->first(); $subscription = CloudBackupSubscription::where( 'id', $subscriptionId )->lockForUpdate()->first(); if ($instance === null || $subscription === null || !(bool) $subscription->enabled || (int) $subscription->instance_id !== (int) $instance->id || (int) $subscription->next_run_at < 1 || (int) $subscription->next_run_at > $now || !CloudInstanceMigrationService::hasOpenMigration( (int) $instance->id )) { return false; } $subscription->next_run_at = $now + self::RETRY_SECONDS; $subscription->updated_at = $now; $subscription->save(); return true; }, 3); } private static function backupsForInstance(CloudInstance $instance): array { $items = []; foreach (CloudInstanceBackup::where( 'source_instance_id', (int) $instance->id )->where('user_id', (int) $instance->user_id) ->where('purpose', 'portable')->where('source', 'automatic') ->where('state', '<>', 'deleted') ->whereNotExists(static function ($query): void { $query->selectRaw('1')->from('cloud_deployment_snapshots') ->whereColumn( 'cloud_deployment_snapshots.backup_id', 'cloud_instance_backups.id' )->where('cloud_deployment_snapshots.state', '<>', 'deleted'); })->orderByDesc('id')->get() as $backup) { $items[] = self::displayBackup($backup, $instance); } return $items; } private static function displayBackup(CloudInstanceBackup $backup, ?CloudInstance $instance): array { $state = in_array((string) $backup->state, [ 'creating', 'ready', 'failed', 'uncertain', 'deleting', 'delete_uncertain', 'delete_attention', ], true) ? (string) $backup->state : 'uncertain'; $restore = CloudOriginalBackupRestorePolicy::evaluate( $instance, $backup ); return [ 'id' => (string) $backup->id, 'name' => (string) $backup->name, 'state' => $state, 'consistency' => in_array((string) $backup->consistency, ['filesystem', 'crash'], true) ? (string) $backup->consistency : 'unknown', 'object_size_bytes' => max(0, (int) $backup->object_size_bytes), 'virtual_size_bytes' => max(0, (int) $backup->virtual_size_bytes), 'scheduled_for' => $backup->scheduled_for === null ? null : max(0, (int) $backup->scheduled_for), 'created_at' => max(0, (int) $backup->created_at), 'ready_at' => $backup->ready_at === null ? null : max(0, (int) $backup->ready_at), 'source_instance' => [ 'id' => (string) $backup->source_instance_id, 'name' => $instance === null ? '' : (string) $instance->name, 'status' => $instance === null ? 'missing' : (string) $instance->status, ], 'can_restore_original' => $restore['eligible'], 'restore_original_block_reason' => $restore['eligible'] ? '' : $restore['reason'], 'can_promote' => $state === 'ready' && self::withinRecoveryGrace($backup), ]; } /** Exclude immutable objects now owned by the deployment-snapshot ledger. */ private static function withoutDeploymentSnapshots($query): void { $query->whereNotExists(static function ($subquery): void { $subquery->selectRaw('1')->from('cloud_deployment_snapshots') ->whereColumn( 'cloud_deployment_snapshots.backup_id', 'cloud_instance_backups.id' )->where('cloud_deployment_snapshots.state', '<>', 'deleted'); }); } /** A paid period remains recoverable until three days after its end. */ public static function withinRecoveryGrace(CloudInstanceBackup $backup, ?int $now = null): bool { return CloudOriginalBackupRestorePolicy::withinRecoveryWindow( $backup, $now ); } private static function displaySubscription( CloudBackupSubscription $subscription ): array { return [ 'enabled' => (bool) $subscription->enabled, 'renew_next_period' => (bool) $subscription->renew_next_period, 'frequency' => (string) $subscription->frequency, 'weekday' => (int) $subscription->weekday, 'retention_count' => (int) $subscription->retention_count, 'timezone' => self::TIMEZONE, 'run_at' => self::RUN_AT, 'next_run_at' => max(0, (int) $subscription->next_run_at), 'last_scheduled_at' => $subscription->last_scheduled_at === null ? null : max(0, (int) $subscription->last_scheduled_at), 'price' => (string) $subscription->price, 'currency' => (string) $subscription->currency, 'price_version' => (int) $subscription->price_version, 'state_revision' => self::stateRevision($subscription), ]; } private static function stateRevision( CloudBackupSubscription $subscription ): int { $revision = (int) $subscription->state_revision; if ($revision < 1 || $revision > 4294967295) { throw new CloudError('自动备份订阅状态版本异常', 409); } return $revision; } private static function advanceStateRevision( CloudBackupSubscription $subscription ): int { $revision = self::stateRevision($subscription); if ($revision >= 4294967295) { throw new CloudError('自动备份订阅状态版本已耗尽', 409); } $subscription->state_revision = $revision + 1; return (int) $subscription->state_revision; } private static function entitled( CloudInstance $instance, ?CloudBackupSubscription $subscription, int $at ): bool { if ($subscription === null) { return false; } return CloudBackupPeriodEntitlement::where( 'subscription_id', (int) $subscription->id )->where('instance_id', (int) $instance->id) ->where('user_id', (int) $instance->user_id) ->where('starts_at', '<=', $at) ->where('ends_at', '>', $at)->exists(); } private static function spec(CloudInstance $instance): array { $spec = json_decode((string) $instance->spec_json, true); if (!is_array($spec) || array_is_list($spec)) { throw new CloudError('实例计费快照损坏', 409); } return $spec; } private static function moneySnapshot($value): string { return CloudMoney::decimal(CloudMoney::cents($value)); } private static function assertOwner(CloudInstance $instance, array $actor): void { if ((int) ($actor['user_id'] ?? 0) !== (int) $instance->user_id) { throw new CloudError('无权查看或修改该实例的自动备份', 403); } } private static function positiveInteger($value, int $minimum, int $maximum): int { if (is_int($value)) { $parsed = $value; } elseif (is_string($value) && preg_match('/^[1-9][0-9]{0,9}$/D', $value) === 1) { $parsed = (int) $value; } else { throw new CloudError('备份库分页参数无效'); } if ($parsed < $minimum || $parsed > $maximum) { throw new CloudError('备份库分页参数超出范围'); } return $parsed; } }