sail — S3 对象存储 CLI

基于标准 S3 协议的命令行工具。单个静态二进制,零运行时依赖,跨平台开箱即用。

sail 面向任何兼容 S3 协议的对象存储服务(AWS S3、MinIO、阿里云 OSS 以及各类自建 S3 兼容服务),提供上传/下载、列举、删除、复制/移动、内容查看、预签名 URL 等日常操作。它不绑定任何特定云厂商,配置即用。

开源地址:https://github.com/BeCrafter/sail
问题反馈:https://github.com/BeCrafter/sail/issues

特性

标准 S3 协议:path-style + SigV4 签名,兼容 AWS S3 / MinIO / 阿里云 OSS 及各类自建 S3 兼容服务
丰富的传输:单文件、目录递归、管道流式上传,大文件自动分片(5MB/16 并发)
批量操作:URL 通配符(cp/rm 's3://b/*.log' 展开)、批量删除(DeleteObjects 每批 1000)、管道逐行删除(ls | rm -r -)
对象与桶管理:下载、列举(长格式/目录视图/树形/排序/列桶)、目录占位对象(mkdir/rmdir)、桶管理(mb/rb)、删除(批量/管道)、复制/移动(本地↔s3、s3↔s3 服务端复制零带宽)
增量同步:rsync 式 sync(大小+时间比对,--checksum 内容校验、--update、--exclude/--include 过滤、--delete、--dry-run),本地↔s3↔s3
检索统计:find(名称/大小/时间过滤)、du(按前缀层级统计占用)
内容查看:多格式智能渲染——文本/JSON/YAML/CSV/XML/图片终端字符画/二进制;head/tail/wc/grep 流式读写不落盘
校验与鉴权:checksum(md5/sha256 计算与比对)、presign 预签名 URL、基于 CDN 域名的公开访问地址
多 profile 配置:prod / test / staging 等多环境切换,密钥可引用环境变量避免明文
跨平台:macOS / Linux,单二进制下载即用;支持 shell 自动补全(zsh / bash / fish)

安装

方式一:npm 安装(推荐,跨平台)

npm install -g @becrafter/sail

npm 会按操作系统和 CPU 架构自动只下载一个匹配的平台二进制,sail 命令开箱即用。支持 macOS(arm64/x64)、Linux(arm64/x64),二进制托管在 npm registry,无需额外联网下载。

方式二:下载二进制

到 Releases 页面下载对应平台的二进制,放入 PATH 即可。

方式三:go install

go install github.com/BeCrafter/sail@latest

方式四:源码构建

git clone https://github.com/BeCrafter/sail.git
cd sail && go build -o sail .

配置

快速初始化

sail config setup

交互式生成或更新 ~/.sail/config.yaml(--reset 重置为全新配置;文件已存在时新增或重配一个 profile,保留其它),并可选安装 shell 自动补全。向导要点:

endpoint 为必填项,留空会原地重问
access-key / secret-key 可直接输入明文;回车留空则引用按 profile 派生的环境变量(机制见下方"密钥安全"),写盘后会打印需要 export 的变量名
重配已有 profile 时,已配置的明文密钥不回显,回车即保留
写盘后输出配置摘要,空字段明确标注,便于核对缺失项

# 密钥可用 ${VAR} 引用环境变量,避免明文。
default-profile: prod
profiles:
  prod:
    endpoint: <your-s3-endpoint>
    access-key: ${SAIL_PROD_ACCESS_KEY}
    secret-key: ${SAIL_PROD_SECRET_KEY}
    bucket: ""
    region: ""
    path-style: true
    cdn-domain: <your-cdn-domain>
    # cdn-bucket-path: false  # CDN 域名是否已含 bucket 路径;注释掉则自动检测
  test:
    endpoint: <your-s3-endpoint-test>
    access-key: ${SAIL_TEST_ACCESS_KEY}
    secret-key: ${SAIL_TEST_SECRET_KEY}
    bucket: ""
    region: ""
    path-style: true
    cdn-domain: <your-cdn-domain-test>
  staging:
    endpoint: <your-s3-endpoint-staging>
    access-key: ${SAIL_STAGING_ACCESS_KEY}
    secret-key: ${SAIL_STAGING_SECRET_KEY}
    bucket: ""
    region: ""
    path-style: true
    cdn-domain: <your-cdn-domain-staging>

向导中留空 access-key/secret-key 时,会自动写入按 profile 派生的占位符 SAIL_<PROFILE>_(ACCESS|SECRET)_KEY(profile 名大写、连字符等非字母数字字符转下划线,清洗后为空则回退 SAIL_ACCESS_KEY 全局名);配置文件中也可手动改为任意 ${VAR}。

