阿里云 OSS 从零到实战：概念、配置与 Spring Boot 集成指南

阿里云 OSS 从零到实战：概念、配置与 Spring Boot 集成指南

一、OSS 核心概念

1.1 什么是 OSS

OSS（Object Storage Service，对象存储服务）是一种海量、安全、低成本的云存储服务。简单理解就是一个无限容量的网盘，通过 API 上传和下载文件。

与传统文件存储的区别：

1.2 核心术语

Endpoint (接入点) │ ▼ Bucket (存储空间) │ ├── folder1/ │ ├── file1.xlsx │ └── file2.pdf │ └── folder2/ └── image.png

1.3 Endpoint 格式

格式：<BucketName>.<Endpoint> 示例：xxx-img-xxx.oss-cn-xxxx.aliyuncs.com 内网访问：xxx-img-xxx.oss-cn-xxx-internal.aliyuncs.com（同地域免流量费）

1.4 Object Key（文件路径）

OSS 没有真正的文件夹概念，"文件夹"只是 Key 中的前缀：

upload/2026/06/10/abc123.xlsx ← 完整的 Object Key ├── upload/2026/06/10/ ← "文件夹"（实际是Key前缀） └── abc123.xlsx ← "文件名"

1.5 访问权限

生产环境通常设为 private，程序通过 SDK 生成带签名的临时 URL 供用户下载。

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

二、首次申请和开通 OSS

2.1 开通步骤

1. 登录阿里云控制台 → 搜索"对象存储 OSS"
2. 点击"立即开通"（按量付费，不用的时候几乎不花钱）
3. 进入 OSS 管理控制台

2.2 创建 Bucket

1. 点击"创建 Bucket"
2. 填写信息：
   • Bucket 名称：全局唯一，如my-app-files
   • 地域：选择离服务器最近的地域（如 cn-qingdao）
   • 存储类型：标准存储（频繁访问）/ 低频访问 / 归档
   • 读写权限：私有（推荐）
   • 同城冗余：生产环境建议开启
3. 点击确认创建

2.3 获取 AccessKey

1. 鼠标悬停右上角头像 → “AccessKey 管理”
2. 创建 AccessKey（会得到 AccessKey ID 和 AccessKey Secret）
3. 重要：Secret 只显示一次，必须保存好

安全建议：不要使用主账号 AccessKey，创建 RAM 子账号并只授予 OSS 权限。

2.4 记录关键信息

创建完成后你会拥有：

Endpoint: oss-cn-xxx.aliyuncs.com Bucket: my-app-files AccessKey ID: xxxx AccessKey Secret: xxxx 访问 URL 前缀: https://my-app-files.oss-cn-xxx.aliyuncs.com/

三、Spring Boot 集成 OSS

3.1 方式一：阿里云官方 SDK（通用）

依赖：

<dependency><groupId>com.aliyun.oss</groupId><artifactId>aliyun-sdk-oss</artifactId><version>3.17.4</version></dependency>

3.3 配置（application.yml）

# 参考工程中的配置格式jsh:oss:endpoint:oss-cn-xxx.aliyuncs.comaccess-key-id:xxaccess-key-secret:xxxbucket-name:ylh-img-testoss-url:https://image.ylhtest.com# CDN 域名或 Bucket 公网域名max-size:52480000# 上传大小限制（50MB）

3.4 配置项含义详解

四、完整示例：Spring Boot + 阿里云 OSS 文件上传下载

4.1 依赖

<dependency><groupId>com.aliyun.oss</groupId><artifactId>aliyun-sdk-oss</artifactId><version>3.17.4</version></dependency>

4.2 配置

oss:endpoint:oss-cn-xxx.aliyuncs.comaccess-key-id:your-access-key-idaccess-key-secret:your-access-key-secretbucket-name:my-app-filesurl-prefix:https://my-app-files.oss-cn-qingdao.aliyuncs.com

4.3 配置类

packagecom.example.config;importcom.aliyun.oss.OSS;importcom.aliyun.oss.OSSClientBuilder;importorg.springframework.beans.factory.annotation.Value;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;/** * 阿里云 OSS 客户端配置. */@ConfigurationpublicclassOssConfig{@Value("${oss.endpoint}")privateStringendpoint;@Value("${oss.access-key-id}")privateStringaccessKeyId;@Value("${oss.access-key-secret}")privateStringaccessKeySecret;/** * 创建 OSS 客户端 Bean. * OSS 客户端是线程安全的，全局共享一个实例即可. */@Bean(destroyMethod="shutdown")publicOSSossClient(){returnnewOSSClientBuilder().build(endpoint,accessKeyId,accessKeySecret);}}

