Go + gRPC 插件式服务框架 —— 技术实现与分析

0 阅读38分钟

Go + gRPC 插件式服务框架 —— 技术实现与分析

image.png

项内容
定位可复用的工程手册。回答"下一个类似系统怎么搭",不描述某一个具体系统
来源《局域网数据中转服务 架构设计方案 v2.0》(长驻采集型) + 《depot 架构设计方案 v2.2》(一次性任务型)
状态沉淀稿,可持续追加
用法① 评估要不要做插件化 → §1;② 判断属于哪种语义 → §2;③ 照着搭 → §3–§9;④ 排障 → §10;⑤ 交付前自检 → §11

这份文档与两份源文档的关系
两份源文档回答"我这个系统怎么设计"。这份回答"这类系统怎么设计"——把两个项目里结构相同、结论相同的部分抽出来(约占 70%),把因语义不同而必须分歧的部分并排列出(约占 30%),并补上源文档里没有写细的工程细节:可复制的代码、跨平台行为差异、能被 CI 卡住的检验。

两个项目的核心结论高度一致,这本身就是最强的可复用性证据:契约层零业务、插件独立进程、事件流单向、宿主不理解插件业务。分歧只出现在"进程活多久"和"状态怎么收敛"这两处。


0. 一页纸总览

这套框架的实质是 5 个部件 + 1 条纪律。

#部件解决什么关键产出
1契约 core/contract + proto宿主与插件之间唯一稳定的东西Plugin 接口、Manifest、FormSchema、Event、4 个 RPC
2插件 SDK pluginkit让插件作者只写业务逻辑pluginkit.Main(p) 一行启动,作者永不 import grpc
3supervisor core/host进程的拉起、握手、超时、杀干净约 400 行,跨平台
4运行时 core/runtime状态机、并发、取消传播、崩溃归因任务/实例的生命周期
5数据面 core/eventbus事件分流、背压、SSE一个 stream → 三个消费者
—纪律契约层不出现任何业务名词一条 CI grep(§3.6)

一句话记住整套设计的判据:

宿主对插件的全部认知,来自 Manifest 的声明;插件对宿主的全部依赖,来自 pluginkit 的封装。中间任何一处需要"宿主知道某个插件特别"的地方,都是抽象泄漏。


1. 决策:什么时候该做插件化

1.1 五个判据(有一个不成立就别做)

#判据不成立时的做法
1存在 ≥3 个功能上彼此无关的实现,且会持续增加1–2 个就是普通模块,加 interface 即可
2它们的依赖会互相打架(同一 SDK 的不同版本、体积巨大的驱动)合并进一个二进制,省掉全部 IPC 成本
3单个实现崩溃/卡死不能拖垮管理面进程内 + recover + 超时即可
4需要独立发版(改一个插件不能要求重装整个平台)随主程序发版,编译期注册最省事
5团队边界清晰(不同人/不同时间写不同插件,且不读框架源码)一个团队短周期迭代,插件化是纯负担

判据 2 和 3 是最容易被低估的两条。它们不是"架构洁癖",而是运行期无解的问题:

  • 依赖冲突没有任何运行期解法。influxdb3-go 和 influxdb-client-go 都拉 apache/arrow,合并后 Go 的 MVS 会强制统一版本,行为不确定且不报错。
  • 崩溃域无法靠 recover 兜住 OOM 和栈溢出。一次大表备份吃满内存,recover 拿不到执行机会。

1.2 三种宿主模式

模式依赖隔离崩溃隔离独立发版调试体验跨平台结论
A 编译期注册(import 注册表)✗✗✗最好✓判据全过但只是"分层",不是插件
B Go 原生 plugin(.so)部分✗部分差✗ Windows 不支持不要用,见下
C 独立进程 + gRPC✓ 完全✓ 完全✓中✓判据 2/3/4 成立时选它

为什么 B 必须排除(不是偏好,是硬约束):

  1. Windows 不支持,而运维类工具的主要使用场景恰恰是 Windows。
  2. 主程序与插件必须完全相同的 Go 版本 + 相同的编译参数 + 相同的依赖版本,一旦不同就是运行时 panic 或静默错乱。这直接否定了它存在的意义——依赖隔离。
  3. 无法卸载,加载后常驻内存。
  4. 崩溃不隔离,.so 里一个 nil deref 拖垮整个宿主。

有些人会问"那 hashicorp/go-plugin 呢"。它是 C 的一种实现,见 §4.0。

1.3 独立进程的四条真实理由(按硬度排序)

序理由不可替代性
1依赖各自收敛无运行期替代方案。这是最硬的一条
2崩溃域隔离无运行期替代方案(OOM / 栈溢出 / 死循环)
3独立发版与灰度可以用特性开关部分替代,但成本更高
4语言中立只在"插件可能不是 Go 写"时成立

第 4 条要特别注意:它经常被当作主要理由,其实它是最弱的一条。纯 Go 团队用插件化,前三条就足够了;反过来,如果只有第 4 条成立而前三条不成立(比如插件都很轻、依赖一致),那用一个独立的小服务 + HTTP 反而更简单。

实践经验:把理由 4 当成决策依据的项目,最后往往发现"其实没人写非 Go 插件",却为此付出了跨语言协议的复杂度。先用前三条例由说服自己,第 4 条当赠品。

1.4 反模式:把"分层"当成"插件化"

反模式症状后果
插件目录 + switch pluginID宿主里出现 if p.ID == "influxdb2-backup"每加一个插件要改宿主,插件化名存实亡
插件共享一个全局 Config 结构体所有插件都 import 宿主的 config 包插件无法独立测试、独立发版
插件直接写宿主数据库插件 import core/store表结构变更要同步改所有插件;事务边界失控
插件自选产物落盘路径插件返回绝对路径保留策略、配额、跨机迁移全部无法实施
宿主为某插件加专用 API/api/influxdb/...新增插件必须改前端,通用性破产

检验方法:把宿主源码 grep 一遍业务名词(见 §3.6)。出现即泄漏。


2. 两种调度语义:这是唯一的真分歧

两个源项目 70% 的结构相同,所有分歧都源于一个问题:插件的进程活多久。

2.1 对照表

