简体中文
接入 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 为例)
- 在 Cloudflare 控制台打开 R2 对象存储,新建一个 bucket,例如
game-assets。保持私有,不要开启公开访问(r2.dev 子域名或自定义域名),否则知道对象键的人可以绕过 token 下载素材。 - 记下 R2 概览页右侧的账户 ID(32 位十六进制)。
- 在「管理 R2 API 令牌」里创建 token:
- 权限选 对象读和写(Object Read & Write);只需要拉取的人选 对象只读(Object Read only)。
- 「指定存储桶」只选这个项目的 bucket。
- 创建后页面会显示 访问密钥 ID 和 机密访问密钥。机密访问密钥离开页面后就看不到了,请立即通过安全渠道(例如密码管理器的共享)交给使用者。
- 每个协作者一个 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 doctorinit 在修改仓库前会做读写探测,不兼容时直接报错、不改任何文件。表格以外声称兼容 S3 的服务没有经过我们测试;能用的话欢迎在 issue 里告诉我们。确实不兼容 S3、又有需要的,请提 issue,或者按存储提供方的开发说明提交一个内置实现。
出问题时
bash
yunbox doctorS3 仓库的检查项是「S3 位置」「S3 密钥」「S3 权限」,没通过的项都附修复命令。常见情况:
- SignatureDoesNotMatch:机密访问密钥不对,或者
s3.region不对(R2 是auto)。 - InvalidAccessKeyId:访问密钥 ID 不存在,或 token 已被删除。
- 只能读取,不能推送:token 是只读的。只需要拉取时用
yunbox doctor --read-only。 - NoSuchBucket:
s3.bucket或s3.endpoint写错了。