存储 URL 策略选择规范

当使用 MinIO/OSS/S3 等对象存储时，正确选择 URL 生成策略。

陷阱 #1: 头像等长期资源使用预签名 URL

场景: 头像、Logo、商品图等需要长期访问的资源

问题根因

预签名 URL 有时效限制（MinIO/S3 最大 7 天），头像等长期资源会过期导致无法访问。

错误示例

java
// ❌ 错误: 预签名 URL 最大 7 天，头像会过期
String avatarUrl = minioService.getPresignedUrl(filePath, 60 * 24 * 365);
// IllegalArgumentException: expiry must be minimum 1 second to maximum 7 days

// ❌ 错误: 即使设置 7 天，头像也会在 7 天后失效
String avatarUrl = minioService.getPresignedUrl(filePath, 60 * 24 * 7);
// 7 天后用户头像显示"图片加载失败"

正确做法

java
// ✅ 方案1: 公开 URL（需配置 bucket 公开读）
public String getPublicUrl(String filePath) {
    String endpoint = minioConfig.getEndpoint();
    if (endpoint.endsWith("/")) {
        endpoint = endpoint.substring(0, endpoint.length() - 1);
    }
    return endpoint + "/" + minioConfig.getBucketName() + "/" + filePath;
}

String avatarUrl = minioService.getPublicUrl(filePath);
// 返回: http://minio:9000/bucket/avatars/xxx.jpeg

// ✅ 方案2: CDN URL（生产环境推荐）
String avatarUrl = cdnService.getCdnUrl(filePath);
// 返回: https://cdn.example.com/avatars/xxx.jpeg

URL 策略选择表

| 资源类型 | 推荐策略 | 有效期 | 适用场景 | 示例 | |---------|---------|-------|---------|------| | 头像/Logo | 公开 URL / CDN | 永久 | 需长期访问 | 用户头像、企业 Logo | | 商品图片 | 公开 URL / CDN | 永久 | 需长期访问 | 电商商品图、文章配图 | | 公开文档 | 公开 URL / CDN | 永久 | 需长期访问 | 用户手册、API 文档 | | 临时文件 | 预签名 URL | 1h-7d | 下载凭证 | 导出的 Excel、临时分享 | | 私密文档 | 预签名 URL | 15min-1h | 临时授权 | 合同、财务报表 | | 上传凭证 | 预签名 URL | 5min-30min | 客户端直传 | 前端直传 OSS |

陷阱 #2: 公开 URL 的 Bucket 未配置公开读

场景: 使用公开 URL 但 bucket 策略未配置

错误示例

java
// ✅ 代码正确生成公开 URL
String avatarUrl = minioService.getPublicUrl(filePath);
// 返回: http://minio:9000/bucket/avatars/xxx.jpeg

// ❌ 但 bucket 未配置公开读，访问返回 403 Forbidden

正确做法

MinIO 配置公开读:

bash
# 方案1: 使用 mc 命令配置（推荐）
mc anonymous set download minio/bucket/avatars

# 方案2: 使用 bucket policy
mc admin policy attach minio readonly --user=public

Bucket Policy 示例:

json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {"AWS": ["*"]},
      "Action": ["s3:GetObject"],
      "Resource": ["arn:aws:s3:::bucket/avatars/*"]
    }
  ]
}

阿里云 OSS 配置:

bash
# 设置 bucket 公共读
ossutil64 set-acl oss://bucket-name public-read

# 或只设置特定目录
ossutil64 set-acl oss://bucket-name/avatars/ public-read --recursive

陷阱 #3: 预签名 URL 的有效期设置不当

场景: 临时文件下载链接有效期过长或过短

规范

| 场景 | 推荐有效期 | 说明 | |------|-----------|------| | 客户端直传凭证 | 5-30 分钟 | 上传时间通常很短 | | 临时分享链接 | 1-24 小时 | 用户可能稍后下载 | | 导出文件下载 | 1-7 天 | 用户可能多次下载 | | 私密文档查看 | 15-60 分钟 | 安全性要求高 |

错误示例

java
// ❌ 错误: 客户端直传凭证有效期 7 天，安全风险高
String uploadUrl = minioService.getPresignedUrl(filePath, 60 * 24 * 7);

// ❌ 错误: 导出文件下载链接只有 5 分钟，用户可能来不及下载
String downloadUrl = minioService.getPresignedUrl(filePath, 5);

正确做法

java
// ✅ 客户端直传凭证: 15 分钟
String uploadUrl = minioService.getPresignedUrl(filePath, 15);

// ✅ 导出文件下载: 24 小时
String downloadUrl = minioService.getPresignedUrl(filePath, 60 * 24);

// ✅ 私密文档查看: 30 分钟
String viewUrl = minioService.getPresignedUrl(filePath, 30);

陷阱 #4: 前端直传时未校验文件类型和大小

场景: 前端直传 OSS，后端生成上传凭证

错误示例

java
// ❌ 错误: 未校验文件类型和大小，任何文件都能上传
@PostMapping("/upload/token")
public ApiResponse<String> getUploadToken(@RequestParam String filename) {
    String uploadUrl = minioService.getPresignedUrl("uploads/" + filename, 15);
    return ApiResponse.success(uploadUrl);
}

正确做法