维度一次性任务型(depot)长驻服务型(数据中转)
进程生命周期一任务一进程,跑完退出常驻,随宿主启停
启动成本每次 50–80ms,可接受只在启动/升级时付一次
数据方向宿主调 Run,插件回流事件插件主动 Emit,宿主被动接收
事件归属天然属于这次 Run不属于任何调用,要带 instance_id
结束判定流 EOF 即结束靠健康探测 + 显式 Stop
状态模型job 状态机 + 启动收敛desired / actual + Reconciler
失败语义不自动重跑,标记 interrupted自动拉起(退避),比对即自愈
热升级不存在(下次执行用新二进制)需要路由表原子交换 + 排空
背压点宿主读循环一处每个 RPC handler 一处
重复执行用户点击产生新 run周期触发,需要防叠加
主要风险产物不完整、磁盘写满插件僵死、数据重复、跨实例串数据

2.2 怎么选

插件执行时间是否可枚举、有明确起止?
├── 是(备份、迁移、导出、巡检、批处理)
│     → 一次性任务型。进程随任务生死。
│       不要引入 Reconciler、健康探测、平滑切换——它们解决的是"进程该一直在但没在",
│       而一次性任务里"进程没了"本来就是正常的。
└── 否(持续采集、长连接、订阅、代理)
      → 长驻服务型。必须引入 desired/actual + Reconciler。
        不要用"命令式启停 + 失败重试"——重启后你无法知道上次该谁在跑。

2.3 复用边界:哪些能抄,哪些必须重写

部件一次性任务长驻服务复用度
契约骨架(Plugin 接口、Manifest、FormSchema)✓✓100%,只需换方法集
pluginkit(启动、sink、脱敏、截断)✓✓95%
supervisor 的启动/握手/令牌✓✓90%
孤儿回收(三层防护)✓ 关键✓ 关键100%
事件流背压✓✓100%
状态机job 状态机desired/actual + Reconciler0%,语义不同
生命周期操作Run / CancelStart / Stop / Health / UpdateConfig0%
产物管理✓ 核心可选(大文件才需要)按需

结论:把 §3–§5 做成一个独立的库,§6 按语义二选一,§7 按需。这是最省力的复用方式。


3. 契约层:唯一需要冻结的东西

3.1 两个方向的 RPC

插件化系统里一定有双向调用,且方向不能混:

宿主 ──控制面──> 插件     宿主决定"做什么"(Describe / Init / Run / Cancel)
插件 ──数据面──> 宿主     插件上报"发生了什么"(Log / Progress / Metric / Artifact)

关键判断:数据面走"Run 返回的流",还是"插件反向调宿主服务"?

走 Run 的单向流走反向 Host 服务
事件归属天然绑定这次调用要插件自己带 run_id
结束判定EOF 即结束,一处判要靠健康探测或显式 Done
背压实现宿主读循环一处每个 handler 一处,易漏
并发安全插件侧要保证 seq 单调(需加锁)天然并发安全
适用一次性任务长驻 / 多路并发数据流

判据一句话:事件是否天然属于某次调用。属于就用流,不属于就用 broker。混用会产生"流结束了但事件还在来"的歧义,这是最难排查的一类 bug。

3.2 proto 骨架(可直接用)

syntax = "proto3";
package plugin.v1;
option go_package = "example.com/framework/pluginkit/proto;proto";

// ===== 宿主 → 插件(插件实现)=====
service Plugin {
  rpc Describe(Empty) returns (Manifest);
  rpc Init(InitRequest) returns (InitResponse);
  rpc Run(RunRequest) returns (stream Event);      // 单向流,插件只发不收
  rpc Cancel(CancelRequest) returns (Empty);
}

message InitRequest {
  string run_id    = 1;
  string workdir   = 2;   // 插件只能写这里
  bytes  params    = 3;   // 已按 schema 校验并类型转换后的 JSON
  map<string,string> env = 4;  // 少量运行时注入(如 locale、代理)
}

message Event {
  int64  seq      = 1;    // 插件侧单调递增,从 1 开始
  int64  ts_ms    = 2;
  Kind   kind     = 3;
  string level    = 4;    // debug|info|warn|error
  string stage    = 5;    // 阶段名,用于"卡在哪一步"
  string message  = 6;
  int64  cur      = 7;    // 进度当前值
  int64  total    = 8;    // 进度总量,0 表示未知
  map<string,string> fields = 9;  // metric 的名字/标签、artifact 的元数据
  bytes  extensions = 15;  // 预留:所有消息都留扩展位

  enum Kind { LOG = 0; STAGE = 1; PROGRESS = 2; METRIC = 3; ARTIFACT = 4; }
}

// ===== 插件 → 宿主(宿主实现)=====
// 只在"数据面不走流"时启用。一次性任务型通常不需要。
service Host {
  rpc Log(LogEntry) returns (Empty);
  rpc ReportMetric(MetricBatch) returns (Empty);
}

三条 proto 纪律:

  1. 所有消息预留 bytes extensions = 15。第一次不用,但一旦有插件需要扩展而你没留,改 proto 就要全量重编译重发布。
  2. 单向流优先于双向流。双向流看起来灵活,实际带来"两边都要处理半关闭"的状态机,收益几乎为零。
  3. proto 里禁止出现业务名词。不是风格问题,是抽象边界的检验(§3.6)。

3.3 Manifest:能力协商优于版本号

type Manifest struct {
    ID      string `json:"id"`       // 全局唯一,只认这里,不认文件名
    Name    string `json:"name"`
    Version string `json:"version"`
    // 协议版本:委托方与被委托方必须声明自己能说哪一版
    SpecVersion string `json:"spec_version"`   // "1.3"
    // 能力声明:正交特性的集合,替代"用版本号猜能力"
    Capabilities []string `json:"capabilities"` // ["cancel", "resume", "artifacts"]
    // 参数定义:前端据此渲染表单,宿主据此校验
    Form FormSchema `json:"form"`
    // 产物契约(跨插件互通时才需要)
    Produces []Format `json:"produces,omitempty"`
    Accepts  []Format `json:"accepts,omitempty"`
    Limits   Limits   `json:"limits"`
}

type Format struct {
    Format  string   `json:"format"`   // "lp.gz" / "clickhouse-native"
    Version int      `json:"version"`  // 格式版本,从 1 开始
    Roles   []string `json:"roles"`    // 一个产物组内的文件角色
}

为什么能力协商必须优于版本号(这是源文档里最容易被当成形式主义的一条):

版本号是全序,能力是偏序。真实世界的能力组合是偏序的:

插件版本支持取消支持断点续传支持产物
A1.2✓✗✓
B1.3✗✓✓
C1.1✓✓✗

三者版本号有高低之分,但能力集合没有包含关系。宿主如果按 version >= 1.2 判断"能取消",对 B 就会判断错误。改成读 capabilities 则完全正确,而且新插件在旧宿主上能自动降级。

