English Manual

rust-supervisor 手册

项目定位

rust-supervisor 是 Rust(编程语言) 任务监督核心库. 它面向 Tokio(异步运行时) 服务, 用声明式模型管理 child(子任务) 的启动, 停止, 重启, 隔离, 状态查询, 事件记录, 健康检查和 Shutdown Without Orphaned Tasks(关闭后不留下孤儿任务).

本项目没有旧接口负担. 使用者应该通过拥有模块路径读取公开类型, 例如 rust_supervisor::runtime::supervisor::Supervisor.

阅读路径

快速开始: 从 YAML(数据序列化格式)配置启动最小 supervisor(监督器).
配置模型: 理解 SupervisorConfig, ConfigState 和配置拒绝启动边界.
监督树: 理解 SupervisorSpec, SupervisorTree 和注册表关系.
任务模型: 理解 ChildSpec, TaskFactory, TaskContext 和 readiness(就绪).
策略模型: 理解重启, 退避, 熔断, 隔离和任务退出分类.
运行时控制: 理解 SupervisorHandle 的控制命令和幂等语义.
Dashboard(看板): 理解 target process(目标进程), relay(中继) 和 dashboard client(看板客户端) 的三端使用流程.
关闭协议: 理解四阶段关闭和 blocking worker(阻塞工作任务)边界.
可观测性: 理解事件, 日志, 追踪, 指标, 审计和运行摘要.
示例程序: 逐个运行 examples/ 下的学习示例.
质量门禁: 运行格式化, 编译, 测试, 文档, SBOM(软件物料清单)和发布检查.

能力边界

supervisor core(监督器核心) 只管理 lifecycle governance(生命周期治理). 高频业务消息属于 data plane(数据面), 不应该每条都经过 supervisor(监督器). control plane(控制面) 只处理生命周期命令, 当前状态, 事件和治理决策.

快速开始

语言: English

前置条件

本项目是 Rust(编程语言) library(库), 需要 Cargo(构建工具) 和 Tokio(异步运行时) 应用环境. 本仓库示例已经包含运行所需依赖.

主配置文件是 examples/config/supervisor.yaml. 配置必须通过 rust-config-tree(集中配置树) v0.1.9 加载 YAML(数据序列化格式), 然后形成 ConfigState(配置状态).

最小运行命令

cargo run --example supervisor_quickstart

该示例执行固定路径: load_config_state 读取 YAML(数据序列化格式), ConfigState::to_supervisor_spec 派生 SupervisorSpec(监督器规格), Supervisor::start 启动 runtime(运行时), current_state 查询当前状态, shutdown_tree 关闭整棵树.

最小代码路径

use rust_supervisor::config::loader::load_config_state;
use rust_supervisor::runtime::supervisor::Supervisor;

#[tokio::main]
async fn main() -> Result<(), rust_supervisor::error::types::SupervisorError> {
    let state = load_config_state("examples/config/supervisor.yaml")?;
    let spec = state.to_supervisor_spec()?;
    let handle = Supervisor::start(spec).await?;
    let current = handle.current_state().await?;
    println!("{current:#?}");
    handle.shutdown_tree("operator", "quickstart complete").await?;
    Ok(())
}

运行结果

当前示例用于验证接入路径, 不是业务任务模板. 使用者需要把自己的 worker(工作任务) 放入 ChildSpec(子任务规格) 和 TaskFactory(任务工厂)边界, 不应该在业务代码中分散启动无人管理的后台任务.

配置模型和结构模式

语言: English

配置入口

配置入口是 rust_supervisor::config::loader::load_config_state. 它只接受 YAML(数据序列化格式)主配置文件, 示例路径是 examples/config/supervisor.yaml.

当前配置形状包含四组数据: supervisor, policy, shutdown 和 observability. 它们分别进入 SupervisorRootConfig(监督器根配置), PolicyConfig(策略配置), ShutdownConfig(关闭配置) 和 ObservabilityConfig(可观测性配置).

rust_supervisor::config::configurable::SupervisorConfig 是公开 root configuration struct(根配置结构体). 它支持 confique::Config(配置派生), schemars::JsonSchema(结构模式生成特征), Serialize(序列化) 和 Deserialize(反序列化). 使用者可以用同一个模型完成 YAML(数据序列化格式) 加载, template generation(模板生成) 和 schema generation(结构模式生成).

