从零到第一台虚拟机：手把手教你部署 ZSvirt

如果你正在评估 ZSvirt，最快的上手方式不是读完整本用户手册，而是亲手把一台虚拟机跑起来。

这篇教程带你走通一条最小可用链路：安装管理节点 → 初始化平台 → 添加主机、存储、网络、镜像 → 创建第一台虚拟机并登录。全程大约 30-40 分钟（不含镜像下载时间），完成后你会得到一个可以 ping 通外网、能打开控制台的虚拟机，平台的核心链路也就全部跑通了。

说明：底层命令和 API 名称仍保留 zstack-ctl、zstack-cli、PrimaryStorage、BackupStorage 等历史字段，这是命令层命名，不影响平台操作。

准备工作：一台服务器就够

最小环境是 All-in-One：一台服务器同时充当管理节点和计算节点。硬件门槛不高：

项目	最低要求	建议配置
CPU	支持 Intel VT 或 AMD-V，不低于 8 核心	24 核及以上
内存	8 GB	24 GB 及以上
系统盘	100 GB	200 GB 及以上
网卡	1 张管理网卡	管理、存储、业务网络分离
IP	固定 IP	固定 IP，提前配置 DNS/NTP

两个容易忽略的点：

• 不要用 DHCP。管理节点 IP 安装后会写入平台配置，换 IP 会很麻烦。
• 校准系统时间。管理节点时间早于安装包构建时间，安装脚本会直接失败——这是新手最常踩的第一个坑。

另外准备好 ISO 安装介质：ZSvirt-x86_64-DVD-<version>-h84r.iso，用物理光驱、U 盘启动盘或服务器远程控制台挂载均可。U 盘刻录推荐 Rufus 或 Fedora Media Writer，Legacy 和 UEFI 引导都支持。

第一步：用 ISO 安装管理节点

从 ISO 启动后，默认进入 Install ZSVirt，无需手动选择，直接进入 INSTALLATION SUMMARY 配置界面：

接下来按顺序完成四项配置：

1. Installation Destination（系统盘）：选中一块磁盘作为系统盘，点击 Done。

2. Software Selection（安装模式）：选择 ZSvirt Management Node，点击 Done。

3. Network & Host Name（网络）：点击 Configure… 打开网卡配置，在 IPv4 Settings 里把 Method 改为 Manual，点 Add 填入规划好的 IP、子网掩码和网关，保存：

别忘了在 General 页勾选 Connect automatically with priority (0)，否则重启后网卡不会自动激活：

4. Root Password（密码）：输入并二次确认 root 密码，点击 Done。

四项全部就绪后，点击 Begin Installation。安装大约需要 10 分钟，完成后系统自动重启，并继续自动安装 ZSvirt 管理节点服务：

当系统进入 TUI 界面、MN 和 UI 状态均为 Running 时，管理节点就装好了：

如果不放心，可以登录系统跑两条命令验证：

zstack-ctl status
zstack-ctl show_configuration | grep management.server.ip

如果安装失败，优先看 /tmp/zstack_installation-*.log；Web UI 装不上则看 /usr/local/zstack/zstack-ui/logs/ui-install.log。

第二步：初始化平台

浏览器直接访问管理节点 IP，用默认账号 admin/password 登录：

⚠️ 生产环境请务必在首次登录后立即修改默认密码。测试环境也建议顺手改掉，养成习惯。

首次登录后，平台会引导你创建数据中心和集群。QuickStart 只需要各建一个：数据中心命名 Datacenter-1，集群命名 Cluster-1：

概念上，数据中心承载一组计算、存储、网络资源；集群负责组织主机、数据存储和分布式交换机。先建起来，后面所有资源都挂在它们下面。

第三步：把管理节点加成主机

All-in-One 的玩法是把管理节点自己也加为一台主机。输入名称、IP 地址（填管理节点 IP）和 root 密码，点击 OK，等主机状态变成已连接：

这一步如果失败，十有八九是 SSH 不通或 root 密码不对，先 ssh root@<主机IP> 手动测一下。

第四步：添加数据存储和镜像存储

虚拟机磁盘放数据存储，系统镜像放镜像存储，两者都要加。

数据存储：测试环境选本地存储即可，输入名称和挂载路径（不要复用系统根目录或临时目录），点击 OK：

