multibucket
一个轻量、异步、后端无关 的对象存储门面。业务代码只针对 [ObjectStorage] trait 编写一次,即可对接任意存储桶——这正是 “multibucket”(多桶)的命名由来。
首个(也是目前唯一的)后端是 七牛云对象存储 Kodo,直接使用其原始 HTTP API 手写实现,因此不引入笨重的第三方 SDK 依赖树。
目录
特性
- 统一 trait:
put/get/delete/exists/stat/list/presign_get,一套接口适配多后端。 - 纯手写七牛鉴权:上传凭证(uploadToken)、私有下载凭证、
QBox管理凭证,签名算法严格对齐七牛官方文档。 - 异步 + 纯 Rust TLS:基于
tokio+reqwest(rustls),在 Windows 上无需 OpenSSL 即可编译。 - 可扩展:新增 S3 / 阿里云 OSS / 腾讯云 COS 只需在
src/backends/下再实现一次 trait。
运行条件
- Rust 1.70+(edition 2021)。安装见 https://rustup.rs。
- 一个七牛账号:开通 对象存储 Kodo,创建 空间(bucket),获取 AccessKey / SecretKey。
- 若使用私有空间下载,需为空间绑定一个 已备案的加速域名。
安装
在本 crate 目录下示例已在 Cargo.toml 就绪。若作为依赖引入其它项目:
[]
= "0.1"
= { = "1", = ["rt-multi-thread", "macros"] }
= "1"
快速开始
use Duration;
use Bytes;
use ;
async
完整可运行示例见 examples/qiniu_basic.rs。
支持的接口
| 方法 | 说明 | 七牛实现 |
|---|---|---|
put(key, body, opts) |
上传(覆盖写) | 表单上传 POST up*.qiniup.com/ |
get(key) |
下载到内存 | GET 下载域名(私有自动签名) |
stat(key) |
读取对象元信息 | POST rs*.qiniucs.com/stat/...(QBox) |
exists(key) |
是否存在 | 基于 stat,612 视为不存在 |
delete(key) |
删除对象 | POST rs*.qiniucs.com/delete/...(QBox) |
list(prefix, opts) |
分页列举 | GET rsf*.qiniucs.com/list(QBox) |
presign_get(key, expires) |
生成带时效的下载 URL | 下载凭证签名 |
put_resumable(key, body, part_size, opts) |
分片 / 断点续传上传 | 分片上传 v2(initiate / uploadPart / mkfile,UpToken 鉴权) |
upload_token(key, ttl) |
生成前端直传凭证(七牛特有) | uploadToken |
七牛后端要点
- 区域与域名:
Region枚举内置 z0/z1/z2/na0/as0/ea0 的上传、管理、列举、下载默认域名。如七牛调整域名或需走私有网关,可在QiniuConfig上用up_host / rs_host / rsf_host覆盖。权威域名可用GET https://uc.qiniup.com/query?ak=<AK>&bucket=<Bucket>查询。 - 私有空间:
QiniuConfig::private_bucket("download.example.com")会开启下载 URL 签名。 - 分片 / 断点续传:
put_resumable(..)走分片上传 v2(默认分片 4 MiB,单片最小 1 MiB,最多 10000 片,逐片自动重试 3 次);需要跨进程恢复时,用initiate_multipart_upload/upload_part/complete手动编排并持久化upload_id与已完成分片(ResumeState)。 - 时钟同步:
deadline/e均基于本机 Unix 时间,频繁 401 请先校准系统时钟。 - putTime:七牛返回的是 100 纳秒单位时间戳,本 crate 已转换为
SystemTime。
运行示例
# Windows PowerShell
$env:QINIU_ACCESS_KEY="..."; $env:QINIU_SECRET_KEY="..."; $env:QINIU_BUCKET="..."
# macOS / Linux
QINIU_ACCESS_KEY=... QINIU_SECRET_KEY=... QINIU_BUCKET=...
发布到 crates.io
发布流程、Cargo.toml 元数据要求、版本号规则、cargo owner 管理等详见
docs/publishing.md。速览:
# 1. 登录(token 会写入 ~/.cargo/credentials)
# 2. 自查包内容与编译
# 3. 先演练(只读),再正式发布
# 4. 打标签
&&
技术架构
multibucket/
├── Cargo.toml
├── README.md
├── LICENSE-MIT / LICENSE-APACHE
├── docs/
│ ├── usage.md # 使用指南
│ └── publishing.md # 发布指南
├── examples/
│ └── qiniu_basic.rs
└── src/
├── lib.rs # crate 门面与文档
├── error.rs # Error / Result
├── types.rs # ObjectMetadata / PutBody / PutOptions / ListOutcome
├── storage.rs # ObjectStorage trait + ListOptions
└── backends/
├── mod.rs
└── qiniu/
├── mod.rs # QiniuClient(实现 ObjectStorage)
├── auth.rs # Mac 签名:uploadToken / 私有下载 / QBox 管理凭证
├── config.rs # QiniuConfig(Builder)
└── region.rs # Region 与各服务域名
依赖:tokio(异步运行时)、reqwest(rustls)、hmac+sha1(签名)、base64、percent-encoding、serde/serde_json、bytes、async-trait、thiserror。
许可证
本项目采用 MIT OR Apache-2.0 双许可。