# multibucket
异步、后端无关的对象存储门面:业务代码只针对 `ObjectStorage` trait 编写一次,即可对接任意存储桶。当前内置两个后端,均直连原始 HTTP API、不引入第三方 SDK:
- **七牛云对象存储 Kodo**(`backends::qiniu`)
- **Amazon S3 / S3 兼容服务**(`backends::s3`):基于 AWS Signature Version 4,因此同样覆盖 MinIO、Cloudflare R2、阿里云 OSS、腾讯云 COS、以及七牛自带的 S3 接口。
## 安装
```toml
[dependencies]
multibucket = "0.3"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
bytes = "1"
```
需要 Rust 1.70+。TLS 使用 `rustls`,Windows 上无需 OpenSSL。
## 构造客户端
```rust
use multibucket::backends::qiniu::{QiniuClient, QiniuConfig, Region};
let cfg = QiniuConfig::new("ACCESS_KEY", "SECRET_KEY", "my-bucket")
// Region: Z0 / CnEast2 / Z1 / Z2 / Na0 / As0 / ApSoutheast2 / ApSoutheast3
.region(Region::Z0);
let client = QiniuClient::new(cfg);
```
私有空间的下载 URL 必须带签名。两种方式:
- 已绑定自定义下载域名(推荐,生产用):
```rust
let cfg = QiniuConfig::new("ACCESS_KEY", "SECRET_KEY", "my-bucket")
.region(Region::Z0)
.private_bucket("download.example.com");
```
- 还没绑定自定义域名:用 `.private()` 直接标记私有,签名会落到七牛默认的
`iovip-<region>.qiniuio.com` 下载主机上(标准私有下载机制,无需域名):
```rust
let cfg = QiniuConfig::new("ACCESS_KEY", "SECRET_KEY", "my-bucket")
.region(Region::Z0)
.private();
```
内置域名若不适用(私有网关、七牛调整域名、需要直连指定 IP),可逐个覆盖:`up_host(..)` / `rs_host(..)` / `rsf_host(..)` / `download_domain(..)`;`use_https(false)` 可切回 http。要控制超时与代理,传入自己的 `reqwest::Client`:
```rust
let http = reqwest::Client::builder()
.timeout(std::time::Duration::from_secs(30))
.build()?;
let client = QiniuClient::new(cfg).with_http(http);
```
## 创建空间(可选)
不想在控制台手工建空间时,可以直接用代码创建(控制面接口,需要该密钥具备管理空间的权限):
```rust
// 空间名 = QiniuConfig::new 的第三个参数,区域 = .region(..)
client.create_bucket(true).await?; // 创建并设为私有
client.set_bucket_private(false).await?; // 只切换已有空间的访问权限
```
空间名称在七牛全系统内唯一,规则为 3~63 位小写字母 / 数字 / `-` 且首尾为字母或数字(不合法的名字会在发请求前报 `Error::InvalidInput`)。`create_bucket(true)` 是两次请求,若第二步失败空间已存在但仍为公开,可再调 `set_bucket_private(true)`。
## 上传
```rust
use bytes::Bytes;
use multibucket::{ObjectStorage, PutBody, PutOptions};
let meta = client
.put(
"docs/readme.txt",
PutBody::from(Bytes::from("hello")),
&PutOptions::with_content_type("text/plain"),
)
.await?;
println!("{} {} bytes, etag={:?}", meta.key, meta.size, meta.etag);
```
`PutBody` 可由 `Bytes`、`Vec<u8>`、`&'static [u8]` 转来;同名 key 直接覆盖写,`PutOptions { insert_only: true, .. }` 可改为拒绝覆盖。
## 下载 / 元信息 / 存在 / 删除
```rust
let data = client.get("docs/readme.txt").await?; // Bytes
let meta = client.stat("docs/readme.txt").await?;
if client.exists("docs/readme.txt").await? {
client.delete("docs/readme.txt").await?;
}
```
未绑定自定义下载域名时,`get()` 会用七牛默认的 `iovip-<region>` 主机;若该主机拒绝(私有桶 401/403/404)或因 DNS / 连接失败不可达,会自动回退到桶的**源站(io_src)域名**下载。也可以显式走源站,它总会带上下载凭证,对私有 / 公开桶都适用:
```rust
// 通过 UC 服务解析出桶真实的源站域名(首次解析后缓存),再签名下载。
let data = client.get_via_io_src("docs/readme.txt").await?;
```
## 列举
```rust
use multibucket::ListOptions;
let mut opts = ListOptions::with_limit(200);
loop {
let page = client.list("docs/", &opts).await?;
for item in &page.items {
println!("{} ({} bytes)", item.key, item.size);
}
match page.next_marker {
Some(marker) => opts.marker = Some(marker),
None => break,
}
}
```
`ListOptions` 另有 `delimiter`(支持 `/`,用于按目录分组)。
## 有时效的下载 URL
```rust
use std::time::Duration;
let url = client.presign_get("docs/readme.txt", Duration::from_secs(300))?;
```
公有桶返回普通 URL,私有桶自动附带下载凭证(同步方法,不发请求)。
> **七牛对私有下载凭证的 `e`(过期时间戳)有硬性上限**:下载服务器只接受 `e` 比其服务器时钟最多超前约 5 分钟的令牌,否则返回 `403 RequestExpiresTooSkewed`(实测 `e=now+300` 可用、`e=now+600` 被拒)。因此本库把下载 URL 的 TTL **自动封顶在 300 秒**,无论调用方传入多大值;上传令牌不受影响(仍用 3600 秒)。若客户端机器时钟与七牛偏差过大,参见下文[处理时钟偏差](#处理时钟偏差)。
## 处理时钟偏差
所有签名(上传令牌 / 私有下载 / `QBox` 管理)都依赖本机时间与七牛服务器时间对齐。若本机时钟偏移过大,七牛会以 `403 RequestExpiresTooSkewed` 拒绝**所有**带 `e` 的请求。两种应对方式:
- **自动对齐(推荐)**:构造客户端后调用一次 `sync_clock()`,它读取七牛响应的 `Date` 头算出 `server_time - local_time` 并缓存,后续令牌自动基于七牛时钟生成。传输失败时静默保留原偏移、返回 `Ok`,不影响正常机器:
```rust
let client = QiniuClient::new(cfg);
client.sync_clock().await?; // 读七牛 Date 头自动对齐时钟
```
- **手动补偿**:已知固定偏差(或无法联网探测)时,用 `QiniuConfig::deadline_offset_secs(offset)` 直接把 `offset = server_time - local_time`(秒)写入配置,作为 `sync_clock` 的初始值 / 替代:
```rust
let cfg = QiniuConfig::new("ACCESS_KEY", "SECRET_KEY", "my-bucket")
.region(Region::Z0)
.deadline_offset_secs(-3600); // 本机比七牛快 1 小时
```
两者都默认 `0`,普通机器无需设置——直接校准系统时钟即可。
## 大文件:分片与断点续传
便捷调用,内部走分片上传 v2,逐片自动重试:
```rust
// part_size = 0 表示使用默认 4 MiB
let meta = client
.put_resumable("video/big.mp4", PutBody::from(bytes), 0, &PutOptions::default())
.await?;
```
需要跨进程恢复时,自行持久化 `upload_id` 与已完成分片:
```rust
use multibucket::backends::qiniu::ResumeState;
let state = ResumeState {
upload_id: saved_upload_id, // 从你的存储里读回
parts: saved_parts, // BTreeMap<分片号, partName>
};
client
.put_resumable_resume(
"video/big.mp4",
PutBody::from(bytes),
4 * 1024 * 1024,
&PutOptions::default(),
&state,
)
.await?;
```
完全手动编排(并发控制、进度上报等场景):
```rust
use multibucket::backends::qiniu::CompletedPart;
let mp = client
.initiate_multipart_upload("video/big.mp4", &PutOptions::default())
.await?;
let upload_id = mp.upload_id().to_string(); // 立刻持久化,便于中断后恢复
let name1 = mp.upload_part(1, part1).await?; // 返回 partName,需保存
let name2 = mp.upload_part(2, part2).await?;
let meta = mp
.complete(&[
CompletedPart {
number: 1,
name: name1,
},
CompletedPart {
number: 2,
name: name2,
},
])
.await?;
```
约束:分片号从 1 开始、最多 10000 片;除最后一片外每片不得小于 1 MiB。中断后可用 `client.multipart_upload(key, upload_id)` 重新接上已存在的上传任务。
## 前端直传凭证
```rust
use std::time::Duration;
let token = client.upload_token("docs/readme.txt", Duration::from_secs(3600))?;
```
把 `token` 下发给浏览器 / 移动端,让它们直接 POST 到七牛上传域名。
## 错误处理
所有方法返回 `multibucket::Result<T>`;后端非 2xx 会收敛为 `Error::Api`:
```rust
use multibucket::Error;
if let Err(Error::Api {
status,
qiniu_code,
body,
}) = client.stat("not-exist.txt").await
{
// 七牛业务码 612 表示文件不存在
println!("http {status}, qiniu {qiniu_code:?}: {body}");
}
```
`exists()` 已把 612 处理为 `false`,不会报错。签名依赖本机时间,频繁 401 请先校准系统时钟。
## S3 后端(兼容 MinIO / R2 / OSS / COS)
与七牛后端实现的是同一个 `ObjectStorage` trait,因此上传 / 下载 / 删除 / 元信息 / 列举 / 预签名接口完全一致,只是构造方式与若干语义略有不同。签名算法为手写 SigV4(见 `src/backends/s3/sigv4.rs`),并用 AWS 官方示例向量做了单测,逐字节对齐。
### 构造客户端
```rust
use multibucket::backends::s3::{S3Client, S3Config};
// AWS S3(us-east-1),默认使用 virtual-hosted 寻址(https://<bucket>.s3.<region>.amazonaws.com)
let cfg = S3Config::new("ACCESS_KEY_ID", "SECRET_ACCESS_KEY", "my-bucket");
// 带区域 / 临时凭证(STS)
let cfg = S3Config::new("AK", "SK", "my-bucket")
.region("cn-north-1")
.session_token("IQoJb3JpZ2luX2Vj...");
let client = S3Client::new(cfg);
```
不同 S3 兼容服务的差异只体现在三个配置项上:
| 服务 | endpoint | force_path_style | region |
| --- | --- | --- | --- |
| AWS S3 | 不填(默认 `s3.<region>.amazonaws.com`) | 否(默认) | 真实区域 |
| MinIO | `localhost:9000` | **是**(必须) | 任意,如 `us-east-1` |
| Cloudflare R2 | `<accountid>.r2.cloudflarestorage.com` | 否 | `auto` |
| 阿里云 OSS | `oss-cn-hangzhou.aliyuncs.com` | 否 | 对应区域 |
| 腾讯云 COS | `cos.ap-guangzhou.myqcloud.com` | 否 | 对应区域 |
| 七牛 S3 接口 | `s3-cn-south-1.qiniucs.com` | 否 | `cn-south-1` |
```rust
// MinIO 示例(path-style 是必须的)
let cfg = S3Config::new("AK", "SK", "my-bucket")
.endpoint("localhost:9000")
.force_path_style(true);
```
`use_https(false)` 可切回 http;超时 / 代理同样用 `with_http(reqwest::Client)` 传入。
### 上传 / 下载 / 删除 / 元信息 / 列举
接口与七牛完全一致,例如:
```rust
use bytes::Bytes;
use multibucket::{ObjectStorage, PutBody, PutOptions, ListOptions};
// 上传(≤ 5 MiB 走简单 PUT;更大自动走分片,见下文)
client.put("docs/readme.txt", PutBody::from(Bytes::from("hello")),
&PutOptions::with_content_type("text/plain")).await?;
// 私有写:insert_only 等价于 S3 的条件写 If-None-Match: *(已存在则报错)
client.put("k", body, &PutOptions { insert_only: true, ..Default::default() }).await?;
let data = client.get("docs/readme.txt").await?; // Bytes
let meta = client.stat("docs/readme.txt").await?; // 含 size / etag / last_modified
if client.exists("docs/readme.txt").await? {
client.delete("docs/readme.txt").await?;
}
// 列举(带分页与目录分隔符)
let mut opts = ListOptions::with_limit(200);
loop {
let page = client.list("docs/", &opts).await?;
for item in &page.items { println!("{} ({} bytes)", item.key, item.size); }
match page.next_marker { Some(m) => opts.marker = Some(m), None => break }
}
```
### 预签名下载 URL
同步方法、不发请求,链接里不含密钥,可安全下发给浏览器 / 移动端:
```rust
use std::time::Duration;
let url = client.presign_get("docs/readme.txt", Duration::from_secs(600))?;
// -> https://<bucket>.s3.<region>.amazonaws.com/docs/readme.txt?X-Amz-Algorithm=...&X-Amz-Signature=...
```
有效期上限按 AWS 的 7 天(`604800` 秒)封顶。
### 大文件:分片上传
```rust
// 便捷调用:part_size = 0 表示使用默认 8 MiB;< 5 MiB 自动降级为简单 PUT
let meta = client.put_resumable("video/big.mp4", PutBody::from(bytes), 0,
&PutOptions::default()).await?;
```
需要跨进程恢复时,自行持久化 `upload_id` 与已完成分片:
```rust
use multibucket::backends::s3::CompletedPart;
let mp = client.create_multipart_upload("video/big.mp4", &PutOptions::default()).await?;
let upload_id = mp.upload_id().to_string(); // 立刻持久化
let etag1 = mp.upload_part(1, part1).await?; // 返回 ETag,需保存
let meta = mp.complete(&[CompletedPart { number: 1, etag: etag1 }]).await?;
// 中断后可:let mp = client.multipart_upload("video/big.mp4", upload_id); 重新接上
// 出错时:mp.abort().await?; 释放已上传的分片
```
约束:除最后一片外每片不得小于 5 MiB;最多 10 000 片;`upload_id` 与分片 `ETag` 由服务端返回。
### 与七牛后端的行为差异
- **删除幂等**:S3 的 `DELETE` 即使 key 不存在也返回 204,因此 `delete` 不会报“不存在”;七牛则会返回 612。
- **签名算法**:七牛用自研 `Mac`/上传令牌,S3 用 AWS SigV4(含 header 签名与 query 预签名两套)。
- **寻址**:S3 支持 virtual-hosted 与 path-style 两种;七牛由各 region 固定域名决定。
- **私有访问**:七牛私有桶下载需 SDK 在 URL 上追加 `e` + `token`(且 `e` 被服务端时钟限制 ≤ 5 分钟);S3 预签名链接自带 `X-Amz-Expires`,最长 7 天。
- **临时凭证**:S3 支持 `session_token`(STS / 角色扮演),七牛无此概念。
## 运行示例
端到端示例覆盖上文全部用法(上传 → 元信息 → 下载 → 签名 URL → 列举 → 删除 → 分片 / 手动编排),凭证从环境变量读取:
```sh
# Windows PowerShell
$env:QINIU_ACCESS_KEY="..."; $env:QINIU_SECRET_KEY="..."; $env:QINIU_BUCKET="..."
cargo run --example qiniu_basic
```
```sh
# macOS / Linux
QINIU_ACCESS_KEY=... QINIU_SECRET_KEY=... QINIU_BUCKET=... cargo run --example qiniu_basic
```
S3 示例(`examples/s3_basic.rs`)覆盖同样的流程,适合对接 AWS S3 或任意 S3 兼容服务:
```sh
# macOS / Linux(AWS S3)
AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... S3_BUCKET=... \
cargo run --example s3_basic
# macOS / Linux(MinIO / path-style)
AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... S3_BUCKET=mybucket \
S3_ENDPOINT=localhost:9000 S3_FORCE_PATH_STYLE=1 cargo run --example s3_basic
```
## 许可证
本项目采用 **MIT OR Apache-2.0** 双许可。