注意：本地存储适合单主机验证，但没法玩跨主机迁移。要体验热迁移，后面需要换成所有主机都能访问的共享存储。

镜像存储：输入名称、镜像存储 IP（同样填管理节点 IP）和密码，点击 Test Connection，选择 Local Directory，点击 OK：

然后添加一个系统镜像（qcow2 或 raw 格式）。测试用的话保持默认参数直接点 OK——系统会自动为你配置一个测试镜像 ZStack-image-1.4，可以直接用来验证创建虚拟机：

镜像导入速度取决于镜像存储、管理节点、主机和数据存储之间的链路，大镜像耐心等一会儿。如果添加失败，先确认镜像 URL 或本地路径对平台可读（可以 curl -I <镜像URL> 或 qemu-img info <镜像文件> 自查）。

第五步：创建网络

新建分布式交换机和分布式端口组。以 vlan-2344 为例，配置 VLAN ID、IP 分配方式和 DNS，点击 OK：

几个建议：

• 快速验证阶段，开启 IP 地址管理和 DHCP，虚拟机能自动拿到 IP，省去手工配置。
• 网络段别覆盖网关、DHCP 服务 IP 和已有业务地址——这是第二个高频坑，虚拟机拿不到 IP 多半是这个原因。
• 集群内所有主机必须有同名物理接口或 bond；用 VLAN 时，交换机侧的 trunk/access 配置要和平台一致。

第六步：创建第一台虚拟机

点击新建虚拟机，输入名称，硬盘 1 选择刚才导入的系统镜像，选择网卡 1，点击确定：

等虚拟机状态变成「运行中」，打开控制台看到登录界面，就成功了大半。

登录虚拟机内部，跑一组验证：

ip addr
ip route
ping -c 4 <网关IP>
ping -c 4 223.5.5.5
ping -c 4 www.baidu.com

判断标准很简单：

• ping 通网关 → 分布式交换机、端口组、DHCP、VLAN 都正常；
• ping 通外网 IP → 上游路由正常；
• ping 通域名 → DNS 正常。

第七步：用 CLI 再确认一遍（可选）

习惯命令行的同学，可以在管理节点上用 CLI 做一次全链路体检：

zstack-cli

LogInByAccount accountName=admin password=<管理员密码>

QueryHost fields=uuid,name,managementIp,state,status
QueryPrimaryStorage fields=uuid,name,type,state,status,availableCapacity,totalCapacity
QueryBackupStorage fields=uuid,name,type,state,status,availableCapacity,totalCapacity
QueryL3Network fields=uuid,name,type
QueryImage fields=uuid,name,state,status
QueryVmInstance name=vm-test-01 fields=uuid,name,state,hostUuid,vmNics

期望看到的结果：

Host state=Enabled status=Connected
PrimaryStorage state=Enabled status=Connected
BackupStorage state=Enabled status=Connected
Image state=Enabled status=Ready
VmInstance state=Running

全部对上了，说明计算、存储、网络、镜像、虚拟机这条链路彻底打通。

踩坑速查

现象	先看哪里
安装脚本退出	系统时间、root 权限、/tmp/zstack_installation-*.log
主机添加失败	SSH 连通性、root 密码、时间同步、防火墙
镜像添加失败	镜像 URL 可读性、镜像格式、镜像存储剩余容量
虚拟机拿不到 IP	网络段是否覆盖网关/保留地址、DHCP 是否开启
控制台打不开	zstack-ctl status、浏览器证书

更完整的排查清单见安装部署文档。

接下来做什么

最小环境跑通后，建议按这个顺序继续：

1. 改掉默认密码，创建个人管理员账号；
2. 配置 NTP，保证管理节点、主机、存储时间一致；
3. 把本地存储换成共享存储，体验跨主机热迁移；
4. 制作标准的 Linux/Windows 模板镜像，并安装 VMTools 获得完整的虚拟机内部监控能力；
5. 需要双管理节点高可用时，参考安装部署升级教程的 HA 章节。

完整的分步参考（含每张截图的详细说明）也可以看文档站的快速开始页面。

如果在部署过程中遇到问题，欢迎到 GitHub 社区 提 Issue 或参与讨论。