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/CloudObjectStorageConfig.php

542 lines
21 KiB
PHTML

<?php
namespace App\Services\Cloud;
use App\Models\Configurations;
/** PHP-owned global S3-compatible object-storage application settings. */
final class CloudObjectStorageConfig
{
private const PREFIX = 'cloud_object_storage_';
private const CREDENTIAL_PURPOSE = 'object-storage-credentials';
private const DEFAULTS = [
'name' => '默认对象存储',
'driver' => 's3',
'endpoint' => '',
'region' => 'us-east-1',
'bucket' => '',
'prefix' => 'virt-cloud',
'path_style' => 'true',
'enabled' => 'false',
'revision' => '0',
'tested_revision' => '0',
'last_test_status' => 'never',
'last_error_code' => '',
'last_tested_at' => '0',
'sealed_credentials' => '',
];
/** @return array<string, mixed> */
public static function view(): array
{
return self::publicState(self::readRaw());
}
/** @return array<string, mixed> */
public static function save(array $input): array
{
CloudInput::only($input, [
'name', 'endpoint', 'region', 'bucket', 'prefix', 'path_style',
'access_key_id', 'secret_access_key', 'expected_revision',
]);
$expected = self::revision($input['expected_revision'] ?? null, true);
$name = self::name($input['name'] ?? '');
$endpoint = self::endpoint($input['endpoint'] ?? '');
$region = self::region($input['region'] ?? '');
$bucket = self::bucket($input['bucket'] ?? '');
$prefix = self::objectPrefix($input['prefix'] ?? '');
$pathStyle = self::boolean($input['path_style'] ?? null, '请选择 S3 寻址方式');
if (!$pathStyle && self::endpointHostIsIp($endpoint)) {
throw new CloudError('IP 地址 Endpoint 只能使用路径寻址');
}
$accessKeyId = is_string($input['access_key_id'] ?? null)
? trim($input['access_key_id']) : '';
$secretAccessKey = is_string($input['secret_access_key'] ?? null)
? $input['secret_access_key'] : '';
if (($accessKeyId === '') !== ($secretAccessKey === '')) {
throw new CloudError('Access Key ID 和 Secret Access Key 必须同时填写');
}
$newCipher = null;
if ($accessKeyId !== '') {
self::assertCredentials($accessKeyId, $secretAccessKey);
$newCipher = CloudSecrets::encrypt([
'access_key_id' => $accessKeyId,
'secret_access_key' => $secretAccessKey,
], self::CREDENTIAL_PURPOSE);
}
self::ensureRow('revision', '0');
$connection = (new Configurations())->getConnection();
$connection->transaction(static function () use (
$expected,
$name,
$endpoint,
$region,
$bucket,
$prefix,
$pathStyle,
$newCipher
): void {
$revisionRow = Configurations::where('name', self::key('revision'))
->lockForUpdate()->firstOrFail();
$actual = (int) $revisionRow->value;
if ($actual !== $expected) {
throw new CloudError('对象存储配置已被修改,请刷新页面后重试', 409);
}
$rows = self::readRaw();
$cipher = trim((string) $rows['sealed_credentials']);
if ($newCipher !== null) {
$cipher = $newCipher;
} elseif ($cipher !== '') {
self::credentials($cipher);
}
if ($cipher === '') {
throw new CloudError('首次保存对象存储必须填写 Access Key 和 Secret Key');
}
self::set('name', $name);
self::set('driver', 's3');
self::set('endpoint', $endpoint);
self::set('region', $region);
self::set('bucket', $bucket);
self::set('prefix', $prefix);
self::set('path_style', $pathStyle ? 'true' : 'false');
self::set('sealed_credentials', $cipher);
self::set('revision', (string) ($actual + 1));
self::invalidateReadiness();
});
return self::view();
}
/** @return array<string, mixed> */
public static function testAndEnable(
$expectedRevision,
?CloudObjectStorageS3Client $client = null
): array {
$expected = self::revision($expectedRevision, false);
$raw = self::readRaw();
if ((int) $raw['revision'] !== $expected) {
throw new CloudError('对象存储配置已被修改,请刷新页面后重试', 409);
}
$runtime = self::runtimeFromRaw($raw);
try {
($client ?? new CloudObjectStorageS3Client())->headBucket(
$runtime['config'],
$runtime['credentials']
);
} catch (CloudObjectStorageTestError $exception) {
self::recordTestFailure($expected, $exception->publicCode);
throw new CloudError($exception->getMessage(), 502);
}
$connection = (new Configurations())->getConnection();
$connection->transaction(static function () use ($expected): void {
$revisionRow = Configurations::where('name', self::key('revision'))
->lockForUpdate()->firstOrFail();
if ((int) $revisionRow->value !== $expected) {
throw new CloudError('连接测试期间配置已改变,请重新测试', 409);
}
self::set('enabled', 'true');
self::set('tested_revision', (string) $expected);
self::set('last_test_status', 'healthy');
self::set('last_error_code', '');
self::set('last_tested_at', (string) time());
});
return self::view();
}
/** @return array<string, mixed> */
public static function disable($expectedRevision): array
{
$expected = self::revision($expectedRevision, false);
self::ensureRow('revision', '0');
$connection = (new Configurations())->getConnection();
$connection->transaction(static function () use ($expected): void {
$revisionRow = Configurations::where('name', self::key('revision'))
->lockForUpdate()->firstOrFail();
if ((int) $revisionRow->value !== $expected) {
throw new CloudError('对象存储配置已被修改,请刷新页面后重试', 409);
}
self::set('revision', (string) ($expected + 1));
self::set('enabled', 'false');
self::set('tested_revision', '0');
self::set('last_test_status', 'disabled');
self::set('last_error_code', '');
self::set('last_tested_at', '0');
});
return self::view();
}
/**
* Future backup services consume this server-side method. It is deliberately
* absent from controller responses so credentials cannot reach a browser.
*
* @return array{config:array<string,mixed>,credentials:array{access_key_id:string,secret_access_key:string},revision:int}
*/
public static function runtime(bool $requireReady = true): array
{
$raw = self::readRaw();
if ($requireReady && !self::isReady($raw)) {
throw new CloudError('对象存储尚未通过当前配置的连接验证', 503);
}
return self::runtimeFromRaw($raw);
}
/** @return array<string, mixed> */
private static function readRaw(): array
{
$raw = self::DEFAULTS;
$names = array_map(self::key(...), array_keys(self::DEFAULTS));
$rows = Configurations::whereIn('name', $names)->get();
foreach ($rows as $row) {
$name = (string) $row->name;
if (!str_starts_with($name, self::PREFIX)) {
continue;
}
$short = substr($name, strlen(self::PREFIX));
if (array_key_exists($short, $raw)) {
$raw[$short] = (string) $row->value;
}
}
return $raw;
}
/** @param array<string, mixed> $raw */
private static function publicState(array $raw): array
{
$status = in_array($raw['last_test_status'], ['never', 'healthy', 'failed', 'disabled'], true)
? $raw['last_test_status'] : 'never';
$credentialsConfigured = trim((string) $raw['sealed_credentials']) !== '';
$ready = self::isReady($raw);
$labels = [
'never' => $credentialsConfigured ? '等待验证' : '未配置',
'healthy' => $ready ? '已启用' : '已停用',
'failed' => '验证失败',
'disabled' => '已停用',
];
$errors = [
'endpoint_unreachable' => '无法连接 Endpoint,请检查证书、DNS 和防火墙。',
'region_mismatch' => 'Bucket 区域不匹配。',
'auth_or_permission_denied' => '凭据或 s3:ListBucket 权限验证失败。',
'bucket_not_found' => 'Bucket 不存在或不可访问。',
'rate_limited' => '对象存储暂时限制请求。',
'service_unavailable' => '对象存储服务暂时不可用。',
'request_rejected' => '对象存储拒绝兼容性检查。',
];
$errorCode = (string) $raw['last_error_code'];
$lastTestedAt = max(0, (int) $raw['last_tested_at']);
return [
'name' => (string) $raw['name'],
'driver' => 's3',
'endpoint' => (string) $raw['endpoint'],
'region' => (string) $raw['region'],
'bucket' => (string) $raw['bucket'],
'prefix' => (string) $raw['prefix'],
'path_style' => self::truthy($raw['path_style']),
'enabled' => self::truthy($raw['enabled']),
'ready' => $ready,
'configured' => (string) $raw['endpoint'] !== ''
&& (string) $raw['bucket'] !== '' && $credentialsConfigured,
'credentials_configured' => $credentialsConfigured,
'revision' => max(0, (int) $raw['revision']),
'tested_revision' => max(0, (int) $raw['tested_revision']),
'last_test_status' => $status,
'last_error_code' => $errorCode,
'last_error' => $errors[$errorCode] ?? '',
'last_tested_at' => $lastTestedAt,
'last_tested_at_text' => $lastTestedAt > 0
? date('Y-m-d H:i:s', $lastTestedAt) : '',
'status_label' => $labels[$status],
'status_class' => $ready ? 'success'
: ($status === 'failed' ? 'danger' : 'secondary'),
];
}
/**
* @param array<string, mixed> $raw
* @return array{config:array<string,mixed>,credentials:array{access_key_id:string,secret_access_key:string},revision:int}
*/
private static function runtimeFromRaw(array $raw): array
{
$config = [
'endpoint' => self::endpoint($raw['endpoint']),
'region' => self::region($raw['region']),
'bucket' => self::bucket($raw['bucket']),
'prefix' => self::objectPrefix($raw['prefix']),
'path_style' => self::truthy($raw['path_style']),
];
if (!$config['path_style'] && self::endpointHostIsIp($config['endpoint'])) {
throw new CloudError('IP 地址 Endpoint 只能使用路径寻址');
}
$cipher = trim((string) $raw['sealed_credentials']);
if ($cipher === '') {
throw new CloudError('对象存储访问凭据尚未配置', 503);
}
return [
'config' => $config,
'credentials' => self::credentials($cipher),
'revision' => max(0, (int) ($raw['revision'] ?? 0)),
];
}
/** @return array{access_key_id:string,secret_access_key:string} */
private static function credentials(string $cipher): array
{
$credentials = CloudSecrets::decrypt($cipher, self::CREDENTIAL_PURPOSE);
$access = $credentials['access_key_id'] ?? null;
$secret = $credentials['secret_access_key'] ?? null;
if (!is_string($access) || !is_string($secret)) {
throw new CloudError('对象存储访问凭据内容无效', 503);
}
self::assertCredentials($access, $secret);
return ['access_key_id' => $access, 'secret_access_key' => $secret];
}
private static function recordTestFailure(int $expected, string $code): void
{
$connection = (new Configurations())->getConnection();
$connection->transaction(static function () use ($expected, $code): void {
$revisionRow = Configurations::where('name', self::key('revision'))
->lockForUpdate()->firstOrFail();
if ((int) $revisionRow->value !== $expected) {
throw new CloudError('连接测试期间配置已改变,请重新测试', 409);
}
self::set('enabled', 'false');
self::set('tested_revision', '0');
self::set('last_test_status', 'failed');
self::set('last_error_code', $code);
self::set('last_tested_at', (string) time());
});
}
private static function invalidateReadiness(): void
{
self::set('enabled', 'false');
self::set('tested_revision', '0');
self::set('last_test_status', 'never');
self::set('last_error_code', '');
self::set('last_tested_at', '0');
}
/** @param array<string, mixed> $raw */
private static function isReady(array $raw): bool
{
$revision = (int) $raw['revision'];
return $revision > 0
&& self::truthy($raw['enabled'])
&& (string) $raw['last_test_status'] === 'healthy'
&& (int) $raw['tested_revision'] === $revision
&& trim((string) $raw['sealed_credentials']) !== '';
}
private static function name($value): string
{
if (!is_string($value)) {
throw new CloudError('对象存储名称格式无效');
}
$value = trim($value);
if ($value === '' || mb_strlen($value, 'UTF-8') > 80
|| preg_match('//u', $value) !== 1
|| preg_match('/[\x00-\x1F\x7F]/u', $value) === 1) {
throw new CloudError('对象存储名称需为 1 至 80 个字符且不能包含控制字符');
}
return $value;
}
private static function endpoint($value): string
{
if (!is_string($value)) {
throw new CloudError('Endpoint 格式无效');
}
$value = trim($value);
$parts = parse_url($value);
if (!is_array($parts) || strtolower((string) ($parts['scheme'] ?? '')) !== 'https'
|| !isset($parts['host']) || isset($parts['user']) || isset($parts['pass'])
|| isset($parts['query']) || isset($parts['fragment'])
|| !in_array((string) ($parts['path'] ?? ''), ['', '/'], true)) {
throw new CloudError('Endpoint 必须是仅包含主机和可选端口的 HTTPS 地址');
}
$host = strtolower(trim((string) $parts['host'], '[]'));
if ($host === '' || $host === 'localhost' || str_ends_with($host, '.localhost')) {
throw new CloudError('Endpoint 主机无效');
}
if (filter_var($host, FILTER_VALIDATE_IP)) {
if (self::blockedEndpointIp($host)) {
throw new CloudError('Endpoint 不能使用回环、链路本地、未指定或组播地址');
}
} else {
if (preg_match('/^[0-9.]+$/D', $host) === 1) {
throw new CloudError('Endpoint IP 地址格式无效');
}
if (strlen($host) > 253 || str_ends_with($host, '.')) {
throw new CloudError('Endpoint 主机名无效');
}
foreach (explode('.', $host) as $label) {
if (preg_match('/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/D', $label) !== 1) {
throw new CloudError('Endpoint 主机名无效');
}
}
}
$port = isset($parts['port']) ? (int) $parts['port'] : 443;
if ($port < 1 || $port > 65535) {
throw new CloudError('Endpoint 端口必须为 1 至 65535');
}
$authority = str_contains($host, ':') ? '[' . $host . ']' : $host;
if ($port !== 443) {
$authority .= ':' . $port;
}
return 'https://' . $authority;
}
private static function endpointHostIsIp(string $endpoint): bool
{
$host = parse_url($endpoint, PHP_URL_HOST);
return is_string($host)
&& filter_var(trim($host, '[]'), FILTER_VALIDATE_IP) !== false;
}
private static function blockedEndpointIp(string $host): bool
{
$packed = inet_pton($host);
if ($packed === false) {
return true;
}
if (strlen($packed) === 4) {
$octets = array_values(unpack('C4', $packed));
return $octets[0] === 0 || $octets[0] === 127
|| ($octets[0] === 169 && $octets[1] === 254)
|| $octets[0] >= 224;
}
$bytes = array_values(unpack('C16', $packed));
return $host === '::' || $host === '::1' || $bytes[0] === 0xff
|| ($bytes[0] === 0xfe && ($bytes[1] & 0xc0) === 0x80);
}
private static function region($value): string
{
if (!is_string($value)) {
throw new CloudError('Region 格式无效');
}
$value = strtolower(trim($value));
if (preg_match('/^[a-z0-9][a-z0-9-]{0,62}$/D', $value) !== 1) {
throw new CloudError('Region 只能包含小写字母、数字和连字符,最多 63 位');
}
return $value;
}
private static function bucket($value): string
{
if (!is_string($value)) {
throw new CloudError('Bucket 名称格式无效');
}
$value = strtolower(trim($value));
if (strlen($value) < 3 || strlen($value) > 63
|| preg_match('/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/D', $value) !== 1
|| str_contains($value, '..') || str_contains($value, '.-')
|| str_contains($value, '-.') || filter_var($value, FILTER_VALIDATE_IP)) {
throw new CloudError('Bucket 名称需符合 S3 DNS 命名规则(3 至 63 位)');
}
return $value;
}
private static function objectPrefix($value): string
{
if (!is_string($value)) {
throw new CloudError('对象前缀格式无效');
}
$value = trim($value, " \t\n\r\0\x0B/");
if ($value === '') {
return '';
}
if (strlen($value) > 255
|| preg_match('/^[A-Za-z0-9][A-Za-z0-9._\/-]*$/D', $value) !== 1
|| str_contains($value, '//')) {
throw new CloudError('对象前缀只能包含英文、数字、点、下划线、连字符和斜线,最多 255 位');
}
foreach (explode('/', $value) as $segment) {
if ($segment === '.' || $segment === '..') {
throw new CloudError('对象前缀不能包含点路径段');
}
}
return $value;
}
private static function assertCredentials(string $access, string $secret): void
{
if (preg_match('/^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/D', $access) !== 1) {
throw new CloudError('Access Key ID 需为 3 至 128 位英文、数字、点、下划线或连字符');
}
if (strlen($secret) < 8 || strlen($secret) > 256
|| trim($secret) !== $secret
|| preg_match('/[\x00-\x1F\x7F]/', $secret) === 1) {
throw new CloudError('Secret Access Key 需为 8 至 256 位且不能包含首尾空格或控制字符');
}
}
private static function revision($value, bool $allowZero): int
{
if (is_int($value)) {
$revision = $value;
} elseif (is_string($value) && preg_match('/^(?:0|[1-9][0-9]{0,9})$/D', $value) === 1) {
$revision = (int) $value;
} else {
throw new CloudError('对象存储配置版本无效,请刷新页面后重试', 409);
}
if ($revision < ($allowZero ? 0 : 1)) {
throw new CloudError('对象存储配置版本无效,请刷新页面后重试', 409);
}
return $revision;
}
private static function boolean($value, string $message): bool
{
$parsed = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
if ($parsed === null) {
throw new CloudError($message);
}
return $parsed;
}
private static function truthy($value): bool
{
return in_array(strtolower(trim((string) $value)), ['1', 'true', 'yes', 'on'], true);
}
private static function key(string $name): string
{
return self::PREFIX . $name;
}
private static function set(string $name, string $value): void
{
$row = Configurations::where('name', self::key($name))->first();
if ($row === null) {
$row = new Configurations();
$row->name = self::key($name);
}
$row->value = $value;
$row->save();
}
private static function ensureRow(string $name, string $value): void
{
if (Configurations::where('name', self::key($name))->first() !== null) {
return;
}
$row = new Configurations();
$row->name = self::key($name);
$row->value = $value;
try {
$row->save();
} catch (\Throwable $exception) {
if (Configurations::where('name', self::key($name))->first() === null) {
throw $exception;
}
}
}
}