rustfs/docs/operations/issue-712-zero-copy-eager-put-ops-guide-zh.md

Issue #712 zero_copy_eager plain PUT 验证手册

1. 目的

本文用于记录当前 zero_copy_eager plain PUT 路径的实际使用方式、验证命令和当前边界。

这条路径当前的目标不是“端到端完全零拷贝”，而是先把 ordinary PUT 从“只有 zero-copy eligibility / metrics”推进到：

1. 真实存在的业务路径
2. 真实命中可观测的 put_path
3. 先减少请求体聚合阶段的额外复制

2. 当前启用条件

当前 zero_copy_eager 只在下面条件同时满足时才会命中：

1. 非加密
2. 非压缩
3. 非 extract 请求
4. 对象大小 > 1MiB
5. 对象大小 <= 32MiB
6. 请求长度已知
7. 不属于需要特殊处理的 aws-chunked 未知长度场景

3. 当前实现边界

这条路径已经是真实业务路径，但当前还不是端到端严格意义上的 zero-copy。

已经做到：

1. 请求体 chunk 以 Bytes 形式进入 zero_copy_eager
2. 不再先把整个对象拼成一个大 Vec<u8> 再进入后续写路径
3. 运行时会记录 put_path=zero_copy_eager
4. 会真实记录 rustfs_zero_copy_write_total

尚未做到：

1. HashReader 之后完全无复制
2. Erasure::encode 的 block ingest 完全无复制
3. shard write 全链路严格 zero-copy

因此当前最准确的描述是：

1. 这是 ordinary PUT 的真实 zero-copy eager ingress 路径
2. 不是完整的 end-to-end zero-copy write path

4. 推荐验证命令

4.1 启动本地单机多盘 RustFS

env \
  RUSTFS_UNSAFE_BYPASS_DISK_CHECK=true \
  RUSTFS_ADDRESS=127.0.0.1:9000 \
  RUSTFS_ACCESS_KEY=rustfsadmin \
  RUSTFS_SECRET_KEY=rustfsadmin \
  RUSTFS_RPC_SECRET=rustfs-rpc-secret \
  RUSTFS_REGION=us-east-1 \
  RUSTFS_CONSOLE_ENABLE=false \
  RUSTFS_OBS_ENDPOINT=http://127.0.0.1:4318 \
  target/debug/rustfs server \
  /private/tmp/issue708-single-node-multidisk/d1 \
  /private/tmp/issue708-single-node-multidisk/d2 \
  /private/tmp/issue708-single-node-multidisk/d3 \
  /private/tmp/issue708-single-node-multidisk/d4

4.2 小面 ordinary PUT 验证

bash scripts/run_put_large_stage_breakdown.sh \
  --endpoint http://127.0.0.1:9000 \
  --access-key rustfsadmin \
  --secret-key rustfsadmin \
  --sizes 16MiB,32MiB \
  --concurrencies 16 \
  --duration 60s \
  --rounds 1 \
  --retry-per-round 1 \
  --retry-sleep-secs 2 \
  --cooldown-secs 15 \
  --out-dir target/bench/issue712-zero-copy-eager-put-verify

5. 运行时必须核对的指标

5.1 PUT path 命中

必须确认：

rustfs_s3_put_object_path_total{
  path=~"zero_copy_eager|small_eager|streaming|stream_compressed"
}

如果看不到 zero_copy_eager：

1. 说明本轮没有真正命中这条路径
2. 不能据此评价它的收益

5.2 zero-copy write 指标

建议同时看：

rustfs_zero_copy_write_total

rustfs_zero_copy_write_size_bytes_sum

5.3 普通 PUT summary

最终固定读取：

1. aggregate_median_summary.csv

6. 当前已知结果

当前分支上已经验证过一次小面 ordinary PUT：

1. 16MiB, c16: 318.77 MiB/s, 851.3ms
2. 32MiB, c16: 276.38 MiB/s, 1846.5ms

并确认运行时命中了：

1. put_path=zero_copy_eager

这说明：

1. 这条路径已经不只是 eligibility / metrics
2. 它已经是真实参与 ordinary PUT 的运行时路径

7. 当前最稳妥的使用建议

当前阶段建议把这条路径当作：

1. 实验性 ordinary PUT 优化路径
2. 需要继续压测验证的真实实现

当前不建议把它描述成：

1. 已完成的端到端 zero-copy write path

8. 下一步方向

如果要继续把收益往下穿透，下一阶段优先顺序建议是：

1. 先继续验证 zero_copy_eager 的普通 PUT 命中率和端到端收益
2. 再评估是否要继续下钻 Erasure::encode 的 block ingest
3. HashReader 层暂时不是第一优先级