4.4 工具类

packagecom.example.util;importcom.aliyun.oss.OSS;importcom.aliyun.oss.model.OSSObject;importcom.aliyun.oss.model.PutObjectRequest;importjakarta.annotation.Resource;importjava.io.File;importjava.io.InputStream;importjava.time.LocalDate;importjava.time.format.DateTimeFormatter;importjava.util.UUID;importlombok.extern.slf4j.Slf4j;importorg.springframework.beans.factory.annotation.Value;importorg.springframework.stereotype.Component;importorg.springframework.web.multipart.MultipartFile;/** * OSS 文件操作工具类. */@Slf4j@ComponentpublicclassOssUtil{@ResourceprivateOSSossClient;@Value("${oss.bucket-name}")privateStringbucketName;@Value("${oss.url-prefix}")privateStringurlPrefix;/** * 上传 MultipartFile（Web 表单文件）. * * @param file 上传的文件 * @param bizFolder 业务文件夹名（如 "import", "export"） * @return 文件访问 URL */publicStringuploadMultipartFile(MultipartFilefile,StringbizFolder){StringobjectKey=generateObjectKey(bizFolder,getExtension(file.getOriginalFilename()));try(InputStreamis=file.getInputStream()){ossClient.putObject(bucketName,objectKey,is);Stringurl=urlPrefix+"/"+objectKey;log.info("文件上传成功，objectKey:{}, url:{}",objectKey,url);returnurl;}catch(Exceptione){log.error("文件上传失败",e);thrownewRuntimeException("文件上传失败",e);}}/** * 上传本地 File 对象. * * @param file 本地文件 * @param bizFolder 业务文件夹名 * @return 文件访问 URL */publicStringuploadFile(Filefile,StringbizFolder){StringobjectKey=generateObjectKey(bizFolder,getExtension(file.getName()));PutObjectRequestrequest=newPutObjectRequest(bucketName,objectKey,file);ossClient.putObject(request);Stringurl=urlPrefix+"/"+objectKey;log.info("文件上传成功，objectKey:{}, url:{}",objectKey,url);returnurl;}/** * 上传字节流. * * @param inputStream 输入流 * @param bizFolder 业务文件夹名 * @param extension 文件扩展名（如 "xlsx"） * @return 文件访问 URL */publicStringuploadStream(InputStreaminputStream,StringbizFolder,Stringextension){StringobjectKey=generateObjectKey(bizFolder,extension);ossClient.putObject(bucketName,objectKey,inputStream);Stringurl=urlPrefix+"/"+objectKey;log.info("文件上传成功，objectKey:{}, url:{}",objectKey,url);returnurl;}/** * 下载文件，返回输入流. * * @param objectKey 文件在 OSS 中的 Key * @return 文件输入流（调用方需要关闭） */publicInputStreamdownloadFile(StringobjectKey){OSSObjectossObject=ossClient.getObject(bucketName,objectKey);returnossObject.getObjectContent();}/** * 通过完整 URL 下载文件. * * @param fileUrl 文件完整 URL * @return 文件输入流 */publicInputStreamdownloadByUrl(StringfileUrl){// 从 URL 中提取 objectKeyStringobjectKey=fileUrl.replace(urlPrefix+"/","");returndownloadFile(objectKey);}/** * 删除文件. * * @param objectKey 文件在 OSS 中的 Key */publicvoiddeleteFile(StringobjectKey){ossClient.deleteObject(bucketName,objectKey);log.info("文件删除成功，objectKey:{}",objectKey);}/** * 生成唯一的 Object Key. * 格式：bizFolder/yyyy/MM/dd/uuid.extension * 例如：import/2026/06/10/a1b2c3d4.xlsx */privateStringgenerateObjectKey(StringbizFolder,Stringextension){StringdatePath=LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"));StringfileName=UUID.randomUUID().toString().replace("-","")+"."+extension;returnbizFolder+"/"+datePath+"/"+fileName;}/** * 获取文件扩展名. */privateStringgetExtension(Stringfilename){if(filename==null||!filename.contains(".")){return"unknown";}returnfilename.substring(filename.lastIndexOf(".")+1).toLowerCase();}}

4.5 业务使用示例

packagecom.example.service.impl;importcom.example.util.OssUtil;importjakarta.annotation.Resource;importjakarta.servlet.http.HttpServletResponse;importjava.io.File;importjava.io.FileOutputStream;importjava.io.InputStream;importlombok.extern.slf4j.Slf4j;importorg.apache.poi.xssf.usermodel.XSSFWorkbook;importorg.springframework.stereotype.Service;importorg.springframework.web.multipart.MultipartFile;@Slf4j@ServicepublicclassFileBusinessService{@ResourceprivateOssUtilossUtil;/** * 场景一：接收用户上传的 Excel 文件，存到 OSS. */publicStringhandleFileUpload(MultipartFilefile){// 直接上传到 OSS 的 "import" 文件夹下returnossUtil.uploadMultipartFile(file,"import");// 返回值如：https://my-app-files.oss-cn-xxx.aliyuncs.com/import/2026/06/10/xxx.xlsx}/** * 场景二：程序生成 Excel 文件（如导入错误报告），上传到 OSS. */publicStringgenerateAndUploadErrorReport(java.util.List<String>errors){FiletempFile=null;try{// 1. 在内存中生成 ExcelXSSFWorkbookworkbook=newXSSFWorkbook();varsheet=workbook.createSheet("错误信息");varheaderRow=sheet.createRow(0);headerRow.createCell(0).setCellValue("行号");headerRow.createCell(1).setCellValue("错误原因");for(inti=0;i<errors.size();i++){varrow=sheet.createRow(i+1);row.createCell(0).setCellValue(i+1);row.createCell(1).setCellValue(errors.get(i));}// 2. 写入临时文件tempFile=File.createTempFile("error_report_",".xlsx");try(FileOutputStreamfos=newFileOutputStream(tempFile)){workbook.write(fos);}workbook.close();// 3. 上传到 OSSreturnossUtil.uploadFile(tempFile,"error-reports");}catch(Exceptione){thrownewRuntimeException("生成错误报告失败",e);}finally{// 4. 清理临时文件if(tempFile!=null&&tempFile.exists()){tempFile.delete();}}}/** * 场景三：从 OSS 下载文件提供给用户. */publicvoiddownloadFromOss(StringfileUrl,HttpServletResponseresponse){try(InputStreamis=ossUtil.downloadByUrl(fileUrl)){response.setContentType("application/octet-stream");response.setHeader("Content-Disposition","attachment;filename=download.xlsx");byte[]buffer=newbyte[8192];intlen;varos=response.getOutputStream();while((len=is.read(buffer))!=-1){os.write(buffer,0,len);}os.flush();}catch(Exceptione){thrownewRuntimeException("文件下载失败",e);}}}

五、OSS 常见使用场景

六、生产环境最佳实践

6.1 安全

• 使用 RAM 子账号，只授予最小权限（如只能操作特定 Bucket）
• AccessKey 不硬编码在代码中，放在环境变量或配置中心（如 Nacos）
• Bucket 设为 private，通过后端接口代理访问或生成临时签名 URL

6.2 签名 URL（临时授权访问）

对于 private 文件，生成有时效的访问 URL：

// 生成有效期 1 小时的签名 URLDateexpiration=newDate(System.currentTimeMillis()+3600*1000);URLsignedUrl=ossClient.generatePresignedUrl(bucketName,objectKey,expiration);

6.3 生命周期管理

配置自动清理规则，避免存储费用无限增长：

• 临时文件（error-reports/）7 天后自动删除
• 导出文件（export/）30 天后转低频存储，90 天后删除
• 在 OSS 控制台 → Bucket → 基础设置 → 生命周期 中配置

6.4 内网访问

如果应用服务器和 OSS 在同一地域，使用内网 Endpoint 可以：

• 免除流量费
• 速度更快、更稳定

# 公网endpoint:oss-cn-qingdao.aliyuncs.com# 内网（同地域 ECS 使用）endpoint:oss-cn-qingdao-internal.aliyuncs.com

6.5 大文件处理

分片上传的好处：

• 断点续传
• 并行上传多个分片提速
• 单个分片失败只需重传该分片

七、费用说明

对于导入导出场景（文件存几天就删，主要走内网），费用非常低。

八、总结