版本号仍然要留,但只承担一件事:判断"这份 manifest 我还能不能解析"。规则收敛为三条(纯 Go monorepo 前提下):

  • major 必须相等,否则拒绝加载并提示"版本不一致,请重装"
  • minor 插件 ≥ 宿主要求的下限
  • 其余一律走 capabilities

3.4 参数 Schema:封闭类型集合

这是"新增插件零前端改动"成立的唯一支点。前端不写任何业务表单,只实现一个 schema 渲染器。

type Field struct {
    Key       string     `json:"key"`        // "src.url",点号表示分组
    Label     string     `json:"label"`
    Type      FieldType  `json:"type"`
    Required  bool       `json:"required"`
    Default   any        `json:"default,omitempty"`
    Options   []Option   `json:"options,omitempty"`   // enum 用
    Help      string     `json:"help,omitempty"`
    DependsOn *Condition `json:"depends_on,omitempty"`
    Secret    bool       `json:"secret,omitempty"`    // 加密入库、回显打码、日志脱敏
}

type FieldType string

const (
    FString   FieldType = "string"    // 单行
    FText     FieldType = "text"      // 多行
    FInt      FieldType = "int"
    FBool     FieldType = "bool"
    FEnum     FieldType = "enum"
    FSecret   FieldType = "secret"    // 与 string 的区别只在存储与展示
    FPath     FieldType = "path"      // 需要宿主做路径校验
    FDuration FieldType = "duration"  // "30m" / "2h"
    FTime     FieldType = "time"      // RFC3339
    FArtifact FieldType = "artifact"  // 从历史产物列表中选择,禁止手输
)

为什么必须封闭:一旦允许插件自定义控件类型,前端就要为每个插件写渲染代码,"零改动"立刻破产。10 种类型足够覆盖 95% 的工具参数;剩下 5% 应该改写参数设计,而不是加类型。

FArtifact 这一项是恢复类工具的保命符。恢复任务如果允许手输产物路径,最常见的事故是:手输了上周的路径,恢复了错误数据,全程无报错。做成枚举,前端从历史产物列表里选,服务端按 accepts 过滤——这类事故直接消失。

校验只写一份:contract.Validate(manifest, values) 同时被宿主 API、CLI、插件自测调用。插件里不再需要 strconv.Atoi。

3.5 契约演进的四条规则

#规则违反后果
1只增字段,不删不改语义已发布插件无法加载,或静默错语义
2所有新增字段必须有默认值语义旧插件不填时宿主行为不确定
3删除/改语义必须升 major见规则 1
4format_version 从第一天就存在已落库/已落盘的数据无法批量重写

规则 4 值得单独说。事件的 format_version、产物的 format + version、API 的 /v1 前缀——这三样即使当前只有 1.0,也必须第一次就写进去。没有版本字段的历史数据,是唯一无法用代码修复的技术债。

3.6 通用性的自动化检验

这是本手册最值得直接抄走的两条 CI 检查。

① 契约层不许出现业务名词

#!/usr/bin/env bash
# ci/check-contract-purity.sh
set -euo pipefail

BAD='influx|clickhouse|mysql|postgres|mqtt|kafka|redis|s3|mongodb'
if grep -rniE "$BAD" core/contract/ pluginkit/proto/ 2>/dev/null; then
  echo "✗ 契约层出现业务名词,抽象已泄漏" >&2
  echo "  修法:把该概念改成通用表达(如 influxdb→timeseries,mqtt→broker)" >&2
  exit 1
fi
echo "✓ 契约层纯净"

② 宿主层的开关语句计数器

# 宿主里出现"按插件 ID 分支"就是插件化在退化,超过阈值即告警
COUNT=$(grep -rnE 'switch .*[Pp]luginID|case "[a-z0-9]+-[a-z0-9]+"' core/ api/ 2>/dev/null | wc -l)
[ "$COUNT" -gt 3 ] && echo "⚠ 宿主出现 $COUNT 处按插件 ID 分支,检查是否泄漏"

这两条检查的意义在于把架构约束变成可执行的门禁。写在文档里的架构原则,三个月后没人记得;写在 CI 里的,每次提交都会被提醒。


4. 宿主 supervisor:约 400 行换来的东西

4.0 先回答"为什么不用 hashicorp/go-plugin"

一句话判断:它的价值集中在长驻插件,而两种语义里只有一种用得上。

维度go-plugin 提供一次性任务需要长驻服务需要
握手 / 版本协商✓✓✓
进程回收部分(见下)✓✓
Ping 健康检查✓✗ 用不上✓
Reattach(宿主重启后接管)✓✗ 用不上部分
GracefulShutdown✓✗ 用不上✓
事件 seq 校验✗✓ 要自己写✗
背压丢弃计数✗✓ 要自己写✓ 要自己写
三源崩溃归因✗✓ 要自己写✓ 要自己写
传递依赖6–8 个(hclog / go-logr / yaml / color …)——

两个决定性事实(基于 main 分支源码核实,换版本需复核):

  1. internal/cmdrunner/cmd_runner.go 的 Start() 只调用 cmd.Start(),Kill() 只调用 cmd.Process.Kill();process_windows.go 里只有一个 _pidAlive,没有 CreateJobObject,没有 Job Object 绑定。也就是说 Windows 上父进程一死,插件必然残留——而这块你无论如何都要自己写。
  2. 它的日志体系是 hclog,与 slog 是两套抽象,并存会让日志格式分裂。

结论:如果你要的是"长驻插件 + 健康探测 + 平滑升级",go-plugin 划算,用它。如果你要的是"一次性任务 + 事件流 + 说清谁杀了进程",自研更省——因为你要的功能它一个都不给。

这个决定是可逆的:gRPC 契约与 supervisor 是两层,换回去只改 core/host 的实现,契约和插件不用动。既然可逆,就选依赖最少、行为最可控的那个。

4.1 寻址与握手

宿主                                       插件进程
 │  CreateJobObject()(Windows,先建)          │
 │  listen(addr)                              │
 │  生成一次性 token                            │
 ├── exec.Command(bin, "--depot-serve") ─────>│
 │   env: ADDR / TOKEN / RUN_ID               │
 │                                            │  连 adv 里给的地址
 │<──────── gRPC 连接 + x-token ──────────────┤
 │   校验 token → 立即作废                     │
 │<──────────── Describe ─────────────────────┤
 │   校验 manifest / spec_version              │
 ├──────────── Init(params) ─────────────────>│
 ├──────────── Run 建立流 ───────────────────>│
 │<──────────── Event… ───────────────────────┤
 │<──────────── EOF ──────────────────────────┤  插件自行退出
 ├── 等退出(超时 Kill)──────────────────────>│
 └── 清理 workdir / listener                   │

