Skip to content

s3.md

Latest commit

 

History

History
172 lines (120 loc) · 5.22 KB

s3.md

File metadata and controls

172 lines (120 loc) · 5.22 KB
Raw

ii S3 中转说明

ii send --s3 是 ii 的对象存储中转模式。发送端先把文件、stdin 内容或目录归档上传到 S3-compatible 存储，再生成 ii recv <ticket>；接收端只靠 ticket 下载，不需要长期 S3 密钥。

当前默认面向 Cloudflare R2。其它 S3-compatible 服务可以通过 ii.toml 增加或修改 profile。

命令

ii send .\video.mp4 --s3
ii send .\video.mp4 --s3 --profile work
ii send .\video.mp4 --s3 -d
ii recv <ticket>

参数含义：

  • --s3: 使用 S3/R2 中转，而不是点对点传输。
  • --profile <name>: 指定 S3 profile，只支持长参数，没有 -P。
  • -d: 接收端成功接收后尝试删除远端对象。

--s3 和 --webdav、--ftp、--sftp、--local、--relay、--no-relay 互斥。--profile 与 -d 只能在中转后端模式下使用。FTP 和 SFTP 的配置与安全限制见 ftp.md 和 sftp.md。

配置路径

S3 配置写入 ii.toml，默认路径固定：

  • Windows: ii.exe 同目录下的 ii.toml
  • Linux/macOS/其他 Unix-like: /etc/ii/ii.toml

ii.exe 只运行普通命令不会主动创建配置文件。第一次执行需要配置的命令，例如 ii send <file> --s3，才会在配置缺失并且上传成功后写入 ii.toml。

profile 规则

不传 --profile 时，S3 使用默认 profile default。旧配置里的 [storage.s3.cloudflare] 会自动兼容迁移为 [storage.s3.default]。

传 --profile work 时，会读取或创建：

[storage.s3.work]

首次缺配置时，ii 会在当前终端提示补齐 Cloudflare R2 字段：

ii: Cloudflare R2 is not configured.
Open this page:
https://dash.cloudflare.com/?to=/:account/r2/api-tokens

Account ID:
Bucket:
Access Key ID:
Secret Access Key:

Secret Access Key 是明文输入，不隐藏。配置只有在上传成功后才保存；上传失败、凭据错误或 bucket 不可用时，不写入坏配置。

配置格式

[storage]
backend = "s3"
profile = "default"

[storage.s3.default]
provider = "cloudflare-r2"
account_id = "xxxx"
bucket = "ii"
endpoint = "https://xxxx.r2.cloudflarestorage.com"
region = "auto"
access_key_id = "xxxx"
secret_access_key = "xxxx"
prefix = "ii/"
presign_ttl_seconds = 86400
path_style = true

字段说明：

  • provider: 默认是 cloudflare-r2。
  • account_id: Cloudflare R2 账号 ID，用来自动拼 endpoint。
  • bucket: 上传目标 bucket。
  • endpoint: S3-compatible endpoint。
  • region: Cloudflare R2 默认 auto。
  • access_key_id / secret_access_key: 只保存在本机 ii.toml，不会写入 ticket。
  • prefix: 远端对象前缀，默认 ii/。
  • presign_ttl_seconds: 预签名下载/删除链接有效期，默认 86400 秒。
  • path_style: 默认启用 path-style。

多个 profile 可以并存：

[storage.s3.work]
provider = "cloudflare-r2"
account_id = "work-account"
bucket = "work-bucket"
endpoint = "https://work-account.r2.cloudflarestorage.com"
region = "auto"
access_key_id = "..."
secret_access_key = "..."
prefix = "ii/"
presign_ttl_seconds = 86400
path_style = true

使用时：

ii send .\video.mp4 --s3 --profile work

对象命名和去重

文件和 stdin 这类有内容 MD5 的输入，远端对象 key 使用：

<prefix>/<md5>

默认就是：

ii/<md5>

中间没有 md5/ 目录，也不保留文件后缀。后缀不需要参与远端对象命名，真实文件名保存在 ticket 里，接收端落盘时仍按 ticket 文件名保存。

如果同 MD5 对象已经存在，ii send --s3 会跳过上传，直接复用已有对象并生成新的 ticket。

目录会先打成 tar 归档再上传；目录归档走随机对象 key，不做跨次 MD5 去重。

ticket 内容

S3 ticket 当前携带：

  • 文件名
  • 文件大小
  • 内容 MD5
  • payload 类型：文件、stdin 或目录
  • S3 object key
  • 短时有效的预签名下载 URL
  • 如果发送端加了 -d，还会携带短时有效的预签名删除 URL

ticket 不携带：

  • access_key_id
  • secret_access_key
  • 其它长期管理凭据

所以 ii recv <ticket> 不需要本机 S3 配置，也不会读取 S3 长期密钥。

接收和删除

接收端执行：

ii recv <ticket>

接收端继续复用本地文件规则：目标不存在就下载，目标更短就续传，同名同尺寸且 MD5 相同就跳过，同名不同内容就覆盖。

如果 ticket 里带有 -d 生成的删除授权，ii recv 在成功下载后会尝试删除远端对象；如果本地文件已经完整且 MD5 相同而直接跳过，也会尝试删除远端对象。删除失败只记录或忽略，不影响本地接收结果。

进度

ii send --s3 上传时会显示实时进度、速率和最终耗时。ii recv 从 S3 下载时也会显示实时进度、速率和最终耗时。

失败处理

非交互终端里缺配置时，ii send --s3 会直接报错，提示先在交互终端初始化一次或手工编辑 ii.toml。

交互终端里缺字段时，ii 会按顺序提示输入。当前实现不会在单次运行中循环重输错误字段；如果上传或校验失败，本次配置不会保存，用户需要重新执行命令或手工修正 ii.toml。