ConfigState(配置状态) 是校验后的不可变状态. 运行时不应该在其它模块里保存运行时可调常量.

ConfigState::to_supervisor_spec 会派生 SupervisorSpec(监督器规格). 当前实现用配置值填充 supervision strategy(监督策略),策略默认值,关闭预算,健康检查时间和可观测性容量.

模板边界

官方 template(模板) 是 examples/config/supervisor.template.yaml. 它默认保持单个 YAML(数据序列化格式) 文件, 并覆盖 supervisor, policy, shutdown 和 observability.

本 crate(包) 不会在公开配置结构体, 官方 schema(结构模式) 或官方 template(模板) 中添加 x-tree-split(树形拆分扩展). 如果使用者项目需要拆分配置文件, 可以在自己的项目中包装或复用 SupervisorConfig(监督器配置), 并自行决定 tree split layout(树形拆分布局).

错误边界

配置加载失败会返回 SupervisorError::FatalConfig. 这些情况会拒绝启动:

配置文件不是 YAML(数据序列化格式).
文件无法读取.
YAML(数据序列化格式)无法解析成 SupervisorConfig.
supervision strategy(监督策略) 不是 OneForOne, OneForAll 或 RestForOne.
数值为零.
初始退避大于最大退避.
jitter(抖动)比例不在零到一之间.

Supervisor::start_from_config_file 会在创建 runtime channel(运行时通道) 或派生 control loop(控制循环) 之前拒绝非法配置.

示例配置

supervisor:
  strategy: OneForAll
policy:
  child_restart_limit: 10
  child_restart_window_ms: 60000
  supervisor_failure_limit: 30
  supervisor_failure_window_ms: 60000
  initial_backoff_ms: 100
  max_backoff_ms: 5000
  jitter_ratio: 0.10
  heartbeat_interval_ms: 1000
  stale_after_ms: 3000
shutdown:
  graceful_timeout_ms: 5000
  abort_wait_ms: 1000
observability:
  event_journal_capacity: 256
  metrics_enabled: true
  audit_enabled: true

监督树

语言: English

声明模型

SupervisorSpec(监督器规格) 描述一个 supervisor(监督器)节点. 它包含 path, strategy, children, config_version, 默认重启策略, 默认退避策略, 默认健康策略, 默认关闭策略, supervisor-level fuse(监督器级熔断)限制, restart_budget(重启预算), escalation_policy(升级策略), group_strategies(分组策略集合), child_strategy_overrides(子任务级覆盖集合) 和 dynamic_supervisor_policy(动态监督器策略).

ChildSpec(子任务规格) 描述一个 child(子任务). 它包含 id, name, kind, factory, restart_policy, shutdown_policy, health_policy, readiness_policy, backoff_policy, dependencies, tags 和 criticality.

树构建

SupervisorTree::build 会校验 SupervisorSpec(监督器规格), 再把 children(子任务集合)转换成带路径的节点. 每个 child(子任务)路径来自父路径和 ChildId(子任务标识).

SupervisorPath::root 表示根路径. SupervisorPath::join 用于拼接子路径. SupervisorPath::parent 用于查找父级路径.

启动和关闭顺序

startup_order 按声明顺序返回节点. shutdown_order 按声明顺序的逆序返回节点. 这个顺序是 Shutdown Without Orphaned Tasks(关闭后不留下孤儿任务) 的基础.

重启计划

restart_execution_plan(重启执行计划函数) 根据 tree(监督树) 和 SupervisorSpec(监督器规格) 解析运行时重启范围. 它把 per-child override(子任务级覆盖), group strategy(分组策略), restart budget(重启预算), escalation policy(升级策略) 和 dynamic supervisor policy(动态监督器策略) 放入同一个 plan(计划), 运行时控制循环不需要重复编写策略选择逻辑.

注册表

RegistryStore(注册表存储)按 child id(子任务标识), supervisor path(监督器路径) 和声明顺序保存 ChildRuntime(子任务运行态). 运行时控制和当前状态查询不应该绕过注册表直接访问内部状态.

任务模型

语言: English

任务类型

