檔案儲存

Doggy 檔案儲存系統基於 League Flysystem 建置，支援本機儲存和 S3 相容儲存，提供檔案上傳、圖片最佳化、URL 產生等能力。

概述

儲存系統位於 src/Service/Storage/：

src/Service/Storage/
├── StorageManager.php          # 存储管理器（适配器选择）
├── FileUploadService.php       # 文件上传服务
├── FileUrlGenerator.php        # URL 生成/缓存
├── ImageOptimizerService.php   # 图片优化（Imagine 库）
└── Adapter/
    ├── StorageAdapterInterface.php
    ├── LocalStorageAdapter.php
    └── S3StorageAdapter.php

相關實體在 src/Entity/Storage/：

實體	說明
`File.php`	檔案記錄
`StorageConfig.php`	儲存設定（配接器類型、參數、CDN 網域名稱）
`UploadSession.php`	上傳工作階段

儲存後端

後端	配接器	適用情境
Local	`LocalStorageAdapter`	開發環境、小規模部署
AWS S3	`S3StorageAdapter`	雲端部署（支援 CDN 網域名稱）

本機儲存

php

// 默认本地存储：public/uploads/
$adapter = new LocalStorageAdapter(
    rootPath: '/var/www/public/uploads',
    publicUrl: '/uploads'
);

S3 儲存

php

// S3 兼容存储（支持 AWS、MinIO、阿里云 OSS 等）
$adapter = new S3StorageAdapter([
    'access_key' => '...',
    'secret_key' => '...',
    'region' => 'us-east-1',
    'bucket' => 'doggy-files',
    'endpoint' => 'https://oss-cn-hangzhou.aliyuncs.com',
    'cdn_domain' => 'https://cdn.example.com',
]);

檔案上傳

FileUploadService 提供完整的上傳流程：

php

$file = $fileUploadService->upload($uploadedFile, [
    'disk' => 'default',
    'optimize' => true,
    'max_size' => 52428800,  // 50MB
]);

上傳流程：

觸發 FileUploadingEvent（可攔截並修改選項）
檔案安全檢查（類型、大小、副檔名、MIME）
SHA-256 雜湊去重
依日期策略產生儲存路徑（Y/m/uuid.ext 或 uuid.ext）
上傳至配接器
建立 File 實體
觸發 FileUploadedEvent
非同步圖片壓縮訊息（ImageCompressMessage）

圖片最佳化

ImageOptimizerService 基於 Imagine 庫：

php

$optimizer->optimize($sourcePath, $targetPath, [
    'max_width' => 1920,
    'max_height' => 1080,
    'quality' => 80,
    'format' => 'webp',
]);

URL 產生

FileUrlGenerator 支援快取和暫時 URL：

php

$url = $urlGenerator->getUrl($file);                          // 带缓存
$tempUrl = $urlGenerator->getTemporaryUrl($file, $expiresAt); // 签名 URL
$urlGenerator->invalidateUrl($file);                          // 清除缓存

管理介面

入口：App\Controller\Admin\StorageConfigController

範本：templates/admin/storage/

檔案儲存 ​

概述 ​

儲存後端 ​

本機儲存 ​

S3 儲存 ​

檔案上傳 ​

圖片最佳化 ​

URL 產生 ​

管理介面 ​