cdn-domain 说明

cdn-domain 用于 sail url 命令生成文件的公开访问地址,填入你的存储服务对应的 CDN 域名即可。

bucket 去重:sail url 会检查 cdn-domain 的路径是否已包含 bucket 段(路径式 .../bucket/),若已包含则不再重复拼接,避免生成 .../bucket/bucket/key 这类失效链接。自动检测仅按路径段判断、不做子域推断;若自动检测失效或有特殊映射(如域名直接映射到 bucket、URL 不含 bucket),可用配置项 cdn-bucket-path 显式声明:true 表示域名已含 bucket(不再追加),false 表示未含(总是追加),注释掉则自动检测;也可用 --no-bucket 单次指定。

注意:只有 public-read 权限的 bucket 的文件才能通过 CDN 域名访问;私有 bucket 只能通过鉴权的 GetObject 访问。

region 与 path-style 说明

这两个是 S3 协议的通用参数,根据你接入的存储服务选择:

参数	含义	AWS S3	MinIO / 自建	阿里云 OSS
`region`	数据中心区域	填实际值如 `us-east-1`	留空	填如 `oss-cn-hangzhou`
`path-style`	URL 寻址方式	`false`(virtual-hosted)	`true`	`false`

path-style:true 时 URL 为 endpoint/bucket/key;false 时 URL 为 bucket.endpoint/key。自建 S3 兼容服务通常只支持 path-style。
region:自建服务通常留空。AWS SDK 内部规则要求 region 非空,留空时代码自动用 us-east-1 占位(不影响实际请求目标,因 endpoint 已被覆盖)。

密钥安全

配置文件中的密钥有两种写法:直接明文,或用 ${VAR} 引用环境变量(避免明文落盘):

access-key: my-plain-access-key        # 写法一:明文
access-key: ${SAIL_TEST_ACCESS_KEY}    # 写法二:引用环境变量

sail config setup 中回车留空密钥时,自动采用写法二并按 profile 派生变量名(profile test → SAIL_TEST_ACCESS_KEY,staging-eu → SAIL_STAGING_EU_ACCESS_KEY,即大写、连字符等非字母数字字符转下划线;清洗后为空回退 SAIL_ACCESS_KEY),各环境互不共享。向导结束时会打印需要 export 的变量名,例如:

export SAIL_TEST_ACCESS_KEY="your-access-key"
export SAIL_TEST_SECRET_KEY="your-secret-key"

未设置这些变量时,sail 命令启动会报 缺少 access-key/secret-key。

注意区分两类环境变量:文件内 ${VAR} 引用的变量(按 profile 派生,如 SAIL_TEST_ACCESS_KEY)负责给密钥赋值;下方"环境变量覆盖"表中的 SAIL_ACCESS_KEY 等是运行时全局覆盖,一旦设置会无视配置文件直接生效。生效优先级:全局覆盖环境变量 > 配置文件内 ${VAR} 展开 > 空(启动报缺少密钥)。

环境变量覆盖

变量	作用
`SAIL_ENDPOINT`	覆盖 endpoint
`SAIL_ACCESS_KEY`	覆盖 access key
`SAIL_SECRET_KEY`	覆盖 secret key
`SAIL_BUCKET`	覆盖默认 bucket
`SAIL_CDN_DOMAIN`	覆盖 CDN 域名

使用

路径语法:s3://bucket/key 显式指定 bucket;s3:///key(空 bucket 段)用配置的默认 bucket;s3://bucket 仅 ls 列桶。跨桶同步仍用显式 s3://bucket/key。

# 查看版本
sail --version          # 或 sail -v

# 复制(本地↔s3、s3↔s3);upload/download 为 cp 的别名
sail cp local.txt s3://mybucket/path/local.txt
sail cp local.txt s3:///path/local.txt           # s3:/// 用配置默认 bucket
sail upload local.txt                            # 1 参:上传到默认 bucket,key 用文件名
sail cp -r ./dir s3://mybucket/prefix/           # 递归镜像目录
sail cp 's3://mybucket/logs/*.log' s3://mybucket/archive/   # 通配符批复制(* 跨 /,保留层级)
sail cp 's3://mybucket/*.json' ./download-dir/   # 通配符批量下载
cat file | sail upload - s3://mybucket/key       # 管道输入

# 桶管理(mb/rb 与 ls --buckets)
sail mb s3://my-new-bucket
sail rb s3://my-old-bucket                       # 仅删空桶;非空先 sail rm -r s3://my-old-bucket/
sail ls --buckets                                # 列出所有桶

