KernLab.Cell 快速开始
定位
KernLab.Cell 是 .NET 的运行时容器库:把隔离单元下沉到进程——每个容器是一个真实子进程, 为多租户宿主提供崩溃隔离(子进程崩溃不带走宿主)与 OS 级资源上限(cgroup v2 / JobObject,执法者是操作系统)。 核心是一条单机 IPC 通信闭环:装载 → 握手 → 调用 → 回调 → 遥测 → drain。宿主侧与容器侧分属两个包, 使用方业务代码以 pack(装载扩展点)形态进容器。
快速上手
最小可运行闭环=宿主 spawn 一个容器进程、调用一个装载点、drain 收场。
第一步:写一个 pack(业务装载点)
using KernLab.Cell.Contracts;
namespace MyApp.Packs;
public sealed class EchoStartup : ICellPackStartup
{
public void Configure(ICellPackBuilder packs)
{
// 装载点键 + 编解码 id + 处理委托(payload 进出都是字节——词汇权归使用方)
packs.RegisterSite("app.echo", CellCodecIds.None,
static (payload, ct) => ValueTask.FromResult<ReadOnlyMemory<byte>>(payload.ToArray()));
}
}
第二步:宿主侧启动容器并调用
using KernLab.Cell;
using KernLab.Cell.Contracts;
var options = new CellProcessStartOptions
{
RuntimeDllPath = "path/to/KernLab.Cell.Runtime.dll",
Packs = ["path/to/MyApp.Packs.dll"],
StartupTypeName = "MyApp.Packs.EchoStartup",
InstanceLabel = "tenant-42", // 握手防误连的实例标签
};
// spec = 租户 + 包集 + 世代(池按 spec 全值分键;替补必须同规格)
var spec = new CellSpec("tenant-42", ["pack.echo"], generation: 0);
var (process, channel, ready) = await CellLoadPipeline.StartAsync(spec, options);
// 调用装载点(串行关联域;deadline 到期自动失败 DEADLINE_EXCEEDED)
var result = await channel.InvokeAsync("app.echo", CellCodecIds.None, "ping"u8.ToArray());
// result.ErrorCode == CellInvocationErrors.Success;result.Payload == "ping"
// drain:容器停接新调用、在途收尾后退出(退出码 0)
await channel.SendByeAsync(drainWindowMilliseconds: 2000);
process.KillTree();
await process.DisposeAsync();
await channel.DisposeAsync();
容器进程无须手写引导代码:宿主侧以 dotnet KernLab.Cell.Runtime.dll 拉起(CellProcessStartOptions
默认即此形态),容器自报端点、完成握手三步后进入服务循环。
概念与术语
| 术语 | 含义 |
|---|---|
| 容器(container) | 一个真实子进程,运行 KernLab.Cell.Runtime 引导器;进程数 = 实例数,不是包数 |
| spec | 租户标识 + 包集 + 世代——池的键;包集变更 = 新世代新容器,热升级不做 |
| pack | 使用方业务程序集,实现 ICellPackStartup 注册装载点;装入容器内可回收的程序集加载上下文 |
| 装载点(site) | pack 注册的可调用单元;Invoke 帧按键分派;未注册键应答 PackNotFound |
| 通道(channel) | 宿主侧会话句柄:调用、取消、回调服务分发、遥测消费、通知收发、drain |
| drain | 有序收场:停接新调用、在途跑完或窗口到期,容器以退出码 0 退出 |
怎么选
| 方案 | 优势 | 代价 | 适用场景 |
|---|---|---|---|
| KernLab.Cell | 崩溃爆炸半径 = 子进程;OS 强制资源上限;包间依赖版本天然共存 | 跨进程往返有微秒级通信税;运维对象多一个进程 | 不可捕获崩溃风险高 / 需要硬资源边界的多租户宿主 |
| 同进程 ALC | 零通信税;部署单元少 | 卸载可能挂起;不可捕获崩溃带走宿主;无 OS 级资源边界 | 纯版本隔离、崩溃风险可控的插件场景 |
决策:要"崩不带走宿主 + 硬资源顶"选 Cell;只是版本隔离、故障面可控,ALC 足够。 同一 pack 契约两档承载皆可(业务代码不变),隔离档位是部署决定。
怎么用
载体选择(tcp / uds / np / shm)
CellProcessStartOptions.Carrier:tcp(缺省,环回)/ uds(仅 Unix;SocketDirectory 指定套接字落点)/
np(仅 Windows——命名管道,UDS 的 Windows 对位物;管道名全自动)/
shm(同机共享内存——数据直写映射内存,段建立与传递全自动)。
各载体同一套通道语义,上层零感知;实测往返(64B 载荷、Release)环回 TCP p50 ≈203µs、UDS ≈90µs(Linux)、
np ≈138µs(Windows,较 tcp 快 ≈1.5×)、shm ≈79µs。同机低时延场景开忙轮询档:
var options = new CellProcessStartOptions
{
Carrier = "shm",
ShmWaitStrategy = ShmRingWaitStrategy.BusySpin, // p50 ≈17µs;代价=每方向一个核
// ...
};
详见通道与调用面·载体选择与性能基线。
流式调用(大体载荷)
4MB 或无固定上界的载荷走分块流式(ChunkBegin/ChunkData/ChunkEnd——内存有界,块 256KB, 与 body 大小无关;
MaxFrameLength4MB 单帧上限不变):
// 容器侧:pack 注册流式装载点(请求体 PipeReader 进、响应 PipeWriter 出)
packs.RegisterStreamingSite("app.body", CellCodecIds.None,
static async (request, response, ct) =>
{
await request.CopyToAsync(response, ct); // 例:逐段回显——真实场景按段消费
await response.CompleteAsync();
});
// 宿主侧:请求体边读边发,响应体流式读;必须读到体尽并等收场尾单
var invocation = await channel.InvokeStreamAsync("app.body", CellCodecIds.None,
requestBodyReader, deadline: TimeSpan.FromMinutes(5));
// ... 逐段消费 invocation.Body ...
var trailer = await invocation.Completion; // ErrorCode 非 0=调用失败(已读体是部分产物)
流控继承有界管道背压(消费慢=对端写侧暂停,无额外往返);deadline 跨全程,
channel.CancelAsync(invocation.CallId) 中断流。≤4MB 小载荷继续走 InvokeAsync 单帧路径。
回调(容器 → 宿主)
容器内 pack 经回调桥调用宿主注册的服务(键 + 委托),requestId 多路复用、并发安全:
// 宿主侧注册;容器内经 packs.CallbackBridge.CallAsync("host.upper", ...) 调用
channel.RegisterCallbackService("host.upper",
static (payload, ct) => ValueTask.FromResult<ReadOnlyMemory<byte>>(
Encoding.UTF8.GetBytes(Encoding.UTF8.GetString(payload.Span).ToUpperInvariant())));
遥测
容器内经 packs.Telemetry.Write(kind, severity, payload) 写遥测;有界队列、满则丢最旧、
永不阻塞调用路径;宿主侧订阅 channel.TelemetryBatch。心跳期空批到达=活性信号。
通知(免应答推送)
双向轻量信号通道(Notify 帧,tag 0x50):免应答、可丢、不占关联域——宿主高频推配置/信号 不阻塞自己,容器上报业务事件不等宿主处理。投递语义=尽力有序(单派发者 FIFO)、有界丢最旧 (256 条 / 1MB 双限)+丢弃计数可见:
// 宿主 → 容器:注册通知 handler(串行分派——应快速返回,重活转投自有任务)
// 容器侧 pack 装配时:
packs.RegisterNotificationHandler("app.config.reload",
static (payload, ct) => { ApplyConfig(payload); return ValueTask.CompletedTask; });
// 宿主侧:免应答推送(即时返回——队列满丢最旧+计数;容器未声明能力=结构化拒绝)
await channel.NotifyAsync("app.config.reload", configBytes);
// 容器 → 宿主:通知出口(ICellTelemetryEgress 同型——即时返回、满则丢最旧、永不阻塞业务路径)
packs.Notifications.Notify("app.event.ready", stateBytes);
long dropped = packs.Notifications.DroppedCount; // 出站丢弃计数
long inboundDropped = packs.Notifications.InboundDroppedCount; // 入站未达 handler 计数
// 宿主侧订阅(事件内联于泵循环——handler 应快速转投自有队列,慢 handler=整通道背压)
channel.ContainerNotification += n => Console.WriteLine($"{n.Key}: {n.Payload.Length}B");
语义边界(负面清单):业务不可丢事件禁走通知——丢不得的走 InvokeAsync/回调桥
(超时即显式失败);遥测道维持纯观测面,业务通知不借道。通知键与装载点键同一词汇纪律
(使用方自定义串)。v1 载荷建议 ≤64KB,大内容走流式调用。
资源上限
CellResourceDeclaration(内存 / CPU 配额 / 进程数)随 CellProcessStartOptions.ResourceLimits
声明,翻译为 cgroup v2(Linux)/ JobObject(Windows)——执法者是 OS,超限即被杀或限流。
两侧执法均有 OS 侧实证回归门:Linux memory.max 下超限子进程被内核击杀;Windows
ProcessMemoryLimit 下超限分配被内核拒绝(OOM 退出)。
消费侧自有 exe 壳(嵌入 RunAsync)
容器进程不必是 dotnet KernLab.Cell.Runtime.dll——使用方可自建瘦 exe 壳(自有进程签名与
CLI 词汇,总体设计 §13 的 PluginHost 映射形态),嵌入 CellContainerRuntime.RunAsync 引导:
using KernLab.Cell.Runtime;
// 自有 exe 壳的 Main:CLI 透传(Parse)或自行组装(编程构造)皆属公开契约
var bootArgs = CellBootArgs.Parse(args);
return await CellContainerRuntime.RunAsync(bootArgs, Console.Out, Console.Error);
嵌入路径与 CLI 同契约(有嵌入回归门钉住,防 API 漂移):
零孤儿在 RunAsync 内:
CellBootArgs.ParentPid非空即启用 1s 轮询看门狗——CLI 与嵌入壳 单一实现(CellOrphanWatch.Start(pid, onParentDead)公开可复用,嵌入方可自选父死处置; RunAsync 缺省按 §6.1 以退出码 0 自杀——容器进程必须死,嵌入壳同受进程级契约约束)。退出码契约:RunAsync 返回值即进程退出码——
0=drain/父退出正常终态,11=运行期致命。stderr 取证前缀:运行期致命写入注入的 stderr(
[cell] fatal:前缀)——嵌入壳注入自有 流即得取证;stdout 端点自报(CELL_ENDPOINT=…)同理走注入流。契约单源集注入:pack 与容器共享的契约程序集缺省=
KernLab.Cell.Contracts+KernLab.Loom.Abstractions+System.IO.Pipelines(凡出现在公开接口签名里的程序集都是契约)。 消费侧自有契约域需与容器单源时经CellRuntimeOptions.SharedContractAssemblies注入 (替换语义——连同缺省项一并列全):return await CellContainerRuntime.RunAsync(bootArgs, Console.Out, Console.Error, new CellRuntimeOptions { SharedContractAssemblies = ["KernLab.Cell.Contracts", "KernLab.Loom.Abstractions", "System.IO.Pipelines", "My.Contracts"] });
零孤儿(宿主 spawn 形态)
宿主编程式 spawn(CellLoadPipeline.StartAsync/CellProcess.StartAsync)显式声明
CellProcessStartOptions.ParentPid——spawn 自动补 --parent-pid,容器内看门狗生效:
宿主进程崩溃(非 drain)=容器自杀(退出码 0),不留孤儿(持资源、端口/段名残留)。
生产形态宿主必填(显式优于隐式,不自动取当前 pid):
var options = new CellProcessStartOptions
{
// ...
ParentPid = Environment.ProcessId, // 宿主自身——宿主死则容器死
};
取消与 deadline
InvokeAsync 传 deadline:到期宿主侧自动失败(不悬挂);容器侧收到取消会向处理委托传 ct。
主动取消用 channel.CancelAsync(callId)。
反模式
| 症状 | 为什么错 | 正确形态 |
|---|---|---|
| 在容器进程里写 HTTP 服务器 / HttpClient / 存储 | 容器是无状态计算壳——状态与出站真源归宿主(负面清单) | 业务出站经回调桥回到宿主侧处理 |
用 Assembly.LoadFrom 在宿主直接装业务 dll 模拟容器 |
类型分裂 + 无进程边界——隔离承诺全部失效 | 走 --pack 装载管线,pack 进容器 |
drain 前直接 KillTree |
在途调用被硬断,结果未知 | 先 SendByeAsync 给收场窗口,超时再 kill 兜底 |
复用 InvokeAsync 返回的 payload 缓冲跨调用 |
帧体缓冲池化归还,复用=读脏数据 | 需要留存就 ToArray() 拷贝 |