Files

30 KiB
Raw Permalink Blame History

插件分发指南(P3-13):打包 / 索引 / 签名 / 安装

适用范围:VDE 微内核插件(format / CAE / CAM / GCS / UI / binding 等)的离线分发最小闭环: 插件包 → 仓库索引 index.json → Ed25519 签名 → 校验与安装。 工具:vde_plugin_tool(P3-13 新增 --build-index / --verify-index / --install / --gen-keypair)。 版本基线:1.0.71+;插件 ABI 1.5(宿主 1.x 兼容 1.0–1.5)。

1. 概念与目录布局

概念 说明
插件包(package) 一个目录:vde-plugin.json + 动态库(entry)+ 可选数据文件;artifacts 为包内全部普通文件的相对路径 + SHA-256
仓库索引(index) 一个 JSON 文件,列出可用插件及其版本、ABI、能力、artifact 哈希;可整体 Ed25519 签名
签名种子(seed) 32 字节 Ed25519 私钥种子;仅发布者持有,不进入插件/索引/客户端
公钥(public key) 32 字节 Ed25519 公钥;随信任配置分发给宿主/安装器
安装布局 <dest>/<plugin-id>/vde-plugin.json + 动态库 + 数据文件(可直接作为宿主插件搜索路径)

示例仓库布局:

repo/
  index.json
  packages/
    com.example.format/
      vde-plugin.json
      vde_template_format.dll
    com.example.gcs/
      vde-plugin.json
      vde_template_gcs.dll

index.json 中每个插件的 path 是相对 index.json 所在目录的包目录(如 packages/com.example.format); 构建与安装时都会拒绝 ..、绝对路径、盘符等逃逸路径。

2. index.json schema v1

字段 类型 必填 说明
schema_version int 是 当前为 1;不匹配时工具拒绝
generated_at string 是 UTC ISO-8601(YYYY-MM-DDTHH:MM:SSZ,仅审计用途)
generator string 是 生成工具(当前 vde_plugin_tool)
publisher string 否 发布者名(进入签名载荷)
key_id string 否 签名密钥标识(进入签名载荷;吊销/轮换用)
signature string 否 索引签名:ed25519:<base64(64B)>(不进入签名载荷)
plugins[] array 是 插件条目;空数组合法(空仓库/占位索引)

plugins[] 条目:

字段 类型 必填 说明
id string 是 反域名唯一 id(不得含路径分隔符)
name string 否 显示名
version string 是 语义化版本 x.y.z
kind string 是 format / cae_solver / cam_strategy / gcs_solver / ui / binding / geom_op
abi object 是 { "major": 1, "minor": 3 };宿主只接受 major 相等且 minor ≤ 宿主 minor
capabilities array 否 能力 ID 列表(与清单一致)
license string 否 SPDX 标识/许可说明
requires array 否 依赖声明:[{ "id": "<plugin-id>", "version_range": ">=1.2.0" }](简化 semver:exact / >= / > / <= / < / ^ / ~ / *,空格分隔=AND)
entry string 是 平台动态库文件名(与清单一致)
path string 是 包目录相对 index.json 的路径
manifest_sha256 string 否 vde-plugin.json 的 SHA-256(审计/快速比对)
signature string 否 插件清单自身签名(P3-5 可选;索引签名覆盖整个索引)
artifacts[] array 是 [{ "path": <包内相对路径>, "sha256": <64 hex>, "url": <可选绝对/相对索引URL> }];至少 1 项

最小示例(unsigned;正式分发必须签名):

{
  "schema_version": 1,
  "generated_at": "2026-10-29T00:00:00Z",
  "generator": "vde_plugin_tool",
  "plugins": [
    {
      "id": "com.example.format",
      "name": "Example Format",
      "version": "0.1.0",
      "kind": "format",
      "abi": { "major": 1, "minor": 3 },
      "capabilities": ["format:example.read", "format:example.write"],
      "entry": "vde_template_format.dll",
      "path": "packages/com.example.format",
      "manifest_sha256": "<sha256>",
      "artifacts": [
        { "path": "vde-plugin.json", "sha256": "<sha256>" },
        { "path": "vde_template_format.dll", "sha256": "<sha256>" }
      ]
    }
  ],
  "key_id": "release-2026",
  "signature": "ed25519:<base64(64B)>"
}