# 下载(s3→本地);download 为 cp 的别名
sail cp s3://mybucket/key local.txt
sail download s3://mybucket/key                  # 1 参:下载到当前目录

# 列举
sail ls s3://mybucket/prefix/
sail ls -l s3://mybucket/                        # 长格式:大小+修改时间
sail ls -l -t s3://mybucket/                     # 按修改时间排序(新→旧),--human 人类可读大小
sail ls -l -S -r s3://mybucket/                  # 按大小排序(大→小)再逆序
sail ls -d s3://mybucket/prefix/                 # 只列该层子目录(不含文件),对齐 ls -d

# 查找与统计
sail find s3://mybucket/logs --name '*.log' -l   # 按文件名通配(可重复多个)
sail find s3://mybucket --size +1M --newer 2026-01-01   # 大小/时间过滤
sail du -h s3://mybucket/prefix/                 # 按前缀层级统计占用
sail du -h --max-depth 1 s3://mybucket           # 只显示 1 层 + 总计
sail du -s s3://mybucket/prefix/                 # 只打印总计

# 树形查看(S3 前缀或本地目录)
sail tree s3://mybucket/prefix/                  # 完整树
sail tree -L 2 s3://mybucket/prefix/             # 限深度 2
sail tree -d s3://mybucket/prefix/               # 只显目录
sail tree -s --human s3://mybucket/prefix/      # 文件附人类可读大小
sail tree ./cmd                                  # 本地目录树

# 删除与目录占位对象
sail rm s3://mybucket/key
sail rm -r s3://mybucket/prefix/                 # 递归删除(批量 DeleteObjects,每批 1000)
sail rm key1 key2 key3                          # 多参数批量
sail rm 's3://mybucket/logs/*.tmp'              # 通配符匹配删除
sail ls s3://mybucket/prefix/ | sail rm -r -    # 管道逐行读取 key(xargs 式)
sail mkdir s3://mybucket/new/dir/               # 目录占位对象(天然 -p 语义)
sail rmdir s3://mybucket/new/dir/               # 只删空目录;非空请用 rm -r

# 增量同步(rsync 式:大小+修改时间比对,幂等;--help 查看全部选项)
sail sync ./dir s3://mybucket/mirror/
sail sync --exclude '*.tmp' --delete ./dir s3://mybucket/mirror/
sail sync --include '*.json' s3://mybucket/mirror/ ./dir2 --dry-run   # 白名单 + 预演
sail sync --checksum ./dir s3://mybucket/mirror/  # 大小相同时按内容 md5 校验
sail sync --update ./dir s3://mybucket/mirror/    # 只传输比目标新的条目

# 预签名 URL(部分服务不支持,见下方"限制")
sail presign s3://mybucket/key --expires 3600

# 生成 CDN 访问地址
sail url s3://mybucket/path/file.jpg
sail url s3://mybucket/path/file.jpg --cdn https://<your-cdn-domain>
sail url s3://mybucket/path/file.jpg --no-bucket   # CDN 域名已含 bucket 路径,不再重复追加

# 查看对象/文件内容(按格式智能渲染,本地文件免配置)
sail view s3://mybucket/config.json              # JSON 自动美化缩进
sail view ./local.log                            # 文本/代码直出
sail view s3://mybucket/data.csv                # CSV 表格对齐
sail view s3://mybucket/photo.png               # 图片终端字符画(半块字符,任意终端可见)
sail view s3://mybucket/data.json --raw         # 原样输出,适合管道:sail view ... --raw | jq .
sail cat s3://mybucket/data.json                 # cat 是 view --raw 的别名
sail view s3://mybucket/big.json --force        # 跳过大小限制
sail view s3://mybucket/photo.png --width 60    # 指定字符画列宽

# 流式读取内容(s3 路径走 Range 只取需要的部分,不下载全量)
sail head -n 20 s3://mybucket/logs/app.log      # 开头 N 行
sail head --bytes 4096 s3://mybucket/data.bin   # 开头 N 字节
sail tail -n 50 s3://mybucket/logs/app.log      # 结尾 N 行(Range 尾部窗口)
sail wc -l s3://mybucket/logs/app.log           # 行数(默认三列:行 词 字节)
sail grep -n "ERROR" s3://mybucket/logs/app.log # 正则逐行搜索(支持 -i/-v/-l/-n)

# 校验和(md5/sha256 流式计算与比对,本地文件免配置)
sail checksum s3://mybucket/data.bin            # 默认 md5
sail checksum --algo sha256 --compare ./local.bin s3://mybucket/data.bin
sail checksum --etag s3://mybucket/data.bin     # 展示原始 ETag(注意:分片对象 ETag≠内容 md5)

