跳到主要内容

开发快速开始

先按这页把最小闭环跑通：

连接 → 上传 → 下载 → 私有签名访问

1. 接入前准备​

开始前请先确认你已经拿到以下信息：

  • Endpoint：https://s3.7caiyun.com
  • Region：us-west
  • AccessKey
  • SecretKey
  • 存储桶名称
  • Bucket 权限类型（公有 / 私有）
  • 访问风格（Virtual Host Style / Path Style）

AccessKey 与 SecretKey 可在控制台生成。建议正式环境与测试环境不要混用同一套密钥。

API 管理页面示意

图示说明：这是 API 管理页面示意。开发接入开始前，通常先在这里确认密钥和接入前置条件是否都准备好了。

2. 最小可用验证流程​

先按下面顺序验证，不要一上来就接业务代码：

  1. 用 S3 工具或 SDK 完成连接
  2. 上传一个小文件，例如 hello.txt
  3. 列出 Bucket 中的对象
  4. 下载刚刚上传的文件
  5. 如果是私有 Bucket，再验证签名访问是否正常

这样可以快速排除是“程序逻辑问题”还是“接入参数问题”。

3. 推荐的环境变量写法​

建议不要把密钥硬编码在代码里，而是通过环境变量管理。

export S3_ENDPOINT="https://s3.7caiyun.com"
export S3_REGION="us-west"
export S3_ACCESS_KEY="<your-access-key>"
export S3_SECRET_KEY="<your-secret-key>"
export S3_BUCKET="<your-bucket>"

4. AWS CLI 快速验证​

本地已安装 AWS CLI 时，可先做最基础的连通性验证。

列出 Bucket​

aws s3 ls s3://$S3_BUCKET \
  --endpoint-url "$S3_ENDPOINT" \
  --region "$S3_REGION"

上传文件​

echo "hello qicai" > hello.txt

aws s3 cp hello.txt s3://$S3_BUCKET/hello.txt \
  --endpoint-url "$S3_ENDPOINT" \
  --region "$S3_REGION"

下载文件​

aws s3 cp s3://$S3_BUCKET/hello.txt ./hello.down.txt \
  --endpoint-url "$S3_ENDPOINT" \
  --region "$S3_REGION"

如果这些步骤都正常，说明你的接入参数、鉴权和 Bucket 基本可用。

5. 访问模式选择建议​

七彩云对象存储同时支持：

  • 主机模式（Virtual Host Style），推荐
  • 路径模式（Path Style）

建议：

  • 优先尝试主机模式
  • 如果某些第三方工具兼容性一般，可切换到路径模式
  • Alist、OpenList 等工具遇到问题时，可重点检查这里

6. 程序接入时的建议顺序​

按这个顺序落业务：

  • 先做服务端上传
  • 再做服务端下载或签名链接
  • 最后再接前端直传、回调或批量任务

原因很简单：

  • 服务端更容易保护密钥
  • 排查问题更直接
  • 出错时日志更完整

7. 正式上线前建议检查​

上线前至少确认以下项目：

  • 测试环境与生产环境密钥分离
  • Bucket 权限符合预期
  • 上传路径有统一规范
  • 私有文件不被直接暴露
  • 签名链接有效期设置合理
  • 大文件上传方案支持重试或分片
  • 监控与错误日志可追踪
  • 所有程序使用统一的 Endpoint 与 Region

相关页面​