地址怎么传:优先 UDS(<run_dir>/<run_id>.sock),不可用时回退 loopback TCP 127.0.0.1:0。

纠正一处常见误判:网上(包括本文档的前置版本)常说"Windows 没有 UDS"。准确的说法是:Windows 10 1803+ 与较新的 Go 支持 AF_UNIX,但受路径长度、所在文件系统(部分网络盘/虚拟盘不支持)、企业安全策略影响,不能假设可用。所以实现上必须"尝试 listen,失败则回退",而不是按 OS 编译期分支。这个区别很重要——按 OS 分支会在"Windows 上其实能用 UDS"的环境里浪费性能,也容易在容器里踩坑。

token 校验的正确位置:连接级,不是请求级。一个插件进程只建一条连接,所以在第一次 RPC上校验,通过后置 consumed = true,之后同 token 再来一律拒绝(防重放)。

type tokenAuth struct {
    token    string
    consumed atomic.Bool
}

func (a *tokenAuth) unary() grpc.UnaryServerInterceptor {
    return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, h grpc.UnaryHandler) (any, error) {
        if info.FullMethod != "/plugin.v1.Plugin/Describe" {
            return h(ctx, req) // 后续请求不再校验,连接已认证
        }
        md, _ := metadata.FromIncomingContext(ctx)
        got := ""
        if v := md.Get("x-depot-token"); len(v) > 0 { got = v[0] }
        if subtle.ConstantTimeCompare([]byte(got), []byte(a.token)) != 1 {
            return nil, status.Error(codes.Unauthenticated, "bad token")
        }
        if !a.consumed.CompareAndSwap(false, true) {
            return nil, status.Error(codes.Unauthenticated, "token already used")
        }
        return h(ctx, req)
    }
}

别用 sleep 等插件就绪。正确做法是等"连接建立 + Describe 返回",配合 10s 超时。sleep 在慢机器上会误判启动失败,在快机器上白等。

4.2 跨平台孤儿回收:三层防护

这是整个宿主实现里最容易漏、最难测、后果最脏的一处。父进程被 kill -9 或被任务管理器结束时,插件会变成孤儿继续写数据——备份写到一半、数据推了一半。

不要指望单一手段。用三层,任意一层生效即可。

第一层:内核级(最快,但有平台差异)

Linux:

//go:build linux

func applyAttrs(cmd *exec.Cmd) {
    cmd.SysProcAttr = &syscall.SysProcAttr{
        Pdeathsig: syscall.SIGKILL, // 父进程死,内核直接 SIGKILL 子进程
        Setpgid:   true,            // 独立进程组,可 kill(-pgid) 一次收掉整棵树
    }
}

Windows:

//go:build windows

type orphanGuard struct{ job windows.Handle }

// newOrphanGuard 必须在 cmd.Start() 之前调用。
// 原因:子进程一旦跑起来就可能派生孙进程,孙进程不会自动进入 job。
func newOrphanGuard() (*orphanGuard, error) {
    job, err := windows.CreateJobObject(nil, nil)
    if err != nil {
        return nil, err
    }
    info := windows.JOBOBJECT_EXTENDED_LIMIT_INFORMATION{
        BasicLimitInformation: windows.JOBOBJECT_BASIC_LIMIT_INFORMATION{
            LimitFlags: windows.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
        },
    }
    if _, err := windows.SetInformationJobObject(
        job,
        windows.JobObjectExtendedLimitInformation,
        uintptr(unsafe.Pointer(&info)),
        uint32(unsafe.Sizeof(info)),
    ); err != nil {
        windows.CloseHandle(job)
        return nil, err
    }
    return &orphanGuard{job: job}, nil
}

// assign 在 cmd.Start() 之后调用。失败不要当致命错误——见下方说明。
func (g *orphanGuard) assign(p *os.Process) error {
    h, err := windows.OpenProcess(
        windows.PROCESS_SET_QUOTA|windows.PROCESS_TERMINATE,
        false, uint32(p.Pid),
    )
    if err != nil {
        return err
    }
    defer windows.CloseHandle(h)
    return windows.AssignProcessToJobObject(g.job, h)
}

func (g *orphanGuard) Close() error { return windows.CloseHandle(g.job) }

三个必须知道的坑:

坑说明处理
AssignProcessToJobObject 可能返回 ERROR_ACCESS_DENIED宿主自己已在一个 job 里(被任务计划程序、CI、容器、systemd 的某些配置启动),Windows 8 之前不支持嵌套 job降级为 warning,不要失败。否则在受限环境直接起不来
job handle 必须保持在宿主进程中打开KILL_ON_JOB_CLOSE 的语义是"最后一个 handle 关闭时杀掉组内所有进程"存到 session 结构体里,别被 GC 前就 Close
cmd.Process.Kill() 在 Windows 上不杀子进程树插件如果调了外部 CLI(influxd、clickhouse-client),那些孙进程会活下来job object 正好覆盖这一点——这是它相对 Kill() 的真正价值
第二层:连接级(跨平台通用,无竞态)

这一层是真正可靠的那一层,很多人漏掉。

插件通过 gRPC 与宿主通信。宿主一死,TCP/UDS 连接必然断开(内核保证)。所以插件只要监视连接状态,断开即自杀:

// pluginkit 内部,插件侧
func watchParent(conn *grpc.ClientConn) {
    go func() {
        for {
            s := conn.GetState()
            if s == connectivity.Shutdown || s == connectivity.TransientFailure {
                // 连续 N 次都无法恢复 → 宿主没了
                if !waitRecover(conn, 30*time.Second) {
                    fmt.Fprintln(os.Stderr, "parent gone, exiting")
                    os.Exit(137) // 128+SIGKILL,便于宿主侧归因
                }
            }
            conn.WaitForStateChange(context.Background(), s)
        }
    }()
}

它的价值在于:Linux 的 Pdeathsig 在 fork 与 prctl 之间有极小窗口,Windows 的 AssignProcessToJobObject 在 Start 与 Assign 之间有极小窗口。这两处窗口都无法在应用层消除。连接级检测没有窗口——它不依赖任何时序,只依赖"连接断了"这个既成事实。

第三层:启动兜底(覆盖一切没预料到的情况)
-- 宿主启动时执行一次,无条件收敛
UPDATE jobs
   SET status      = 'interrupted',
       error       = '宿主重启,任务状态未知;未自动重跑',
       finished_at = :now
 WHERE status IN ('pending', 'running');

同时扫描 work/ 目录,把残留目录清掉。

