使用吞吞

常用 S3 操作

把 endpoint、AK、SK 准备好后，aws-cli 的常用命令可以直接使用。区域可以填任意值，服务端按签名与桶配置处理。

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=us-east-1
E=http://127.0.0.1:9000

aws --endpoint-url $E s3 mb s3://photos
aws --endpoint-url $E s3 cp ./cover.jpg s3://photos/cover.jpg
aws --endpoint-url $E s3 ls s3://photos/
aws --endpoint-url $E s3 presign s3://photos/cover.jpg --expires-in 3600
aws --endpoint-url $E s3 rm s3://photos/cover.jpg

大文件会自动走 multipart。Range GET、x-amz-meta-*、Storage Class 与对象标签都按 S3 语义处理。

Multipart、partNumber 与 Range

除普通分块上传外，还支持从已有对象复制分段、列举未完成上传，以及按段读取。

# 从源对象复制一段作为 part（区间为闭区间）
aws --endpoint-url $E s3api upload-part-copy --bucket photos \
  --key big.bin --upload-id <upload-id> --part-number 2 \
  --copy-source photos/source.bin --copy-source-range bytes=0-5242879

# 列举未完成的分块上传
aws --endpoint-url $E s3api list-multipart-uploads --bucket photos

# 读取第 2 段
aws --endpoint-url $E s3api get-object --bucket photos --key big.bin \
  --part-number 2 part2.bin

• ListObjects v1 已实现：aws s3api list-objects 支持 marker / delimiter / max-keys。
• HEAD 支持单区间 Range；多区间 GET 不返回 multipart/byteranges，服务端会剥离 Range 并返回 200 整对象。
• 若客户端把 Range 计入 SigV4 SignedHeaders，剥离后验签会失败（403 SignatureDoesNotMatch）；预签名 URL 不受影响。

控制台

控制台是 React 19 + antd 的单页应用，覆盖桶、对象、用户、访问密钥、权限、访问点、作业、Inventory、分层与 Raft 集群状态。

• 开发模式：后端 9000，前端 5173。
• Compose 模式：控制台由 nginx 提供，默认 8080。
• 登录后先创建访问密钥，再让 aws-cli 或 SDK 使用。

控制台里的桶模式、版本控制、生命周期与访问点操作，最终都会走同一套控制面命令。单机是本地 SQLite，强一致模式经 Raft 提交。

版本与生命周期

版本控制支持 Off / Enabled / Suspended 三态。开启后删除对象会生成 delete marker，旧版本仍可读取与恢复；Suspended 下只替换 null 版本。

aws --endpoint-url $E s3api put-bucket-versioning \
  --bucket photos --versioning-configuration Status=Enabled

aws --endpoint-url $E s3api list-object-versions --bucket photos
aws --endpoint-url $E s3api get-object --bucket photos --key cover.jpg \
  --version-id <version-id> cover.old.jpg

生命周期规则可在控制台配置，也可以走 S3 API。支持 tag / size / And Filter、Expiration.Date、ExpiredObjectDeleteMarker、多转换、noncurrent expiration / transition 与分层 Restore。对象生命周期图如下。

加密与对象锁

oss 支持 SSE-S3 与 SSE-KMS 两种服务端加密模式，密钥库启用后访问密钥的 SK 也会加密落库。对象锁需要桶在创建时开启，开启后按保留策略阻止覆盖与删除。

# 服务端加密上传
aws --endpoint-url $E s3api put-object \
  --bucket photos --key secret.bin \
  --body ./secret.bin --server-side-encryption AES256

# 对象锁桶需要创建时开启
aws --endpoint-url $E s3api create-bucket \
  --bucket legal --object-lock-enabled-for-bucket

STS 临时凭据分为 AssumeRole 与 GetSessionToken。AssumeRole 只允许管理员调用，避免子账户自铸管理员会话。

保留期与匿名访问

对象锁桶可对指定版本设置保留期。COMPLIANCE 到期前不可缩短或清除；GOVERNANCE 需要 x-amz-bypass-governance-retention 才能缩短。控制台对象列表会显示 retention / legal-hold 状态。

aws --endpoint-url $E s3api put-object-retention \
  --bucket legal --key doc.pdf --version-id <version-id> \
  --retention 'Mode=COMPLIANCE,RetainUntilDate=2027-01-01T00:00:00Z'

aws --endpoint-url $E s3api get-object-retention \
  --bucket legal --key doc.pdf --version-id <version-id>

匿名访问只对数据面对象操作生效，且必须由桶策略显式 Allow；控制面、桶级操作、对象锁头一律拒绝。示例策略：