仓库内 plugins/index.json 是占位/空索引(plugins: []),用于文档与仓库结构示例; 发布时由 --build-index 生成实际索引。

3. 签名规范(复用 P3-5)

  • 签名算法:Ed25519(RFC 8032,32B 公钥 / 64B 签名 / 32B 私钥种子);
  • 签名载荷:canonical_manifest_payload(index_json)——即索引 JSON 去掉顶层 signature 字段后的 确定性序列化(对象键字典序、无空白、数组保序、数字最短往返、UTF-8);与插件清单签名同规则;
  • key_id、publisher、generated_at、全部插件条目与 artifacts 哈希都在签名载荷内(防篡改);
  • 索引签名串:ed25519:<base64(64B)>;signature 字段自身不参与签名;
  • 插件清单的 signature(P3-5)与索引签名相互独立:前者由宿主 verify 校验,后者由 --verify-index/--install 校验;生产建议两者都签。

4. 命令与退出码

工具位置:<build>/tools/vde_plugin_tool(Windows .exe)。

4.1 生成密钥(测试/开发)

vde_plugin_tool --gen-keypair --out-dir keys/
# keys/plugin_signing.key(seed hex,保密)
# keys/plugin_signing.pub(公钥 hex,分发)

生产签名应在离线/受控环境执行;工具仅提供测试/开发用密钥生成。公钥通过可信通道分发 (宿主配置/安装器内置/企业 PKI),不要从索引或插件包内读取公钥。

4.2 打包 + 构建索引(可签名)

# 1) 打包:把插件构建产物(vde-plugin.json + DLL + 数据)复制到 repo/packages/<id>/
#    注意不要带 build 中间产物;artifacts 由 --build-index 自动计算 SHA-256。
# 2) 构建索引(签名可选但生产必需):
vde_plugin_tool --build-index repo/packages -o repo/index.json `
    --sign keys/plugin_signing.key --key-id release-2026 --publisher "Example Corp"

输出包含每个插件的 id/version/ABI/artifact 数与公钥指纹;--sign 缺省生成 unsigned 索引。

4.3 校验索引

vde_plugin_tool --verify-index repo/index.json --pubkey keys/plugin_signing.pub
# 校验:schema、签名、路径安全、每个 artifact 存在且 SHA-256 一致、ABI 与宿主兼容、重复条目

--allow-unsigned 仅用于内网/开发;正式分发应始终带 --pubkey 并拒绝 unsigned。

--pubkey 支持内联 ed25519:<base64|hex> 或文件路径;文件内容需为单行纯 hex/base64 或 ed25519:<...>(--gen-keypair 生成的 .pub 可直接使用;若手工拼接,确保没有多余换行/前缀)。

吊销签名 key(P3-13b):--verify-index/--install/--upgrade 支持 --revoked-keys <file>,验签后若索引 key_id 命中吊销列表则退出码 3(诊断含 index signing key_id '<id>' is revoked)。文件格式:每行一个 key_id(# 注释、可逗号分隔) 或 JSON {"revoked_key_ids":["..."]};格式错误/空文件同样退出 3(诊断含 invalid --revoked-keys)。吊销列表由调用方/宿主策略显式提供,不要从索引内读取。

# 拒绝已吊销 key_id 签名的索引(行格式吊销文件)
vde_plugin_tool --verify-index repo/index.json --pubkey keys/plugin_signing.pub `
    --revoked-keys revoked_keys.txt
# JSON 格式
vde_plugin_tool --verify-index repo/index.json --pubkey keys/plugin_signing.pub `
    --revoked-keys revoked_keys.json

4.4 安装

# 从索引安装(推荐;自动验签/哈希/ABI)
vde_plugin_tool --install repo/index.json --dest installed/ `
    --id com.example.format --pubkey keys/plugin_signing.pub