# 复制对象/文件(本地↔s3、s3↔s3 走服务端 CopyObject 零带宽)
sail cp ./local.txt s3://mybucket/path/copied.txt
sail cp ./local.txt s3://mybucket/path/          # 尾 / 表示进目录
sail cp s3://mybucket/a.txt ./out.txt
sail cp -r ./dir s3://mybucket/mirror/           # 递归镜像本地目录
sail cp -r s3://mybucket/prefix/ s3://mybucket/dest/   # 服务端递归复制
sail cp --dry-run ./local.txt s3://mybucket/x   # 预演,不实际复制

# 移动对象/文件(复制后删除源)
sail mv s3://mybucket/a.txt s3://mybucket/moved.txt     # 单对象,无确认
sail mv ./local.txt s3://mybucket/uploaded.txt
sail mv -r s3://mybucket/src/ s3://mybucket/dst/         # 递归,交互确认 [y/N]
sail mv -r --yes s3://mybucket/src/ s3://mybucket/dst/   # 跳过确认

# 查看对象/文件元信息(HeadObject / os.Stat)
sail stat s3://mybucket/config.json             # size/content-type/last-modified/etag
sail stat ./local.log                           # 本地文件元信息

# 切换 profile
sail -p test upload local.txt s3://testbucket/local.txt

与 AWS CLI 对照验证

行为与 aws s3 一致,可用 AWS CLI 对照:

aws s3 ls --endpoint-url <your-s3-endpoint> s3://mybucket/

限制

Bucket 与 Object key 的命名规则、长度上限取决于所接入的 S3 服务,遵循各服务约束。
部分 S3 兼容服务不支持预签名 URL:某些自建 S3 服务不支持 query string 认证(返回 "Authorization empty"),只支持 Authorization header 认证。如需公开访问,请通过 CDN 域名访问已设置为公开的文件。

实现细节

S3 兼容性适配

部分自建 S3 兼容服务与标准 AWS S3 存在差异,工具已做适配:

checksum 禁用:AWS SDK v2 默认在上传时使用 aws-chunked content encoding + CRC32 trailing checksum。部分 S3 兼容服务端不解码 aws-chunked,导致存储的数据被 trailer 污染(大文件 multipart upload 尤其严重)。工具在 client 和 uploader 两处均设置了 RequestChecksumCalculation = WhenRequired 和 ResponseChecksumValidation = WhenRequired 来禁用此行为。
region 占位:部分 S3 服务 region 为空,但 AWS SDK v2 的 endpoint 规则要求 region 非空。工具用 us-east-1 作为占位值(endpoint 已被 BaseEndpoint 覆盖,实际不影响请求)。
CopyObject 回退:部分 S3 兼容服务的 CopyObject 返回成功但生成 0 字节对象。cp/mv 的 s3↔s3 路径在 CopyObject 后用 HEAD 校验目标大小与源一致;不一致时自动回退到 download→re-upload,保证数据正确。标准 S3(AWS/MinIO)上 CopyObject 校验通过,仍走零带宽服务端复制。

发布

发布走 GitHub Actions 自动化:推送形如 vX.Y.Z 的 tag 即触发交叉编译 + 发布到 npm,无需本地登录。

在仓库 Settings → Secrets and variables → Actions 添加 NPM_TOKEN(npm automation token,需有 @becrafter scope 发布权)。

打 tag 并推送:

git tag v0.1.0 && git push origin v0.1.0

workflow 跑完,4 个平台子包 + 主包即发布到 registry.npmjs.org。也可在 Actions 页面手动触发并填版本号。

本地发布(无 CI 时)仍可用:make release VERSION=0.1.0(未登录会引导 npm login)。

贡献

欢迎提 Issue 或 Pull Request:https://github.com/BeCrafter/sail/pulls

许可证

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
cmd		cmd
internal		internal
npm		npm
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Navigation Menu

Uh oh!

Repository files navigation

sail — S3 对象存储 CLI

特性

安装

方式一:npm 安装(推荐,跨平台)

方式二:下载二进制

方式三:go install

方式四:源码构建

配置

快速初始化

cdn-domain 说明

region 与 path-style 说明

密钥安全

环境变量覆盖

使用

与 AWS CLI 对照验证

限制

实现细节

S3 兼容性适配

发布

贡献

许可证

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

sail — S3 对象存储 CLI

特性

安装

方式一:npm 安装(推荐,跨平台)

方式二:下载二进制

方式三:go install

方式四:源码构建

配置

快速初始化

cdn-domain 说明

region 与 path-style 说明

密钥安全

环境变量覆盖

使用

与 AWS CLI 对照验证

限制

实现细节

S3 兼容性适配

发布

贡献

许可证

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages