API 文档 | oss（吞吞）

oss S3 API

oss 兼容 S3 的桶与对象操作，支持 SigV4、Multipart Upload / UploadPartCopy / ListMultipartUploads、partNumber、Range GET 与 HEAD Range、ListObjects v1、版本三态、完整生命周期、桶策略与匿名 Principal、对象锁与保留期、事件通知、Select、复制与访问点。直接使用 aws-cli、rclone 或任意 S3 SDK。

服务端点：http://127.0.0.1:9000，路径风格访问。
认证：访问密钥 AK/SK，SigV4 签名。
完整命令与配置：oss README。

最小请求

aws --endpoint-url http://127.0.0.1:9000 s3api list-buckets
aws --endpoint-url http://127.0.0.1:9000 s3api head-object \
  --bucket photos --key cover.jpg

协议边界

partNumber 与 Range 同时出现 → 400 InvalidRequest；v1.15 起复制与 tier 摄入透传 part_sizes，MPU 分段边界保持可读。
GET 多区间 bytes=0-9,20-29 不返回 multipart/byteranges：未签入 Range 时剥离并返回 200 整对象；Range 计入 SigV4 SignedHeaders 时返回确定性 400 InvalidArgument。
匿名 AP 策略 Principal:"*" 与桶策略匿名基线取交集，仅放行数据面对象操作；控制面与对象锁/保留期头一律 403。
生命周期支持 AbortIncompleteMultipartUpload；STS 支持 AssumeRoleWithWebIdentity（默认关闭，需 OIDC 配置）；AP 跨账户已支持账户根 principal，VPC 端点真实 PrivateLink 身份仍为非目标。
Select 支持 CSV/JSON/Parquet 输入与 BZIP2/GZIP（BZIP2 仅 CSV/JSON；ScanRange 与压缩流互斥）。MPU 新 upload_id 可跨节点路由；存量裸 UUID 仍粘原节点。
Batch 支持同提交者协作抢占与跨账户清单（管理员）；OSSCTL2/3 快照分别携带 level-2/3 数据，旧读者明确拒绝。
v1.17：多租户账户 MVP（账户/成员/状态/桶数配额；账户写不参与 Raft）；AP 跨账户账户根 principal 与 aws:SourceVpce 来源证明。
v1.17：DP-0 数据面 wire 版本握手（混版 503 peer_incompatible）；M8 运行态 fencing；M7 未映射 REPLICA 对账（管理员 CLI/控制台，默认 dry-run）。
v1.17：tier 分块哈希与归档 Range 直读（默认关闭）；CMK 离线 scan/rewrap/delete/trash；REPLICA 头需 site token 认证。
v1.19：DP-1 数据面混版门控与降级头；能力级别 1..3/OSSCTL3（扩展区、Ext 容器，生产 registry 为空）；租户 schema/回填与 M8 运行态快照；maintenance 与 cluster-shrink plan 只读规划。缩容 apply、Raft 租户 API、M8 多节点与生产 Ext 命令未交付。
v1.20：mesh gRPC 入站 TLS 物料热轮换（新连接取新配置，旧连接保持旧物料）；账户/成员写走 7 个 level-3 Raft 命令（按 username 自然键，OSSCTL3 快照含账户行）；缩容 topology v4 与离线 apply/verify/commit/rollback（v4 只在 commit 写，作回退防线）；滚动 e2e 在同版本 3 节点与 v1.13.1 旧二进制上通过。
v1.24.0：M8-2 inventory 三表与 lifecycle 游标经 level-5 Raft 命令复制（独立激活标记；旧本地历史不迁移；feature 5 单向门）；桶删除 apply 级联。
v1.23.0：M8-2 jobs/job_tasks 与 Restore 受理行经 level-4 Raft 命令复制（feature 4，全 peer ≥4 才启用；旧节点单向门）；重试抖动修复；LC-4 回滚矩阵与 4 节点 re-ingest e2e。
v1.22.0：桶数量硬配额并发原子（leader append 前/standalone 写锁）；follower 权限追赶；只读 tier-audit；升级 preflight 与单机→集群 re-ingest 脚本；Level C v1.20.1 窗口验证。
v1.21.1：文档补丁，无代码/API 变更；同步文档与站点并清理已删除的旧兼容线引用。
v1.21：控制台一致读 ?consistent=1 + x-oss-applied-index；账户管理员 UI；tier 归档/直读绑定源整对象 SHA-256（C1–C4）；AP 静态 VPC 端点 registry（注册断言）；Raft follower 滞后时 attach/member-status 追赶。硬配额、M8-2 运行态复制与 Level C 完整双向混写仍未交付。
v1.20.1：账户软字节配额只读用量端点 GET /accounts/{id}/usage 与独立配置路由 PUT /accounts/{id}/soft-quota（只告警不阻写；集群丢 peer 时 complete=false/头 partial）；level-3 AccountSetSoftQuota 命令，混版窗口需先全集群升级；缩容 4→3 真进程 loopback e2e（97/0）；修复 v1.20.0 源码归档的 Cargo.lock。

继续阅读

安装文档：Docker、源码构建与首次启动。
使用说明：S3 操作、控制台、版本、加密与强一致。
版本日志：从 v1.0.0 到 v1.24.0。
oss README：完整协议与运维细节（随发布同步）。