# 指定版本(索引可含同一 id 多版本;缺省选最高 semver)
vde_plugin_tool --install repo/index.json --dest installed/ `
    --id com.example.format --version 0.1.0 --pubkey keys/plugin_signing.pub

# 从本地插件目录安装(开发便利;无签名校验,host 侧仍可 verify)
vde_plugin_tool --install path/to/plugin_dir --dest installed/

安装结果:<dest>/<plugin-id>/(vde-plugin.json + 动态库 + 数据文件)。已存在时需 --force 覆盖。

安装同样支持 --revoked-keys <file>:索引签名 key_id 被吊销时在任何文件写入前拒绝(退出码 3)。

4.5 退出码

退出码 含义
0 成功
2 用法/参数错误(含非法公钥文本)
3 校验失败:schema/签名/哈希/路径逃逸/ABI 不兼容/插件不存在/目标已存在/签名 key_id 被吊销(--revoked-keys)
4 加密不可用:签名索引未提供 --pubkey,或工具未链接 vde_license(无 Ed25519)

4.6 远程索引获取(--fetch-index,P3-17)

vde_plugin_tool --fetch-index <url|file> -o <index.json> \
    [--pubkey keys/plugin_signing.pub] [--allow-unsigned] [--verify-artifacts]
  • 来源支持本地路径/file://、http:///https://(Windows 构建经 WinHTTP;Linux/macOS 当前仅本地文件, URL 获取返回明确错误);
  • 获取后写入 -o,随即复用索引校验:schema → 签名(--pubkey 必填,unsigned 需 --allow-unsigned)→ 路径安全 → ABI 兼容;
  • --verify-artifacts:额外校验索引中每个 artifact 的 SHA-256;要求 -o 所在目录已有对应 path 的 package(例如先解包/下载插件包再 fetch 到同目录);远程只取索引作元数据时可不开;
  • 失败语义与 --verify-index 一致:0 成功、2 用法、3 校验/网络/格式失败、4 签名索引缺 pubkey 或工具无 Ed25519;
  • 信任模型:公钥必须来自可信通道(宿主内置/企业 PKI/发布说明);不要信任从索引或同一站点下载的公钥。

示例(本地镜像,离线/CI 常用):

# 已有仓库目录 repo/(index.json + packages/):
vde_plugin_tool --fetch-index repo/index.json -o fetched/index.json \
    --pubkey keys/plugin_signing.pub --verify-artifacts
# 指定包目录在 fetched/ 下时,artifacts 会按索引相对路径校验。

4.7 远程包安装与依赖解析(--fetch-packages,P3-17c)

vde_plugin_tool --install <index.json|url> --dest <dir> [--id <id>] [--version <x.y.z>] \
    --fetch-packages [--verify-artifacts] \
    [--pubkey keys/plugin_signing.pub] [--allow-unsigned] [--force]
  • 包文件获取:URL 索引按索引 URL 相对路径下载(http(s) 经 WinHTTP;artifact.url 可覆盖为绝对/相对 URL); 本地索引从索引目录复制;每个 artifact 写入 <dest>/.vde-staging-* 后立即校验 SHA-256;
  • 依赖解析(requires):已安装版本满足则跳过;否则从索引选择最高满足版本,递归闭包一并安装; 缺失依赖/版本冲突/循环依赖返回退出码 3 与明确错误;依赖按 postorder 先装;
  • 原子性:所有包先落 staging 并校验,全部成功后再 rename 到 <dest>/<id>/;任一步失败清理 staging、 回滚本批已提交的包(含覆盖前的备份),不留部分安装;
  • 远程索引 URL 必须配合 --fetch-packages(否则退出码 3);--verify-artifacts 与 --fetch-packages 语义合并(都要求逐工件获取并校验哈希);
  • 失败语义:0 成功、2 用法、3 校验/下载/依赖/哈希/路径失败;

4.8 卸载(--uninstall,P3-17c)

vde_plugin_tool --uninstall <plugin-id> --dest <dir>
  • 安全校验:id 不得含路径分隔符或 ..;目标必须位于 --dest 规范化路径下且含 vde-plugin.json;
  • P4-41 增强:新增 --root 别名;目标必须是安装根直接子目录;读取 manifest 校验 id 匹配后才删除;
  • 只删除 <dest>/<plugin-id>/;未知 id/非法路径/非插件目录/id 不匹配退出码 3;

4.9 原子升级(--upgrade,P3-17c)

vde_plugin_tool --upgrade <index.json|url> --id <plugin-id> --dest <dir> [--version <x.y.z>] \
    [--fetch-packages] [--pubkey keys/plugin_signing.pub] [--allow-unsigned] [--force] \
    [--revoked-keys <file>]
  • 流程:检查已安装版本(未安装/同版本拒绝)→ 索引选版本(--version 或最高)→ 补装缺失依赖 → staging 下载 + SHA-256 校验 → 旧目录备份 .vde-bak-* → 同卷 rename 原子替换 → 成功清理备份;
  • 失败(下载/哈希/路径/依赖/替换)恢复旧版本并清理 staging,不破坏现有安装;
  • --version 可选择回滚到索引保留的旧版本(原子替换同样适用);
  • 失败语义:0 成功、2 用法、3 校验/下载/依赖/哈希/替换失败,或签名 key_id 被 --revoked-keys 吊销;

4.10 打包(package,P4-41)

vde_plugin_tool package <plugin_dir> -o <file.vdeplugin>
  • 校验:vde-plugin.json 可解析、id/version/entry 非空、entry 文件存在、capabilities 非空、 ABI 与当前宿主兼容(major 相等且 minor ≤ 宿主);限制 10000 文件 / 1GiB;
  • 自定义确定性归档(VDEPKG1,不依赖 zip 库):magic + 单行 JSON metadata (id/version/kind/abi/entry/files)+ 按路径字典序的 FILE <sha256> <size> <path> 头 + 按序 payload;不写时间戳/权限,同一输入重复打包 SHA-256 相同;
  • 输出归档 SHA-256 到 stdout,并写 <archive>.sha256 sidecar(<hex> <filename>);
  • 失败语义:2 用法错误、3 manifest/entry/ABI/capabilities/IO 校验失败;

4.11 校验与解包(verify-package / unpack,P4-41)

vde_plugin_tool verify-package <file.vdeplugin>
vde_plugin_tool unpack <file.vdeplugin> --dest <dir>
  • verify-package:校验 magic/metadata、文件表、每个 payload 的 SHA-256;不写文件;
  • unpack:校验通过后按归档内相对路径写出(自动建目录),存在则覆盖; 拒绝绝对路径、.. 逃逸与非法路径(is_artifact_path_safe),并校验目标规范化后仍位于 dest 下;
  • 失败语义:2 用法错误、3 归档损坏/校验失败/路径逃逸/IO 失败;

4.12 列出已安装插件(list,P4-41)

vde_plugin_tool list <install_root>
# 兼容旧写法:vde_plugin_tool --list <dir>
  • 递归扫描 <install_root> 下的 vde-plugin.json,逐项输出 id/version/kind/ABI/entry/ capabilities/manifest 路径/status;
  • status=installed:manifest 位于 <install_root>/<id>/vde-plugin.json 且 manifest.id 等于目录名; 其它位置为 discovered;无效 manifest 计为 invalid 并以退出码 3 汇总;

4.13 卸载安全增强(uninstall,P4-41)

vde_plugin_tool uninstall <plugin-id> --root <install_root>
# 兼容旧写法(--dest 同义):vde_plugin_tool --uninstall <plugin-id> --dest <dir>
  • 路径安全:id 禁止 /、\、.、..;目标必须为 <root> 的直接子目录(规范化 parent == root);
  • id 匹配:读取 <root>/<id>/vde-plugin.json 并解析,manifest.id 必须等于请求 id,否则拒绝删除;
  • 只删除目标 <root>/<id>/;未安装、非插件目录、id 不匹配、路径逃逸均退出码 3;
  • 回归:tests/plugin/package_tool_smoke.cmake 覆盖 pack→verify→unpack 往返、确定性/SHA-256、list(installed/discovered)、uninstall 仅删目标/id 匹配/路径逃逸、坏 manifest/缺 DLL/归档路径逃逸;

4.14 包升级与回滚(upgrade,P4-48)

vde_plugin_tool upgrade <file.vdeplugin> --root <install_root> [--force] [--rollback]
  • verify:完整校验归档 magic/metadata/FILE 表/逐 payload SHA-256、manifest 存在、id/version; 先解包到 <root>/.vde-stage-<id>-<suffix>,再解析 staged manifest 并校验 id/version/entry 一致;
  • semver 门控:读取已安装 <root>/<id>/vde-plugin.json 版本;默认仅允许 严格更高 版本, 相等版本(重装)或降级会被拒绝;--force 允许相等/降级/覆盖重装;未安装时等同 install;
  • 原子替换:旧目录 rename 为 <root>/<id>.vde-bak-<suffix> → staged rename 为 <root>/<id>; 任一步失败自动恢复旧版本并清理 stage;成功后清理备份;stage 位于同一 root(同卷 rename 原子);
  • --rollback:在 <root> 下查找 <id>.vde-bak-* 备份并恢复最新一个;当前版本先移到 <id>.vde-old-<suffix>,若恢复失败则回滚该移动;无备份/非安装根/路径不合法退出码 3;
  • 路径安全:id 禁止 /、\、.、..、以 . 开头;target 必须是 <root> 直接子目录 (规范化 parent == root);归档内相对路径禁止 ../绝对路径逃逸;
  • 退出码:0 成功、2 用法错误、3 verify/semver/IO/回滚失败;
  • 回归:tests/plugin/upgrade_tool_smoke.cmake 覆盖未安装安装、相等/降级拒绝与 --force、 正常升级、坏包/归档路径逃逸后旧版本保留、--rollback 恢复人工备份、无备份错误;
  • 说明:--upgrade <index.json|url> --id ... --dest ... 仍为 P3-17c 的索引/远程升级入口; 本命令是 P4-41 .vdeplugin 本地包升级入口。

5. 端到端示例(sample_vbox + sample_gcs)

以下命令在 VDE 构建目录执行(build-fb-dist 为本轮独立构建目录);包内容为构建产物 plugins/sample_vbox/、plugins/sample_gcs/。

# 1) 打包
New-Item -ItemType Directory -Force repo/packages/sample_vbox, repo/packages/sample_gcs | Out-Null
Copy-Item <build>/plugins/sample_vbox/vde-plugin.json, <build>/plugins/sample_vbox/vde_sample_vbox.dll repo/packages/sample_vbox/
Copy-Item <build>/plugins/sample_gcs/vde-plugin.json, <build>/plugins/sample_gcs/vde_sample_gcs.dll repo/packages/sample_gcs/

# 2) 生成密钥并签名建索引
vde_plugin_tool --gen-keypair --out-dir keys/
vde_plugin_tool --build-index repo/packages -o repo/index.json --sign keys/plugin_signing.key --key-id test-key --publisher example
vde_plugin_tool --verify-index repo/index.json --pubkey keys/plugin_signing.pub

# 3) 安装并检查
vde_plugin_tool --install repo/index.json --dest installed/ --id com.vde.sample.vbox --pubkey keys/plugin_signing.pub
vde_plugin_tool --install repo/index.json --dest installed/ --id com.vde.sample.gcs --pubkey keys/plugin_signing.pub
vde_plugin_tool --check installed/com.vde.sample.vbox
vde_plugin_tool --list installed/ ; # 宿主 PluginManager 指向 installed/ 即可发现

本轮实测(1.0.71 / MinGW Release):签名为 ed25519;索引含 2 插件;安装后 --check PASS; 负例(篡改 artifact、改索引内容导致坏签名、路径逃逸、ABI 2.0 不兼容、unsigned 未加 --allow-unsigned、已存在目标未加 --force)均返回非 0(详见报告记录)。

6. 信任模型与密钥管理

  1. 私钥离线:签名种子只在发布流水线/离线机使用;泄露需立即轮换并吊销旧 key_id;
  2. 公钥可信分发:宿主/安装器内置公钥或从企业 PKI 获取;不要信任索引里的公钥;
  3. key_id:索引顶层 key_id 标识签名密钥;配合 P3-5 的 trusted_keys/revoked_key_ids 策略,宿主可按 key_id 选择/吊销;P3-13b 起工具内置索引级吊销:--verify-index/--install/ --upgrade --revoked-keys <file> 在验签通过后强制拒绝已吊销 key_id(退出 3);吊销列表须由 调用方显式提供(可信通道),不要信任索引内自带列表;
  4. 多层校验:--verify-index 校验索引签名 + artifact 哈希;插件清单签名(P3-5)可再 由宿主 verify 校验;两者独立;
  5. 路径安全:索引里 path/artifact 路径必须是包内相对路径;--verify-index/--install 拒绝 ..、绝对路径、盘符,防止 zip-slip 类逃逸;
  6. ABI 门禁:安装前按宿主 ABI 拒绝不兼容插件(major 必须相等、minor ≤ 宿主 minor);
  7. 审计:索引记录 generated_at/publisher/key_id/artifact 哈希,可用于发布审计与 供应链比对。

7. 升级 / 回滚 / 卸载

  • 升级(推荐):--upgrade <index|url> --id <id> --dest <dir> [--version x.y.z] [--fetch-packages]; 先下载/校验到 staging,再备份旧目录并同卷 rename 原子替换,失败自动恢复旧版;
  • 回滚:对索引保留的旧版本条目执行 --upgrade --version <old>;成功升级会清理临时备份;
  • 卸载:--uninstall <plugin-id> --dest <dir>(id/路径安全校验,只删目标插件目录);
  • 原子性:P3-17c 起 install/upgrade 均为 staging + 原子提交;批量依赖安装失败会回滚本批已提交包; 断电等极端场景建议同时保留发布侧备份与幂等重试。

8. 发布者检查清单(CI 建议)

[ ] 插件在独立 build 目录用 SDK 头构建通过;--check 通过
[ ] 包内容只含 vde-plugin.json + 动态库 + 必要数据(无构建中间产物/调试符号)
[ ] --build-index --sign 生成索引;--verify-index --pubkey 通过
[ ] 负例回归:篡改任一 artifact / 改索引内容 / 改 ABI / 路径逃逸均失败
[ ] 在干净宿主安装目录上 --install 并通过 PluginManager 发现/加载/调用/卸载
[ ] 公钥/指纹与发布说明一致;key_id 登记;旧版本保留可回滚
[ ] 吊销预案:发布侧登记 key_id;安装/校验侧提供 --revoked-keys(本地策略文件),负例验证被吊销 key 拒绝

9. 当前边界(后续 roadmap)

  • 远程包安装/依赖解析/卸载/原子升级:P3-17c 已提供 --install --fetch-packages(http(s)/本地、 SHA-256 校验、requires 简化 semver 解析、staging 原子提交与回滚)、--uninstall、--upgrade; 尚未提供:远程仓库索引刷新(--fetch-index 已可单独使用)、增量/差量更新、吊销列表自动分发/在线 CRL、容器/隔离安装;
  • 索引级吊销(P3-13b):--verify-index/--install/--upgrade 支持显式 --revoked-keys <file> 并在验签后强制拒绝已吊销签名 key_id(退出 3);吊销列表由调用方/宿主策略提供,自动分发/CRL 待后续;
  • 依赖解析为简化 semver(单 token 比较/空格 AND;无预发布版本/复杂范围);升级为单插件原子替换,不批量升级依赖;
  • 索引签名只覆盖索引文件本身;插件清单签名/工件签名可叠加(P3-5),生产建议双签;
  • 与 P3-14 外部服务、P3-12 模板包/--check、P3-17 scaffold/--fetch-index 配合: scaffold 生成工程 → --check → 打包 → 索引 → 签名 → fetch/verify/install。

10. 独立 vde-plugin-sdk 包(P3-12b)

插件开发者可不依赖 VDE 源码树/内核,仅安装纯 C ABI SDK:

cmake --install <build> --prefix <prefix> --component vde-plugin-sdk
  • 内容:include/vde/plugin/vde_plugin_api.h(纯 C ABI 契约)+ lib/cmake/vde-plugin-sdk/ 配置;
  • consumer:find_package(vde-plugin-sdk CONFIG REQUIRED) → target_link_libraries(my_plugin PRIVATE vde::plugin-sdk) (header-only,无库依赖;版本 SameMajorVersion);
  • 与插件分发关系:SDK 只用于编译插件;插件包的上架/下载/安装/升级走本文索引与 --build-index/--fetch-index/--install/--upgrade 流程;
  • 生成条件:VDE_INSTALL=ON 且 VDE_INSTALL_SDK=ON(默认);VDE_INSTALL=OFF 时 SDK 包不生成;
  • 端到端回归:CTest VDE_PluginSdkConsumerSmoke(安装 SDK component → 独立纯 C consumer 构建/运行 PASS);
  • 限制:不含 plugin_manager.h 等宿主 C++ API(改由 vde-kernel 包/宿主提供);不含模板与示例。

11. 相关文档

  • 插件开发指南:docs/guides/plugin-development.md(ABI/扩展点/--check);
  • 插件安全:docs/design/plugin-security.md(签名规范/策略/密钥轮换);
  • 路线图:docs/design/architecture-plugin-roadmap.md(P3-13);
  • 示例插件:plugins/official/*、plugins/sample_vbox、plugins/sample_gcs;
  • 模板与 scaffold:plugins/templates/(四类最小插件工程)、docs/guides/plugin-development.md §14.4;
  • 远程索引:--fetch-index(本文 §4.6)。

12. 插件 ABI 兼容矩阵(1.0–1.5)

宿主 ABI 1.5 对插件清单 abi 字段的加载规则:major 必须相等,minor <= 宿主 minor。

插件 ABI 新增内容 注册结构(64-bit) 宿主 1.5 行为
1.0 格式插件基础(format/generic) 24B 接受
1.1 宿主服务 body_from_mesh(尾部追加) 24B 接受
1.2 CAE solver / CAM strategy 扩展点 40B 接受
1.3 GCS solver 扩展点 48B 接受(旧 48B 安全)
1.4 Mesher 扩展点(VdeMesherPlugin) 56B 接受(旧 56B 安全)
1.5 Optimizer + IO_BATCH 扩展点(VdeOptimizerPlugin / VdeIoBatchPlugin) 72B(optimizer offset 56、io_batch offset 64) 接受
2.0+ major 不兼容 — 拒绝(动态库加载前)
  • 注册结构按 struct_size 尾扩展:宿主只读取声明尺寸内字段;旧插件无需重编;
  • 声明 kind=optimizer/io_batch 但 struct_size < 72 的插件会被明确拒绝;旧 1.4(56B)插件正常加载;
  • 能力前缀约定:format: / cae_solver: / cam_strategy: / gcs: / mesher: / optimizer: / io_batch: (vde_plugin_tool --check 对不匹配仅 warning);
  • P4 示例:plugins/sample_mesher/(1.4,capability mesher:tet)、plugins/sample_optimizer/(1.5,optimizer:mock)、 plugins/sample_io_batch/(1.5,io_batch:mock);
  • ABI 矩阵回归:plugins/abi_matrix(接受 1.0–1.5,拒绝 2.0);tests/plugin/test_plugin_mesher.cpp(1.4)与 tests/plugin/test_plugin_abi15.cpp(1.5:72B/offset 56/64、旧 1.4 兼容、56B 声明新 kind 拒绝);
  • vde_plugin_tool --abi 打印当前宿主 ABI(1.5)、注册结构尺寸与 Optimizer/IoBatch 结构尺寸; 发布索引 abi 字段应据此声明;旧宿主(1.4)会拒绝 1.5 插件(minor > 宿主),需要旧宿主兼容时按 1.4 构建发布。

13. 本地/自托管索引服务(P4-07)

无外部服务/runner 时,可用工具自带的纯标准库 HTTP 服务演示完整分发链路: 生成签名索引 → HTTP 获取索引 → 远程下载插件包并安装。

13.1 启动

python tools/vde_index_server.py --root repo/ --host 127.0.0.1 --port 0 \
    [--index index.json] [--log]
  • --root <dir>:仓库根目录(含 index.json 与 packages/);
  • --host 默认 127.0.0.1;--port 0 为 ephemeral(自动分配,启动后打印实际端口), 也可指定固定端口;--index 为相对 root 的索引路径(默认 index.json);--log 打印请求日志;
  • 启动输出(stdout,flush):VDE_INDEX_SERVER http://127.0.0.1:<port>/、root=...、index=...; 支持 Ctrl+C 退出。

13.2 路由与安全

  • GET/HEAD / 或 GET/HEAD /<index>:返回索引 JSON;
  • GET/HEAD /<path>:返回 root 下静态文件(插件包/artifact),带 Content-Type、Content-Length、 Cache-Control: no-cache、ETag(内容 SHA-256);
  • 条件刷新:请求带 If-None-Match: <ETag> 且内容未变时返回 304、空 body,避免重复下载索引/包;
  • 路径安全:URL 解码后规范化,拒绝 ..、绝对路径/盘符、反斜杠、空字节与符号链接逃逸; 越界返回 403,不存在返回 404,非 GET/HEAD 返回 405(Allow: GET, HEAD),不列目录;
  • 只读、单 root、无鉴权/无 TLS:仅用于本地开发/CI/可信内网,不要直接暴露公网; 多租户/权限/审计/TLS/限流等真实市场能力后续提供。

13.3 端到端示例

# 1) 生成密钥、构建并签名索引(repo/index.json + repo/packages/...)
vde_plugin_tool --gen-keypair --out-dir keys/
vde_plugin_tool --build-index repo/packages -o repo/index.json \
    --sign keys/plugin_signing.key --key-id test-key --publisher example

# 2) 启动本地索引服务(记下打印的端口)
python tools/vde_index_server.py --root repo/ --port 0

# 3) 另一终端:HTTP 获取索引 + 远程安装插件包
vde_plugin_tool --fetch-index http://127.0.0.1:<port>/index.json \
    -o repo/index_fetched.json --pubkey keys/plugin_signing.pub --verify-artifacts
vde_plugin_tool --install http://127.0.0.1:<port>/index.json --dest installed/ \
    --id com.example.format --fetch-packages --pubkey keys/plugin_signing.pub

说明:--fetch-index --verify-artifacts 按输出目录旁本地 packages 校验哈希(用于离线缓存场景); 远程安装由 --install --fetch-packages 从服务下载每个 artifact 并逐项 SHA-256 校验。

13.4 自动回归

python tests/plugin/index_server_smoke.py --tool <build>/tools/vde_plugin_tool
  • 自动查找 build*/tools/vde_plugin_tool[.exe](也可用 --tool / VDE_PLUGIN_TOOL_EXE 指定);
  • 覆盖:gen-keypair → build-index 签名 → 启动服务(ephemeral)→ HTTP fetch-index (签名+artifact 哈希)→ HTTP install(下载+安装)→ 直接 GET artifact;
  • 负例:404、路径逃逸(403/404 且不泄漏 root 外文件)、篡改 artifact 哈希(fetch/install 均失败);
  • 仅依赖 Python 标准库与已构建的 vde_plugin_tool。

13.5 限制

  • 只读静态服务,不提供上传/发布/删除/鉴权/审计;
  • 无 TLS、无限流、无多 root/虚拟主机;生产市场请置于反向代理/对象存储/鉴权网关之后;
  • 与 P4-08(CRL/吊销分发)配合时,可复用同目录静态托管 revoked-keys 文件(本服务只负责托管);
  • 端口/目录安全语义以本文为准;若需公网部署,必须补充 TLS 与访问控制。

--rollback 语义补充:仅从 <install_root>/<id>.vde-bak-* 备份目录恢复最近一次备份;成功 upgrade 后会清理本次自动备份,因此无人工/外部备份时 --rollback 会正确拒绝。