跳到主要内容

接入参数说明

通过 S3 协议连接七彩云对象存储时，通常需要以下参数。很多“明明参数都填了还是连不上”的问题，最后都出在这里。

先把这几个参数核对清楚，再排查 SDK 或业务代码。

API 管理页面示意

图示说明：这是 API 管理页面示意。接入参数里的 AccessKey、SecretKey 等内容，通常都需要先到后台相关页面确认。

核心参数总览​

接入七彩云对象存储时，通常至少需要：

  • Endpoint：https://s3.7caiyun.com
  • Region：us-west
  • AccessKey
  • SecretKey
  • Bucket 名称
  • 访问风格（视工具或 SDK 而定）

Endpoint​

Endpoint 是 S3 服务接入地址，客户端、SDK 或第三方工具会通过它连接对象存储服务。

使用建议：

  • 以平台提供的实际地址为准
  • 不要自行猜测或拼接
  • 注意是否包含协议头，例如 https://
  • 不要把访问域名误当成 S3 接入地址

常见问题：

  • 少写了 https://
  • 把下载域名当成了 S3 接入地址
  • 生产环境和测试环境用了不同 Endpoint 但代码没同步

Region​

Region 是 S3 协议中常用的区域配置参数。

说明：

  • 它是接入配置的一部分
  • 不一定等同于你直观理解的物理服务器地区
  • 实际填写值以平台提供的信息为准
  • Region 填错时，常见表现是签名失败或请求被拒绝

常见误区：

  • 以为不填 Region 也能长期稳定工作
  • 自己按“华东、华南”之类习惯命名去猜
  • 不同 SDK 里 Region 配成了不同值

AccessKey​

AccessKey 用于标识访问身份，通常与 SecretKey 配合使用。

建议：

  • 不同环境尽量使用不同密钥
  • 不同项目不要长期共用同一套密钥

SecretKey​

SecretKey 用于签名和身份校验，必须妥善保管。

建议：

  • 不要写进前端代码
  • 不要提交到 Git 仓库
  • 怀疑泄露时立即更换

Bucket 名称​

Bucket 是文件存储和管理的基础单位。接入前需要先创建存储桶。

建议确认：

  • Bucket 是否已创建
  • Bucket 名称拼写是否准确
  • 当前账号是否有目标 Bucket 的操作权限
  • Bucket 的公有 / 私有属性是否符合预期

访问风格​

很多 S3 工具或 SDK 还会涉及访问风格配置：

  • Virtual Host Style
  • Path Style

如果遇到连接正常但文件访问异常，可重点排查这里。

Virtual Host Style​

常见表现形式：

  • https://<bucket>.<endpoint>/object-key

特点：

  • 结构更接近标准 S3 常见用法
  • 某些工具默认优先使用这种方式

Path Style​

常见表现形式：

  • https://<endpoint>/<bucket>/object-key

特点：

  • 某些兼容场景下更容易调通
  • 某些 SDK 需要显式开启，例如 forcePathStyle

常见配置组合​

大多数工具都会要求填写：

  • Endpoint
  • Region
  • AccessKey
  • SecretKey
  • Bucket

部分 SDK 或工具还可能需要：

  • 强制 Path Style 选项
  • 签名版本
  • 是否启用 HTTPS
  • 自定义域名

推荐的排查顺序​

接入失败时，可按这个顺序排查：

  1. Endpoint 是否正确
  2. Region 是否与平台提供值一致
  3. AccessKey / SecretKey 是否可用
  4. Bucket 是否存在且有权限
  5. 访问风格是否匹配工具默认行为
  6. 本地系统时间是否准确

使用建议​

  • 接入前先在控制台验证 Bucket 是否可用
  • 密钥建议区分测试环境和正式环境
  • 先使用小文件测试连接，再上传大文件
  • 同一项目尽量统一一套接入参数来源，避免有人手填、有人写死、有人从环境变量读取，导致排查困难
  • 如果一个 SDK 调不通，先用 AWS CLI 验证参数本身，再回头修 SDK 配置

相关页面​