[ 'position' => 1, 'label' => '准备源实例', 'running_state' => 'preparing_source', 'job_kind' => 'instance_migration_prepare', 'job_field' => 'source_prepare_job_id', 'task_key' => 'prepare_task_id', 'finish_handler' => 'finishPrepareLocked', 'reconcile_action' => 'reconcile_prepare', 'failure_policy' => 'conditional_abort', 'failure_action' => null, 'required_recovery_actions' => ['abort_prepare'], 'recovery_actions' => [ 'abort_prepare' => [ 'label' => '中止迁移并恢复源实例', 'handler' => 'recoverAbortPrepare', 'destructive' => true, 'recorded_actions' => [ 'reconcile_prepare', 'abort_prepare', ], 'requires_abort_evidence' => true, ], ], ], 'vpc_target' => [ 'position' => 2, 'label' => '切换私网路由', 'running_state' => 'vpc_target_routing', 'job_kind' => null, 'job_field' => null, 'task_key' => null, 'finish_handler' => null, 'reconcile_action' => 'reconcile_vpc_target', 'failure_policy' => 'external_orchestration', 'failure_action' => 'retry_vpc_target', 'required_recovery_actions' => [ 'retry_vpc_target', 'abort_vpc_target', ], 'recovery_actions' => [ 'retry_vpc_target' => [ 'label' => '重试目标私网路由', 'handler' => 'recoverRetryVpcTargetLocked', 'destructive' => false, 'recorded_actions' => ['retry_vpc_target'], 'requires_abort_evidence' => false, ], 'abort_vpc_target' => [ 'label' => '恢复源私网并中止迁移', 'handler' => 'recoverAbortVpcTargetLocked', 'destructive' => true, 'recorded_actions' => ['retry_vpc_target'], 'requires_abort_evidence' => false, ], ], ], 'transfer' => [ 'position' => 3, 'label' => '传输磁盘与快照', 'running_state' => 'transferring', 'job_kind' => 'instance_migration_transfer', 'job_field' => 'target_receive_job_id', 'task_key' => 'transfer_task_id', 'finish_handler' => 'finishTransferLocked', 'reconcile_action' => 'reconcile_transfer', 'failure_policy' => 'manual_recovery', 'failure_action' => 'retry_transfer', 'required_recovery_actions' => [ 'retry_transfer', 'abort_transfer', ], 'recovery_actions' => [ 'retry_transfer' => [ 'label' => '继续分块传输', 'handler' => 'recoverRetryTransferLocked', 'destructive' => false, 'recorded_actions' => ['retry_transfer'], 'requires_abort_evidence' => false, ], 'abort_transfer' => [ 'label' => '中止传输并恢复源实例', 'handler' => 'recoverAbortTransferLocked', 'destructive' => true, 'recorded_actions' => ['retry_transfer'], 'requires_abort_evidence' => false, ], ], ], 'cutover' => [ 'position' => 4, 'label' => '切换实例账本', 'running_state' => 'cutover', 'job_kind' => null, 'job_field' => null, 'task_key' => null, 'finish_handler' => null, 'reconcile_action' => null, 'failure_policy' => 'inline_transaction', 'failure_action' => null, 'required_recovery_actions' => [], 'recovery_actions' => [], ], 'firewall' => [ 'position' => 5, 'label' => '恢复目标防火墙', 'running_state' => 'firewall_running', 'job_kind' => 'firewall_apply', 'job_field' => 'firewall_job_id', 'task_key' => 'firewall_task_id', 'finish_handler' => 'finishFirewallLocked', 'reconcile_action' => 'reconcile_firewall', 'failure_policy' => 'manual_recovery', 'failure_action' => 'retry_firewall', 'required_recovery_actions' => ['retry_firewall'], 'recovery_actions' => [ 'retry_firewall' => [ 'label' => '重试目标防火墙', 'handler' => 'recoverRetryFirewallLocked', 'destructive' => false, 'recorded_actions' => ['retry_firewall'], 'requires_abort_evidence' => false, ], ], ], 'activation' => [ 'position' => 6, 'label' => '恢复目标电源状态', 'running_state' => 'activation_running', 'job_kind' => 'instance_migration_activate', 'job_field' => 'activate_job_id', 'task_key' => 'activation_task_id', 'finish_handler' => 'finishActivationLocked', 'reconcile_action' => 'reconcile_activation', 'failure_policy' => 'manual_recovery', 'failure_action' => 'retry_activation', 'required_recovery_actions' => ['retry_activation'], 'recovery_actions' => [ 'retry_activation' => [ 'label' => '重试目标状态恢复', 'handler' => 'recoverRetryActivationLocked', 'destructive' => false, 'recorded_actions' => ['retry_activation'], 'requires_abort_evidence' => false, ], ], ], 'cleanup' => [ 'position' => 7, 'label' => '清理源副本', 'running_state' => 'cleanup_running', 'job_kind' => 'instance_migration_cleanup', 'job_field' => 'cleanup_job_id', 'task_key' => 'cleanup_task_id', 'finish_handler' => 'finishCleanupLocked', 'reconcile_action' => 'reconcile_cleanup', 'failure_policy' => 'source_retained', 'failure_action' => null, 'required_recovery_actions' => [], 'recovery_actions' => [], ], 'vpc_source' => [ 'position' => null, 'label' => '恢复源私网路由', 'running_state' => 'vpc_source_routing', 'job_kind' => null, 'job_field' => null, 'task_key' => null, 'finish_handler' => null, 'reconcile_action' => 'reconcile_vpc_source', 'failure_policy' => 'external_orchestration', 'failure_action' => 'retry_vpc_source', 'required_recovery_actions' => ['retry_vpc_source'], 'recovery_actions' => [ 'retry_vpc_source' => [ 'label' => '重试恢复源私网路由', 'handler' => 'recoverRetryVpcSourceLocked', 'destructive' => false, 'recorded_actions' => ['retry_vpc_source'], 'requires_abort_evidence' => false, ], ], ], 'rollback' => [ 'position' => null, 'label' => '恢复源实例', 'running_state' => 'rollback_running', 'job_kind' => 'instance_migration_rollback', 'job_field' => 'rollback_job_id', 'task_key' => 'rollback_task_id', 'finish_handler' => 'finishRollbackLocked', 'reconcile_action' => 'reconcile_rollback', 'failure_policy' => 'manual_recovery', 'failure_action' => 'retry_rollback', 'required_recovery_actions' => ['retry_rollback'], 'recovery_actions' => [ 'retry_rollback' => [ 'label' => '重试恢复源实例', 'handler' => 'recoverRetryRollbackLocked', 'destructive' => false, 'recorded_actions' => ['retry_rollback'], 'requires_abort_evidence' => false, ], ], ], ]; private const PASSIVE_STATES = [ 'attention_required', 'source_retained', 'completed', 'rolled_back', 'failed', ]; /** @return array> */ public static function stages(): array { self::assertIntegrity(); return self::STAGES; } /** @return array|null */ public static function job(string $kind): ?array { self::assertIntegrity(); foreach (self::STAGES as $key => $stage) { if ($stage['job_kind'] === $kind) { return ['key' => $key] + $stage; } } return null; } /** @return list */ public static function blockingStates(): array { self::assertIntegrity(); $states = ['attention_required']; foreach (self::STAGES as $stage) { $states[] = $stage['running_state']; } return array_values(array_unique($states)); } public static function blocksInstance(string $state): bool { return in_array($state, self::blockingStates(), true); } public static function blocksNewMigration(string $state): bool { return self::blocksInstance($state) || $state === 'source_retained'; } public static function isRecoveryAction(string $action): bool { return self::recoveryDefinition($action) !== null; } public static function recoveryHandler(string $action): ?string { $definition = self::recoveryDefinition($action); return $definition === null ? null : (string) $definition['handler']; } public static function failureAction(string $stageKey): ?string { self::assertIntegrity(); if (!isset(self::STAGES[$stageKey])) { throw new \LogicException( 'Unknown maintenance-migration stage: ' . $stageKey ); } $action = self::STAGES[$stageKey]['failure_action']; return $action === null ? null : (string) $action; } /** * @return list */ public static function recoveryOptions( CloudInstanceMigration $migration, bool $hasAbortPrepareEvidence ): array { self::assertIntegrity(); if ((string) $migration->state !== 'attention_required') { return []; } $recorded = (string) $migration->recovery_action; $options = []; foreach (self::STAGES as $stage) { foreach ($stage['recovery_actions'] as $action => $definition) { if (!in_array($recorded, $definition['recorded_actions'], true)) { continue; } if ($definition['requires_abort_evidence'] && !$hasAbortPrepareEvidence) { continue; } $options[] = [ 'action' => $action, 'label' => (string) $definition['label'], 'destructive' => (bool) $definition['destructive'], ]; } } return $options; } /** @return list */ public static function recoveryActions( CloudInstanceMigration $migration, bool $hasAbortPrepareEvidence ): array { return array_map( static fn (array $option): string => $option['action'], self::recoveryOptions($migration, $hasAbortPrepareEvidence) ); } public static function assertState( string $state, string $recoveryAction ): void { self::assertIntegrity(); $knownStates = self::PASSIVE_STATES; foreach (self::STAGES as $stage) { $knownStates[] = $stage['running_state']; } if (!in_array($state, $knownStates, true)) { throw new \LogicException( 'Unknown maintenance-migration state: ' . $state ); } if ($state === 'attention_required') { if (!self::isRecordedRecoveryAction($recoveryAction)) { throw new \LogicException( 'Attention state requires a registered recovery action' ); } return; } if ($state === 'source_retained') { if (!in_array($recoveryAction, ['', 'reconcile_cleanup'], true)) { throw new \LogicException( 'Source-retained state has an invalid recovery action' ); } return; } if ($recoveryAction !== '') { throw new \LogicException( 'Migration state does not accept a recovery action: ' . $state ); } } /** * A stable, byte-progress-free projection. PeerMigration V3 currently * returns no durable transfer telemetry, so the panel reports truthful * stage progress instead of inventing a percentage. * * @return array */ public static function progress( CloudInstanceMigration $migration ): array { self::assertIntegrity(); $state = (string) $migration->state; $currentKey = self::stageForStateOrRecovery( $state, (string) $migration->recovery_action ); $mainStages = array_filter( self::STAGES, static fn (array $stage): bool => is_int($stage['position']) ); uasort($mainStages, static fn (array $left, array $right): int => $left['position'] <=> $right['position']); $currentPosition = $currentKey !== null && is_int(self::STAGES[$currentKey]['position']) ? self::STAGES[$currentKey]['position'] : null; $terminalCompleted = $state === 'completed'; $onRollbackPath = in_array($currentKey, ['vpc_source', 'rollback'], true) || $state === 'rolled_back'; $steps = []; foreach ($mainStages as $key => $stage) { $stepStatus = 'pending'; if ($onRollbackPath) { if ($key === 'prepare') { // A transfer job can only be queued after source prepare // succeeds. Unlike error_code, this durable link is not // rewritten when rollback itself fails and is retried. $stepStatus = $migration->source_was_running === null ? 'interrupted' : 'completed'; } elseif ($key === 'vpc_target') { $stepStatus = $migration->vpc_port_id === null ? 'skipped' : ($migration->target_receive_job_id === null ? 'interrupted' : 'completed'); } elseif ($key === 'transfer') { $stepStatus = $migration->target_receive_job_id === null ? 'skipped' : 'interrupted'; } } elseif ($terminalCompleted) { $stepStatus = self::stageWasSkipped($migration, $key) ? 'skipped' : 'completed'; } elseif ($state === 'source_retained') { if ($key === 'cleanup') { $stepStatus = (string) $migration->recovery_action === 'reconcile_cleanup' ? 'attention_required' : 'available'; } else { $stepStatus = self::stageWasSkipped($migration, $key) ? 'skipped' : 'completed'; } } elseif ($currentPosition !== null && $stage['position'] < $currentPosition) { $stepStatus = self::stageWasSkipped($migration, $key) ? 'skipped' : 'completed'; } elseif ($key === $currentKey) { $stepStatus = $state === 'attention_required' ? 'attention_required' : 'running'; } $steps[] = [ 'key' => $key, 'label' => (string) $stage['label'], 'status' => $stepStatus, 'status_label' => self::stepStatusLabel($stepStatus), ]; } if ($migration->vpc_port_id !== null && (in_array($currentKey, ['vpc_source', 'rollback'], true) || $state === 'rolled_back')) { $sourceRouteStatus = $currentKey === 'vpc_source' ? ($state === 'attention_required' ? 'attention_required' : 'running') : 'completed'; $steps[] = [ 'key' => 'vpc_source', 'label' => (string) self::STAGES['vpc_source']['label'], 'status' => $sourceRouteStatus, 'status_label' => self::stepStatusLabel($sourceRouteStatus), ]; } if ($currentKey === 'rollback' || $state === 'rolled_back') { $steps[] = [ 'key' => 'rollback', 'label' => (string) self::STAGES['rollback']['label'], 'status' => $state === 'rolled_back' ? 'completed' : ($state === 'attention_required' ? 'attention_required' : 'running'), 'status_label' => $state === 'rolled_back' ? self::stepStatusLabel('completed') : self::stepStatusLabel( $state === 'attention_required' ? 'attention_required' : 'running' ), ]; } $status = match ($state) { 'completed' => 'completed', 'rolled_back' => 'rolled_back', 'source_retained' => (string) $migration->recovery_action === 'reconcile_cleanup' ? 'attention_required' : 'source_retained', 'attention_required' => 'attention_required', 'failed' => 'failed', default => 'running', }; $currentStage = $currentKey === null ? null : [ 'key' => $currentKey, 'label' => (string) self::STAGES[$currentKey]['label'], 'index' => self::STAGES[$currentKey]['position'], ]; return [ 'status' => $status, 'label' => self::progressLabel($status, $currentStage), 'blocks_instance' => self::blocksInstance($state), 'blocks_new_migration' => self::blocksNewMigration($state), 'current_stage' => $currentStage, 'stage_count' => count($mainStages), 'steps' => $steps, 'byte_progress_available' => false, 'updated_at' => (int) $migration->updated_at, ]; } public static function assertIntegrity(): void { static $checked = false; if ($checked) { return; } self::assertDefinitions(self::STAGES); $checked = true; } /** @param array> $stages */ public static function assertDefinitions(array $stages): void { $required = [ 'position', 'label', 'running_state', 'job_kind', 'job_field', 'task_key', 'finish_handler', 'reconcile_action', 'failure_policy', 'failure_action', 'required_recovery_actions', 'recovery_actions', ]; $failurePolicies = [ 'conditional_abort', 'manual_recovery', 'inline_transaction', 'source_retained', 'external_orchestration', ]; $positions = []; $states = []; $jobKinds = []; $jobFields = []; $taskKeys = []; $reconcileActions = []; $actions = []; if ($stages === []) { throw new \LogicException( 'Maintenance-migration workflow has no stages' ); } foreach ($stages as $key => $stage) { if (!is_string($key) || $key === '' || !is_array($stage) || array_diff($required, array_keys($stage)) !== [] || !is_string($stage['label']) || $stage['label'] === '' || !is_string($stage['running_state']) || $stage['running_state'] === '' || ($stage['position'] !== null && !is_int($stage['position'])) || !is_string($stage['failure_policy']) || !in_array( $stage['failure_policy'], $failurePolicies, true ) || ($stage['failure_action'] !== null && (!is_string($stage['failure_action']) || $stage['failure_action'] === '')) || !is_array($stage['required_recovery_actions']) || !array_is_list($stage['required_recovery_actions']) || array_filter( $stage['required_recovery_actions'], static fn ($action): bool => !is_string($action) || $action === '' ) !== [] || count($stage['required_recovery_actions']) !== count(array_unique( $stage['required_recovery_actions'] )) || !is_array($stage['recovery_actions'])) { throw new \LogicException( 'Incomplete maintenance-migration stage: ' . $key ); } if (isset($states[$stage['running_state']])) { throw new \LogicException( 'Duplicate maintenance-migration running state' ); } $states[$stage['running_state']] = true; if (is_int($stage['position'])) { if (isset($positions[$stage['position']])) { throw new \LogicException( 'Duplicate maintenance-migration stage position' ); } $positions[$stage['position']] = true; } if ($stage['job_kind'] !== null) { foreach (['job_kind', 'job_field', 'task_key', 'finish_handler', 'reconcile_action'] as $field) { if (!is_string($stage[$field]) || $stage[$field] === '') { throw new \LogicException( 'Executable migration stage is incomplete: ' . $key ); } } if (isset($jobKinds[$stage['job_kind']]) || isset($jobFields[$stage['job_field']]) || isset($taskKeys[$stage['task_key']]) || isset($reconcileActions[$stage['reconcile_action']])) { throw new \LogicException( 'Duplicate maintenance-migration job definition' ); } $jobKinds[$stage['job_kind']] = true; $jobFields[$stage['job_field']] = true; $taskKeys[$stage['task_key']] = true; $reconcileActions[$stage['reconcile_action']] = true; } elseif ($stage['failure_policy'] === 'external_orchestration') { if ($stage['job_field'] !== null || $stage['task_key'] !== null || $stage['finish_handler'] !== null || !is_string($stage['reconcile_action']) || $stage['reconcile_action'] === '' || isset($reconcileActions[$stage['reconcile_action']])) { throw new \LogicException( 'External migration stage is incomplete: ' . $key ); } $reconcileActions[$stage['reconcile_action']] = true; } elseif ($stage['job_field'] !== null || $stage['task_key'] !== null || $stage['finish_handler'] !== null || $stage['reconcile_action'] !== null) { throw new \LogicException( 'Non-job migration stage contains partial job metadata' ); } foreach ($stage['recovery_actions'] as $action => $definition) { if (isset($actions[$action]) || !is_string($action) || $action === '' || !is_array($definition) || !is_string($definition['label'] ?? null) || ($definition['label'] ?? '') === '' || !is_string($definition['handler'] ?? null) || ($definition['handler'] ?? '') === '' || !is_bool($definition['destructive'] ?? null) || !is_array($definition['recorded_actions'] ?? null) || $definition['recorded_actions'] === [] || !array_is_list($definition['recorded_actions']) || array_filter( $definition['recorded_actions'], static fn ($recorded): bool => !is_string($recorded) || $recorded === '' ) !== [] || !is_bool( $definition['requires_abort_evidence'] ?? null )) { throw new \LogicException( 'Invalid maintenance-migration recovery definition' ); } $actions[$action] = true; } $definedActions = array_keys($stage['recovery_actions']); $requiredActions = $stage['required_recovery_actions']; sort($definedActions); sort($requiredActions); if ($definedActions !== $requiredActions) { throw new \LogicException( 'Migration stage recovery exits do not match its contract: ' . $key ); } $failureAction = $stage['failure_action']; if ($stage['failure_policy'] === 'manual_recovery') { if ($stage['job_kind'] === null || $failureAction === null || !isset($stage['recovery_actions'][$failureAction])) { throw new \LogicException( 'Manual-recovery stage has no failure exit: ' . $key ); } foreach ($stage['required_recovery_actions'] as $action) { if (!in_array( $failureAction, $stage['recovery_actions'][$action]['recorded_actions'], true )) { throw new \LogicException( 'Recovery exit is unreachable from stage failure: ' . $key ); } } } elseif ($stage['failure_policy'] === 'external_orchestration') { if ($stage['job_kind'] !== null || $failureAction === null || !isset($stage['recovery_actions'][$failureAction])) { throw new \LogicException( 'External migration stage has no failure exit: ' . $key ); } foreach ($stage['required_recovery_actions'] as $action) { if (!in_array( $failureAction, $stage['recovery_actions'][$action]['recorded_actions'], true )) { throw new \LogicException( 'External recovery exit is unreachable: ' . $key ); } } } elseif ($stage['failure_policy'] === 'conditional_abort') { if ($stage['job_kind'] === null || $failureAction !== null || $stage['required_recovery_actions'] === []) { throw new \LogicException( 'Conditional-abort stage has an invalid failure contract: ' . $key ); } foreach ($stage['required_recovery_actions'] as $action) { $definition = $stage['recovery_actions'][$action]; if (!$definition['requires_abort_evidence'] || !in_array( $stage['reconcile_action'], $definition['recorded_actions'], true )) { throw new \LogicException( 'Conditional abort is not evidence-gated: ' . $key ); } } } elseif ($stage['failure_policy'] === 'inline_transaction') { if ($stage['job_kind'] !== null || $failureAction !== null || $stage['required_recovery_actions'] !== []) { throw new \LogicException( 'Inline stage exposes an invalid recovery contract: ' . $key ); } } elseif ($stage['job_kind'] === null || $failureAction !== null || $stage['required_recovery_actions'] !== []) { throw new \LogicException( 'Source-retained stage exposes an invalid recovery contract: ' . $key ); } } ksort($positions); if (array_keys($positions) !== range(1, count($positions))) { throw new \LogicException( 'Maintenance-migration stage positions are not contiguous' ); } foreach ($stages as $stage) { foreach ($stage['recovery_actions'] as $definition) { foreach ($definition['recorded_actions'] as $recorded) { if (!isset($actions[$recorded]) && !isset($reconcileActions[$recorded])) { throw new \LogicException( 'Recovery button references an unknown ledger action' ); } } } } } /** @return array|null */ private static function recoveryDefinition(string $action): ?array { self::assertIntegrity(); foreach (self::STAGES as $stageKey => $stage) { if (isset($stage['recovery_actions'][$action])) { return ['stage_key' => $stageKey] + $stage['recovery_actions'][$action]; } } return null; } private static function isRecordedRecoveryAction(string $action): bool { if ($action === '') { return false; } foreach (self::STAGES as $stage) { if ($stage['reconcile_action'] === $action) { return true; } foreach ($stage['recovery_actions'] as $definition) { if (in_array($action, $definition['recorded_actions'], true)) { return true; } } } return false; } private static function stageForStateOrRecovery( string $state, string $recoveryAction ): ?string { foreach (self::STAGES as $key => $stage) { if ($stage['running_state'] === $state) { return $key; } if ($state === 'attention_required') { if ($stage['reconcile_action'] === $recoveryAction) { return $key; } foreach ($stage['recovery_actions'] as $definition) { if (in_array($recoveryAction, $definition['recorded_actions'], true)) { return $key; } } } } if ($state === 'source_retained' || $state === 'completed') { return 'cleanup'; } if ($state === 'rolled_back') { return 'rollback'; } return null; } private static function stageWasSkipped( CloudInstanceMigration $migration, string $stageKey ): bool { if ($stageKey === 'vpc_target') { return $migration->vpc_port_id === null; } if ($stageKey === 'firewall') { return $migration->firewall_job_id === null; } return false; } private static function stepStatusLabel(string $status): string { return match ($status) { 'completed' => '已完成', 'running' => '执行中', 'skipped' => '已跳过', 'attention_required' => '需要处理', 'available' => '可手动清理', 'interrupted' => '已中止', default => '等待中', }; } /** @param array{key:string,label:string,index:int|null}|null $stage */ private static function progressLabel( string $status, ?array $stage ): string { return match ($status) { 'completed' => '迁移已完成', 'rolled_back' => '迁移已中止,源实例已恢复', 'source_retained' => '目标已切换,源副本已保留', 'attention_required' => '迁移需要核对或人工处理', 'failed' => '迁移失败', default => $stage === null ? '迁移进行中' : '正在' . (string) $stage['label'], }; } }