跳到主要内容

S3 工具接入示例

七彩云对象存储兼容 S3 协议，因此大多数支持 S3 的工具都可以直接接入。下面给出几种常见方式。

API 管理页面示意

图示说明：这是 API 管理页面示意。开始用 AWS CLI、rclone 或 mc 之前，先确认 AccessKey、SecretKey 和 Bucket 等信息已经准备好。

接入前统一准备​

你通常需要准备：

  • Endpoint：https://s3.7caiyun.com
  • Region：us-west
  • AccessKey
  • SecretKey
  • 存储桶（Bucket）名称
  • 访问风格（如果工具支持切换）

可先按这个顺序做：

  1. 先确认存储桶已创建
  2. 先确认密钥和 Region 正确
  3. 先用最基础的列表 / 上传 / 下载跑通
  4. 再进入批量同步、备份或自动化任务

AWS CLI​

适合：

  • 快速验证连接
  • 简单上传下载
  • 脚本自动化
  • 排查是不是参数本身有问题

配置示例​

aws configure

然后输入：

  • AWS Access Key ID → 你的 AccessKey
  • AWS Secret Access Key → 你的 SecretKey
  • Default region name → us-west
  • Default output format → 可留空

常用命令​

aws s3 ls s3://<bucket> --endpoint-url https://s3.7caiyun.com --region us-west
aws s3 cp ./demo.txt s3://<bucket>/demo.txt --endpoint-url https://s3.7caiyun.com --region us-west
aws s3 cp s3://<bucket>/demo.txt ./demo.txt --endpoint-url https://s3.7caiyun.com --region us-west

最小闭环实战​

下面这组命令适合第一次验证环境，按顺序跑就行：

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

echo "hello qicai" > hello.txt
aws s3 cp ./hello.txt s3://$S3_BUCKET/demo/hello.txt --endpoint-url "$S3_ENDPOINT" --region "$S3_REGION"
aws s3 ls s3://$S3_BUCKET/demo/ --endpoint-url "$S3_ENDPOINT" --region "$S3_REGION"
aws s3 cp s3://$S3_BUCKET/demo/hello.txt ./hello.down.txt --endpoint-url "$S3_ENDPOINT" --region "$S3_REGION"
cat ./hello.down.txt

你应该能看到：

  • 上传成功
  • 列表里出现 demo/hello.txt
  • 下载后的文件内容和原文件一致

适合用来做什么​

  • 验证密钥是否可用
  • 验证存储桶是否存在
  • 验证上传下载是否正常
  • 给后续 SDK 接入做基线验证

rclone​

适合：

  • 同步目录
  • 定时备份
  • 大批量迁移
  • 本地目录与对象存储之间的批量同步

创建 remote​

rclone config

建议按提示选择：

  • Storage → s3
  • provider → Other
  • access_key_id → 你的 AccessKey
  • secret_access_key → 你的 SecretKey
  • endpoint → https://s3.7caiyun.com
  • region → us-west
  • location_constraint → us-west

常用命令​

rclone ls qicai:<bucket>
rclone copy ./local-dir qicai:<bucket>/backup
rclone sync ./public qicai:<bucket>/public

目录备份实战​

如果你要把本地 ./backup 目录备份到对象存储，可以先这样做：

mkdir -p ./backup
echo "backup test" > ./backup/readme.txt
rclone copy ./backup qicai:<bucket>/backup-demo
rclone ls qicai:<bucket>/backup-demo

如果你要做长期同步：

rclone sync ./backup qicai:<bucket>/backup-prod --progress --checkers 4 --transfers 4

建议：

  • 第一次先用 copy
  • 确认方向没问题后，再考虑 sync
  • 正式任务最好记录日志，并先在测试存储桶验证

使用建议​

  • copy 更适合保守同步
  • sync 会让目标尽量与源保持一致，使用前要特别确认方向
  • 正式环境批量任务可先在测试存储桶验证

MinIO Client（mc）​

适合：

  • 命令行管理对象存储
  • 快速查看存储桶 / 对象
  • 简单自动化脚本
  • 临时排查对象路径或访问情况

配置别名​

mc alias set qicai https://s3.7caiyun.com <accessKey> <secretKey>

常用命令​

mc ls qicai/<bucket>
mc cp ./demo.txt qicai/<bucket>/demo.txt
mc cp qicai/<bucket>/demo.txt ./demo.txt

适合做什么​

  • 临时验证对象路径
  • 检查某个前缀下有没有文件
  • 快速上传下载单个文件

关于访问模式​

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

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

说明：

  • 大多数 SDK 更适合主机模式
  • 某些第三方工具可能更适合路径模式
  • Alist、OpenList 等工具如遇兼容问题，可优先切换这里

真实测试补充说明​

这页列出的常见工具已经完成一轮真实接口测试。

本轮已确认真实通过的包括：

  • AWS CLI
  • rclone
  • MinIO Client（mc）

其中：

  • AWS CLI 已实测列 Bucket、上传、列对象、下载
  • rclone 已实测上传、列对象、读回对象内容
  • mc 已实测上传、列对象、读回对象内容

如果你在自己环境里遇到 RequestTimeTooSkewed，优先先检查系统时间是否准确。

工具选择​

  • 只做连通性验证：优先用 AWS CLI
  • 做备份或同步：优先用 rclone
  • 想直接在命令行管理对象：可以用 mc

常见问题​

能连接但上传失败​

优先检查：

  • 存储桶名称是否正确
  • 存储桶权限是否允许当前操作
  • Endpoint / Region 是否填错
  • 工具是否需要切换访问风格
  • 本地文件路径是否正确

下载链接能访问，但 SDK 报签名错误​

常见原因：

  • Region 不一致
  • Endpoint 不一致
  • 服务端时间偏差过大
  • 使用了错误的签名版本或访问风格

为什么同一个参数在不同工具里表现不一样？​

因为不同工具对 S3 兼容实现、默认签名方式、路径风格支持并不完全一致。遇到问题时，建议先用 AWS CLI 验证，再回到目标工具排查。

实战建议​

  • 先把 AWS CLI 跑通，再换目标工具
  • 大批量同步前，先用小目录做验证
  • 自动化脚本里尽量使用环境变量，而不是把密钥写死在命令里
  • 正式环境的同步和备份任务，建议记录日志并保留失败重试机制

相关页面​