跳到正文

接入 Cloudflare R2 和 S3 兼容存储 ​

除了腾讯云 COS,云匣也能让 git-lfs 直连 S3 兼容的对象存储:Cloudflare R2(下载流量免费,适合素材经常被拉取的团队)、AWS S3、MinIO,以及其他支持 S3 对象接口和 Signature Version 4 的服务。和 COS 一样,中间没有服务端:每个人电脑上的 git-yunbox lfs-agent 用自己的密钥签名,直接上传、下载。

git push / clone ──▶ git-lfs ──▶ git-yunbox lfs-agent ──▶ R2 / S3 / MinIO

安装命令行和 COS 一样,见快速开始。

R2 的 token 只能限定到 bucket,不能限定到前缀

R2 的 API token 可以只授权一个或几个 bucket,但没有「只授权 bucket 里某个目录(前缀)」的选项。能访问某个 bucket 的 token,可以读写这个 bucket 里所有前缀的素材。

所以用 R2 时建议每个项目单独建一个 bucket,给协作者的 token 只授权这个 bucket。不要像 COS 那样多个项目共用一个 bucket、靠前缀隔开:在 R2 上,任何一个项目的 token 都能读写其他项目的素材。

管理员:建 bucket 和 token(以 R2 为例) ​

  1. 在 Cloudflare 控制台打开 R2 对象存储,新建一个 bucket,例如 game-assets。保持私有,不要开启公开访问(r2.dev 子域名或自定义域名),否则知道对象键的人可以绕过 token 下载素材。
  2. 记下 R2 概览页右侧的账户 ID(32 位十六进制)。
  3. 在「管理 R2 API 令牌」里创建 token:
    • 权限选 对象读和写(Object Read & Write);只需要拉取的人选 对象只读(Object Read only)。
    • 「指定存储桶」只选这个项目的 bucket。
    • 创建后页面会显示 访问密钥 ID 和 机密访问密钥。机密访问密钥离开页面后就看不到了,请立即通过安全渠道(例如密码管理器的共享)交给使用者。
  4. 每个协作者一个 token,有人离开时在控制台删除他的 token 即可,不影响其他人。

云匣不调用 Cloudflare 的管理接口:yunbox buckets、yunbox policy、yunbox subaccount 只支持腾讯云 COS,在 S3 仓库里运行会提示去控制台操作。

管理员:给仓库接上 R2 ​

bash
yunbox login --provider s3      # 输入访问密钥 ID 和机密访问密钥
git yunbox init --preset r2 --account-id <账户 ID> --bucket game-assets
git add .gitattributes .yunbox/config
git commit -m "chore: 用 YunBox 把 LFS 素材直传到 R2"
git push

不带参数运行 git yunbox init --provider s3 会逐项询问。init 在修改仓库之前先用你的密钥在 <前缀>/_yunbox/probe 做一次写入、读取探测,失败时不改动任何文件。

.yunbox/config 提交到仓库供全组共享,不含任何密钥:

ini
[storage]
	provider = s3
[s3]
	endpoint = https://<账户 ID>.r2.cloudflarestorage.com
	bucket = game-assets
	region = auto
	prefix = yunbox/team/game
	addressingStyle = path

对象键是 <前缀>/<oid 前两位>/<oid 第 3–4 位>/<oid>,和 COS 相同。每个项目一个 bucket 时,前缀可以留默认值,也可以用 --prefix '' 放在 bucket 根目录。

其他服务 ​

服务命令说明
Cloudflare R2--preset r2 --account-id <账户 ID>endpoint 为 https://<账户 ID>.r2.cloudflarestorage.com,region 为 auto,路径风格
AWS S3--preset aws --region <地域>endpoint 为 https://s3.<地域>.amazonaws.com,虚拟主机风格(<bucket>.s3.<地域>.amazonaws.com);用 IAM 策略把权限限定到 arn:aws:s3:::<bucket>/<前缀>/* 的 s3:PutObject、s3:GetObject
MinIO--preset minio --endpoint https://minio.example.com路径风格,region 默认 us-east-1(服务端改过时用 --region)
其他--endpoint <地址> --region <地域>默认路径风格,--addressing virtual 改为虚拟主机风格