TaskKind(任务类型) 区分 AsyncWorker(异步工作任务), BlockingWorker(阻塞工作任务) 和 Supervisor(监督器节点). blocking worker(阻塞工作任务)不能被当作普通 async worker(异步工作任务)立即强制终止.

任务工厂

TaskFactory(任务工厂)是核心任务构造契约. 每次 attempt(尝试)必须创建 fresh future(新异步任务). service_fn(函数适配器)只是人体工学入口, 它仍然适配到 TaskFactory(任务工厂), 不替换内核模型.

TaskResult(任务结果)区分 Succeeded(成功), Cancelled(已取消) 和 Failed(已失败). Failed 携带 TaskFailure(任务失败)和 TaskFailureKind(任务失败类别).

任务上下文

TaskContext(任务上下文)包含 child id(子任务标识), supervisor path(监督器路径), generation(代次), attempt(尝试次数), cancellation token(取消令牌), heartbeat(心跳)发送入口和 readiness(就绪)发送入口.

worker(工作任务)应该通过 TaskContext::heartbeat 报告健康信号, 通过 TaskContext::mark_ready 报告显式就绪, 通过 TaskContext::is_cancelled 或 TaskContext::cancellation_token 响应关闭.

就绪语义

ReadinessPolicy(就绪策略)支持 Immediate(立即就绪)和 Explicit(显式就绪). 显式就绪的 child(子任务)在报告 ready(已就绪)之前, 不应该被 current state(当前状态)或事件显示为 ready(已就绪).

策略模型

语言: English

监督策略

SupervisionStrategy(监督策略)决定失败后的重启范围. OneForOne(一对一)只选择失败 child(子任务). OneForAll(一对全部)选择已选范围内的全部 child(子任务). RestForOne(从失败处开始)选择已选范围内的失败 child(子任务)和之后声明的 child(子任务).

restart_scope 根据 SupervisorTree(监督树), 策略和失败 child id(子任务标识)计算重启范围.

restart_execution_plan(重启执行计划函数) 会把 supervisor strategy(监督器策略), GroupStrategy(分组策略), ChildStrategyOverride(子任务级覆盖), RestartBudget(重启预算), EscalationPolicy(升级策略) 和 DynamicSupervisorPolicy(动态监督器策略) 合并成 StrategyExecutionPlan(策略执行计划). child override(子任务级覆盖) 优先于 group strategy(分组策略), group strategy(分组策略) 优先于 supervisor-wide strategy(监督器全局策略).

runtime control loop(运行时控制循环) 现在会接收 child exit(子任务退出), 并在 policy(策略) 返回重启决策时自动执行选定的 StrategyExecutionPlan(策略执行计划). runtime lifecycle event(运行时生命周期事件) 使用 restart_plan(重启计划), 让 operator(操作者) 可以看到选中的 strategy(策略), group(分组) 和 child scope(子任务范围).

分组策略和子任务覆盖

GroupStrategy(分组策略) 使用 child tag(子任务标签) 定义更小的重启范围. 一个 child(子任务) 最多只能属于一个已配置 strategy group(策略分组). ChildStrategyOverride(子任务级覆盖) 在单个 child(子任务) 需要比 group(分组) 或 supervisor(监督器) 更严格的重启行为时生效.

重启预算和升级策略

RestartBudget(重启预算) 记录选中计划的最大重启次数和计数窗口. EscalationPolicy(升级策略) 记录重启治理不能停留在本地时的后续动作, 包含 parent escalation(父级升级), tree shutdown(整棵树关闭) 或 scope quarantine(范围隔离).

动态监督器策略

DynamicSupervisorPolicy(动态监督器策略) 控制运行时 add_child(添加子任务) 是否被接受. 当前命令接收 child manifest(子任务清单文本), 并跟踪 dynamic manifest count(动态清单数量). 当 dynamic supervision(动态监督) 被禁用, 或已经达到配置的 child limit(子任务上限) 时, 添加会被拒绝.

重启策略

RestartPolicy(重启策略)包含 Permanent(永久), Transient(瞬时)和 Temporary(临时). PolicyEngine(策略引擎)读取 TaskExit(任务退出), 失败类别和重启策略, 输出 RestartDecision(重启决策).

退避和抖动

