0050 GitOps 静态签名插件市场、五维环境筛选与多平台官方编译分发
- 状态:已接受(2026-11-19)
- 相关:设计文档
10-dual-tier-plugin-and-market-plan.md§1.2–§1.4、§2.6;ADR 0048(.slp签名与多副本同步)、0049(双轨插件架构)
背景
随着双轨插件体系(Tier 1 跨平台 JS/WASM 与 Tier 2 原生 Go 多平台二进制)落地,插件与主题的分发面临三大核心问题:
- 市场架构零运维与高可用:社区早期无需维护重型动态市场后端数据库与账户体系,但需要同时满足国内外站点的低延迟访问、故障自动切换与防中间人(MITM)篡改。
- 原生二进制供应链安全:允许第三方开发者直接上传编译好的原生可执行文件存在极高的投毒与后门风险;生产站点必须确保所有来自官方市场的原生二进制均由公开源码在受控环境中编译并由官方私钥签名。
- 异构平台与依赖兼容匹配:不同自托管站点的操作系统/CPU 架构(
linux/amd64、linux/arm64、windows/amd64、darwin/arm64、darwin/amd64)、SkinLoom 版本、Go 版本及已安装依赖各不相同,单节点与多架构集群均需自动筛选并拉取精确匹配的平台包。
决策
1. GitOps 静态签名插件市场(模式 A:skinloom-registry 独立仓库 & RegistryClient)
- 官方市场采用纯静态 GitOps 独立仓库(
Entropy-Increase-Team/skinloom-registry):- 开发者仅提交
manifests/<id>.yaml(声明开源 Git 仓库地址与固定 40 位 Commit SHA)。 - 分级 PR 审核(
pr-check.yml):非首次上架且未新增敏感/高危权限的纯 JS/主题更新由 CI 跑skinloom-plugin lint自动校验;首次上架、新增敏感/高危权限或任何runtime: "native"插件强制打上needs-security-review标签并运行go vet、govulncheck与 CodeQL 扫描,须经人工源码审计后方可合并。 - 官方受控交叉编译与 Ed25519 签名(
publish.yml):合并后由隔离 Runner 拉取固定 Commit SHA,以CGO_ENABLED=0交叉编译五平台独立分包(--native --split-platforms),使用受保护的官方 Ed25519 私钥对每个.slp包及总索引index.v1.json生成签名(index.v1.json.sig),同步发布至国内 CDN 主源(https://registry.skinloom.cn)与 GitHub 备用源。
- 开发者仅提交
- 宿主内置多源客户端
internal/plugin/registry_client.go(站点设置plugin.registries):- 支持主备镜像自动故障转移与 15 分钟内存 + 本地磁盘缓存;
- 对官方市场源强制使用内置
OfficialPublicKeyPEM验证index.v1.json.sig,彻底防止中间人篡改索引或伪造阻断名单; - 每 6 小时定时巡检及手动刷新市场时执行
EnforceBlockedPlugins:仅采信通过签名验证的市场源blocked名单,命中已启用插件时立即热停用、记录plugin.blocked_disabled审计日志并向所有超级管理员发送站内安全通知。
2. 五维环境与依赖兼容性筛选引擎(internal/plugin/compat.go)
- 宿主拉取
index.v1.json后,基于本机运行环境(CurrentHostEnv)对每个包版本执行五维校验并由SelectBestVersion选出最佳可安装版本:- 平台匹配:
runtime == "js"匹配"any";runtime == "native"精确匹配GOOS/GOARCH产物。 - SkinLoom SemVer 范围匹配(
engines.skinloom)。 - API 与原生 gRPC 协议版本匹配(
apiVersion == 1、nativeProtocolVersion == 1)。 - Go 基线版本校验(
engines.go)。 - 依赖树 DFS 解析(
ResolveDependencyPlanWithBlocked):支持已装插件与市场可用包联合求解,自动产出按拓扑顺序排列的一键级联安装计划(DependencyPlan),并检测版本冲突、循环依赖与被阻断依赖。
- 平台匹配:
3. 三平台分包为主、多架构集群按需回源与生产强制验签
- 单平台分包为主、全平台胖包(
--fat)为辅:市场分发默认采用单平台分包(单包上限50 MiB,仅下载当前服务器架构二进制),同时支持离线内网使用--fat全平台胖包(上限150 MiB)。 - 多架构集群同步(
PlatformPackages+FetchPlatformPackage):plugins表记录platform_packages(各平台GOOS/GOARCH -> sha256映射)与registry_source。当异构集群(如linux/amd64+linux/arm64)中某节点从市场安装原生插件后,另一架构节点在SyncCluster时自动通过RegistryClient.FetchPlatformPackage回源拉取本机架构分包并严格核对platform_packages[hostPlatform]的 SHA-256。 - 生产模式原生包强制验签:生产模式下(
AllowUnsignedNative == false),InstallPackage对runtime == "native"强制要求通过官方公钥或超管在plugins.trusted_keys中配置的可信 Ed25519 公钥验签,拒绝跳过签名安装未验签的原生二进制(ErrUnsignedNativeForbidden)。
备选方案
- 默认将所有 5 个平台的 Go 二进制打入同一个
.slp胖包分发:会导致每次市场下载体积膨胀至 60–100 MiB,浪费带宽与对象存储空间;采用按GOOS/GOARCH拆分的独立.slp分包并在index.v1.json的artifacts映射中按平台索引,兼顾了极速下载与多架构集群回源校验。