Rivet Actors RunnerConfig 详解normal 与 serverless 两种运行模式的 Rust SDK 配置指南【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actorsRivet 中RunnerConfig 是定义 Actor 运行时调度与生命周期策略的核心配置模型它决定了一个 Actor 是运行在常驻的 normal 模式下还是运行在按需唤醒的 serverless 模式下并控制驱逐eviction、排水drain、元数据轮询与并发等关键行为。本文基于 RunnerConfig.md 及其关联模型文档结合engine/sdks/rust下由 OpenAPI 生成的 Rust SDK 源码逐字段讲解两种模式的配置项、序列化规则与典型使用方式帮助你为 AI 智能体、协作类应用等有状态负载正确配置 Runner 运行策略。RunnerConfig 模型概览RunnerConfig 位于 Rust SDK 的模型层源码实现见 runner_config.rs整体结构由以下四个字段构成字段类型说明是否可选normalRunnerConfigKindOneOfNormalnormal常驻模式的配置必填serverlessRunnerConfigKindOneOf1Serverlessserverless按需模式的配置必填drain_on_version_upgradeOptionbool版本升级时是否触发排水Deprecated已弃用可选metadataOptionserde_json::Value自定义元数据任意 JSON 值可选从 Rust 源码可以看出normal与serverless两个字段在序列化时使用#[serde(rename normal)]/#[serde(rename serverless)]映射到 JSON 键且均为必填字段——RunnerConfig::new()构造函数要求同时传入两种模式的配置对象pub fn new( normal: models::RunnerConfigKindOneOfNormal, serverless: models::RunnerConfigKindOneOf1Serverless, ) - RunnerConfig { RunnerConfig { normal: Box::new(normal), serverless: Box::new(serverless), drain_on_version_upgrade: None, metadata: None, } }而drain_on_version_upgrade与metadata采用double_optionskip_serializing_if Option::is_none的组合含义是当字段未设置时序列化输出中直接省略该键即便设置为Some(None)同样会从 JSON 中剔除。这与下面的模式变体枚举RunnerConfigVariant相互呼应——两种运行模式分别由两个必填子对象承载变体字符串值对应子模型ServerlessserverlessRunnerConfigKindOneOf1ServerlessNormalnormalRunnerConfigKindOneOfNormal枚举与字符串值的映射见 RunnerConfigVariant.md而两个子模型分别由RunnerConfigKindOneOf与RunnerConfigKindOneOf1两个枚举变体引用见 RunnerConfigKind.md。normal 模式常驻 Runner 的驱逐策略normal 模式面向始终在线、需要保持热度的常驻工作负载。其配置模型RunnerConfigKindOneOfNormal实现见 runner_config_kind_one_of_normal.rs包含以下字段字段类型说明单位actor_eviction_delayOptioni32驱逐延迟秒actor_eviction_periodOptioni32驱逐周期秒actor_eviction_rateOptionf32驱逐速率每秒驱逐的 Actor 数drain_on_version_upgradeOptionbool版本升级时是否排水-驱逐eviction机制是 normal 模式的核心语义当需要释放资源、缩容或滚动升级时系统会按照actor_eviction_period设定的时间窗口、以actor_eviction_rate设定的速率每秒多少个 Actor驱逐空闲实例并通过actor_eviction_delay控制驱逐前的延迟缓冲。三个参数共同构成一个可调谐的驱逐节流策略避免瞬间大量实例下线影响服务质量。对应 Rust 源码中的序列化定义如下全部字段可缺省缺省时从 JSON 中省略#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct RunnerConfigKindOneOfNormal { /// Seconds. #[serde(rename actor_eviction_delay, default, with ::serde_with::rust::double_option, skip_serializing_if Option::is_none)] pub actor_eviction_delay: OptionOptioni32, /// Seconds. #[serde(rename actor_eviction_period, default, with ::serde_with::rust::double_option, skip_serializing_if Option::is_none)] pub actor_eviction_period: OptionOptioni32, /// Actors per second. #[serde(rename actor_eviction_rate, default, with ::serde_with::rust::double_option, skip_serializing_if Option::is_none)] pub actor_eviction_rate: OptionOptionf32, #[serde(rename drain_on_version_upgrade, default, with ::serde_with::rust::double_option, skip_serializing_if Option::is_none)] pub drain_on_version_upgrade: OptionOptionbool, }典型 JSON 示例{ normal: { actor_eviction_delay: 30, actor_eviction_period: 60, actor_eviction_rate: 2.0, drain_on_version_upgrade: true } }含义每 60 秒为一个驱逐周期每个周期最多按每秒 2 个的速率驱逐 Actor驱逐动作延迟 30 秒执行版本升级时同时触发排水让旧版本实例平滑退出。serverless 模式按需唤醒的弹性策略serverless 模式面向间歇性流量与按需计算场景其配置模型RunnerConfigKindOneOf1Serverless实现见 runner_config_kind_one_of_1_serverless.rs在包含驱逐参数之外还引入了请求生命周期、并发上限、元数据轮询与已弃用的伸缩字段。必填字段字段类型说明单位request_lifespani32单个请求允许存活的最大时长秒urlStringserverless 入口的服务地址-在 Rust 构造函数中这两个字段是RunnerConfigKindOneOf1Serverless::new()仅有的两个必传参数pub fn new(request_lifespan: i32, url: String) - RunnerConfigKindOneOf1Serverless { ... }request_lifespan决定了按需创建的 Runner 上单个请求的生命周期上限超时后系统会回收相关资源url则指向 serverless 处理入口是请求路由到该 Runner 的地址。可选字段字段类型说明actor_eviction_delayOptioni32驱逐延迟秒actor_eviction_periodOptioni32驱逐周期秒actor_eviction_rateOptionf32驱逐速率每秒 Actor 数drain_grace_periodOptioni32排水宽限期秒优雅下线窗口drain_on_version_upgradeOptionbool版本升级时是否排水headersOptionHashMapString, String附加请求头键值对形式max_concurrent_actorsOptioni64单 Runner 上允许的最大并发 Actor 数metadata_poll_intervalOptioni64元数据轮询间隔毫秒不设置则使用全局默认值max_runnersOptioni32最大 Runner 数Deprecated已弃用min_runnersOptioni32最小 Runner 数Deprecated已弃用runners_marginOptioni32Runner 冗余余量Deprecated已弃用slots_per_runnerOptioni32每 Runner 槽位数Deprecated已弃用其中几个值得重点说明drain_grace_periodserverless 模式特有的优雅下线窗口。当需要销毁 Runner 时系统会等待该时长让在途请求完成避免强制中断造成请求失败。与 normal 模式的驱逐参数配合可以实现平滑缩容。headers以std::collections::HashMapString, String承载的附加请求头用于在请求路由到 serverless 入口时注入认证、租户标识等自定义信息。metadata_poll_interval控制客户端轮询服务端元数据的频率单位为毫秒。文档明确说明不设置则使用全局默认值适合在默认值不满足需求时按场景调优。max_concurrent_actors限制单个 Runner 上同时运行的 Actor 数量是控制资源占用上限的关键参数。而max_runners、min_runners、runners_margin、slots_per_runner四个字段在文档与源码中均被明确标记为Deprecated仅保留兼容性新项目不应依赖它们做容量规划。典型 JSON 示例{ serverless: { url: https://runner.example.com, request_lifespan: 300, max_concurrent_actors: 100, drain_grace_period: 60, metadata_poll_interval: 5000, headers: { x-tenant-id: acme }, actor_eviction_delay: 30, actor_eviction_period: 60, actor_eviction_rate: 2.0 } }完整配置组合与 Rust 使用方式将两种模式合并即可得到一个完整的 RunnerConfig 请求体。以下 Rust 代码展示如何通过 SDK 构造完整配置use rivet_api::models::{ RunnerConfig, RunnerConfigKindOneOfNormal, RunnerConfigKindOneOf1Serverless, }; let normal RunnerConfigKindOneOfNormal { actor_eviction_delay: Some(Some(30)), actor_eviction_period: Some(Some(60)), actor_eviction_rate: Some(Some(2.0)), drain_on_version_upgrade: Some(Some(true)), }; let serverless RunnerConfigKindOneOf1Serverless { actor_eviction_delay: Some(Some(30)), actor_eviction_period: Some(Some(60)), actor_eviction_rate: Some(Some(2.0)), drain_grace_period: Some(Some(60)), drain_on_version_upgrade: Some(Some(true)), headers: Some(HashMap::from([(x-tenant-id.into(), acme.into())])), max_concurrent_actors: Some(Some(100)), max_runners: None, metadata_poll_interval: Some(Some(5000)), min_runners: None, request_lifespan: 300, runners_margin: None, slots_per_runner: None, url: https://runner.example.com.into(), }; let config RunnerConfig::new(normal, serverless);对应的完整 JSON 请求体{ normal: { actor_eviction_delay: 30, actor_eviction_period: 60, actor_eviction_rate: 2.0, drain_on_version_upgrade: true }, serverless: { url: https://runner.example.com, request_lifespan: 300, max_concurrent_actors: 100, drain_grace_period: 60, metadata_poll_interval: 5000, headers: { x-tenant-id: acme }, actor_eviction_delay: 30, actor_eviction_period: 60, actor_eviction_rate: 2.0 }, metadata: { team: platform, env: prod } }构造完成后RunnerConfig 通常作为ActorsCreateRequest或RunnerConfigsUpsertRequestBody等请求体的一部分提交对应的 API 文档见 ActorsCreateRequest.md 与 RunnerConfigsUpsertRequestBody.md。服务端返回时则使用RunnerConfigResponse模型它在 RunnerConfig 基础上额外携带protocol_version与runner_pool_error两个字段用于反馈协议版本与 Runner 池健康状态见 RunnerConfigResponse.md。序列化与可缺省语义本 SDK 由 OpenAPI Generator 生成所有可选字段统一采用双重 Option 条件省略的序列化策略双重 Optiondouble_option外层Option表示该字段是否在 JSON 中出现内层Option表示JSON 中出现时的值是否可为 null从而区分未设置与显式置空两种语义skip_serializing_if Option::is_none当外层为None时序列化输出中不输出该键保证请求体最小化。因此使用 SDK 时只需按需设置需要的字段其余保持None即可反序列化时缺失的字段同样会得到None不会导致解析失败。实践建议常驻热度型负载如实时协作、多人游戏房间以 normal 模式为主重点调优actor_eviction_delay/actor_eviction_period/actor_eviction_rate让驱逐平滑进行避免突发下线版本升级场景可开启drain_on_version_upgrade实现优雅滚动。间歇性 / 按需型负载如 AI 智能体会话、突发请求以 serverless 模式为主合理设置request_lifespan请求存活上限、max_concurrent_actors单 Runner 并发上限与drain_grace_period下线宽限期并通过metadata_poll_interval控制元数据轮询频率以平衡实时性与开销。规避弃用字段drain_on_version_upgradeRunnerConfig 顶层、max_runners、min_runners、runners_margin、slots_per_runner均已被标记为 Deprecated请勿在新的配置中依赖它们。参考文档RunnerConfig.mdRunnerConfigKindOneOfNormal.mdRunnerConfigKindOneOf1Serverless.mdRunnerConfigKind.mdRunnerConfigVariant.mdRunnerConfigResponse.md源码实现runner_config.rs、runner_config_kind_one_of_normal.rs、runner_config_kind_one_of_1_serverless.rs【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/18 0:58:42 · 阅读 1.2k Rivet Actors RunnerConfig 详解：normal 与 serverless 两种运行模式的 Rust SDK 配置指南
Rivet Actors RunnerConfig 详解normal 与 serverless 两种运行模式的 Rust SDK 配置指南【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actorsRivet 中RunnerConfig 是定义 Actor 运行时调度与生命周期策略的核心配置模型它决定了一个 Actor 是运行在常驻的 normal 模式下还是运行在按需唤醒的 serverless 模式下并控制驱逐eviction、排水drain、元数据轮询与并发等关键行为。本文基于 RunnerConfig.md 及其关联模型文档结合engine/sdks/rust下由 OpenAPI 生成的 Rust SDK 源码逐字段讲解两种模式的配置项、序列化规则与典型使用方式帮助你为 AI 智能体、协作类应用等有状态负载正确配置 Runner 运行策略。RunnerConfig 模型概览RunnerConfig 位于 Rust SDK 的模型层源码实现见 runner_config.rs整体结构由以下四个字段构成字段类型说明是否可选normalRunnerConfigKindOneOfNormalnormal常驻模式的配置必填serverlessRunnerConfigKindOneOf1Serverlessserverless按需模式的配置必填drain_on_version_upgradeOptionbool版本升级时是否触发排水Deprecated已弃用可选metadataOptionserde_json::Value自定义元数据任意 JSON 值可选从 Rust 源码可以看出normal与serverless两个字段在序列化时使用#[serde(rename normal)]/#[serde(rename serverless)]映射到 JSON 键且均为必填字段——RunnerConfig::new()构造函数要求同时传入两种模式的配置对象pub fn new( normal: models::RunnerConfigKindOneOfNormal, serverless: models::RunnerConfigKindOneOf1Serverless, ) - RunnerConfig { RunnerConfig { normal: Box::new(normal), serverless: Box::new(serverless), drain_on_version_upgrade: None, metadata: None, } }而drain_on_version_upgrade与metadata采用double_optionskip_serializing_if Option::is_none的组合含义是当字段未设置时序列化输出中直接省略该键即便设置为Some(None)同样会从 JSON 中剔除。这与下面的模式变体枚举RunnerConfigVariant相互呼应——两种运行模式分别由两个必填子对象承载变体字符串值对应子模型ServerlessserverlessRunnerConfigKindOneOf1ServerlessNormalnormalRunnerConfigKindOneOfNormal枚举与字符串值的映射见 RunnerConfigVariant.md而两个子模型分别由RunnerConfigKindOneOf与RunnerConfigKindOneOf1两个枚举变体引用见 RunnerConfigKind.md。normal 模式常驻 Runner 的驱逐策略normal 模式面向始终在线、需要保持热度的常驻工作负载。其配置模型RunnerConfigKindOneOfNormal实现见 runner_config_kind_one_of_normal.rs包含以下字段字段类型说明单位actor_eviction_delayOptioni32驱逐延迟秒actor_eviction_periodOptioni32驱逐周期秒actor_eviction_rateOptionf32驱逐速率每秒驱逐的 Actor 数drain_on_version_upgradeOptionbool版本升级时是否排水-驱逐eviction机制是 normal 模式的核心语义当需要释放资源、缩容或滚动升级时系统会按照actor_eviction_period设定的时间窗口、以actor_eviction_rate设定的速率每秒多少个 Actor驱逐空闲实例并通过actor_eviction_delay控制驱逐前的延迟缓冲。三个参数共同构成一个可调谐的驱逐节流策略避免瞬间大量实例下线影响服务质量。对应 Rust 源码中的序列化定义如下全部字段可缺省缺省时从 JSON 中省略#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct RunnerConfigKindOneOfNormal { /// Seconds. #[serde(rename actor_eviction_delay, default, with ::serde_with::rust::double_option, skip_serializing_if Option::is_none)] pub actor_eviction_delay: OptionOptioni32, /// Seconds. #[serde(rename actor_eviction_period, default, with ::serde_with::rust::double_option, skip_serializing_if Option::is_none)] pub actor_eviction_period: OptionOptioni32, /// Actors per second. #[serde(rename actor_eviction_rate, default, with ::serde_with::rust::double_option, skip_serializing_if Option::is_none)] pub actor_eviction_rate: OptionOptionf32, #[serde(rename drain_on_version_upgrade, default, with ::serde_with::rust::double_option, skip_serializing_if Option::is_none)] pub drain_on_version_upgrade: OptionOptionbool, }典型 JSON 示例{ normal: { actor_eviction_delay: 30, actor_eviction_period: 60, actor_eviction_rate: 2.0, drain_on_version_upgrade: true } }含义每 60 秒为一个驱逐周期每个周期最多按每秒 2 个的速率驱逐 Actor驱逐动作延迟 30 秒执行版本升级时同时触发排水让旧版本实例平滑退出。serverless 模式按需唤醒的弹性策略serverless 模式面向间歇性流量与按需计算场景其配置模型RunnerConfigKindOneOf1Serverless实现见 runner_config_kind_one_of_1_serverless.rs在包含驱逐参数之外还引入了请求生命周期、并发上限、元数据轮询与已弃用的伸缩字段。必填字段字段类型说明单位request_lifespani32单个请求允许存活的最大时长秒urlStringserverless 入口的服务地址-在 Rust 构造函数中这两个字段是RunnerConfigKindOneOf1Serverless::new()仅有的两个必传参数pub fn new(request_lifespan: i32, url: String) - RunnerConfigKindOneOf1Serverless { ... }request_lifespan决定了按需创建的 Runner 上单个请求的生命周期上限超时后系统会回收相关资源url则指向 serverless 处理入口是请求路由到该 Runner 的地址。可选字段字段类型说明actor_eviction_delayOptioni32驱逐延迟秒actor_eviction_periodOptioni32驱逐周期秒actor_eviction_rateOptionf32驱逐速率每秒 Actor 数drain_grace_periodOptioni32排水宽限期秒优雅下线窗口drain_on_version_upgradeOptionbool版本升级时是否排水headersOptionHashMapString, String附加请求头键值对形式max_concurrent_actorsOptioni64单 Runner 上允许的最大并发 Actor 数metadata_poll_intervalOptioni64元数据轮询间隔毫秒不设置则使用全局默认值max_runnersOptioni32最大 Runner 数Deprecated已弃用min_runnersOptioni32最小 Runner 数Deprecated已弃用runners_marginOptioni32Runner 冗余余量Deprecated已弃用slots_per_runnerOptioni32每 Runner 槽位数Deprecated已弃用其中几个值得重点说明drain_grace_periodserverless 模式特有的优雅下线窗口。当需要销毁 Runner 时系统会等待该时长让在途请求完成避免强制中断造成请求失败。与 normal 模式的驱逐参数配合可以实现平滑缩容。headers以std::collections::HashMapString, String承载的附加请求头用于在请求路由到 serverless 入口时注入认证、租户标识等自定义信息。metadata_poll_interval控制客户端轮询服务端元数据的频率单位为毫秒。文档明确说明不设置则使用全局默认值适合在默认值不满足需求时按场景调优。max_concurrent_actors限制单个 Runner 上同时运行的 Actor 数量是控制资源占用上限的关键参数。而max_runners、min_runners、runners_margin、slots_per_runner四个字段在文档与源码中均被明确标记为Deprecated仅保留兼容性新项目不应依赖它们做容量规划。典型 JSON 示例{ serverless: { url: https://runner.example.com, request_lifespan: 300, max_concurrent_actors: 100, drain_grace_period: 60, metadata_poll_interval: 5000, headers: { x-tenant-id: acme }, actor_eviction_delay: 30, actor_eviction_period: 60, actor_eviction_rate: 2.0 } }完整配置组合与 Rust 使用方式将两种模式合并即可得到一个完整的 RunnerConfig 请求体。以下 Rust 代码展示如何通过 SDK 构造完整配置use rivet_api::models::{ RunnerConfig, RunnerConfigKindOneOfNormal, RunnerConfigKindOneOf1Serverless, }; let normal RunnerConfigKindOneOfNormal { actor_eviction_delay: Some(Some(30)), actor_eviction_period: Some(Some(60)), actor_eviction_rate: Some(Some(2.0)), drain_on_version_upgrade: Some(Some(true)), }; let serverless RunnerConfigKindOneOf1Serverless { actor_eviction_delay: Some(Some(30)), actor_eviction_period: Some(Some(60)), actor_eviction_rate: Some(Some(2.0)), drain_grace_period: Some(Some(60)), drain_on_version_upgrade: Some(Some(true)), headers: Some(HashMap::from([(x-tenant-id.into(), acme.into())])), max_concurrent_actors: Some(Some(100)), max_runners: None, metadata_poll_interval: Some(Some(5000)), min_runners: None, request_lifespan: 300, runners_margin: None, slots_per_runner: None, url: https://runner.example.com.into(), }; let config RunnerConfig::new(normal, serverless);对应的完整 JSON 请求体{ normal: { actor_eviction_delay: 30, actor_eviction_period: 60, actor_eviction_rate: 2.0, drain_on_version_upgrade: true }, serverless: { url: https://runner.example.com, request_lifespan: 300, max_concurrent_actors: 100, drain_grace_period: 60, metadata_poll_interval: 5000, headers: { x-tenant-id: acme }, actor_eviction_delay: 30, actor_eviction_period: 60, actor_eviction_rate: 2.0 }, metadata: { team: platform, env: prod } }构造完成后RunnerConfig 通常作为ActorsCreateRequest或RunnerConfigsUpsertRequestBody等请求体的一部分提交对应的 API 文档见 ActorsCreateRequest.md 与 RunnerConfigsUpsertRequestBody.md。服务端返回时则使用RunnerConfigResponse模型它在 RunnerConfig 基础上额外携带protocol_version与runner_pool_error两个字段用于反馈协议版本与 Runner 池健康状态见 RunnerConfigResponse.md。序列化与可缺省语义本 SDK 由 OpenAPI Generator 生成所有可选字段统一采用双重 Option 条件省略的序列化策略双重 Optiondouble_option外层Option表示该字段是否在 JSON 中出现内层Option表示JSON 中出现时的值是否可为 null从而区分未设置与显式置空两种语义skip_serializing_if Option::is_none当外层为None时序列化输出中不输出该键保证请求体最小化。因此使用 SDK 时只需按需设置需要的字段其余保持None即可反序列化时缺失的字段同样会得到None不会导致解析失败。实践建议常驻热度型负载如实时协作、多人游戏房间以 normal 模式为主重点调优actor_eviction_delay/actor_eviction_period/actor_eviction_rate让驱逐平滑进行避免突发下线版本升级场景可开启drain_on_version_upgrade实现优雅滚动。间歇性 / 按需型负载如 AI 智能体会话、突发请求以 serverless 模式为主合理设置request_lifespan请求存活上限、max_concurrent_actors单 Runner 并发上限与drain_grace_period下线宽限期并通过metadata_poll_interval控制元数据轮询频率以平衡实时性与开销。规避弃用字段drain_on_version_upgradeRunnerConfig 顶层、max_runners、min_runners、runners_margin、slots_per_runner均已被标记为 Deprecated请勿在新的配置中依赖它们。参考文档RunnerConfig.mdRunnerConfigKindOneOfNormal.mdRunnerConfigKindOneOf1Serverless.mdRunnerConfigKind.mdRunnerConfigVariant.mdRunnerConfigResponse.md源码实现runner_config.rs、runner_config_kind_one_of_normal.rs、runner_config_kind_one_of_1_serverless.rs【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考