You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/web/app/Services/Cloud/CloudAgentSettingsService.php

741 lines
29 KiB
PHP

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

<?php
namespace App\Services\Cloud;
use App\Models\CloudHost;
use App\Models\CloudHostAgent;
use App\Models\CloudHostStorageConfiguration;
final class CloudAgentSettingsService
{
private const MAX_NETWORK_SELECTORS = 64;
private const PUBLIC_NETWORK_CONTRACT = 1;
private const REQUIRED_FEATURES = [
'create_vm', 'delete_vm', 'power', 'resources', 'settings', 'network',
'reinstall', 'snapshots', 'backups', 'firewall', 'rescue', 'metrics',
'console', 'templates', 'user_iso',
];
/** Hosts that may receive catalog replicas or VM operations. */
public static function enabledHostIds(): array
{
return CloudHostAgent::query()
->join('cloud_hosts', 'cloud_hosts.id', '=',
'cloud_host_agents.host_id')
->join('cloud_host_storage_configurations as host_storage',
'host_storage.host_id', '=', 'cloud_host_agents.host_id')
->where('cloud_host_agents.enabled', 1)
->where('cloud_host_agents.last_test_status', 'healthy')
->where('cloud_host_agents.tested_revision', '>', 0)
->whereColumn('cloud_host_agents.tested_revision',
'cloud_host_agents.revision')
->where('host_storage.state', 'applied')
->where('cloud_hosts.enabled', 1)
->orderBy('cloud_host_agents.host_id')
->pluck('cloud_host_agents.host_id')->map(
static fn ($id): int => (int) $id
)->all();
}
public static function listing(): array
{
$hosts = CloudAdminHostProjectionService::listing();
$agents = [];
$byHost = [];
foreach ($hosts['hosts'] as $host) {
$agent = self::projectedDto($host);
$agents[] = $agent;
$byHost[(int) $agent['host_id']] = $agent;
}
$regions = [];
foreach ($hosts['regions'] as $region) {
$group = [
'id' => $region['id'],
'code' => $region['code'],
'name' => $region['name'],
'status' => $region['status'],
'sort' => $region['sort'],
'country_code' => $region['country_code'],
'country_name' => $region['country_name'],
'country_flag' => $region['country_flag'],
'summary' => self::emptyAgentSummary(),
'agents' => [],
];
foreach ($region['hosts'] as $host) {
$hostId = (int) ($host['id'] ?? 0);
if (!isset($byHost[$hostId])) {
continue;
}
$group['agents'][] = $byHost[$hostId];
self::addAgentToSummary($group['summary'], $byHost[$hostId]);
}
$regions[] = $group;
}
$summary = self::emptyAgentSummary() + ['regions_total' => 0];
$summary['regions_total'] = count(array_filter(
$regions,
static fn (array $region): bool => $region['id'] !== null
));
foreach ($agents as $agent) {
self::addAgentToSummary($summary, $agent);
}
return [
'summary' => $summary,
'regions' => $regions,
'agents' => $agents,
];
}
public static function read(int $hostId): array
{
$host = self::host($hostId);
return self::dto($host, CloudHostAgent::find($hostId),
CloudHostStorageConfiguration::find($hostId));
}
public static function save(int $hostId, array $input): array
{
CloudInput::only($input, [
'enabled', 'api_secret', 'expected_revision',
]);
$enabled = filter_var($input['enabled'] ?? null,
FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
$secret = $input['api_secret'] ?? '';
$expectedRevision = $input['expected_revision'] ?? null;
if ($enabled === null) {
throw new CloudError('Agent 启用状态无效');
}
if (!is_string($secret)) {
throw new CloudError('Agent API 密钥格式无效');
}
if ($secret !== '' && (strlen($secret) < 32 || strlen($secret) > 256
|| preg_match('/^[\x21-\x7e]+$/D', $secret) !== 1)) {
throw new CloudError('Agent API 密钥需为 32 至 256 位无空格可打印 ASCII 字符');
}
if (!is_int($expectedRevision) || $expectedRevision < 0) {
throw new CloudError('Agent 配置版本无效,请刷新页面后重试', 409);
}
$host = self::host($hostId);
$connection = (new CloudHostAgent())->getConnection();
$setting = $connection->transaction(static function () use (
$hostId, $enabled, $secret, $expectedRevision
): CloudHostAgent {
$setting = CloudHostAgent::query()->where('host_id', $hostId)
->lockForUpdate()->first();
$actualRevision = $setting === null ? 0 : (int) $setting->revision;
if ($actualRevision !== $expectedRevision) {
throw new CloudError('Agent 配置已被修改,请刷新页面后重试', 409);
}
$isNew = $setting === null;
if ($setting === null) {
if ($secret === '') {
throw new CloudError('首次保存 Agent 配置必须填写 API 密钥');
}
$setting = new CloudHostAgent();
$setting->host_id = $hostId;
$setting->created_at = time();
} elseif ($secret === '' && trim((string) $setting->sealed_api_secret) === '') {
throw new CloudError('启用 Agent 前必须配置 API 密钥');
}
$enabledChanged = $isNew
|| (bool) $setting->enabled !== $enabled;
$secretChanged = $secret !== '';
if (!$enabledChanged && !$secretChanged) {
return $setting;
}
$setting->enabled = $enabled;
if ($secret !== '') {
$setting->sealed_api_secret = CloudAgentSecretCipher::encrypt($secret, $hostId);
}
if ($enabled && trim((string) $setting->sealed_api_secret) === '') {
throw new CloudError('启用 Agent 前必须配置 API 密钥');
}
self::invalidateReadiness($setting);
return $setting;
});
return self::dto($host, $setting,
CloudHostStorageConfiguration::find($hostId));
}
public static function test(int $hostId, array $actor, array $input): array
{
CloudInput::only($input, ['expected_revision']);
$expectedRevision = $input['expected_revision'] ?? null;
if (!is_int($expectedRevision) || $expectedRevision < 1) {
throw new CloudError('Agent 配置版本无效,请刷新页面后重试', 409);
}
$host = self::host($hostId);
$setting = CloudHostAgent::find($hostId);
if ($setting === null || !(bool) $setting->enabled
|| trim((string) $setting->sealed_api_secret) === '') {
throw new CloudError('请先保存并启用宿主机 Agent 配置', 409);
}
if ((int) $setting->revision !== $expectedRevision) {
throw new CloudError('Agent 配置已被修改,请刷新页面后重试', 409);
}
try {
$health = self::client($setting)->request('GET', '/v1/health', $actor);
if (($health['status'] ?? null) !== 'ok'
|| ($health['service'] ?? null) !== 'virt-host-agent'
|| !is_string($health['version'] ?? null)
|| preg_match('/^[\x21-\x7e]{1,64}$/D', $health['version']) !== 1) {
throw new CloudAgentError('宿主机 Agent 健康响应格式无效', 502,
'agent_invalid_health', true, 200);
}
$capabilities = self::client($setting)->request(
'GET', '/v1/capabilities', $actor
);
$summary = self::capabilitySummary($capabilities);
self::recordTest($hostId, $expectedRevision, 'healthy', '',
$health['version'], $summary['network_selectors'],
$summary['public_network'], $summary['portable_restore']);
self::scheduleTemplateBackfill($hostId, $actor, 'agent_ready');
self::scheduleRescueBackfill($hostId, $actor, 'agent_ready');
$fresh = CloudHostAgent::find($hostId);
return self::dto($host, $fresh,
CloudHostStorageConfiguration::find($hostId)) + [
'health' => [
'status' => 'ok',
'service' => 'virt-host-agent',
'version' => $health['version'],
],
'capabilities' => $summary,
];
} catch (CloudAgentError $error) {
self::recordTest($hostId, $expectedRevision, 'unhealthy',
$error->agentCode, '', []);
throw $error;
}
}
/** Return bounded feature flags and panel network references, never host paths. */
private static function capabilitySummary(array $capabilities): array
{
$features = $capabilities['features'] ?? null;
$checks = $capabilities['checks'] ?? null;
$storageCheck = is_array($checks) && !array_is_list($checks)
? ($checks['storage_configuration'] ?? null) : null;
if (($capabilities['backend'] ?? null) !== 'libvirt'
|| !is_array($features) || array_is_list($features)
|| !is_array($storageCheck) || array_is_list($storageCheck)
|| !is_bool($storageCheck['available'] ?? null)
|| (array_key_exists('reason', $storageCheck)
&& (!is_string($storageCheck['reason'])
|| preg_match('/^[a-z][a-z0-9_]{0,63}$/D',
$storageCheck['reason']) !== 1))
) {
throw new CloudAgentError('宿主机 Agent 后端能力响应无效', 502,
'agent_invalid_capabilities', false, 200);
}
$selectors = self::networkSelectorsFromCapabilities($capabilities);
$publicNetwork = self::normalizePublicNetworkCapabilities(
$capabilities['public_network'] ?? null
);
$portableRestore = self::normalizePortableRestoreCompatibility(
$capabilities['portable_restore'] ?? null
);
$known = array_merge(self::REQUIRED_FEATURES,
['uefi', 'secure_boot']);
foreach ($known as $feature) {
if (!array_key_exists($feature, $features)
|| !is_bool($features[$feature])) {
throw new CloudAgentError('宿主机 Agent 能力响应缺少必要字段',
502, 'agent_invalid_capabilities', false, 200);
}
}
$missing = array_values(array_filter(
self::REQUIRED_FEATURES,
static fn (string $feature): bool => $features[$feature] !== true
));
if ($storageCheck['available'] !== true) {
throw new CloudAgentError(
'宿主机尚未完成存储目录注册,不能参与调度',
409, 'agent_storage_not_configured', false, 200
);
}
if ($features['uefi'] !== true
|| $features['secure_boot'] !== false || $missing !== []) {
$detail = $missing === [] ? '' : ':' . implode(', ', $missing);
throw new CloudAgentError(
'宿主机 Agent 未满足 Virt Cloud 必要能力' . $detail,
409, 'agent_capability_mismatch', false, 200
);
}
return [
'backend' => 'libvirt',
'uefi' => true,
'secure_boot' => false,
'storage_configuration' => true,
'network_selectors' => $selectors,
'public_network' => $publicNetwork,
'portable_restore' => $portableRestore,
'required_feature_count' => count(self::REQUIRED_FEATURES),
'available_features' => self::REQUIRED_FEATURES,
'unavailable_features' => [],
];
}
/** The caller holds the Agent row lock or is inserting it in a transaction. */
public static function invalidateReadiness(CloudHostAgent $setting): void
{
$setting->revision = (int) $setting->revision + 1;
$setting->tested_revision = 0;
$setting->last_test_status = 'never';
$setting->last_error_code = '';
$setting->last_agent_version = '';
$setting->network_selectors_json = '[]';
$setting->public_network_capabilities_json = '{}';
$setting->portable_restore_contract_json = '{}';
$setting->portable_restore_contract_sha256 = '';
$setting->last_tested_at = 0;
$setting->updated_at = time();
$setting->save();
}
public static function clientForHost(
int $hostId,
float $timeoutSeconds = 20.0
): CloudAgentClient
{
$setting = CloudHostAgent::find($hostId);
if ($setting === null || !(bool) $setting->enabled) {
throw new CloudAgentError('宿主机 Agent 尚未配置或未启用', 503,
'agent_not_configured', false);
}
if (!$setting->isReady()) {
throw new CloudAgentError(
'当前 Agent 配置版本尚未通过健康与能力测试',
503, 'agent_not_tested', false
);
}
if (CloudHost::find($hostId) === null) {
throw new CloudAgentError(
'宿主机不存在', 503, 'agent_not_configured', false
);
}
$storage = CloudHostStorageConfiguration::find($hostId);
if ($storage === null || !$storage->isApplied()) {
throw new CloudAgentError(
'宿主机尚未完成存储目录注册', 503,
'agent_storage_not_configured', false
);
}
return self::client($setting, $timeoutSeconds);
}
/**
* Storage bootstrap must be possible before the Agent has passed its
* capability probe. This client still requires an enabled registration
* and a valid sealed secret, but deliberately does not bypass any public
* HTTP authorization or expose an Agent address.
*/
public static function clientForConfiguration(
int $hostId,
float $timeoutSeconds = 120.0
): CloudAgentClient {
$setting = CloudHostAgent::find($hostId);
if ($setting === null || !(bool) $setting->enabled
|| trim((string) $setting->sealed_api_secret) === '') {
throw new CloudAgentError('请先保存并启用宿主机 Agent API 配置',
409, 'agent_not_configured', false);
}
return self::client($setting, $timeoutSeconds);
}
/**
* Read the Agent's current network candidates through the authenticated
* gateway. This is discovery evidence only; it does not make an Agent or
* attachment ready and is not persisted as a successful full test.
*/
public static function probeNetworkSelectors(
int $hostId,
array $actor,
bool $requireReady = false
): array {
self::host($hostId);
$before = CloudHostAgent::find($hostId);
if ($before === null) {
throw new CloudAgentError('宿主机 Agent 尚未配置', 409,
'agent_not_configured', false);
}
$revision = (int) $before->revision;
$testedRevision = (int) $before->tested_revision;
$client = $requireReady
? self::clientForHost($hostId)
: self::clientForConfiguration($hostId);
$capabilities = $client->request('GET', '/v1/capabilities', $actor);
$selectors = self::networkSelectorsFromCapabilities($capabilities);
$setting = CloudHostAgent::find($hostId);
if ($setting === null || (int) $setting->revision !== $revision
|| (int) $setting->tested_revision !== $testedRevision) {
throw new CloudError(
'Agent 配置或测试代数在网络发现期间已变化,请重试', 409
);
}
return [
'host_id' => $hostId,
'agent_revision' => $revision,
'tested_revision' => $testedRevision,
'network_selectors' => $selectors,
];
}
/** Exact, current-revision selector evidence persisted by a full test. */
public static function testedNetworkSelectors(
CloudHostAgent $setting
): array {
try {
return self::normalizeNetworkSelectors(
$setting->testedNetworkSelectors()
);
} catch (CloudAgentError) {
return [];
}
}
/** Current-revision proof for one selector's guarded dual-stack contract. */
public static function publicNetworkReady(
CloudHostAgent $setting,
string $selector,
int $verifiedRevision
): bool {
if (!$setting->isReady()
|| $verifiedRevision < 1
|| $verifiedRevision !== (int) $setting->revision
|| $verifiedRevision !== (int) $setting->tested_revision
|| !in_array(
$selector,
self::testedNetworkSelectors($setting),
true
)) {
return false;
}
try {
$decoded = json_decode(
(string) $setting->public_network_capabilities_json,
true,
8,
JSON_THROW_ON_ERROR
);
self::normalizePublicNetworkCapabilities($decoded);
return true;
} catch (\Throwable) {
return false;
}
}
private static function client(
CloudHostAgent $setting,
float $timeoutSeconds = 20.0
): CloudAgentClient
{
return new CloudAgentClient(
(string) $setting->host_id,
CloudAgentSecretCipher::decrypt(
(string) $setting->sealed_api_secret,
(int) $setting->host_id
),
null,
$timeoutSeconds
);
}
private static function recordTest(
int $hostId,
int $expectedRevision,
string $status,
string $errorCode,
string $version,
array $networkSelectors = [],
array $publicNetworkCapabilities = [],
array $portableRestoreCompatibility = []
): void {
$encodedSelectors = $status === 'healthy'
? json_encode(
self::normalizeNetworkSelectors($networkSelectors),
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
)
: '[]';
$encodedPublicNetwork = $status === 'healthy'
? json_encode(
self::normalizePublicNetworkCapabilities(
$publicNetworkCapabilities
),
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
)
: '{}';
$portableRestore = $status === 'healthy'
? CloudPortableRestoreCompatibility::fromPayload(
$portableRestoreCompatibility
) : null;
$updated = CloudHostAgent::query()->where('host_id', $hostId)
->where('revision', $expectedRevision)->update([
'last_test_status' => $status,
'tested_revision' => $status === 'healthy'
? $expectedRevision : 0,
'last_error_code' => substr($errorCode, 0, 64),
'last_agent_version' => substr($version, 0, 64),
'network_selectors_json' => $encodedSelectors,
'public_network_capabilities_json' => $encodedPublicNetwork,
'portable_restore_contract_json' => $portableRestore === null
? '{}' : $portableRestore->json(),
'portable_restore_contract_sha256' => $portableRestore === null
? '' : $portableRestore->sha256(),
'last_tested_at' => time(),
'updated_at' => time(),
]);
if ($updated !== 1) {
throw new CloudError('Agent 配置在测试期间已被修改,请刷新后重试', 409);
}
}
private static function networkSelectorsFromCapabilities(
array $capabilities
): array {
return self::normalizeNetworkSelectors(
$capabilities['network_selectors'] ?? null
);
}
/** Persist only the four security properties consumed by placement. */
private static function normalizePublicNetworkCapabilities(
mixed $value
): array {
if (!is_array($value) || array_is_list($value)
|| ($value['contract'] ?? null) !== self::PUBLIC_NETWORK_CONTRACT
|| ($value['dual_stack_required'] ?? null) !== true
|| ($value['project_owned_filter'] ?? null) !== true
|| ($value['ndp_guard'] ?? null) !== true) {
throw new CloudAgentError(
'宿主机 Agent 未满足双栈公网网络安全合同',
409,
'agent_capability_mismatch',
false,
200
);
}
return [
'contract' => self::PUBLIC_NETWORK_CONTRACT,
'dual_stack_required' => true,
'project_owned_filter' => true,
'ndp_guard' => true,
];
}
private static function normalizePortableRestoreCompatibility(
mixed $value
): array {
try {
return CloudPortableRestoreCompatibility::fromPayload(
$value
)->toArray();
} catch (\InvalidArgumentException) {
throw new CloudAgentError(
'宿主机 Agent 未满足可移植恢复平台合同',
409,
'agent_capability_mismatch',
false,
200
);
}
}
private static function normalizeNetworkSelectors(mixed $selectors): array
{
if (!is_array($selectors) || !array_is_list($selectors)
|| $selectors === []
|| count($selectors) > self::MAX_NETWORK_SELECTORS) {
throw new CloudAgentError('宿主机 Agent 网络选择器响应无效',
502, 'agent_invalid_capabilities', false, 200);
}
$previous = null;
foreach ($selectors as $selector) {
if (!CloudNetworkSelector::isValid($selector)
|| ($previous !== null && strcmp($previous, $selector) >= 0)) {
throw new CloudAgentError('宿主机 Agent 网络选择器响应无效',
502, 'agent_invalid_capabilities', false, 200);
}
$previous = $selector;
}
return $selectors;
}
/** A completed health test must not be rolled back by optional backfill. */
private static function scheduleTemplateBackfill(
int $hostId,
array $actor,
string $reason
): void {
try {
CloudTemplateHostBackfillService::scheduleReadyHost(
$hostId,
$actor,
$reason
);
} catch (\Throwable $error) {
error_log(sprintf(
'cloud template backfill host=%d trigger=%s unavailable: %s',
$hostId,
$reason,
get_class($error)
));
}
}
private static function scheduleRescueBackfill(
int $hostId,
array $actor,
string $reason
): void {
try {
CloudRescueTemplateHostBackfillService::scheduleReadyHost(
$hostId,
$actor,
$reason
);
} catch (\Throwable $error) {
error_log(sprintf(
'cloud rescue backfill host=%d trigger=%s unavailable: %s',
$hostId,
$reason,
get_class($error)
));
}
}
private static function host(int $hostId): CloudHost
{
if ($hostId < 1 || ($host = CloudHost::find($hostId)) === null) {
throw new CloudError('宿主机不存在', 404);
}
return $host;
}
private static function dto(CloudHost $host, ?CloudHostAgent $setting,
?CloudHostStorageConfiguration $storage = null): array
{
$ready = $setting !== null && $setting->isReady()
&& $storage !== null && $storage->isApplied();
return self::withStatus([
'host_id' => (int) $host->id,
'host_name' => (string) $host->name,
'region' => (string) $host->region,
'country_code' => (string) $host->country_code,
'host_enabled' => (bool) $host->enabled,
'agent_id' => (string) $host->id,
'ready' => $ready,
'storage_configured' => $storage !== null
&& $storage->isApplied(),
] + self::settingFields($setting));
}
private static function projectedDto(array $host): array
{
$agent = is_array($host['agent'] ?? null) ? $host['agent'] : [];
$readiness = is_array($host['readiness'] ?? null)
? $host['readiness'] : [];
$ready = ($agent['ready'] ?? false) === true
&& ($readiness['network_selector_ready'] ?? false) === true
&& ($readiness['storage_ready'] ?? false) === true;
return self::withStatus([
'host_id' => (int) ($host['id'] ?? 0),
'host_name' => (string) ($host['name'] ?? ''),
'region' => (string) ($host['region'] ?? ''),
'country_code' => (string) ($host['country_code'] ?? ''),
'host_enabled' => ($host['enabled'] ?? false) === true,
'scheduler_state' => (string) ($host['scheduler_state']
?? 'disabled'),
'placement' => is_array($host['placement'] ?? null)
? $host['placement'] : [],
'location' => is_array($host['location'] ?? null)
? $host['location'] : [],
'agent_id' => (string) ($host['id'] ?? ''),
'enabled' => ($agent['enabled'] ?? false) === true,
'secret_configured' =>
($agent['secret_configured'] ?? false) === true,
'revision' => (int) ($agent['revision'] ?? 0),
'tested_revision' => (int) ($agent['tested_revision'] ?? 0),
'ready' => $ready,
'storage_configured' =>
($readiness['storage_ready'] ?? false) === true,
'last_test_status' => (string) ($agent['last_test_status']
?? 'never'),
'last_error_code' => (string) ($agent['last_error_code'] ?? ''),
'last_agent_version' => (string) ($agent['version'] ?? ''),
'last_tested_at' => (int) ($agent['last_tested_at'] ?? 0),
'updated_at' => (int) ($agent['updated_at'] ?? 0),
]);
}
private static function settingFields(?CloudHostAgent $setting): array
{
return [
'enabled' => $setting !== null && (bool) $setting->enabled,
'secret_configured' => $setting !== null
&& trim((string) $setting->sealed_api_secret) !== '',
'revision' => $setting === null ? 0 : (int) $setting->revision,
'tested_revision' => $setting === null
? 0 : (int) $setting->tested_revision,
'last_test_status' => $setting === null
? 'never' : (string) $setting->last_test_status,
'last_error_code' => $setting === null
? '' : (string) $setting->last_error_code,
'last_agent_version' => $setting === null
? '' : (string) $setting->last_agent_version,
'last_tested_at' => $setting === null
? 0 : (int) $setting->last_tested_at,
'updated_at' => $setting === null ? 0 : (int) $setting->updated_at,
];
}
private static function withStatus(array $agent): array
{
if (!($agent['secret_configured'] ?? false)) {
$status = 'unconfigured';
} elseif (!($agent['enabled'] ?? false)) {
$status = 'disabled';
} elseif (($agent['ready'] ?? false) === true) {
$status = 'ready';
} elseif (($agent['last_test_status'] ?? '') === 'unhealthy') {
$status = 'failed';
} else {
$status = 'pending';
}
$agent['status'] = $status;
$agent['needs_attention'] = in_array(
$status, ['unconfigured', 'pending', 'failed'], true
);
return $agent;
}
private static function emptyAgentSummary(): array
{
return [
'agents_total' => 0,
'ready_agents' => 0,
'pending_agents' => 0,
'failed_agents' => 0,
'unconfigured_agents' => 0,
'disabled_agents' => 0,
'attention_agents' => 0,
];
}
private static function addAgentToSummary(array &$summary,
array $agent): void
{
$status = (string) ($agent['status'] ?? 'unconfigured');
$key = $status . '_agents';
$summary['agents_total']++;
if (array_key_exists($key, $summary)) {
$summary[$key]++;
}
$summary['attention_agents'] +=
($agent['needs_attention'] ?? false) ? 1 : 0;
}
}