关于"不自动重跑":这一条容易被改成"自动重试",但备份类任务重跑可能覆盖你想保留的产物,恢复类任务重跑可能覆盖目标库。状态未知时,让人决定,不要猜。 前端给一个"用原参数再跑一次"的按钮就够了。

4.3 超时与取消

取消必须是三段式,不能只有一段:

段动作目的
1调 Cancel RPC,等 30s让插件停在安全点(关闭文件、flush、删半成品)
2超时 → Kill()(整组)插件不响应时强制终止
3记 canceled,error 写明"未响应取消,已强制终止"用户必须能区分"干净取消"和"被砍死"

第 3 段的意义在于:被砍死的任务,产物可能是半个文件。如果两种情况都显示"已取消",用户会拿半个文件去恢复。

插件侧的硬性要求(写进模板注释第一行):每个可中断点检查 ctx.Err()。长循环里不检查,取消就只能靠强杀。

4.4 快速路径:--describe

插件列表页要显示所有插件的表单。如果每个插件都完整启动 + gRPC 握手,20 个插件就是 20 ×(启动 60ms + 握手 20ms)= 1.6s。

加一个"只输出 manifest 就退出"的模式:

// pluginkit.Main
func Main(p Plugin) {
    if len(os.Args) > 1 && os.Args[1] == "--describe" {
        enc := json.NewEncoder(os.Stdout)
        enc.SetEscapeHTML(false)
        if err := enc.Encode(p.Manifest()); err != nil {
            os.Exit(1)
        }
        os.Exit(0)
    }
    serve(p) // 走 gRPC
}

同样的 20 个插件降到 0.2s。

注意这里 stdout 是安全的,因为 --describe 模式不进入 serve,不涉及任何协议。但在 serve 模式下,stdout 必须被宿主接住(接到 ring buffer),否则插件里一句 fmt.Println 会让管道写满而阻塞——这是"插件看起来卡死"的常见原因,且极难排查。

缓存要带指纹:

type cacheKey struct {
    Path    string
    Size    int64
    ModTime int64
}

只按文件名缓存,插件升级后仍显示旧表单。这是最容易出的一个"看起来像 bug 的缓存问题"。

4.5 崩溃归因:三源合并

宿主看到的错误,通常只有一句 exit status 1。必须合并三个来源,才能变成可行动的信息:

源拿到什么
gRPC statuscodes.Aborted + 插件自己写的 message → 业务错误
cmd.Wait() 的 exit code137 = SIGKILL(OOM 或被强杀);1 = 常规退出
stderr 尾部 ring buffer(保留最后 20 行 / 64KB)panic 堆栈、runtime: out of memory、signal: killed

合并规则:

现象结论给用户的提示
codes.Aborted + 进程未退出插件主动报错直接显示插件给的 message
codes.Canceled用户取消"已取消"
Unavailable / UnexpectedEOF + 进程已退出进程崩溃显示 stderr 尾部
exit 137 且 stderr 有 signal: killed、无 panic 堆栈被 OOM killer 杀"内存不足,请减小批次大小或分批执行"
正常 EOF 但没有 result插件提前退出"插件未返回结果即退出(插件 bug)"
exit 1 + stderr 有 panic 堆栈插件代码 panic显示堆栈前 10 行

必须区分 OOM 和插件 bug:两者的处置完全不同。不区分的话,用户会去报"插件有 bug",而真实原因是批次开太大。


5. 数据面:事件流

5.1 读循环只做分发,不做业务

一个事件流有三个消费者,它们的速度差异巨大(落库 ms 级、SSE 网络级、内存 μs 级)。如果串行处理,最慢的那个决定整体速度。

func (s *Session) pump(stream pb.Plugin_RunClient) (*RunResult, error) {
    var lastSeq int64
    for {
        ev, err := stream.Recv()
        if err == io.EOF {
            return s.collectResult()
        }
        if err != nil {
            return nil, s.attribute(err) // 崩溃归因,见 §4.5
        }
        if ev.Seq <= lastSeq {
            s.dropped.Add(1) // 乱序或重复:宿主侧再校验一次,防插件并发写 sink
            continue
        }
        lastSeq = ev.Seq

        // 三方分发,互不阻塞
        s.snapshot.update(ev)   // 内存快照:直接更新 map,最便宜
        s.hub.publish(ev)       // SSE:非阻塞,慢订阅者自己丢
        select {
        case s.persistCh <- ev: // 落库:有界队列
        default:
            s.dropped.Add(1)
        }
    }
}

关键点:ev 只解析一次(stream.Recv() 已完成反序列化),三方共享同一个结构体。不要在每个消费者里各自解析——那是三倍 CPU 和三倍 GC 压力。

5.2 背压:丢弃必须可见

// 落库消费者
func (s *Session) persistLoop() {
    batch := make([]*pb.Event, 0, 200)
    tick := time.NewTicker(300 * time.Millisecond)
    for {
        select {
        case ev := <-s.persistCh:
            batch = append(batch, ev)
            if len(batch) >= 200 {
                s.flush(batch); batch = batch[:0]
            }
        case <-tick.C:
            if len(batch) > 0 { s.flush(batch); batch = batch[:0] }
            if n := s.dropped.Swap(0); n > 0 {
                s.metrics.EventsDropped.Add(float64(n))
                s.hub.system("已丢弃 " + strconv.FormatInt(n, 10) + " 条事件")
            }
        }
    }
}

丢弃计数不是可选项。没有它,你就永远不知道看到的日志是不是完整的——排障时会把"日志没显示"误判成"事情没发生"。前端应该在日志窗口顶部常驻显示"已丢弃 N 条"。

为什么选择丢弃而不是阻塞:阻塞读循环的后果是插件侧流控停住,整个任务卡住。宁可丢日志也不能卡任务——但必须让人看见丢了。

5.3 seq 与续传

  • 插件侧 seq 从 1 单调递增(必须是单一 goroutine 写,或加锁,并发写 sink 是乱序的唯一来源)
  • 宿主侧再校验一次(ev.Seq <= lastSeq 即丢弃并计数)
  • 落库用 INSERT OR IGNORE(重复 seq 不报错,因为重连可能重发)
  • SSE 的 id: 就是 seq,重连时浏览器带 Last-Event-ID,服务端从 seq+1 续读

5.4 脱敏放在哪一层

这条容易被做错,且后果是安全事故。

位置能脱敏吗结论
宿主读循环✗ 宿主不知道哪个字符串是密码—
前端展示时✗ 已经落库了,明文在磁盘上太晚
插件进程内(sink 实现里)✓ 插件知道参数里的哪个字段是 secret正确位置

