Rivet Actors Runner Configs Upsert API 详解:用 PUT /runner-configs 管理多数据中心 Runner 配置
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)。因此:
- 传入空
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:
| 属性 | 类型 | 说明 |
|---|---|---|
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,核心流程如下:
- 认证:
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 的配置:本地区域(
- 结果聚合:对每个 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 = 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 配置编排与滚动变更。