{
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"AWS": "*"},
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::photos/*"
  }]
}

配置后可用无签名请求读取：curl $E/photos/cover.jpg -o cover.jpg。传输层加密（监听器、Raft/mesh、site/repl/tier、Kafka）见 安装页的 TLS 章节。

事件与复制

事件通知通过 oss.toml 配置 Kafka 目标，桶上再写通知配置。S3 Select 走事件与查询路径，桶复制与多站点复制负责把版本送到另一个位置。

• 事件：桶事件写入 event_outbox，worker 投递到 Kafka，失败重试与死信可查。
• Select：支持 CSV / JSON 查询，结果流式返回，限制在内存预算内。
• 复制：每桶规则、PENDING 到 COMPLETED 状态、停机积压追平与 marker 处理。

强一致

强一致模式把控制面放到 Raft 上，并把跨站点数据面分成两种模式。两者互斥，按桶或按集群选择。

sync 桶通过控制台创建时选择 sync 模式，或调用控制面 API：

curl -s -X POST http://127.0.0.1:9000/api/v1/buckets \
  -H "authorization: Bearer <token>" \
  -H 'content-type: application/json' \
  -d '{"name":"compliance","replication_mode":"sync"}'

强一致的成员变更、witness 部署、cutover 与 force recovery 是运维动作，按 README 的 runbook（随发布同步）执行。不要在运行中的集群手改 raft.db。

控制面滚动升级

控制面可以逐节点替换：保持 [raft].feature_level = 1（默认），先升级所有 voter 与 learner；leader 的生效级别取当前 voter/learner 的最小值。全部节点都升级后，再把 feature_level 改为 2 或 3（范围 1..=3）并重启，激活会写入 schema_meta.raft_feature_level。级别 3/OSSCTL3 当前承载账户、运行态扩展与 Ext 容器，生产 Ext registry 为空。

• 回滚只在激活前可行（停集群、换回旧二进制、删除 feature_level 键后启动）；激活后必须换回支持该级别的二进制。
• 成员 add/promote 会预检目标节点的 wire/feature 级别，混合版本时返回 409 并拒绝。
• 数据面自 v1.19.0 起为 DP-1 混版门控（NodeHealth wire/epoch/hash；ListObjects V1 带 x-oss-degraded: list-marker、LMU 带 mpu-union，ListObjectVersions 与 MPU 转发对旧对端 fail-closed）；v1.20.0 起 mesh gRPC 入站支持 TLS 物料热轮换（新连接取新配置，旧连接保持旧物料），并已有同版本 3 节点与 v1.13.1 旧二进制的滚动 e2e 通过；生产升级仍需维护窗口。

运维命令

服务端二进制自带巡检、修复、扩容与清理命令。建议先用只读或 dry-run 看报告，再执行写操作。

oss-server clean 1          # 回收 1 天前的 tmp/trash 残骸
oss-server fsck             # 全盘巡检，报告落 .oss.sys/fsck/
oss-server fsck --repair    # 最小修复：删孤儿 + 读时修
oss-server heal             # fsck --repair + 桶目录补建
oss-server scrub            # 深度巡检，逐块对偶校验
oss-server rebalance --dry-run
oss-server rebalance --apply
oss-server cluster-shrink plan --to shrink.toml --json      # 只读规划
oss-server cluster-shrink apply --plan plan.json --yes  # 离线拷贝
oss-server cluster-shrink verify --plan plan.json       # 校验
oss-server cluster-shrink commit --plan plan.json --yes # 写 topo v4
oss-server cluster-shrink rollback --plan plan.json --yes # commit 前回滚

巡检与修复不要和在途上传、写入并跑。每节点各自执行，远端孤儿只由该节点自己回收。

能力边界

以下能力仍是明确非目标，或需要单独的架构工作；调用会 fail-closed 或返回 501：

已知限制：复制/tier 摄入已透传 part_sizes；签名内的多区间 Range 返回确定性 400 InvalidArgument；MPU 存量裸 UUID 仍粘原节点；tier 直读默认关闭且仅支持 Range；未映射 legacy 副本需管理员对账；AP 转发头只在 TLS 监听器 + 可信对端 CIDRS 下采信；DP-1 混版窗口的 ListObjects V1/LMU 可能重复或缺项（降级头标记），ListObjectVersions 与 MPU 转发对旧对端 fail-closed。完整清单见 README 与版本日志。

继续阅读

• README：完整配置、S3 API、控制面与强一致 runbook（随发布同步）。
• 安装文档：Docker、源码、首次启动与访问密钥。
• 版本日志：每个版本的变更与验收记录。
• API 文档：S3 端点、认证、最小请求与协议边界。