芋道 Spring Boot 框架 + AWS S3 图片上传显示

本文为针对 Yudao Spring Boot 框架 + AWS S3 的完整使用说明，结合你提供的配置示例。内容会涵盖 配置、上传、下载、访问、签名 URL 生成等关键环节。

---

一、前提条件

1. 框架：Yudao Cloud

2. 存储服务：Amazon S3

3. 依赖 ：Yudao 已内置 aws-java-sdk-s3，无需额外安装 SDK

4. Spring 配置文件 ：application.yml 或 application-dev.yml

---

二、S3 配置说明

你的 JSON 配置：

{
  "@class":"cn.iocoder.yudao.module.infra.framework.file.core.client.s3.S3FileClientConfig",
  "endpoint":"https://leon-api-file.s3.us-east-1.amazonaws.com",
  "domain":"",
  "bucket":"leon-api-file",
  "accessKey":"XXXX",
  "accessSecret":"XXXXX+XXX",
  "enablePathStyleAccess":true,
  "enablePublicAccess":false
}

---

1️⃣ 配置字段说明

字段	含义	建议
endpoint	S3 服务 URL	对 AWS S3，可以使用 https://s3.us-east-1.amazonaws.com，不要重复 bucket 名称
bucket	桶名称	例如 leon-api-file
domain	文件访问域名	可以为空，如果用 CDN 可填写 https://cdn.example.com
accessKey	AWS Access Key	必须安全存储，不要泄露
accessSecret	AWS Secret Key	必须安全存储，不要泄露
enablePathStyleAccess	路径风格访问	对 AWS S3 建议 false（Virtual-hosted 风格），如果用 MinIO 或自建 S3 可 true
enablePublicAccess	是否公开	false 表示私有文件，需要生成签名 URL

⚠️ 注意：你的配置里 enablePathStyleAccess=true 对 AWS S3 不是最佳实践，可能导致证书或重复 bucket 问题。建议改为 false。

---

三、Yudao S3 使用流程

Yudao 提供了 S3FileClient + FileService 来操作文件。

1️⃣ 上传文件

@Autowired
private FileService fileService;

public String uploadFile(MultipartFile file) throws IOException {
    // 1. 上传到 S3
    FileDO fileDO = fileService.createFile(file.getInputStream(), file.getOriginalFilename());

    // 2. 获取存储路径
    return fileDO.getUrl(); // 返回前端可访问 URL
}

上传逻辑：

1. S3FileClient 将文件上传到 bucket

2. Yudao 会生成一个对象 key，例如：

   20260309/afd4052403a842ad8fe565bfffba7851.png

3. 数据库存储对象信息：bucket + objectKey + url

---

2️⃣ 获取文件 URL

Yudao 支持两种访问：

① 私有文件（签名 URL）

String presignedUrl = fileService.getFileUrl(fileId);

返回 URL：

https://leon-api-file.s3.us-east-1.amazonaws.com/20260309/file.png?X-Amz-Signature=xxx

• X-Amz-Expires 默认 24 小时（86400 秒）

• 逾期后无法访问

• 用于私有访问场景，如合同、用户文档

② 公开文件（Public URL）

如果配置：

enablePublicAccess: true

直接返回：

https://leon-api-file.s3.us-east-1.amazonaws.com/20260309/file.png

适用于头像、商品图等公开资源。

---

3️⃣ 删除文件

fileService.deleteFile(fileId);

Yudao 会：

1. 删除 S3 上的文件

2. 删除数据库记录

---

四、推荐 S3 Bucket & Object Key 设计

类型	示例目录
用户头像	avatar/userId.png
产品图片	product/20260309/product123.png
文档文件	document/contract/20260309/contract123.pdf

注意：不要重复 bucket 名称到 object key，否则会出现 leon-api-file/leon-api-file/... 的情况。

---

五、Yudao + AWS 最佳实践

1. endpoint 使用 AWS 官方格式：

   endpoint: https://s3.us-east-1.amazonaws.com
   enablePathStyleAccess: false

2. 私有文件生成签名 URL

   • enablePublicAccess=false

   • 调用 fileService.getFileUrl() 获取 URL

3. 公开文件可直接访问

   • enablePublicAccess=true

   • URL 永久有效，可放 CDN

4. 避免重复 bucket

   • object key 不要包含 bucket 名

   • 如：20260309/file.png

5. 安全

   • AWS key 必须加密或使用 IAM 角色

   • 定期 rotate key

6. 可选优化

   • 配合 CloudFront CDN

   • 图片 URL 使用 domain 字段

   • 减少 S3 直接访问压力

---

六、示例完整配置（建议修改版）

yudao:
  infra:
    file:
      s3:
        endpoint: https://s3.us-east-1.amazonaws.com
        bucket: leon-api-file
        accessKey: YOUR_NEW_ACCESS_KEY
        accessSecret: YOUR_NEW_SECRET
        enablePathStyleAccess: false   # AWS 推荐 Virtual-hosted 风格
        enablePublicAccess: false      # 私有文件
        domain: ""                     # 可选 CDN

---

七、总结

1. Virtual-Hosted 风格是 AWS 推荐方式

2. enablePublicAccess=false → 生成 presigned URL

3. 避免重复 bucket，Yudao object key 只存日期/目录 + 文件名

4. 上传/下载/删除 都通过 FileService 完成

5. 安全：密钥不要暴露，必要时使用 IAM 角色

---