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

原创2026-09-17 21:16:441,445 阅读
文章标签:后端云原生Serverless任务调度工作流自动化微服务

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

本文以 Rivet Actors 的 Rust SDK(rivet-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_upsert PUT /runner-configs/{runner_name} 创建 / 更新 / 删除指定 Runner 在各数据中心的配置

接口签名如下(Rust):

pub async fn runner_configs_upsert(
    configuration: &configuration::Configuration,
    runner_name: &str,
    namespace: &str,
    runner_configs_upsert_request_body: models::RunnerConfigsUpsertRequestBody,
) -> Result<models::RunnerConfigsUpsertResponse, Error<RunnerConfigsUpsertError>>

对应的完整客户端实现位于 runner_configs_upsert_api.rs:它构造 PUT {base_path}/runner-configs/{runner_name} 请求,将 namespace 作为 URL 查询参数(?namespace=...)追加,请求体以 JSON 序列化发送,并自动携带 bearer_auth 认证头。

请求头与认证

  • Content-Type: application/json
  • Accept: application/json
  • Authorization: bearer_auth(Bearer Token)

请求参数详解

参数 类型 位置 必填 说明
runner_name String URL 路径 是 Runner 的名称,作为配置的唯一标识。同一 Runner 名称在同一个 Namespace 下唯一
namespace String URL 查询参数 是 目标命名空间名称,用于隔离不同项目的 Runner 配置
runner_configs_upsert_request_body RunnerConfigsUpsertRequestBody 请求体 是 按数据中心下发的 Runner 配置映射

请求体:RunnerConfigsUpsertRequestBody

请求体模型定义于 RunnerConfigsUpsertRequestBody.md,只有一个字段:

属性 类型 说明
datacenters HashMap<String, RunnerConfig> 以数据中心名称(Datacenter label)为键、RunnerConfig 为值的映射,声明该 Runner 在每个数据中心应使用的配置

对应 Rust 结构体见 runner_configs_upsert_request_body.rs,其 new(datacenters) 构造函数要求传入完整的映射。

理解 upsert 语义的关键:这是一个"全量对齐"而非"增量合并"接口。服务端会把请求中的 datacenters 映射与系统拓扑中已启用的数据中心逐一比对——出现在请求里的数据中心执行写入(upsert),未出现在请求里的数据中心则执行删除(delete)。因此:

RunnerConfig:两种配置变体

RunnerConfig 描述单个数据中心内某个 Runner 的完整运行配置,模型见 RunnerConfig.md 与实现 runner_config.rs:

属性 类型 说明
normal RunnerConfigKindOneOfNormal 常驻型 Runner 配置(必填字段之一)
serverless RunnerConfigKindOneOf1Serverless 弹性伸缩型 Runner 配置(必填字段之一)
drain_on_version_upgrade Option<bool> 已弃用(Deprecated),可选
metadata Option<serde_json::Value> 任意自定义元数据,可选,会随配置下发

normal 与 serverless 分别对应 RunnerConfigKindOneOf(包裹 normal)与 RunnerConfigKindOneOf1(包裹 serverless)两个枚举变体,枚举类型见 RunnerConfigKind.md。构造 RunnerConfig::new(normal, serverless) 时必须同时提供两个变体的值,序列化时按字段是否设置决定最终生效的是哪种模式。

测试代码中的典型构造方式如下(来自 api_runner_configs_upsert.rs):

rivet_api_types::namespaces::runner_configs::RunnerConfig {
    kind: rivet_api_types::namespaces::runner_configs::RunnerConfigKind::Normal {},
    metadata: None,
    drain_on_version_upgrade: true,
}

Normal 变体:常驻型 Runner

RunnerConfigKindOneOfNormal(见 RunnerConfigKindOneOfNormal.md)用于始终在线、可承载长连接(WebSocket)或实时状态的有状态工作负载。全部字段可选:

属性 类型 说明
actor_eviction_delay Option<i32> Actor 逐出延迟,单位:秒
actor_eviction_period Option<i32> Actor 逐出周期,单位:秒
actor_eviction_rate Option<f32> Actor 逐出速率,单位:个/秒
drain_on_version_upgrade Option<bool> 版本升级时是否先排空再替换

逐出(eviction)机制用于在容量紧张时回收空闲 Actor,三个参数配合可以控制"多久开始回收、以什么节奏回收、单个周期回收多少"。

Serverless 变体:弹性伸缩型 Runner

RunnerConfigKindOneOf1Serverless(见 RunnerConfigKindOneOf1Serverless.md)面向请求驱动的无状态弹性场景,有两个必填字段:

属性 类型 必填 说明
url String 是 Serverless Runner 的入口 URL
request_lifespan i32 是 单次请求生命周期上限,单位:秒
max_concurrent_actors Option<i64> 否 单个 Runner 上最大并发 Actor 数
drain_grace_period Option<i32> 否 排空宽限期,单位:秒
headers Option<HashMap<String, String>> 否 转发请求时附加的 HTTP 头
metadata_poll_interval Option<i64> 否 元数据轮询间隔,单位:毫秒;不设置则使用全局默认值
actor_eviction_delay Option<i32> 否 Actor 逐出延迟,单位:秒
actor_eviction_period Option<i32> 否 Actor 逐出周期,单位:秒
actor_eviction_rate Option<f32> 否 Actor 逐出速率,单位:个/秒
drain_on_version_upgrade Option<bool> 否 版本升级时是否先排空
max_runners Option<i32> 否 已弃用
min_runners Option<i32> 否 已弃用
runners_margin Option<i32> 否 已弃用
slots_per_runner Option<i32> 否 已弃用

测试中一个完整 serverless 配置示例(见 api_runner_configs_upsert.rs):

rivet_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_changed bool 是否有任意数据中心发生端点级配置变更

该字段是聚合结果:服务端对每个数据中心执行写入后,只要任意一个数据中心报告配置发生变更,即为 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,核心流程如下:

  1. 认证:ctx.auth().await? 校验 Bearer Token。
  2. 数据中心对齐校验:将请求体中的 datacenters 与当前拓扑(ctx.config().topology().datacenters)逐一比对;如果请求里出现了拓扑中不存在的数据中心,直接返回 Datacenter::NotFound 错误(upsert.rs)。
  3. 扇出执行:对每个数据中心并行处理(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)。
  4. 结果聚合:对每个 DC 返回的 endpoint_config_changed 做逻辑或,得到最终返回值。
  5. 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 = true upsert_runner_config_normal_single_dc
多 DC 同时下发 所有 DC 均写入,返回 true upsert_runner_config_normal_multiple_dcs
Serverless 配置 正常创建并返回 true upsert_runner_config_serverless
更新已有配置(含 metadata) 更新成功,返回 true upsert_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_namespace
normal 覆盖为 serverless 变体切换成功,返回 true upsert_runner_config_overwrites_different_variant
重复提交相同配置 幂等成功,不报错 upsert_runner_config_idempotent
slots_per_runner = 0(serverless) 请求被拒绝 upsert_runner_config_serverless_slots_per_runner_zero
drain_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?namespace=my-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 配置编排与滚动变更。

登录后查看全文
rivet