clock = $clock ?? time(...); } protected static function lockIntent(string $id): CloudTemplateImportIntent { $intent = CloudTemplateImportIntent::query() ->where('id', $id)->lockForUpdate()->first(); if ($intent === null) { throw new CloudError('云镜像导入记录不存在', 404); } return $intent; } protected static function requestKey(array $actor): string { $key = $actor['request_idempotency_key'] ?? null; if (!is_string($key) || preg_match('/^[A-Za-z0-9_.-]{16,128}$/D', $key) !== 1) { throw new CloudError('请求幂等标识无效', 400); } return $key; } protected static function fingerprint(array $canonical): string { ksort($canonical, SORT_STRING); return hash('sha256', json_encode( $canonical, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE )); } protected static function remoteSource( CloudTemplateImportIntent $intent ): array { $source = CloudSecrets::decrypt( (string) $intent->sealed_source, self::SOURCE_PURPOSE ); if (($source['kind'] ?? null) !== 'remote' || !is_string($source['url'] ?? null) || !is_string($source['expected_sha256'] ?? null)) { throw new CloudError('远程云镜像来源账本无效', 503); } $url = self::remoteUrl($source['url']); $sha256 = strtolower(trim($source['expected_sha256'])); if ($sha256 !== '' && preg_match('/^[a-f0-9]{64}$/D', $sha256) !== 1) { throw new CloudError('远程云镜像来源账本无效', 503); } return ['url' => $url, 'expected_sha256' => $sha256]; } protected static function remoteUrl($value): string { if (!is_string($value) || strlen($value) > 2048 || preg_match('//u', $value) !== 1) { throw new CloudError('云镜像地址无效'); } $value = trim($value); $parts = parse_url($value); if (!is_array($parts) || strtolower((string) ($parts['scheme'] ?? '')) !== 'https' || !is_string($parts['host'] ?? null) || $parts['host'] === '' || isset($parts['user']) || isset($parts['pass']) || isset($parts['fragment']) || (isset($parts['port']) && (int) $parts['port'] !== 443) || !str_ends_with(strtolower((string) ($parts['path'] ?? '')), '.qcow2')) { throw new CloudError( '请填写无需账号、使用 443 端口的 HTTPS 镜像直链' ); } return $value; } protected static function inferRemoteSystem( string $url, string $name ): array { $haystack = strtolower($url . ' ' . $name); $families = [ 'AlmaLinux' => ['almalinux', ['10', '9', '8']], 'Debian' => ['debian', ['13', '12', '11']], 'Ubuntu' => ['ubuntu', ['26.04', '25.10', '25.04', '24.04', '22.04', '20.04']], 'CentOS Stream' => ['centos', ['10', '9']], ]; foreach ($families as $family => [$needle, $versions]) { if (!str_contains($haystack, $needle)) { continue; } foreach ($versions as $version) { if (preg_match('/(?:^|[^0-9])' . preg_quote($version, '/') . '(?:[^0-9]|$)/', $haystack) === 1) { return [$family, $version]; } } } throw new CloudError( '无法从名称或官方地址识别受支持的系统版本' ); } protected static function remoteFilename(string $url): string { $path = parse_url($url, PHP_URL_PATH); $filename = is_string($path) ? basename($path) : ''; if ($filename === '' || strlen($filename) > 255 || preg_match('/\.qcow2$/iD', $filename) !== 1) { throw new CloudError('官方云镜像文件名无效', 422); } return $filename; } protected static function filename($value): string { if (!is_string($value) || strlen($value) > 255 || str_contains($value, "\0") || preg_match('/\.qcow2$/iD', $value) !== 1) { throw new CloudError('请选择扩展名为 .qcow2 的云镜像文件'); } return $value; } protected static function label($value, string $label, int $maximum): string { if (!is_string($value) || preg_match('//u', $value) !== 1) { throw new CloudError($label . '无效'); } $value = trim($value); if ($value === '' || mb_strlen($value, 'UTF-8') > $maximum || preg_match('/[\x00-\x1f\x7f]/u', $value) === 1) { throw new CloudError($label . '无效'); } return $value; } protected static function integer( $value, int $minimum, int $maximum, string $message ): int { $integer = filter_var($value, FILTER_VALIDATE_INT, [ 'options' => ['min_range' => $minimum, 'max_range' => $maximum], ]); if ($integer === false) { throw new CloudError($message, 422); } return (int) $integer; } protected static function newTemplateId(string $family, string $version): string { $prefix = strtolower(preg_replace('/[^A-Za-z0-9]+/', '-', $family . '-' . $version) ?? 'image'); return substr(trim($prefix, '-'), 0, 55) . '-' . bin2hex(random_bytes(8)); } protected static function catalogKey(string $family, string $version): string { $key = strtolower(preg_replace('/[^A-Za-z0-9]+/', '-', $family . '-' . $version) ?? 'image'); $key = trim($key, '-'); if ($key === '' || strlen($key) > 80) { throw new CloudError('云镜像目录标识无效', 422); } return $key; } }