java
// ✅ 后端校验文件类型和大小
@PostMapping("/upload/token")
public ApiResponse<UploadToken> getUploadToken(
    @RequestParam String filename,
    @RequestParam String contentType,
    @RequestParam Long fileSize) {

    // 校验文件类型
    List<String> allowedTypes = Arrays.asList("image/jpeg", "image/png", "image/gif");
    if (!allowedTypes.contains(contentType)) {
        return ApiResponse.error("不支持的文件类型");
    }

    // 校验文件大小（5MB）
    if (fileSize > 5 * 1024 * 1024) {
        return ApiResponse.error("文件大小不能超过 5MB");
    }

    // 生成安全的文件名（防止路径遍历）
    String safeFilename = UUID.randomUUID() + getExtension(filename);
    String filePath = "avatars/" + LocalDate.now() + "/" + safeFilename;

    String uploadUrl = minioService.getPresignedUrl(filePath, 15);
    return ApiResponse.success(new UploadToken(uploadUrl, filePath));
}

陷阱 #5: CDN 回源配置错误

场景: 使用 CDN 加速但回源配置不正确

错误示例

java
// ✅ 代码正确返回 CDN URL
String avatarUrl = "https://cdn.example.com/avatars/xxx.jpeg";

// ❌ 但 CDN 回源配置错误:
// 1. 回源 Host 未设置为 MinIO endpoint
// 2. 回源协议未设置为 HTTP
// 3. 回源路径未包含 bucket 名称
// 导致 CDN 返回 404 或 403

正确做法

阿里云 CDN 回源配置:

回源 Host: minio.example.com
回源协议: HTTP
回源地址: minio.example.com:9000
回源路径: /bucket${uri}

腾讯云 CDN 回源配置:

源站类型: 自有源
源站地址: minio.example.com:9000
回源协议: HTTP
回源 Host: minio.example.com
回源路径: /bucket${uri}

陷阱 #6: 响应层 URL 补全逻辑散落在各 Service

场景: 数据库存储相对路径（如 images/4/2026-04/xxx.png），多个 Service 各自写一份 resolveImageUrl 方法将 path 转为可访问 URL

问题根因

当"数据库存 path、响应时补全 URL"成为项目约定后，每个返回图片字段的 Service 都需要做 URL 补全。如果没有统一工具方法，就会出现：

• 7+ 个 Service 各写一份几乎相同的 resolveImageUrl
• 新增接口时容易忘记补全，导致前端拿到相对路径无法显示图片
• 修复时逐个 Service 排查，形成"散弹式修复"

错误示例

java
// ❌ 错误: 每个 Service 各写一份
// ProductService.java
private String resolveImageUrl(String imageUrl) {
    if (imageUrl == null || imageUrl.startsWith("http")) return imageUrl;
    return minioService.getPresignedUrl(imageUrl, 60 * 24 * 7);
}

// MiniProductService.java — 又写一份
private String resolveImageUrl(String imageUrl) { /* 同样逻辑 */ }

// CartService.java — 又写一份
private String resolveImageUrl(String imageUrl) { /* 同样逻辑 */ }

// MiniOrderService.java — 又写一份...

正确做法

java
// ✅ 正确: 抽成共享工具类，所有 Service 复用
@Component
public class ImageUrlResolver {
    private final MinioService minioService;

    public String resolve(String imageUrl) {
        if (imageUrl == null || imageUrl.isBlank()) return imageUrl;
        if (imageUrl.startsWith("http://") || imageUrl.startsWith("https://")) {
            return imageUrl;
        }
        return minioService.getPresignedUrl(imageUrl, 60 * 24 * 7);
    }

    public List<String> resolveAll(List<String> urls) {
        if (urls == null) return List.of();
        return urls.stream().map(this::resolve).toList();
    }
}

// 各 Service 注入后直接用
@Service
public class ProductService {
    private final ImageUrlResolver imageUrlResolver;

    private ProductDTO convertToDTO(Product product) {
        return ProductDTO.builder()
            .mainImageUrl(imageUrlResolver.resolve(mainImagePath))
            .build();
    }
}

检查清单

• ] 项目中是否有统一的图片 URL 补全工具类
• ] 新增返回图片字段的接口时，是否经过了统一补全
• ] 是否存在 3+ 个 Service 各自写了相同的 URL 补全逻辑
• ] 修复图片显示问题时，是否先做全局扫描（grep getImageUrl）再一次性补齐

检查清单（存储 URL 策略）

URL 策略选择:

• ] 头像/Logo 是否使用公开 URL 或 CDN
• ] 临时文件是否使用预签名 URL
• ] 预签名 URL 的有效期是否 ≤ 7 天
• ] 预签名 URL 的有效期是否符合业务场景

Bucket 配置:

• ] 公开 URL 的 bucket 是否配置了公开读策略
• ] 公开读策略是否只针对特定目录（如 avatars/）
• ] 是否配置了 CORS（前端直传需要）

CDN 配置:

• ] 生产环境是否使用 CDN 加速
• ] CDN 回源 Host 是否正确
• ] CDN 回源路径是否包含 bucket 名称
• ] CDN 是否配置了缓存规则

安全性:

• ] 前端直传是否校验文件类型和大小
• ] 文件名是否使用 UUID 防止路径遍历
• ] 私密文件是否使用预签名 URL 而非公开 URL

响应层 URL 补全:

• ] 是否有统一的图片 URL 补全工具类（而非各 Service 各写一份）
• ] 新增图片字段接口是否经过统一补全
• ] 修复图片问题时是否先全局扫描再一次性补齐

适用范围

• MinIO
• 阿里云 OSS
• 腾讯云 COS
• AWS S3
• 七牛云 Kodo
• 华为云 OBS

规则溯源

> 📋 本回复遵循：`storage-url-safety` - 存储 URL 策略选择规范