endpoint 必须是 https,只有本机地址(localhost、127.0.0.1)可以用 http。bucket 名里有「.」时只能用路径风格。

协作者加入 ​

拿到访问密钥 ID 和机密访问密钥后:

bash
npm install -g yunbox
git yunbox clone <仓库地址>               # 第一次会提示还没有密钥
cd <仓库目录>
yunbox login                              # 在仓库里运行时自动按 S3 保存,并用这个 bucket 检查密钥
git yunbox init && git lfs pull

也可以先在任意目录运行 yunbox login --provider s3(这时没有 bucket 可以检查,接入后用 yunbox doctor 检查),再 git yunbox clone <仓库地址>。

  • 机密访问密钥输入时不显示,也不接受命令行参数。
  • macOS 上存进登录钥匙串的「yunbox / s3」项;Linux 和 Windows 上存在 ~/.config/yunbox/credentials-s3.json(Windows 为 %APPDATA%\yunbox),只有本人可读。COS 的密钥单独保存,两者互不覆盖。
  • CI 等场景可以用环境变量 YUNBOX_S3_ACCESS_KEY_ID、YUNBOX_S3_SECRET_ACCESS_KEY(临时凭据再加 YUNBOX_S3_SESSION_TOKEN)。云匣不读取 AWS_ACCESS_KEY_ID 等通用变量,避免把你的 AWS 身份发给 R2 之类的其他服务。
  • 一台电脑上同一时间只保存一组 S3 密钥。同时参与多个 R2 项目时,请管理员给你一个授权了这几个 bucket 的 token。
  • yunbox logout --provider s3 删除 S3 密钥;不带 --provider 时 COS 和 S3 的都删除。

安全和可靠性 ​

  • 上传带 If-None-Match: *,已存在的对象不会被覆盖;上传前还会先查询,已经存在的直接跳过,重复推送不会重复上传。服务不支持这个请求头(返回 501)时,退回到「先查询、再上传」。
  • 上传时签名的内容哈希就是对象 ID(SHA-256),存储服务会拒绝内容不符的上传;下载时边写边算 SHA-256,大小或哈希不符的文件会被丢弃,不会交给 git-lfs。
  • 日志和错误信息不包含密钥、签名和带签名的地址。
  • 没有服务端就没有文件锁,同一个素材同一时间请只由一个人编辑。

常见问题 ​

能用插件接入别的存储吗? ​

不能。云匣只有内置的存储:腾讯云 COS 和 S3 兼容存储,不会加载任何第三方插件。存储的实现要拿到你的密钥来签名,而且每次 push、pull 都会运行;插件和云匣在同一个进程里,能读到钥匙串里的全部密钥,一个被篡改的插件会出现在全组每个人的每次推送里。「不覆盖已有对象」「下载校验 SHA-256」「日志不出现密钥」这些保证也只在内置的共用代码里成立。

我的存储不在上面的表里? ​

先当作 S3 兼容存储试一下:

bash
git yunbox init --provider s3 --endpoint <服务地址> --region <地域> --bucket <bucket>
yunbox doctor

init 在修改仓库前会做读写探测,不兼容时直接报错、不改任何文件。表格以外声称兼容 S3 的服务没有经过我们测试;能用的话欢迎在 issue 里告诉我们。确实不兼容 S3、又有需要的,请提 issue,或者按存储提供方的开发说明提交一个内置实现。

出问题时 ​

bash
yunbox doctor

S3 仓库的检查项是「S3 位置」「S3 密钥」「S3 权限」,没通过的项都附修复命令。常见情况:

  • SignatureDoesNotMatch:机密访问密钥不对,或者 s3.region 不对(R2 是 auto)。
  • InvalidAccessKeyId:访问密钥 ID 不存在,或 token 已被删除。
  • 只能读取,不能推送:token 是只读的。只需要拉取时用 yunbox doctor --read-only。
  • NoSuchBucket:s3.bucket 或 s3.endpoint 写错了。

MIT 许可证发布