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
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\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;
}
}
}
}