rustfs/docs/operations/issue-712-multipart-put-server-path-validation-runbook-zh.md

Issue #712 multipart PUT server-path 静默验证 Runbook

1. 目的

本文给 #712 第二批工作提供一个只关注 multipart server path 的静默验证 runbook。

目标：

1. 不再扩散客户端参数矩阵
2. 固定当前推荐 baseline
3. 把注意力集中到 server-path 观测增强后的阶段结果

2. 固定 baseline

当前固定 baseline：

1. 1GiB -> 64MiB part / pc4
2. 2GiB -> 128MiB part / pc4

可选补充：

1. 2GiB -> 256MiB part / pc4

但默认不作为首选 baseline。

3. 推荐脚本

直接使用：

1. scripts/run_gt1g_multipart_put_server_path_focus.sh

该脚本默认只跑：

1. 1g-64m-pc4
2. 2g-128m-pc4

可选补充：

1. 2g-256m-pc4

4. 静默执行命令

4.1 默认两组

bash scripts/run_gt1g_multipart_put_server_path_focus.sh \
  --host 127.0.0.1:9000 \
  --access-key rustfsadmin \
  --secret-key rustfsadmin \
  --bucket-prefix issue712-multipart-focus \
  --duration 10m \
  --out-dir target/bench/issue712-multipart-server-path-focus

4.2 加上 2g-256m-pc4

bash scripts/run_gt1g_multipart_put_server_path_focus.sh \
  --host 127.0.0.1:9000 \
  --access-key rustfsadmin \
  --secret-key rustfsadmin \
  --bucket-prefix issue712-multipart-focus \
  --duration 10m \
  --profiles 1g-64m-pc4,2g-128m-pc4,2g-256m-pc4 \
  --out-dir target/bench/issue712-multipart-server-path-focus-wide

5. 强制要求

这轮 runbook 的要求是：

1. 静默跑
2. 只读 summary.csv
3. 如需解释异常，再去看 dashboard / 日志

6. 结果目录

建议统一：

target/bench/
  issue712-multipart-server-path-focus/
    run_manifest.txt
    commands.txt
    summary.csv
    logs/
    benchdata/

7. 需要记录的指标

最终结果表之外，强制记录以下阶段：

1. multipart_ingress_prepare
2. multipart_set_disk_writer_setup
3. multipart_set_disk_encode
4. multipart_complete_tail

同时建议固定记录 multipart path 计数：

1. multipart_write_pipeline
2. multipart_write_pipeline_batched_large
3. multipart_write_single_block_non_inline

8. 本轮的判断顺序

先看：

1. summary.csv

再看：

1. multipart_complete_tail
2. multipart_set_disk_encode
3. multipart_set_disk_writer_setup
4. multipart_ingress_prepare

9. 结果解释

9.1 summary.csv 先分出好坏组合

先回答：

1. 1GiB / 64MiB / pc4 是否仍是最稳 baseline
2. 2GiB / 128MiB / pc4 是否仍是最稳 baseline

9.2 再用 Dashboard 回答热点层

再回答：

1. multipart_complete_tail 是否最高
2. multipart_set_disk_encode 是否主导
3. multipart_set_disk_writer_setup 是否异常高
4. multipart_ingress_prepare 是否已经被 body buffering 放大

10. 下一步动作判定

如果 multipart_set_disk_encode 最高

下一步优先：

1. multipart part 专用 batching gate
2. multipart encode path 单独策略

如果 multipart_complete_tail 最高

下一步优先：

1. complete path metadata / checksum / rename tail 优化

如果 multipart_set_disk_writer_setup 最高

下一步优先：

1. writer init / bitrot writer path 优化

如果 multipart_ingress_prepare 最高

下一步优先：

1. part ingress buffer 分层
2. body read / HashReader 前的缓冲调整

11. multipart_* 指标为空时的排查顺序

如果本轮跑的是 multipart PUT，但 Prometheus 里查不到任何 multipart_* stage：

1. 先不要直接判定“新打点无效”
2. 先查当前 rustfs_s3_put_object_stage_duration_ms 里到底有哪些 stage
3. 如果只看到了 ordinary PUT 的 ingress_prepare / set_disk_writer_setup / set_disk_encode / set_disk_rename，要优先怀疑当前 127.0.0.1:9000 上跑的不是预期的新二进制

推荐先查：

topk(
  40,
  count by (__name__, stage) (
    {__name__=~"rustfs_s3_put_object_stage_duration_ms.*"}
  )
)

如果结果里只有 ordinary stage，而没有：

1. multipart_ingress_prepare
2. multipart_set_disk_writer_setup
3. multipart_set_disk_encode
4. multipart_complete_tail

则应优先检查：

1. 本轮 RustFS 进程是否确实来自当前 worktree 的 target/debug/rustfs
2. 重启脚本是否真的清掉了旧进程
3. RUSTFS_OBS_ENDPOINT 是否仍然指向当前可查询 backend

12. 已确认的假阴性根因样例

在 2026-06-24 的第三批继续验证中，出现过一次典型假阴性：

1. multipart benchmark 已经成功跑完
2. Prometheus 里却只有 ordinary PUT stage，没有任何 multipart_*
3. 根因并不是打点代码失效，而是 127.0.0.1:9000 上仍然挂着更早启动的旧 RustFS 进程

纠偏方式：

1. 用当前 worktree 的 target/debug/rustfs 前台直接拉起服务
2. 再跑最小化 focused smoke
3. 立刻查询 multipart_* stage

这次纠偏后的前台复测已经确认：

1. multipart_* 四个阶段可以正常上报
2. 当前热点仍然稳定落在 multipart_set_disk_encode