企业官网建设流程全解析

• 后端
• 虚拟化
• 运维
• 云原生

ZSvirt 插件开发是让 ZSvirt（ZStack 核心 IaaS 引擎）适配新虚拟化技术、新网络方案或新存储后端的唯一正途。本文是一份面向新手的 ZSvirt 插件开发完整教程，用"扩展点接口 + XML 注册 + API 定义"三步法，带你从零开始扩展自己的计算、网络、存储能力，全程不改动核心代码。

一、先懂架构：为什么 ZSvirt 插件这么简单 🏗️

ZSvirt 采用进程内微服务架构：计算、网络、存储等所有服务运行在同一个"管理节点"进程中，服务之间通过消息总线（CloudBus）通信，代码高度松耦合。

这种设计带来一个关键特性——插件友好：

• 每个插件就是一个普通的Maven 模块（一个 jar），对核心只依赖header接口，互不编译耦合；
• 插件通过扩展点（Extension Point）接口挂接到核心流程，核心在运行时动态发现所有实现；
• 服务无独占线程，统一共享线程池按需调度，插件代码无需操心并发与高可用：

一句话总结：你的插件 = 实现一组 header 扩展点接口 + 一个 XML 注册文件 + 若干 API 消息类。

二、插件开发六步总览

三、第一步：创建插件 Maven 模块

在 plugin/ 目录下按现有插件（如 plugin/kvm/、plugin/vxlan/、plugin/ceph/）新建目录，编写 pom.xml：

• parent 指向plugin聚合模块，并声明 plugin/pom.xml 中新增 module；
• 按功能依赖对应核心模块，例如 KVM 计算插件依赖compute、securityGroup、console，参见 plugin/kvm/pom.xml；
• 构建配置需包含Groovy 混合编译器与AspectJ 切面库（core、header的 aspectLibrary），否则扩展点的依赖注入不生效。

四、第二步：实现扩展点接口（核心中的核心 ⚙️）

所有扩展点接口都集中在 header/ 模块——这是插件与核心之间的"契约层"。三类典型场景：

1. 计算扩展：接入新的 Hypervisor

实现 HypervisorFactory.java，告诉系统如何创建/查询你的主机类型：

public interface HypervisorFactory { HostVO createHost(HostVO vo, AddHostMessage msg); Host getHost(HostVO vo); HypervisorType getHypervisorType(); }

KVM 插件的实现注册见 conf/springConfigXml/Kvm.xml，同时挂上了ManagementNodeReadyExtensionPoint、ProxyHardwareFactory等多个扩展点。

2. 网络扩展：接入新的 L2/L3 网络

• L2 网络：实现L2NetworkRealizationExtensionPoint（如 VXLAN 后端）；
• L3 网络：实现 L3NetworkFactory.java 注册一种新的 L3 网络类型；
• 安全组后端：实现SecurityGroupHypervisorBackend，让你的 Hypervisor 能下发安全组规则。

VXLAN 网络插件开发完成后，UI 上会直接出现创建入口：

3. 存储扩展：接入新的主存储/备份存储

参考 plugin/nfsPrimaryStorage/ 与 plugin/ceph/：实现对应PrimaryStorageFactory/BackupStorageFactory，并通过Volume相关扩展点挂接卷的创建、挂载、快照流程。

五、第三步：XML 注册插件

ZSvirt 自定义了一个 Spring 命名空间zstack:plugin，由 PluginNameSpaceHandler.java 解析，把 Bean 自动登记到扩展点容器。注册格式如下（摘自 conf/springConfigXml/Kvm.xml）：

<bean id="KVMHostReconnectTaskFactory" class="org.zstack.kvm.KVMHostReconnectTaskFactory"> <zstack:plugin> <zstack:extension interface="org.zstack.compute.host.HostReconnectTaskFactory" /> </zstack:plugin> </bean>

然后只需在 conf/zstack.xml 中加一行<import resource="springConfigXml/你的插件.xml"/>，管理节点启动时即可载入插件——全程零核心代码改动，这正是观察者模式插件结构的威力。

六、第四步：定义 API、全局配置与错误码

插件对外能力通过三件套交付：

1. API：编写APIXxxMsg消息类并加@RestRequest注解，系统自动暴露 HTTP/CLI 接口与文档，范例见 APIAddKVMHostMsg.java：

@RestRequest(path = "/hosts/kvm", method = HttpMethod.POST) public class APIAddKVMHostMsg extends APIAddHostMsg implements AddKVMHostMessage

2. 全局配置：在conf/globalConfig/下提供 XML（如 conf/globalConfig/kvm.xml），即可让用户通过 API 动态调整插件参数；

3. 错误码：在插件资源目录提供错误码 XML（参考 conf/errorCodes/），保证异常提示可本地化。

七、第五步：用 LongJob 编排长任务

添加主机、创建存储这类操作包含"检查→下发→轮询→收尾"多个步骤，ZSvirt 用LongJob（长任务框架）编排，天然支持进度条展示与失败回滚：

• 长任务实现：AddKVMHostLongJob.java
• 框架文档与示例：docs/modules/longjob/、LongJobManager.xml

八、第六步：构建与验证

mvn -pl plugin/kvm -am package -DskipTests

验证路径建议：先跑 test/ 下的集成测试框架（testlib），再在本地集群实际添加一台主机观察 API 行为。测试编写指南见 docs/modules/test/pages/integration-test/usages/write-test-case.adoc。

九、常见问题 FAQ ❓

Q1：插件一定要实现很多接口吗？不一定。最小可用插件只需一个 API + 一两个核心扩展点（如HypervisorFactory），按需扩展即可，接口列表可全局搜索ExtensionPoint快速定位。

Q2：插件之间会互相影响吗？不会编译耦合。各插件只依赖 header/ 接口模块，运行期通过消息总线交互，删除某个插件不影响其它插件。

Q3：如何调试插件没被加载？检查三点：① XML 是否在 conf/zstack.xml 中 import；②<zstack:extension interface>全限定类名是否拼写正确；③ 启动日志中该 Bean 是否注册成功。

Q4：想支持 ARM 架构或新 Guest 类型怎么办？参考 docs/modules/ROOT/images/overview-multi-arch.png 的多架构说明，同样以插件方式扩展镜像与 Hypervisor 适配层。

十、总结与进阶路线 🚀

掌握"扩展点接口 → XML 注册 → API 交付"这一套路，你就拥有了改造 ZSvirt 的完整能力。架构原理解读可继续阅读 docs/modules/core/pages/in-process-microservice.adoc 与 docs/modules/core/pages/index.adoc。

• 后端
• 虚拟化
• 运维
• 云原生