ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Rivet Actors Runner Configs Upsert API 详解:用 PUT /runner-configs 管理多数据中心 Runner 配置

Rivet Actors Runner Configs Upsert API 详解:用 PUT /runner-configs 管理多数据中心 Runner 配置 Rivet Actors Runner Configs Upsert API 详解用 PUT /runner-configs 管理多数据中心 Runner 配置【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors本文以 Rivet Actors 的 Rust SDKrivet-api-full中RunnerConfigsUpsertApi为切入点系统讲解通过PUT /runner-configs/{runner_name}接口创建、更新与删除 Runner 配置的完整流程从请求参数、RunnerConfig模型两种变体normal / serverless的字段语义到服务端多数据中心Datacenter扇出写入与验证测试的底层原理。读完本文你将能够使用该接口为某个命名 Runner 在不同数据中心分别下发差异化的运行配置并正确理解返回值endpoint_config_changed的含义。接口总览RunnerConfigsUpsertApi是 Rivet 公共 API 中 Runner 配置管理系列接口Upsert、Delete、List、RefreshMetadata、ServerlessHealthCheck的核心入口之一。SDK 文档定义在 RunnerConfigsUpsertApi.md所有 URL 均相对于http://localhost实际部署时替换为你的控制平面网关地址。方法HTTP 请求说明runner_configs_upsertPUT/runner-configs/{runner_name}创建 / 更新 / 删除指定 Runner 在各数据中心的配置接口签名如下Rustpub async fn runner_configs_upsert( configuration: configuration::Configuration, runner_name: str, namespace: str, runner_configs_upsert_request_body: models::RunnerConfigsUpsertRequestBody, ) - Resultmodels::RunnerConfigsUpsertResponse, ErrorRunnerConfigsUpsertError对应的完整客户端实现位于 runner_configs_upsert_api.rs它构造PUT {base_path}/runner-configs/{runner_name}请求将namespace作为 URL 查询参数?namespace...追加请求体以 JSON 序列化发送并自动携带bearer_auth认证头。请求头与认证Content-Type:application/jsonAccept:application/jsonAuthorization:bearer_authBearer Token请求参数详解参数类型位置必填说明runner_nameStringURL 路径是Runner 的名称作为配置的唯一标识。同一 Runner 名称在同一个 Namespace 下唯一namespaceStringURL 查询参数是目标命名空间名称用于隔离不同项目的 Runner 配置runner_configs_upsert_request_bodyRunnerConfigsUpsertRequestBody请求体是按数据中心下发的 Runner 配置映射请求体RunnerConfigsUpsertRequestBody请求体模型定义于 RunnerConfigsUpsertRequestBody.md只有一个字段属性类型说明datacentersHashMapString, RunnerConfig以数据中心名称Datacenter label为键、RunnerConfig为值的映射声明该 Runner 在每个数据中心应使用的配置对应 Rust 结构体见 runner_configs_upsert_request_body.rs其new(datacenters)构造函数要求传入完整的映射。理解 upsert 语义的关键这是一个全量对齐而非增量合并接口。服务端会把请求中的datacenters映射与系统拓扑中已启用的数据中心逐一比对——出现在请求里的数据中心执行写入upsert未出现在请求里的数据中心则执行删除delete。因此传入空HashMap等价于删除该 Runner 在所有数据中心的配置见测试 api_runner_configs_upsert.rs只传入部分数据中心则其余数据中心的该 Runner 配置会被移除见 upsert_runner_config_removes_missing_dcs重复提交相同内容则幂等成功不会报错见 upsert_runner_config_idempotent。RunnerConfig两种配置变体RunnerConfig描述单个数据中心内某个 Runner 的完整运行配置模型见 RunnerConfig.md 与实现 runner_config.rs属性类型说明normalRunnerConfigKindOneOfNormal常驻型 Runner 配置必填字段之一serverlessRunnerConfigKindOneOf1Serverless弹性伸缩型 Runner 配置必填字段之一drain_on_version_upgradeOptionbool已弃用Deprecated可选metadataOptionserde_json::Value任意自定义元数据可选会随配置下发normal与serverless分别对应 RunnerConfigKindOneOf包裹normal与 RunnerConfigKindOneOf1包裹serverless两个枚举变体枚举类型见 RunnerConfigKind.md。构造RunnerConfig::new(normal, serverless)时必须同时提供两个变体的值序列化时按字段是否设置决定最终生效的是哪种模式。测试代码中的典型构造方式如下来自 api_runner_configs_upsert.rsrivet_api_types::namespaces::runner_configs::RunnerConfig { kind: rivet_api_types::namespaces::runner_configs::RunnerConfigKind::Normal {}, metadata: None, drain_on_version_upgrade: true, }Normal 变体常驻型 RunnerRunnerConfigKindOneOfNormal见 RunnerConfigKindOneOfNormal.md用于始终在线、可承载长连接WebSocket或实时状态的有状态工作负载。全部字段可选属性类型说明actor_eviction_delayOptioni32Actor 逐出延迟单位秒actor_eviction_periodOptioni32Actor 逐出周期单位秒actor_eviction_rateOptionf32Actor 逐出速率单位个/秒drain_on_version_upgradeOptionbool版本升级时是否先排空再替换逐出eviction机制用于在容量紧张时回收空闲 Actor三个参数配合可以控制多久开始回收、以什么节奏回收、单个周期回收多少。Serverless 变体弹性伸缩型 RunnerRunnerConfigKindOneOf1Serverless见 RunnerConfigKindOneOf1Serverless.md面向请求驱动的无状态弹性场景有两个必填字段属性类型必填说明urlString是Serverless Runner 的入口 URLrequest_lifespani32是单次请求生命周期上限单位秒max_concurrent_actorsOptioni64否单个 Runner 上最大并发 Actor 数drain_grace_periodOptioni32否排空宽限期单位秒headersOptionHashMapString, String否转发请求时附加的 HTTP 头metadata_poll_intervalOptioni64否元数据轮询间隔单位毫秒不设置则使用全局默认值actor_eviction_delayOptioni32否Actor 逐出延迟单位秒actor_eviction_periodOptioni32否Actor 逐出周期单位秒actor_eviction_rateOptionf32否Actor 逐出速率单位个/秒drain_on_version_upgradeOptionbool否版本升级时是否先排空max_runnersOptioni32否已弃用min_runnersOptioni32否已弃用runners_marginOptioni32否已弃用slots_per_runnerOptioni32否已弃用测试中一个完整 serverless 配置示例见 api_runner_configs_upsert.rsrivet_api_types::namespaces::runner_configs::RunnerConfigKind::Serverless { url: http://example.com.to_string(), headers: None, request_lifespan: 30, max_concurrent_actors: Some(5), drain_grace_period: None, slots_per_runner: 10, min_runners: Some(1), max_runners: 5, runners_margin: Some(2), metadata_poll_interval: None, }返回值RunnerConfigsUpsertResponse响应模型见 RunnerConfigsUpsertResponse.md只有一个字段属性类型说明endpoint_config_changedbool是否有任意数据中心发生端点级配置变更该字段是聚合结果服务端对每个数据中心执行写入后只要任意一个数据中心报告配置发生变更即为true。首次创建、变更变体normal → serverless、增删数据中心等都会返回true见测试中的assert!(response.endpoint_config_changed)断言。对于完全幂等的重复提交返回值可能为true也可能为false取决于实现是否判定端点配置真正变化见 upsert_runner_config_idempotent 的注释说明。服务端实现多数据中心扇出写入runner_configs_upsert的网关侧实现位于 engine/packages/api-public/src/runner_configs/upsert.rs核心流程如下认证ctx.auth().await?校验 Bearer Token。数据中心对齐校验将请求体中的datacenters与当前拓扑ctx.config().topology().datacenters逐一比对如果请求里出现了拓扑中不存在的数据中心直接返回Datacenter::NotFound错误upsert.rs。扇出执行对每个数据中心并行处理buffer_unordered(16)最多 16 路并发若请求中包含该 DC 的配置本地区域dc_label匹配调用内部 peer 接口runner_configs::upsert直接写入远端区域则通过request_remote_datacenter将PUT /runner-configs/{runner_name}转发到对应数据中心若请求中不含该 DC 的配置等价于调用DELETE /runner-configs/{runner_name}删除该 DC 上的配置任一 peer 请求失败即整体失败// NOTE: We must error when any peer request fails, not all。结果聚合对每个 DC 返回的endpoint_config_changed做逻辑或得到最终返回值。Namespace 解析与缓存预热按名称解析出 Namespace不存在则报Namespace::NotFound并调用pegboard::ops::runner::list_runner_config_enabled_dcs预取启用该配置的数据中心列表用于预热 epoxy 缓存。这种入口网关扇出 各 DC 本地落库的架构保证了一次PUT调用即可实现跨数据中心的一致性配置对齐。行为边界与验证测试服务端的集成测试集中在 engine/packages/engine/tests/runner/api_runner_configs_upsert.rs覆盖了以下行为边界可作为实际使用的参考场景预期行为测试单 DC 创建 normal 配置返回endpoint_config_changed trueupsert_runner_config_normal_single_dc多 DC 同时下发所有 DC 均写入返回trueupsert_runner_config_normal_multiple_dcsServerless 配置正常创建并返回trueupsert_runner_config_serverless更新已有配置含 metadata更新成功返回trueupsert_runner_config_update_existing携带任意 metadata元数据随配置持久化upsert_runner_config_with_metadata请求省略某 DC该 DC 配置被删除upsert_runner_config_removes_missing_dcs空datacenters映射删除该 Runner 全部配置upsert_runner_config_empty_map_deletes_all不存在的 Namespace请求报错upsert_runner_config_non_existent_namespacenormal 覆盖为 serverless变体切换成功返回trueupsert_runner_config_overwrites_different_variant重复提交相同配置幂等成功不报错upsert_runner_config_idempotentslots_per_runner 0serverless请求被拒绝upsert_runner_config_serverless_slots_per_runner_zerodrain_grace_period超过 Actor 停止阈值请求被拒绝upsert_runner_config_serverless_drain_grace_period_exceeds_actor_stop_threshold完整调用示例结合 runner_configs_upsert_api.rs 的函数签名一个完整的 Rust 调用示例如下use rivet_api_full::apis::configuration::Configuration; use rivet_api_full::apis::runner_configs_upsert_api; use rivet_api_full::models::{ RunnerConfig, RunnerConfigKind, RunnerConfigKindOneOf, RunnerConfigKindOneOf1, RunnerConfigKindOneOf1Serverless, RunnerConfigKindOneOfNormal, RunnerConfigsUpsertRequestBody, }; use std::collections::HashMap; let config Configuration::new(http://localhost); // 记得设置 bearer_access_token let normal RunnerConfigKindOneOfNormal::new(); // 常驻型全部字段可选 let serverless RunnerConfigKindOneOf1Serverless::new( https://my-app.example.com.to_string(), // url必填 30, // request_lifespan必填秒 ); let mut datacenters HashMap::new(); datacenters.insert( dc-1.to_string(), RunnerConfig::new( RunnerConfigKind::from(RunnerConfigKindOneOf::new(normal)), // 或 RunnerConfigKindOneOf1::new(serverless) RunnerConfigKind::from(RunnerConfigKindOneOf1::new(serverless)), ), ); let response runner_configs_upsert_api::runner_configs_upsert( config, my-runner, // runner_name my-namespace, // namespace RunnerConfigsUpsertRequestBody::new(datacenters), ) .await?; println!(endpoint_config_changed {}, response.endpoint_config_changed);对应的原始 HTTP 请求形如PUT /runner-configs/my-runner?namespacemy-namespace Authorization: Bearer token Content-Type: application/json { datacenters: { dc-1: { normal: { actor_eviction_delay: 60, actor_eviction_period: 30, actor_eviction_rate: 5.0 }, serverless: { url: https://my-app.example.com, request_lifespan: 30 }, drain_on_version_upgrade: true, metadata: { team: platform } } } }SDK 安装与 API 全貌可参考 api-full Rust 客户端 README其中列出了RunnerConfigsUpsertApi与其他 15 个 API 类Actors、Namespaces、Datacenters、Runners 等的完整方法索引。小结RunnerConfigsUpsertApi是 Rivet Actors 中管理 Runner 运行形态常驻 / Serverless与多数据中心分布的单一入口PUT /runner-configs/{runner_name}?namespace...以请求体全量对齐的语义完成创建、更新与删除endpoint_config_changed是判断端点配置是否实际变更的关键信号。配合 服务端实现 中的数据中心扇出逻辑与 集成测试 覆盖的边界行为你可以在自己的项目中安全地用它做跨 DC 的 Runner 配置编排与滚动变更。【免费下载链接】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),仅供参考
返回列表