'默认对象存储', '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 */ public static function view(): array { return self::publicState(self::readRaw()); } /** @return array */ 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 */ 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 */ 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,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 */ 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 $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 $raw * @return array{config:array,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 $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; } } } }