BackoffPolicy(退避策略)描述初始延迟, 最大延迟, jitter(抖动)模式和 reset-after(稳定后重置). 测试可以使用 deterministic jitter(确定性抖动), 避免依赖随机结果.

熔断和隔离

MeltdownPolicy(熔断策略)限制一个窗口内的重启或失败次数. 超过 child-level fuse(子任务级熔断)会进入 quarantine(隔离). 超过 supervisor-level fuse(监督器级熔断)会升级到父级.

任务退出分类

TaskExit(任务退出)区分成功, 取消, 类型化失败, panic(恐慌)和 timeout(超时). 策略层必须读取类型化分类, 不应该从字符串推断行为.

运行时控制

语言: English

控制入口

SupervisorHandle(监督器句柄)是运行时控制入口. 它通过命令通道把请求发送给 runtime control loop(运行时控制循环), 并返回 CommandResult(命令结果).

控制命令

add_child: 当 DynamicSupervisorPolicy(动态监督器策略) 允许新增 child(子任务) 时, 接受 dynamic child manifest(动态子任务清单文本).
remove_child: 先关闭目标 child(子任务), 再移除注册表记录.
restart_child: 请求目标 child(子任务)重启.
pause_child: 暂停目标 child(子任务)治理.
resume_child: 恢复目标 child(子任务)治理.
quarantine_child: 把目标 child(子任务)放入隔离状态.
shutdown_tree: 关闭整棵监督树.
current_state: 返回当前 SupervisorState(监督器状态).
subscribe_events: 订阅生命周期事件.

幂等语义

重复控制命令不应该制造不可恢复错误. 已暂停的 child(子任务)再次暂停时返回当前状态. 已隔离的 child(子任务)再次隔离时返回当前状态. 已完成 shutdown(关闭)后再次关闭时返回已有关闭结果.

动态添加

运行时会在接受 manifest(清单文本) 前执行 dynamic addition(动态添加) 治理. 当 dynamic supervision(动态监督) 被禁用, 或 declared child count(声明子任务数量) 加 dynamic child count(动态子任务数量) 已经达到配置上限时, add_child(添加子任务) 会被拒绝. current_state(当前状态) 的 child_count(子任务数量) 包含已经接受的 dynamic manifest(动态清单文本).

审计数据

每个控制命令都带有 requested_by(请求者), reason(原因), target_path(目标路径), accepted_at(接受时间)和 command_id(命令标识). 这些字段用于 audit event(审计事件)和问题追踪.

Dashboard(看板) 三端使用流程

语言: English

dashboard(看板) 功能由三个仓库共同完成. rust-supervisor 只负责 target process(目标进程) 本机 IPC(进程间通信) 和 shared contract(共享契约). ~/rust-supervisor-relay 负责 relay(中继) 和外部 wss:// session(会话). ~/rust-supervisor-ui 负责 browser dashboard client(浏览器看板客户端).

下面的 screenshot(截图) 展示 dashboard client(看板客户端) 的 target list(目标列表), topology(拓扑), state(状态) 和 runtime stream(运行时流) 集中视图.

rust-supervisor dashboard(看板) screenshot(截图)

三端职责

rust-supervisor: target process(目标进程) 读取 SupervisorConfig(监督器配置), 在 ipc.enabled=true 时打开 Unix domain socket(Unix 域套接字), 并生成 snapshot(快照), event record(事件记录), log record(日志记录), command result(命令结果) 和 registration heartbeat(注册心跳).
rust-supervisor-relay: relay(中继) 监听 registration socket(注册套接字), 保存 target registry(目标注册表), 对外提供 wss:// dashboard session(看板会话), 校验 mTLS(双向传输层安全协议认证) 和 allowed IPC path prefix(允许的进程间通信路径前缀), 并把会话命令转发到 target process(目标进程).
rust-supervisor-ui: dashboard client(看板客户端) 通过 wss:// 连接 relay(中继), 显示 target list(目标列表), topology(拓扑), state(状态), event stream(事件流), log tail(日志尾部) 和 command audit(命令审计).

本地演示流程

先启动 relay(中继). 它必须先监听 registration socket(注册套接字), target process(目标进程) 才能注册自己.

cd ~/rust-supervisor-relay
cargo run -- --config examples/config/dashboard-relay.local.yaml

