['8', '9', '10'], 'Debian' => ['11', '12', '13'], 'Ubuntu' => ['20.04', '22.04', '24.04', '25.04', '25.10', '26.04'], 'CentOS Stream' => ['9', '10'], ]; private function actor($request, bool $write = false): array { $actor = $request->getAttribute('cloud_actor') ?? CloudAccess::actor(); if (!$actor['is_admin']) { throw new CloudError('需要管理员权限', 403); } if ($write) { CloudAccess::manage($actor); } return $actor; } private function host($id): CloudHost { $host = CloudHost::find($id); if ($host === null) { throw new CloudError('宿主机不存在', 404); } return $host; } public function scan($request, $response) { $actor = $this->actor($request, true); $body = CloudInput::object($request); CloudInput::only($body, ['host', 'port']); return $response->withJson((new CloudEngineClient())->request('POST', '/internal/v1/hosts/scan', $actor, $body)); } public function hosts($request, $response, $args = []) { $write = $request->getMethod() !== 'GET'; $actor = $this->actor($request, $write); $engine = new CloudEngineClient(); if (!$write && !isset($args['id'])) { return $response->withJson(['hosts' => CloudHost::orderBy('id')->get()->toArray()]); } if (!$write) { $host = $this->host($args['id']); return $response->withJson(array_merge($host->toArray(), $engine->host((int) $host->id, 'GET', 'host', $actor))); } $body = CloudInput::object($request, 131072); CloudInput::only($body, ['name', 'enabled', 'host', 'port', 'private_key', 'private_key_passphrase', 'host_key', 'confirmed_fingerprint', 'storage_pool', 'iso_pool', 'rescue_iso_pool', 'default_network', 'region', 'country_code', 'fabric_endpoint_ip', ]); $name = $body['name'] ?? ''; if (!is_string($name) || trim($name) === '' || mb_strlen($name) > 80) { throw new CloudError('宿主机名称需为 1 至 80 字符'); } $enabled = filter_var($body['enabled'] ?? true, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE); if ($enabled === null) { throw new CloudError('启用状态无效'); } $region = $body['region'] ?? ''; if (!is_string($region) || trim($region) === '' || mb_strlen(trim($region)) > 64) { throw new CloudError('宿主机位置标签需为 1 至 64 字符'); } $body['region'] = trim($region); $fabricEndpointIp = $body['fabric_endpoint_ip'] ?? ''; if (!is_string($fabricEndpointIp)) { throw new CloudError('Fabric 传输地址格式无效'); } $fabricEndpointIp = trim($fabricEndpointIp); if ($fabricEndpointIp !== '' && filter_var( $fabricEndpointIp, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4 ) === false) { throw new CloudError('Fabric 传输地址必须为 IPv4 地址'); } // This is an Engine-owned host setting, like the SSH address and // storage paths. An empty value deliberately asks the Engine to use // the literal IPv4 SSH host as the current public-underlay default. $body['fabric_endpoint_ip'] = $fabricEndpointIp; $countryCode = CloudCountryCatalog::normalize($body['country_code'] ?? null); $privateKey = $body['private_key'] ?? ''; if (!is_string($privateKey)) { throw new CloudError('SSH 私钥格式无效'); } $hasPrivateKey = trim($privateKey) !== ''; if (!$hasPrivateKey) { $body['private_key'] = ''; } unset($body['name'], $body['enabled'], $body['country_code']); $host = isset($args['id']) ? $this->host($args['id']) : new CloudHost(); if (!$host->exists && !$hasPrivateKey) { throw new CloudError('首次添加宿主机必须提供现有 SSH 私钥', 422); } if ($host->exists) { $engineHost = $engine->host( (int) $host->id, 'GET', 'host', $actor ); if (!$hasPrivateKey && ($engineHost['configured'] ?? false) !== true) { throw new CloudError('该宿主机尚未完成引擎配置,请重新粘贴现有 SSH 私钥', 422); } // Public pools have their own revisioned endpoint. Host edits do // not accept those fields, but the engine's legacy HostBody still // requires them to round-trip until compatibility fields retire. if (($engineHost['configured'] ?? false) === true) { $body['public_pool_cidr'] = (string) ( $engineHost['public_pool_cidr'] ?? '' ); $body['public_gateway'] = (string) ( $engineHost['public_gateway'] ?? '' ); $body['public_dns_servers'] = is_array( $engineHost['public_dns_servers'] ?? null ) ? array_values($engineHost['public_dns_servers']) : []; $body['public_reserved_ips'] = is_array( $engineHost['public_reserved_ips'] ?? null ) ? array_values($engineHost['public_reserved_ips']) : []; $body['public_vm_prefix'] = is_int( $engineHost['public_vm_prefix'] ?? null ) ? $engineHost['public_vm_prefix'] : null; } } if (!$host->exists) { $host->name = trim($name); $host->region = ''; $host->country_code = $countryCode; $host->enabled = false; $host->default_network = 'default'; $host->created_at = $host->updated_at = time(); $host->save(); } // Secrets only transit this request. They are exclusively encrypted/stored by the engine. $result = $engine->host((int) $host->id, 'PUT', 'host', $actor, $body); $host->name = trim($name); $host->region = (string) ($result['region'] ?? $body['region'] ?? ''); $host->country_code = $countryCode; $host->default_network = (string) ($result['default_network'] ?? $body['default_network'] ?? 'default'); $host->enabled = $enabled; $host->updated_at = time(); $host->save(); $warnings = is_array($result['warnings'] ?? null) ? $result['warnings'] : []; // Host registration is configuration-only. The panel owns all // schedulable capacity and IP ledger rows; saving a host never scans // or imports arbitrary guests from the hypervisor. return $response->withJson(array_merge($result, $host->toArray(), [ 'warnings' => array_values(array_filter($warnings)), ]), isset($args['id']) ? 200 : 201); } public function test($request, $response, $args) { $actor = $this->actor($request, true); $this->host($args['id']); $body = CloudInput::object($request, 131072); return $response->withJson((new CloudEngineClient())->host((int) $args['id'], 'POST', 'host/test', $actor, $body)); } public function hostScheduling($request, $response, $args) { $write = $request->getMethod() !== 'GET'; $this->actor($request, $write); $hostId = (int) $args['id']; if (!$write) { $result = CloudAdminHostSchedulingService::read($hostId); } else { $body = CloudInput::object($request); CloudInput::only($body, [ 'resource_pool_id', 'scheduler_state', 'configured_cpu_cores', 'configured_memory_mib', 'configured_disk_gib', 'safety_cpu_cores', 'safety_memory_mib', 'safety_disk_gib', 'max_instances', ]); $result = CloudAdminHostSchedulingService::save($hostId, $body); } return $response->withJson($result) ->withHeader('Cache-Control', 'no-store'); } public function userIsoSettings($request, $response) { $write = $request->getMethod() !== 'GET'; $this->actor($request, $write); if (!$write) { return $response->withJson(['enabled' => CloudUserIsoFeature::enabled()]); } $body = CloudInput::object($request); CloudInput::only($body, ['enabled']); $enabled = filter_var($body['enabled'] ?? null, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE); if ($enabled === null) { throw new CloudError('用户 ISO 开关状态无效'); } CloudUserIsoFeature::save($enabled); return $response->withJson(['enabled' => $enabled]); } public function templates($request, $response, $args = []) { $method = $request->getMethod(); $actor = $this->actor($request, $method !== 'GET'); $body = in_array($method, ['POST', 'PATCH', 'PUT'], true) ? CloudInput::object($request) : null; $kind = $args['kind']; if ($kind === 'cloud') { $templateId = isset($args['id']) ? CloudInput::template((string) $args['id']) : null; $templateCreatedAt = null; if ($method === 'DELETE') { $body = CloudInput::object($request); CloudInput::only($body, ['created_at']); $templateCreatedAt = $body['created_at'] ?? null; if (!is_int($templateCreatedAt) || $templateCreatedAt < 1) { throw new CloudError('云镜像版本无效,请刷新目录后重试'); } CloudTemplateDeletionService::begin( (string) $templateId, $templateCreatedAt ); } if ($body !== null) { unset($body['host_id']); if ($method === 'POST' && isset($body['sha256']) && is_string($body['sha256']) && trim($body['sha256']) === '') { unset($body['sha256']); } } $path = '/internal/v1/vm-templates'; if ($templateId !== null) { $path .= '/' . rawurlencode($templateId); } elseif ($method === 'POST') { $path .= '/import'; } if (isset($args['job_id'])) { $path .= '/import-jobs/' . rawurlencode($args['job_id']); } $engine = new CloudEngineClient(); $fullCatalogRead = $method === 'GET' && !isset($args['job_id']) && !isset($args['id']); try { if ($method === 'POST') { $result = CloudTemplateDeletionService::queueImport( static fn (): array => $engine->request( $method, $path, $actor, $body ) ); } elseif ($fullCatalogRead) { $result = CloudTemplateDeletionService::fetchAuthoritativeCatalog( static fn (): array => $engine->request( $method, $path, $actor, $body ), static function (array $catalog): void { CloudDeploymentPageService::rememberTemplateCatalog( $catalog ); } ); } else { $result = $engine->request( $method, $path, $actor, $body ); } } catch (CloudError $error) { if ($method === 'DELETE' && $templateId !== null && $templateCreatedAt !== null) { if ($error->httpStatus === 404 && $error->getMessage() === '云镜像模板不存在') { CloudTemplateDeletionService::complete( $templateId, $templateCreatedAt, static function () use ($templateId): void { CloudDeploymentPageService::forgetTemplate( $templateId ); } ); return $response->withJson([ 'deleted' => true, 'cache_cleanup_pending' => false, ]); } elseif ($error->httpStatus === 409 && $error->getMessage() === '云镜像版本已变化,请刷新后重试') { CloudTemplateDeletionService::cancel( $templateId, $templateCreatedAt ); } } throw $error; } if ($method === 'DELETE' && $templateId !== null) { CloudTemplateDeletionService::complete( $templateId, (int) $templateCreatedAt, static function () use ($templateId): void { CloudDeploymentPageService::forgetTemplate($templateId); } ); } elseif (is_array($result['template'] ?? null)) { CloudTemplateDeletionService::reactivateImportedTemplate( CloudInput::template($result['template']['id'] ?? ''), filter_var($result['template']['created_at'] ?? null, FILTER_VALIDATE_INT) ?: 0, static function () use ($result): void { CloudDeploymentPageService::rememberTemplate( $result['template'] ); } ); } return $response->withJson($result); } // Rescue ISOs remain deliberately scoped to one host and its separate // rescue directory. $query = $request->getQueryParams(); $hostId = filter_var($query['host_id'] ?? $body['host_id'] ?? null, FILTER_VALIDATE_INT); if (!$hostId) { throw new CloudError('请选择宿主机'); } $this->host($hostId); if ($body !== null) { unset($body['host_id']); } $resource = 'rescue-templates'; if (isset($args['id'])) { $resource .= '/' . rawurlencode($args['id']); } if (isset($args['job_id'])) { $resource .= '/import-jobs/' . rawurlencode($args['job_id']); } return $response->withJson((new CloudEngineClient())->host($hostId, $method, $resource, $actor, $body)); } public function rescueUpload($request, $response) { $actor = $this->actor($request, true); $query = $request->getQueryParams(); $hostId = filter_var($query['host_id'] ?? null, FILTER_VALIDATE_INT); $name = $query['name'] ?? ''; if (!$hostId || !is_string($name) || trim($name) === '' || mb_strlen($name) > 64) { throw new CloudError('请选择宿主机并填写救援模板名称'); } $this->host($hostId); if (strtolower(trim(explode(';', $request->getHeaderLine('Content-Type'))[0])) !== 'application/octet-stream') { throw new CloudError('请直接上传 ISO 文件内容'); } $temporary = tempnam(sys_get_temp_dir(), 'cloud-rescue-'); if ($temporary === false) { throw new CloudError('无法准备私有上传文件', 503); } chmod($temporary, 0600); $file = fopen($temporary, 'wb'); try { if ($file === false) { throw new CloudError('无法准备私有上传文件', 503); } $bytes = 0; $stream = $request->getBody(); while (!$stream->eof()) { $chunk = $stream->read(1048576); $bytes += strlen($chunk); if ($bytes > 8 * 1024 * 1024 * 1024) { throw new CloudError('救援 ISO 超过 8 GiB', 413); } if ($chunk === '' && !$stream->eof()) { throw new CloudError('上传中断'); } if (fwrite($file, $chunk) !== strlen($chunk)) { throw new CloudError('无法保存上传文件', 503); } } fclose($file); $file = null; if ($bytes < 32768) { throw new CloudError('ISO 文件内容无效'); } return $response->withJson((new CloudEngineClient())->upload('/internal/v1/hosts/' . $hostId . '/rescue-templates?name=' . rawurlencode(trim($name)), $actor, $temporary), 202); } finally { if (is_resource($file)) { fclose($file); } unlink($temporary); } } public function cloudTemplateUpload($request, $response) { $actor = $this->actor($request, true); $query = $request->getQueryParams(); $name = $query['name'] ?? ''; $family = $query['os_family'] ?? ''; $version = $query['os_version'] ?? ''; $filename = $query['filename'] ?? ''; if (!is_string($name) || preg_match('//u', $name) !== 1 || trim($name) === '' || mb_strlen(trim($name)) > 64 || preg_match('/[\x00-\x1F\x7F]/u', $name) === 1) { throw new CloudError('模板名称应为 1 至 64 个字符'); } if (!is_string($family) || !is_string($version) || !isset(self::CLOUD_IMAGE_VERSIONS[$family]) || !in_array($version, self::CLOUD_IMAGE_VERSIONS[$family], true)) { throw new CloudError('云镜像系统版本无效'); } if (!is_string($filename) || strlen($filename) > 255 || str_contains($filename, '/') || str_contains($filename, '\\') || preg_match('/[\x00-\x1F\x7F]/', $filename) === 1 || !str_ends_with(strtolower($filename), '.qcow2')) { throw new CloudError('请选择 .qcow2 云镜像文件'); } if (strtolower(trim(explode(';', $request->getHeaderLine('Content-Type'))[0])) !== 'application/octet-stream') { throw new CloudError('请直接上传 QCOW2 文件内容'); } $declaredSize = null; $contentLength = trim($request->getHeaderLine('Content-Length')); if ($contentLength !== '') { if (preg_match('/^[0-9]+$/D', $contentLength) !== 1) { throw new CloudError('云镜像上传长度无效'); } $declaredSize = (int) $contentLength; if ($declaredSize < self::CLOUD_IMAGE_UPLOAD_MIN_BYTES) { throw new CloudError('云镜像文件不能小于 1 MiB'); } if ($declaredSize > self::CLOUD_IMAGE_UPLOAD_MAX_BYTES) { throw new CloudError('云镜像超过 4 GiB 限制', 413); } } $temporary = tempnam(sys_get_temp_dir(), 'cloud-template-'); if ($temporary === false || !chmod($temporary, 0600)) { if (is_string($temporary)) { @unlink($temporary); } throw new CloudError('无法准备私有上传文件', 503); } $file = fopen($temporary, 'wb'); try { if ($file === false) { throw new CloudError('无法准备私有上传文件', 503); } $bytes = 0; $stream = $request->getBody(); while (!$stream->eof()) { $chunk = $stream->read(1048576); if ($chunk === '' && !$stream->eof()) { throw new CloudError('云镜像上传中断'); } $bytes += strlen($chunk); if ($bytes > self::CLOUD_IMAGE_UPLOAD_MAX_BYTES) { throw new CloudError('云镜像超过 4 GiB 限制', 413); } $length = strlen($chunk); for ($offset = 0; $offset < $length;) { $written = fwrite($file, substr($chunk, $offset)); if ($written === false || $written === 0) { throw new CloudError('无法保存上传文件', 503); } $offset += $written; } } if ($bytes < self::CLOUD_IMAGE_UPLOAD_MIN_BYTES) { throw new CloudError('云镜像文件不能小于 1 MiB'); } if ($declaredSize !== null && $bytes !== $declaredSize) { throw new CloudError('云镜像上传内容不完整'); } if (!fflush($file) || (function_exists('fsync') && !fsync($file))) { throw new CloudError('无法保存上传文件', 503); } fclose($file); $file = null; $path = '/internal/v1/vm-templates/upload?name=' . rawurlencode(trim($name)) . '&os_family=' . rawurlencode($family) . '&os_version=' . rawurlencode($version); $engine = new CloudEngineClient(); $result = CloudTemplateDeletionService::queueImport( static fn (): array => $engine->upload($path, $actor, $temporary), 'upload' ); return $response->withJson($result, 202); } finally { if (is_resource($file)) { fclose($file); } @unlink($temporary); } } }