理由:最可能泄漏 DSN 的地方是插件的错误处理路径——fmt.Errorf("connect %s failed", dsn)。宿主看不到这条字符串是怎么产生的,只能由 pluginkit 的 sink 持有明文列表并统一替换:

type redactor struct {
    secrets []string // Init 时从 params 里按 Secret:true 的字段收集,含常见变体
}

func (r *redactor) Apply(s string) string {
    for _, sec := range r.secrets {
        if len(sec) < 8 { continue } // 太短的替换会把正常文本打碎
        s = strings.ReplaceAll(s, sec, "***")
    }
    return s
}

附加价值:脱敏做在 sink 里,插件作者写错也不会泄漏——这比"要求作者记得脱敏"可靠一个数量级。


6. 状态与恢复

6.1 一次性任务:状态机 + 启动收敛

pending ──start──> running ──ok──> succeeded
   │                  │
   │                  ├──err──> failed
   │                  ├──cancel──> canceled
   │                  └──宿主死──> interrupted(重启后收敛,不自动重跑)
   └──排队超时/磁盘水位不足──> rejected

六个状态,不要再加。加一个 retrying 就要处理"重试几次"、"重试间隔"、"重试是否复用 run_id",而这些都属于调度层,不属于任务本身。

状态迁移必须用乐观锁:

UPDATE jobs
   SET status = 'running', started_at = :now
 WHERE id = :id AND status = 'pending';
-- RowsAffected == 0 → 别人抢先了,放弃

没有 AND status = ... 条件,并发调度(手动点击 + cron 同时触发)会产生两个执行者写同一条记录。

6.2 长驻插件:desired / actual + Reconciler

type Instance struct {
    ID      string
    Desired State // Running | Stopped
    Actual  State // Starting | Running | Failed | Stopped
}

每 5s 比对一次,不一致就收敛。它解决三个具体问题:

  1. 宿主重启后不需要知道"上次谁该在跑"——读 desired 即可
  2. 插件被 OOM 杀掉后不需要崩溃回调链——比对发现不一致就拉起
  3. "启动/停止"操作的语义变成"写 desired + 轮询收敛结果",重试免费

这不是 K8s 形式主义。它把"命令式状态迁移"换成"声明式收敛",代价是 5s 延迟,收益是所有失败路径统一处理。

6.3 什么时候两者都要

有些系统两类插件都有(比如"定时巡检"是任务型,"常驻采集"是服务型)。这时不要合并成一套状态模型:

jobs       表:一次性任务,有起止时间,有产物
instances  表:长驻实例,只有 desired/actual,无产物

两套表、两套状态机、两个 executor。合并会导致"任务有 desired 字段但永远是空"、"实例有 finished_at 但永远不为空"这类语义污染,后期无法维护。


7. 大对象:产物管理

一次性任务型系统(备份、导出、迁移)的核心产出就是几十 GB 的文件。这部分在"长驻采集型"系统里是空的,必须单独设计。

7.1 四条硬规则

#规则不遵守的后果
1插件不许自选落盘路径,只能写 workdir,产物由宿主搬运登记保留策略、磁盘配额、跨机迁移全部无法实施
2产物引用只用 ID,不用路径路径会因保留策略失效;ID 能给出"产物已被清理"的明确错误
3下载走 http.ServeFile(自带 Range),绝不读进内存10GB 文件读进内存 = 必 OOM
4磁盘水位低于阈值时拒绝接受写入型任务备份到一半磁盘满,比不备份更糟(占着空间还不可用)

7.2 格式契约:唯一跨插件契约

当 A 的产物要喂给 B(备份 → 恢复 / 迁移)时,产物格式从"插件私事"升级为插件间契约:

// manifest 里声明
Produces: []Format{{Format: "lp.gz", Version: 1, Roles: []string{"data", "meta"}}}
Accepts:  []Format{{Format: "lp.gz", Version: 1, Roles: []string{"data"}}}

产物组模型:一个 run 可能产出多个文件,逻辑上是一组。存储上必须拆成两张表:

artifact_groups(id, job_id, format, format_version, status, total_size)
artifacts(id, group_id, role, name, path, size, sha256)

写入必须在一个事务里,且先 pending 后 complete:

插组(status=pending) → 插各 role → 校验 roles 齐全 → 更新组 status=complete

理由:归档流程是"算 SHA256 → 搬文件 → 落库",搬大文件可能中断。如果先写 complete,中断后会留下一个"看起来可用"的组,而磁盘上文件不全——恢复时选中它,读到一半才失败,比直接看不到更糟。

删除必须按组删,不能按单文件删。否则会留下"meta.json 还在但 data 没了"的组,而列表页看起来完全正常。

格式兼容校验要在提交时做,不是运行时做:

  • 校验依赖 manifest(提交时已知)→ 可以早校验
  • 取值依赖执行结果(运行时才有)→ 必须晚解析

这两件事经常被混为一谈,导致两种错误:要么链跑到第二步才发现不兼容,要么在启动时就读取空值。正确表述是:类型早校验,取值晚解析。

7.3 保留与清理

  • 按 group_id 整组过期删除(TTL 配置在产物格式上,不在产物上)
  • 清理前校验"是否被任何未完成任务引用",否则会删掉正在恢复的文件
  • 清理记录要落审计(谁删的、删了什么、多大),否则磁盘空间对不上时无从查起

8. 前端零改动:SchemaForm

8.1 封闭类型集合是刻意约束

前端只实现 一个 组件:把 FormSchema 渲染成表单。它不认识任何插件。

function SchemaForm({ schema, value, onChange }) {
  return (
    <Form layout="vertical">
      {schema.fields
        .filter(f => evaluate(f.depends_on, value))   // 联动
        .map(f => (
          <Form.Item key={f.key} label={f.label} required={f.required}
                     help={f.help} name={f.key}>
            {renderField(f, value[f.key], v => onChange(f.key, v))}
          </Form.Item>
        ))}
    </Form>
  );
}

renderField 是一个 10 分支的 switch,就这么简单。

8.2 联动:depends_on

type Condition struct {
    Field  string   `json:"field"`
    Op     string   `json:"op"`      // eq | ne | in | gt | nonempty
    Values []string `json:"values"`
}

典型用法:选"全量"才显示"起始时间"。没有联动,插件只能靠运行时校验拒绝,用户要先点一次运行才知道参数矛盾。

不要做条件表达式引擎。eq / ne / in / gt / nonempty 五种操作符覆盖 99% 场景,引入表达式求值等于把代码写进配置——审计、兼容、安全三输。