再启动 target process(目标进程). 它会打开本机 IPC(进程间通信) socket(套接字), 并向 relay(中继) 发送 registration heartbeat(注册心跳).

cd ~/rust-supervisor
cargo run --example demo -- --config examples/config/supervisor.local.yaml

最后启动 dashboard client(看板客户端). browser script(浏览器脚本) 只连接 relay(中继), 不直接读取 target process(目标进程) 的本机 IPC(进程间通信) socket(套接字).

cd ~/rust-supervisor-ui
VITE_SUPERVISOR_RELAY_URL=wss://localhost:9443/supervisor npm run dev

运行顺序

relay(中继) 接收到 registration heartbeat(注册心跳) 后, 只把 target process(目标进程) 放入 target registry(目标注册表). 这个注册动作不会触发 event(事件) 或 log(日志) 主动推送. dashboard client(看板客户端) 建立 authenticated dashboard session(已认证看板会话) 并选择目标后, relay(中继) 才连接 target process(目标进程) IPC(进程间通信) socket(套接字), 读取 state(状态), 并按会话请求订阅 events.subscribe 或 logs.tail.

控制命令必须从 dashboard client(看板客户端) 发起, 经过 relay(中继) session validation(会话校验), 再发送到 target process(目标进程). 每个命令必须带上 operator identity(操作者身份), target identity(目标身份) 和 reason(原因). dangerous command(危险命令) 还必须在 client(客户端) 中完成确认.

验证命令

cd ~/rust-supervisor
cargo test --test dashboard_config_test --test dashboard_protocol_shape_test --test dashboard_state_test --test dashboard_stream_test --test dashboard_performance_test

cargo test --manifest-path ~/rust-supervisor-relay/Cargo.toml
npm --prefix ~/rust-supervisor-ui run test
npm --prefix ~/rust-supervisor-ui run build
npm --prefix ~/rust-supervisor-ui run test:e2e:three-end

生产接入注意事项

target process(目标进程) 只能暴露本机 Unix domain socket(Unix 域套接字), 不能直接把 IPC(进程间通信) 暴露到外网. relay(中继) 对外只能使用 wss://. mTLS(双向传输层安全协议认证) client certificate(客户端证书) 由 browser(浏览器) 或 operating system certificate store(操作系统证书库) 选择, page script(页面脚本) 不能读取证书私钥. ipc.path, registration.relay_registration_path 和 relay(中继) 的 allowed IPC path prefix(允许的进程间通信路径前缀) 必须同时匹配, 否则目标会注册失败或被 relay(中继) 拒绝连接.

关闭协议

语言: English

正式术语

本项目使用 Shutdown Without Orphaned Tasks(关闭后不留下孤儿任务) 描述关闭目标. root shutdown(根关闭)完成后, runtime(运行时)不应该留下 orphan task(孤儿任务).

四阶段

关闭协议包含四个阶段:

request stop(请求停止): 接受关闭原因并传播 cancellation token(取消令牌).
graceful drain(优雅排空): 等待 child(子任务)自行结束.
abort stragglers(强制终止拖尾任务): 对超时的异步任务执行强制终止或升级.
reconcile(状态对账): 统一 registry(注册表), current state(当前状态), metrics(指标)和 event journal(事件日志缓冲区).

顺序

启动按声明顺序执行. 关闭按声明顺序的逆序执行. 这个规则由 startup_order 和 shutdown_order 提供.

阻塞任务边界

BlockingWorker(阻塞工作任务)表示 spawn_blocking(阻塞任务启动) 或其它不能假设立即 abort(强制终止)的任务. 关闭超时后, runtime(运行时)应该记录不可立即终止边界, 并按照升级策略处理.

关闭原因

ShutdownCause(关闭原因)记录 requested_by(请求者)和 reason(原因). 它应该进入审计和诊断输出.

可观测性

语言: English

事件模型

SupervisorEvent(监督器事件)描述一次 lifecycle fact(生命周期事实). 它包含 When(何时), Where(何处), What(发生内容), sequence(序号)和 correlation id(关联标识).

When(何时)记录 wall time(墙钟时间), monotonic time(单调时间), uptime(运行时长), generation(代次)和 attempt(尝试次数). Where(何处)记录 supervisor path(监督器路径), child id(子任务标识), parent id(父标识)和任务名称. What(发生内容)记录状态迁移, 策略决定, 健康状态, 退出原因或控制命令.

