开发者 - 9 - 测试扩展配置

适用范围

test_spec_config 是测试、benchmark、故障隔离和实现实验专用的开发者入口。普通部署应省略整个配置块。这些开关可能绕过生产路径或改变性能行为，不属于稳定用户配置契约。

稳定的用户网络策略与传输调优入口是 network。公开 YAML 不再提供 protocol 配置块；协议选择只保留在测试入口 test_spec_config.protocol_type 下。

未知字段会被拒绝。Fluxon KV master 和 client 配置都接受 test_spec_config；TestStack 在 profiles.<id>.runtime.test_stack.runtime_config.kv_base.test_spec_config 下接受同一组字段，并额外提供一个仅由 runner 消费的字段。

协议选择

测试使用 TCP：

test_spec_config:
  protocol_type: tcp

测试使用 RDMA 并固定设备：

test_spec_config:
  protocol_type: rdma
  rdma_device_names:
    - mlx5_0

省略 protocol_type 时，Fluxon KV 保持当前默认 RDMA。这里的 rdma_device_names 是测试覆盖项，优先于 network.rdma_device_names。Mooncake 测试路径固定使用 RDMA，不消费这项 Fluxon KV 协议覆盖。

Runtime 字段

可观测性、索引与数据路径

字段	类型与默认值	作用
`disable_observability`	`bool`，`false`	关闭 Fluxon KV 可观测性和 OTLP 后台任务。
`disable_master_replica_cache`	`bool`，`false`	关闭 master replica cache 维护。
`disable_prefix_index`	`bool`，`false`	关闭 master prefix index 维护。
`prefer_local_placement`	`bool`，`false`	保留的测试解析字段；当前没有 runtime 分支消费它。
`short_circuit_put_payload_path`	`bool`，`false`	保留 put allocation，但跳过 payload copy 和 transfer，用于隔离路径开销。
`skip_put_end_commit`	`bool`，`false`	payload transfer 后直接返回，不执行 `put_end` commit；清理由 inflight-put TTL 完成。

协议、IPC 与线程调优

字段	类型与默认值	作用
`protocol_type`	`tcp` / `rdma`；除派生 side-transfer worker 外，省略时为 RDMA	为 Fluxon KV 测试选择协议。
`transport_mode`	`transfer_only` / `transfer_with_rpc`；除 side-transfer worker 外，有效默认值为 `transfer_with_rpc`	关闭或启用 transfer RPC fast path。
`rdma_device_names`	非空字符串列表；缺省	为测试固定并展开 RDMA 设备；输入会去空白、去重并排序。
`disable_local_ipc`	`bool`，`false`	关闭全部同机 local IPC，使 peer 使用 direct transport。
`disable_crossowner_ipc`	`bool`，`false`	保留同 owner local IPC，同机跨 owner 流量改走 direct transport。
`enable_iceoryx_logs`	`bool`，`false`	打开默认被抑制的 iceoryx2 日志。
`iceoryx_external_busy_poll`	`bool`，`false`	external local-IPC receiver 使用 busy poll，不使用 wait set。
`iceoryx_owner_client_busy_poll`	`bool`，`true`	owner/client local-IPC receiver 使用 busy poll。
`tcp_thread_reactor_shard_count`	整数 `1..16`；缺省	覆盖 TCP-thread reactor shard 数。
`tcp_thread_bulk_lane_count`	整数 `1..8`；缺省	覆盖 TCP-thread bulk lane 数。
`tcp_thread_control_lane_count`	整数 `1..8`；缺省	覆盖 TCP-thread control lane 数。
`user_rpc_sync_handler_thread_count`	正整数；缺省	覆盖 user RPC 专用同步 worker 线程数。
`require_transfer_rpc_fast_path_ready_timeout_seconds`	正整数；缺省	owner ready 前等待 transfer RPC fast path，超时值使用该字段。

Side transfer 与 KV SSD 实验

字段	类型与默认值	作用
`enable_side_transfer`	`bool`，`false`	为当前 client 打开 TCP side-transfer fast path。
`side_transfer_worker_count`	非负整数，`0`	让 owner 启动指定数量的 side-transfer worker。
`side_transfer_worker_p2p_port_base`	非零 `u16`；缺省	将 worker 端口固定为 `base + worker_index`。
`side_transfer_role`	`worker`；缺省	将 zero-contribution client 标记为内部 side-transfer worker；其协议派生为 TCP。
`kv_ssd_storage_backend`	`native` / `foyer`，`native`	为测试选择 KV SSD 实现。
`kv_ssd_uring_mode`	`single_buffer` / `iovec`，`single_buffer`	选择 native KV SSD 的 io_uring buffer 模式。

组合约束

rdma_device_names 只适用于有效协议为 RDMA 的配置；与 protocol_type: tcp 组合会被拒绝。
RDMA 测试显式设置 transport_mode 时，必须同时显式设置 test_spec_config.rdma_device_names，避免 benchmark 变体隐式选择设备。TCP 不需要 RDMA 设备列表。
require_transfer_rpc_fast_path_ready_timeout_seconds 要求 transport_mode: transfer_with_rpc。RDMA 还要求显式测试设备列表；TCP 必须显式选择。
side_transfer_role: worker 要求 zero-contribution client 模式。worker 的 TCP 协议由角色派生，因此不能设置 protocol_type 或 rdma_device_names。
正数 side_transfer_worker_count 只允许 owner 使用。配置端口基址时，基址必须非零，所有派生 worker 端口都必须落在 u16 范围内。
kv_ssd_storage_backend: foyer 只支持 kv_ssd_uring_mode: single_buffer；iovec 只适用于 native。

TestStack 专用字段

TestStack 额外接受：

字段	类型与默认值	作用
`p2p_transport_impl`	`tcp` / `tcp_thread`；缺省	选择匹配的 staged P2P transport artifact set。runner 消费该字段，并在生成 runtime YAML 前将其删除。

配置位置示例：

profiles:
  example_profile:
    runtime:
      test_stack:
        runtime_config:
          kv_base:
            test_spec_config:
              protocol_type: tcp
              p2p_transport_impl: tcp_thread

不要把 p2p_transport_impl 直接写入 Fluxon KV master 或 client runtime 配置。

Fluxon Docs

Explorer