8.3 为什么这是通用性的试金石

判断一个插件框架是否真的通用,最简单的检验不是看架构图,而是问:

新增一个业务完全不同的插件,前端要改代码吗?

  • 要改 → 抽象泄漏了,前端在承担业务逻辑
  • 不改 → 通用性成立

这个检验比任何架构评审都有效,因为它无法靠文档辩解。

8.4 SSE 的两个实现坑

坑现象修法
反向代理缓冲日志"卡住不动",刷新才出来响应头加 X-Accel-Buffering: no + Cache-Control: no-cache
EventSource 不支持自定义 header无法带鉴权 token用 fetch + ReadableStream 手写 SSE 解析(约 40 行)

9. 工程骨架

9.1 目录与 go.work

framework/
├── go.work                      # 串起所有 module,改一处即时生效
├── core/
│   ├── contract/                # 零第三方依赖:接口 + schema + 校验
│   ├── model/                   # 领域模型
│   ├── store/                   # 持久化
│   ├── runtime/                 # 状态机 / 并发池 / 取消
│   ├── eventbus/                # 事件分流
│   └── host/                    # supervisor(唯一与平台相关的模块)
├── pluginkit/                   # 插件作者 import 的唯一包
│   ├── proto/                   # 生成的 gRPC 代码
│   ├── serve.go                 # Main() / serve()
│   ├── sink.go                  # EventSink:seq、截断、脱敏
│   └── debug.go                 # 开发期本地直跑(不构成第二执行路径)
├── api/                         # REST + SSE
├── cmd/
│   ├── frameworkd/              # 服务端
│   └── frameworkctl/            # CLI(纯 API 客户端)
├── plugins/
│   ├── _template/               # gonew 复制即得新插件
│   └── <each>/                  # 每个插件独立 module + 独立 go.mod
└── web/                         # React + Vite

每个插件独立 module 是关键。理由不是洁癖,而是:

  • 依赖各自收敛(ch-go 这种巨大依赖不会传导给其他插件)
  • 将来若从"独立进程"退回"编译期注册",go.mod 不用改
  • 插件可以单独 go test ./...,改动不会触发全量重编译

go.work:

go 1.24

use (
    .
    ./core/contract
    ./pluginkit
    ./plugins/backup
    ./plugins/restore
)

各插件的 go.mod 需要 replace example.com/framework/contract => ../../core/contract(monorepo 内部引用),发布时改成真实版本号。

9.2 插件模板

插件作者要写的全部:

package main

import (
    "context"
    "example.com/framework/contract"
    "example.com/framework/pluginkit"
)

func main() { pluginkit.Main(p{}) }

type p struct{}

func (p) Manifest() contract.Manifest {
    return contract.Manifest{
        ID: "example-tool", Name: "示例工具", Version: "1.0.0",
        SpecVersion: "1.0",
        Capabilities: []string{"cancel", "artifacts"},
        Form: contract.FormSchema{Fields: []contract.Field{
            {Key: "src.url", Label: "源地址", Type: contract.FString, Required: true},
        }},
    }
}

func (p) Run(ctx context.Context, in contract.RunInput, out contract.EventSink) (contract.RunResult, error) {
    // 硬约束(写在这里是刻意的,模板是用来被复制的):
    // 1. 所有输出走 out,不要 fmt.Print —— 直接打印的日志在平台上不可见,且不脱敏
    // 2. 每个可中断点检查 ctx.Err(),否则取消只能靠强杀,会留下半成品
    out.Log(contract.Info, "start")
    return contract.RunResult{}, nil
}

配套一个 manifest 单测:

func TestManifest(t *testing.T) {
    if err := contract.ValidateManifest(p{}.Manifest()); err != nil {
        t.Fatalf("manifest 不合法: %v", err)
    }
}

这个测试的价值:schema 写错在 go test 阶段就被拦住,而不是等宿主扫描后标记 invalid。在 monorepo 里,它还能防止"改 contract 导致某个插件静默失效"。

9.3 开发期直跑:pluginkit.Debug()

没有它,改一行逻辑的验证流程是:编译 → 拷进插件目录 → 重启宿主 → 开页面 → 点运行 → 翻日志。

有它:

//go:build dev

pluginkit.Debug(ctx, p{}, params)

边界必须写死:Debug() 只用于开发期,不构成第二条执行路径——不写库、不归档、不做平台职责。生产环境只有服务端能拉起插件。这条边界不写清,半年后一定会出现"CLI 能跑但平台上跑不通"的分歧,而排查这件事的成本远高于 Debug() 省下的时间。

9.4 测试策略:四层

