30 KiB
插件分发指南(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>.sha256sidecar(<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. 信任模型与密钥管理
- 私钥离线:签名种子只在发布流水线/离线机使用;泄露需立即轮换并吊销旧
key_id; - 公钥可信分发:宿主/安装器内置公钥或从企业 PKI 获取;不要信任索引里的公钥;
- 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);吊销列表须由 调用方显式提供(可信通道),不要信任索引内自带列表; - 多层校验:
--verify-index校验索引签名 + artifact 哈希;插件清单签名(P3-5)可再 由宿主verify校验;两者独立; - 路径安全:索引里
path/artifact 路径必须是包内相对路径;--verify-index/--install拒绝..、绝对路径、盘符,防止 zip-slip 类逃逸; - ABI 门禁:安装前按宿主 ABI 拒绝不兼容插件(major 必须相等、minor ≤ 宿主 minor);
- 审计:索引记录
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,capabilitymesher: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会正确拒绝。