概述

产品与术语

在对象存储系统中：

• Bucket（存储空间）：对象的组织管理单位，可理解为一类文件的集合。一个账号可以创建多个 Bucket。
• Key（对象名）：对象在 Bucket 内的唯一标识，可理解为文件名（可包含 / 形成“目录效果”）。
• 公有/私有 Bucket：公有 Bucket 的对象可直接访问；私有 Bucket 的对象需通过签名鉴权访问。

Region 与访问域名（ObjectConfig）

Java SDK 通过 ObjectConfig 配置访问区域与域名后缀（如 ufileos.com），或直接使用已登记的自定义域名。

• Region：Bucket 创建所在的地区编码（例如 cn-bj、cn-sh2 等）。
• 域名后缀（ProxySuffix）：通常为 ufileos.com。
• 自定义域名：可使用根域或任意子域（不要求包含 www），并需解析到对应 Bucket + Region 的访问域名。

关于 Region、域名后缀以及访问域名的说明，请参考 地域和域名地址。

说明：本文档中的 ObjectConfig 与示例默认使用 US3 协议访问域名（如 https://{bucket}.{region}.ufileos.com 或已登记的自定义域名）。 请勿将 S3 兼容 Endpoint（如 https://s3-{region}.ufileos.com，用于 AWS S3 / MinIO 等客户端）填写到 ObjectConfig 中，以免导致访问失败或签名不匹配。

鉴权与签名（Java SDK）

US3 API 基于 HTTP，并通过签名机制保证请求安全。Java SDK 已封装签名逻辑，使用时只需按场景选择合适的鉴权方式：

• 本地签名（Local Authorization）：在应用中使用账号长期 API 公私钥进行签名（适合服务端环境）。
• 远程签名（Remote Authorization）：将签名私钥放在签名服务器上，由应用向签名服务请求签名（更安全，适合多端/零信任场景）。
• STS 临时安全凭证：使用临时 PublicKey/PrivateKey + SecurityToken 三元组进行访问（适合短时授权、细粒度权限控制）。
• 预签名 URL（签名 URL）：生成带签名的下载/上传 URL，前端或第三方可直接使用 URL 进行 GET/PUT，无需暴露密钥。

签名 URL 相关规则可参考：签名URL API文档。

SDK 源码与示例程序

• 源码仓库：ucloud/ufile-sdk-java
• 示例程序：示例代码位于 ufile-sample-java，其中 cn/ucloud/ufile/sample/object 目录覆盖了上传/下载/预签名 URL/分片上传等常见场景。

常用示例（部分）：

示例文件	示例内容
PutObjectSample	简单上传（PutObject）
DownloadFileSample	下载文件（DownloadFile）
PresignedDownloadSample	生成下载签名 URL（GET）
PresignedUploadSample	生成上传预签名 URL（PUT）并上传
MultiUploadSample	分片上传
ObjectProfileSample	获取文件信息（ObjectProfile）
ObjectListSample	前缀列表查询
CopyObjectSample	文件拷贝
DeleteObjectSample	文件删除