层测什么实现要点
L1 契约manifest 合法、schema 自洽、proto 兼容每个插件一个 TestManifest,CI 里跑全部
L2 supervisor宿主在坏插件下不崩、能归因写三个故意坏掉的假插件,见下
L3 端到端真插件跑一次,产物可下载可校验一个最小数据集 + SHA256 断言
L4 回归所有插件 --describe 可解析一个测试遍历 plugins/*,起进程收 manifest

L2 的三个假插件是这套测试的核心,也是几乎所有人都会漏的一层:

假插件模拟断言
crash启动后立即 os.Exit(2)宿主标记 failed,错误文本含 exit code,不含"取消"
hang收 Run 后 select {} 永不返回取消在 30s 内生效,转 canceled,进程被杀死
flood死循环打日志,每秒 10 万条宿主内存不涨、任务正常结束、丢弃计数 > 0

第三个最关键。没有它,你不会知道背压是不是真的生效——而它的故障形态是"跑几小时后宿主 OOM",复现成本极高。


10. 血泪清单

按"踩到概率 × 排查难度"降序。前 8 条是必踩的。

#坑症状处理
1只靠 Pdeathsig / Job Object 做孤儿防护偶发插件残留,日志里查不出原因加连接级检测(§4.2 第二层);内核级有竞态窗口,消不掉
2宿主没接住插件的 stdout插件"卡死",实际是管道写满阻塞cmd.Stdout 接到 ring buffer;--describe 除外
3EVENT 丢弃没有计数用户以为日志完整,按残缺日志排障丢弃必计数并显示(§5.2)
4状态迁移没加 AND status = ...并发触发产生两个执行者乐观锁 + 检查 RowsAffected
5用文件名判断插件 ID插件改名后"消失",或两个插件冲突ID 只认 manifest
6manifest 缓存只看文件名插件升级后仍显示旧表单缓存 key 加 size + mtime
7取消只有"强杀"一段产物留半个文件,用户拿去恢复三段式取消(§4.3)
8大文件下载读进内存10GB 备份包一点就 OOMhttp.ServeFile 拿 Range 支持
9gRPC 默认 4MB 上限大堆栈日志导致 stream 断,报 ResourceExhausted调 MaxRecvMsgSize + 插件侧单条日志截断到 64KB
10插件里调外部 CLI,只 Kill() 直接子进程孙进程活下来继续写数据进程组(Linux Setpgid)/ Job Object(Windows)
11Windows AssignProcessToJobObject 失败就报错退出在被任务计划程序/CI 启动的环境里完全起不来降级为 warning
12SSE 被 Nginx 缓冲日志"卡住不动",刷新才出X-Accel-Buffering: no
13用 EventSource 带鉴权无法加 header,只能把 token 放 URL(进日志)fetch + ReadableStream
14模板在链启动时解析引用上一步产物永远为空每个 step 开始前才解析
15按单文件删产物留下"半组"产物,列表看起来正常按 group_id 整组删
16事件表无限增长磁盘几个月后涨到几十 GBretention + 定期 DELETE
17脱敏做在前端明文早已落库做在插件进程内的 sink(§5.4)
18启动没收敛残留状态前端永远转圈启动时一条 UPDATE 全标 interrupted
19Debug() 里写了库操作开发环境和生产行为不一致边界写死:不写库、不归档
20proto 没留 extensions 字段第一个扩展需求就要全量重编译重发布所有消息预留 bytes extensions = 15

11. 落地检查清单

按阶段勾选。P2 是质量闸门,不许跳过——契约定错的成本随插件数量线性增长。

P0 环境与骨架

  • 确认目标平台(Windows 是否主力?决定 UDS/TCP 回退路径必须 P0 验证)
  • go.work + 各 module go.mod 就位,replace 生效
  • core/contract 编译通过且零第三方依赖(go list -m all 只有自己)
  • CI 加上契约纯净度检查(§3.6)
  • 一次性 token 校验 + echo 假插件能跑通 Describe

P1 执行闭环

  • supervisor 能拉起 / 握手 / 收事件 / 等退出 / 清理
  • 三层孤儿防护全部实现(内核级 + 连接级 + 启动兜底)
  • 事件流三消费者解耦,丢弃计数可见
  • 崩溃归因三源合并,OOM 与插件 bug 可区分
  • 三段式取消,干净取消与被杀可区分
  • --describe 快速路径,20 个插件扫描 < 500ms

P2 语义验证(闸门)

  • 三个假插件(crash / hang / flood)全部通过(§9.4)
  • 用两个形态差异最大的真实业务写插件(不是两个相似插件)
  • 验证:新增第二个插件时,宿主代码零改动
  • 验证:新增第二个插件时,前端代码零改动
  • 契约冻结评审:4 个 RPC + Manifest 字段 + 事件字段

P3 持久化与产物

  • 状态机乐观锁 + 启动收敛
  • 产物组事务写入(先 pending 后 complete)
  • 按组删除 + 被引用检查
  • Range 下载 + 磁盘水位检查

P4 调度与前端

  • cron / 任务链(按需)
  • SchemaForm 渲染器 + 10 种类型 + 联动
  • SSE 实时日志 + 续传
  • 页面数据流(列表轮询、详情 SSE)

P5 真实工具

  • 第一个真实插件端到端跑通并校验产物
  • 第二个插件复制第一个的结构(验证模板可用性)
  • 反向验证:删掉第一个插件,平台仍正常运行

附录 A:两个项目的决策对照

同一个问题,两个项目给出了不同答案——差异全部来自"进程活多久",没有一处是风格偏好。

问题一次性任务型长驻服务型差异根源
事件走哪Run 返回的单向流插件反向调 HostBroker.Emit事件是否属于某次调用
结束判定流 EOF健康探测 + 显式 Stop是否有明确起止
健康探测不需要必须(失败 3 次标不健康)进程该一直在但可能僵死
平滑切换不存在路由表原子交换 + 排空长驻进程升级不能中断服务
状态收敛启动一次性收敛为 interruptedReconciler 每 5s 比对命令式 vs 声明式
失败重试不自动重跑退避重拉重跑可能覆盖产物 vs 重拉是幂等的
背压位置读循环一处每个 handler数据入口数量
产物管理核心(几十 GB)可选(大文件走 claim-check)是否以文件为产出
资源约束磁盘水位 + 产物配额并发上限 + 缓冲上限 + 软配额主要耗尽哪种资源

附录 B:什么时候该换掉某个部件

选型不是一次性的。给出触发条件,把"以后可能要"变成可执行的判断。

部件换的触发条件换成改动范围
自研 supervisor需要连接池复用(插件启动 >2s 且任务频繁)常驻进程池(要先解决状态残留)仅 core/host
自研 supervisor需要不可信第三方插件强隔离per-plugin 容器 / 微虚拟机仅 core/host
SQLite多实例共享状态 / 并发写 > 200 TPSPostgreSQL + 分布式锁core/store
SQLite单机写锁 P99 > 50ms分段日志实现队列接口不变
本地磁盘存产物需要跨机访问 / 单机磁盘不够S3 兼容对象存储artifact 模块接口不变
内置指标需要 > 90 天 / 跨节点聚合Prometheus / VictoriaMetrics只换读取端
单向流事件需要多路并发数据流Host broker 服务契约变更(大)
gRPC插件全在浏览器 / 需要穿透严格防火墙Connect / HTTP+JSON契约基本不变

最后一条要特别注意:Connect 协议(gRPC / gRPC-Web / HTTP+JSON 三合一)可以做到"一份 proto,三种客户端"。如果将来需要 Web 端直连插件,这是成本最低的路径——proto 完全不用改。

附录 C:一页速查

契约层必须零业务名词        ← CI grep 卡死
Manifest 用 capabilities    ← 不用版本号猜能力
参数 10 种类型封闭          ← 前端零改动的前提
插件独立 module             ← 依赖收敛
一任务一进程(任务型)      ← 崩溃域隔离
三层孤儿防护                ← 内核级有竞态,连接级才可靠
事件流三消费者解耦          ← 慢的不许阻塞快的不许阻塞任务
丢弃必计数                  ← 否则你不知道日志是否完整
状态迁移必带乐观锁          ← 否则并发产生双执行
取消三段式                  ← 干净取消 vs 被砍死必须可区分
产物不许自选路径            ← 否则保留策略无法实施
产物按组删                  ← 否则留下半组
类型早校验,取值晚解析      ← 链提交时校验格式,运行时才解析引用
启动必收敛残留状态          ← 不自动重跑
新插件零前端改动            ← 通用性的唯一检验