管线输出

observability pipeline(可观测性管线)把同一事实同步为这些信号:

SupervisorEvent(监督器事件).
structured log(结构化日志).
tracing(结构化追踪) span(追踪范围)和 event(追踪事件).
metrics(指标).
audit event(审计事件).
event journal(事件日志缓冲区).
test recorder(测试记录器).

指标标签

metrics label(指标标签)必须保持低基数. 可以使用 supervisor path(监督器路径), child id(子任务标识), state(状态), decision(决定)和 failure category(失败类别). 不应该使用错误全文, 用户输入或无界动态值.

诊断回放

event journal(事件日志缓冲区)保存固定容量的最近事件. RunSummary(运行摘要)从事件日志, current state(当前状态)和策略决定生成诊断摘要, 用于解释 meltdown(熔断), 关闭超时或父级升级.

示例程序

语言: English

快速开始

cargo run --example supervisor_quickstart

supervisor_quickstart 读取 examples/config/supervisor.yaml, 派生 SupervisorSpec(监督器规格), 启动 supervisor(监督器), 查询 current state(当前状态), 然后关闭整棵树.

配置树

cargo run --example config_tree_supervisor

config_tree_supervisor 展示 rust-config-tree(集中配置树) v0.1.9 的 YAML(数据序列化格式)配置加载路径, 并打印派生后的 SupervisorSpec(监督器规格).

重启策略实验

cargo run --example restart_policy_lab

restart_policy_lab 展示 TaskFailure(任务失败), TaskFailureKind(任务失败类别), RestartPolicy(重启策略), canonical spec::supervisor::SupervisionStrategy(规范归属的监督策略) 和 RestartDecision(重启决策) 的基本形状.

关闭树

cargo run --example shutdown_tree

shutdown_tree 展示 request stop(请求停止), graceful drain(优雅排空), abort stragglers(强制终止拖尾任务)和 reconcile(状态对账)四个阶段, 然后执行 shutdown_tree.

可观测性探针

cargo run --example observability_probe

observability_probe 订阅事件流, 查询当前状态, 打印一个事件, 然后执行关闭. 它用于检查 observability(可观测性)接入路径.

监督树故事

cargo run --example supervisor_tree_story

supervisor_tree_story 声明 market feed(行情输入), risk engine(风控引擎) 和 audit sink(审计输出) 三个 child(子任务), 展示 dependencies(依赖), tags(标签), criticality(关键程度), explicit readiness(显式就绪), startup order(启动顺序), shutdown order(关闭顺序) 和 RestForOne(从失败处开始) restart scope(重启范围).

运行时控制故事

cargo run --example runtime_control_story

runtime_control_story 启动真实 supervisor(监督器), 执行 add_child, pause_child, resume_child, quarantine_child, current_state, subscribe_events 和 shutdown_tree. 它覆盖 operator control(操作员控制) 和 audit event(审计事件) 的组合场景.

策略失败矩阵

cargo run --example policy_failure_matrix

policy_failure_matrix 对 Permanent(永久), Transient(瞬时) 和 Temporary(临时) restart policy(重启策略) 分别输入 success(成功), external dependency(外部依赖), fatal bug(致命缺陷) 和 panic(恐慌) 退出结果, 同时展示 deterministic jitter(确定性抖动) 和 meltdown tracker(熔断跟踪器).

诊断回放

cargo run --example diagnostic_replay

diagnostic_replay 构造 deterministic event(确定性事件), 写入 event journal(事件日志缓冲区), 回放 failure(失败), backoff(退避) 和 restart(重启) 事实, 然后生成 metrics(指标) 样本和 RunSummary(运行摘要). 它用于排查生产事件后的 replay(回放) 和 report(报告) 路径.

质量门禁

语言: English

基线命令

cargo fmt --check
cargo check
cargo test
cargo doc --no-deps
cargo package --list
scripts/check-coding-standard.sh
scripts/check-maintainability.sh
scripts/generate-sbom.sh
scripts/validate-sbom.sh
cargo publish --dry-run

Keyboard shortcuts

rust-tokio-supervisor 手册