Go + gRPC 插件式服务框架 —— 技术实现与分析
| 项 | 内容 |
|---|---|
| 定位 | 可复用的工程手册。回答"下一个类似系统怎么搭",不描述某一个具体系统 |
| 来源 | 《局域网数据中转服务 架构设计方案 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 |
| 3 | supervisor 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 必须排除(不是偏好,是硬约束):
- Windows 不支持,而运维类工具的主要使用场景恰恰是 Windows。
- 主程序与插件必须完全相同的 Go 版本 + 相同的编译参数 + 相同的依赖版本,一旦不同就是运行时 panic 或静默错乱。这直接否定了它存在的意义——依赖隔离。
- 无法卸载,加载后常驻内存。
- 崩溃不隔离,
.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 + Reconciler | 0%,语义不同 |
| 生命周期操作 | Run / Cancel | Start / Stop / Health / UpdateConfig | 0% |
| 产物管理 | ✓ 核心 | 可选(大文件才需要) | 按需 |
结论:把 §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 纪律:
- 所有消息预留
bytes extensions = 15。第一次不用,但一旦有插件需要扩展而你没留,改 proto 就要全量重编译重发布。 - 单向流优先于双向流。双向流看起来灵活,实际带来"两边都要处理半关闭"的状态机,收益几乎为零。
- 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"` // 一个产物组内的文件角色
}
为什么能力协商必须优于版本号(这是源文档里最容易被当成形式主义的一条):
版本号是全序,能力是偏序。真实世界的能力组合是偏序的:
| 插件 | 版本 | 支持取消 | 支持断点续传 | 支持产物 |
|---|---|---|---|---|
| A | 1.2 | ✓ | ✗ | ✓ |
| B | 1.3 | ✗ | ✓ | ✓ |
| C | 1.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 |
| 4 | format_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 分支源码核实,换版本需复核):
internal/cmdrunner/cmd_runner.go的Start()只调用cmd.Start(),Kill()只调用cmd.Process.Kill();process_windows.go里只有一个_pidAlive,没有CreateJobObject,没有 Job Object 绑定。也就是说 Windows 上父进程一死,插件必然残留——而这块你无论如何都要自己写。- 它的日志体系是
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 status | codes.Aborted + 插件自己写的 message → 业务错误 |
cmd.Wait() 的 exit code | 137 = 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 比对一次,不一致就收敛。它解决三个具体问题:
- 宿主重启后不需要知道"上次谁该在跑"——读
desired即可 - 插件被 OOM 杀掉后不需要崩溃回调链——比对发现不一致就拉起
- "启动/停止"操作的语义变成"写
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 除外 |
| 3 | EVENT 丢弃没有计数 | 用户以为日志完整,按残缺日志排障 | 丢弃必计数并显示(§5.2) |
| 4 | 状态迁移没加 AND status = ... | 并发触发产生两个执行者 | 乐观锁 + 检查 RowsAffected |
| 5 | 用文件名判断插件 ID | 插件改名后"消失",或两个插件冲突 | ID 只认 manifest |
| 6 | manifest 缓存只看文件名 | 插件升级后仍显示旧表单 | 缓存 key 加 size + mtime |
| 7 | 取消只有"强杀"一段 | 产物留半个文件,用户拿去恢复 | 三段式取消(§4.3) |
| 8 | 大文件下载读进内存 | 10GB 备份包一点就 OOM | http.ServeFile 拿 Range 支持 |
| 9 | gRPC 默认 4MB 上限 | 大堆栈日志导致 stream 断,报 ResourceExhausted | 调 MaxRecvMsgSize + 插件侧单条日志截断到 64KB |
| 10 | 插件里调外部 CLI,只 Kill() 直接子进程 | 孙进程活下来继续写数据 | 进程组(Linux Setpgid)/ Job Object(Windows) |
| 11 | Windows AssignProcessToJobObject 失败就报错退出 | 在被任务计划程序/CI 启动的环境里完全起不来 | 降级为 warning |
| 12 | SSE 被 Nginx 缓冲 | 日志"卡住不动",刷新才出 | X-Accel-Buffering: no |
| 13 | 用 EventSource 带鉴权 | 无法加 header,只能把 token 放 URL(进日志) | fetch + ReadableStream |
| 14 | 模板在链启动时解析 | 引用上一步产物永远为空 | 每个 step 开始前才解析 |
| 15 | 按单文件删产物 | 留下"半组"产物,列表看起来正常 | 按 group_id 整组删 |
| 16 | 事件表无限增长 | 磁盘几个月后涨到几十 GB | retention + 定期 DELETE |
| 17 | 脱敏做在前端 | 明文早已落库 | 做在插件进程内的 sink(§5.4) |
| 18 | 启动没收敛残留状态 | 前端永远转圈 | 启动时一条 UPDATE 全标 interrupted |
| 19 | Debug() 里写了库操作 | 开发环境和生产行为不一致 | 边界写死:不写库、不归档 |
| 20 | proto 没留 extensions 字段 | 第一个扩展需求就要全量重编译重发布 | 所有消息预留 bytes extensions = 15 |
11. 落地检查清单
按阶段勾选。P2 是质量闸门,不许跳过——契约定错的成本随插件数量线性增长。
P0 环境与骨架
- 确认目标平台(Windows 是否主力?决定 UDS/TCP 回退路径必须 P0 验证)
-
go.work+ 各 modulego.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 次标不健康) | 进程该一直在但可能僵死 |
| 平滑切换 | 不存在 | 路由表原子交换 + 排空 | 长驻进程升级不能中断服务 |
| 状态收敛 | 启动一次性收敛为 interrupted | Reconciler 每 5s 比对 | 命令式 vs 声明式 |
| 失败重试 | 不自动重跑 | 退避重拉 | 重跑可能覆盖产物 vs 重拉是幂等的 |
| 背压位置 | 读循环一处 | 每个 handler | 数据入口数量 |
| 产物管理 | 核心(几十 GB) | 可选(大文件走 claim-check) | 是否以文件为产出 |
| 资源约束 | 磁盘水位 + 产物配额 | 并发上限 + 缓冲上限 + 软配额 | 主要耗尽哪种资源 |
附录 B:什么时候该换掉某个部件
选型不是一次性的。给出触发条件,把"以后可能要"变成可执行的判断。
| 部件 | 换的触发条件 | 换成 | 改动范围 |
|---|---|---|---|
| 自研 supervisor | 需要连接池复用(插件启动 >2s 且任务频繁) | 常驻进程池(要先解决状态残留) | 仅 core/host |
| 自研 supervisor | 需要不可信第三方插件强隔离 | per-plugin 容器 / 微虚拟机 | 仅 core/host |
| SQLite | 多实例共享状态 / 并发写 > 200 TPS | PostgreSQL + 分布式锁 | 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 被砍死必须可区分
产物不许自选路径 ← 否则保留策略无法实施
产物按组删 ← 否则留下半组
类型早校验,取值晚解析 ← 链提交时校验格式,运行时才解析引用
启动必收敛残留状态 ← 不自动重跑
新插件零前端改动 ← 通用性的唯一检验