过去两天,我们宣布了 ZSvirt 正式开源,也聊了这个决定背后的原因。今天,让我们动手把它跑起来。
如果你在评估 ZSvirt,最快的了解方式不是通读整本用户手册,而是亲手把一台虚拟机跑起来。
本教程带你看一条最小端到端路径:安装管理节点 → 初始化平台 → 添加主机、存储、网络与镜像 → 创建第一台虚拟机并登录。完成后,你将得到一台可以访问外网、可以打开控制台的虚拟机——这意味着平台的每个核心链路都已打通。
更喜欢看视频?本教程也有手把手的视频版:https://www.bilibili.com/video/BV182Yx6kESh/?spm_id_from=333.1387.upload.video_card.click&vd_source=a78a449a21a7000b7c82d652b9e9d799
说明:底层命令与 API 名称仍沿用
zstack-ctl、zstack-cli、PrimaryStorage、BackupStorage 等历史字段,内置测试镜像名为ZStack-image-1.4。这些仅为命令层命名,不影响平台功能操作。
开始之前:一台服务器就够了
最小部署方式是 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 在安装时会写入平台配置,事后修改非常麻烦。
- 同步系统时间。 如果管理节点的时钟早于安装包的构建时间,安装程序会直接失败——这是新手最常踩的第一个坑。
同时准备好 ISO 安装介质:ZSvirt-x86_64-DVD-<version>.iso。可以通过物理光驱、U 盘或服务器带外控制台挂载 ISO 启动。制作 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 密码):输入两次 root 密码,点击 Done。

四项全部就绪后,点击 Begin Installation。安装完成后系统会自动重启,并继续安装 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 登录:

⚠️ 生产环境中,首次登录后务必立即修改默认密码。即使在测试环境,也建议养成这个习惯。
首次登录后,平台会引导你创建数据中心与集群。快速上手各创建一个即可:数据中心命名为 Datacenter-1,集群命名为 Cluster-1:


概念上,数据中心承载一组计算、存储与网络资源,集群则组织主机、数据存储与分布式交换机。先创建它们——其他所有资源都挂在这两层之下。
第三步:将管理节点添加为主机
All-in-One 的关键一步,是把管理节点本身添加为主机。填写名称、IP 地址(即管理节点 IP)和 root 密码,点击 确定,等待主机状态变为已连接:

如果这一步失败,十有八九是 SSH 连通性或 root 密码问题——先手动 ssh root@<主机 IP> 验证。
第四步:添加数据存储与镜像存储
虚拟机磁盘放在数据存储上,系统镜像放在镜像存储上,两者都需要。
数据存储:测试环境用本地数据存储即可。填写名称与挂载路径(不要复用系统根目录或临时目录),点击 确定:

说明:本地数据存储适合单主机验证,但无法跨主机迁移。后续想体验热迁移,请改用所有主机均可访问的共享存储。
镜像存储:填写名称、镜像存储 IP(依然是管理节点 IP)和密码,点击 测试连接,选择 本地目录,点击 确定:

然后添加系统镜像(qcow2 或 raw 格式)。测试用默认配置即可,直接点击 确定。系统会自动内置一个测试镜像 ZStack-image-1.4,可以直接用来验证虚拟机创建:

导入速度取决于镜像存储、管理节点、主机与数据存储之间的网络路径,大镜像请耐心等待。如果失败,先确认平台能读到镜像 URL 或本地路径(curl -I <镜像 URL> 或 qemu-img info <镜像文件> 都很好用)。
第五步:创建网络
创建一个分布式交换机和一个分布式端口组。以 vlan-2344 为例,配置 VLAN ID、IP 分配方式与 DNS,点击 确定:

几点提示:
- 快速验证场景下,开启 IP 地址管理与 DHCP,虚拟机即可自动获取 IP。
- 网段不要与网关、DHCP 服务 IP 或已有业务地址重叠——这是第二常见的坑,绝大多数“虚拟机拿不到 IP”都源于此。
- 集群内所有主机需要有同名的物理网卡或 bond;使用 VLAN 时,交换机侧的 trunk/access 配置必须与平台一致。
第六步:创建第一台虚拟机
点击 创建虚拟机,填写名称,磁盘 1 选择刚导入的系统镜像,选择 网卡 1,确认创建:

当虚拟机状态变为 Running,且控制台出现登录界面,就大功告成了。
登录虚拟机,做一轮快速验证:
ip addr
ip route
ping -c 4 <网关 IP>
ping -c 4 1.1.1.1
ping -c 4 example.com
结果判读很简单:
- 网关通 → 分布式交换机、端口组、DHCP、VLAN 全部正常;
- 外网 IP 通 → 上游路由正常;
- 域名能解析且有响应 → DNS 正常。
第七步:用 CLI 复核一遍(可选)
如果你更喜欢命令行,可以在管理节点上做一轮全链路健康检查:
zstack-cli
LogInByAccount accountName=admin password=<admin 密码>
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、浏览器证书 |
更完整的排查清单见文档站。
接下来做什么
最小环境跑通后,建议按这个顺序继续:
- 修改默认密码,并为管理员创建独立账号;
- 配置 NTP,让管理节点、主机与存储保持时间一致;
- 将本地数据存储切换为共享存储,体验跨主机热迁移;
- 制作标准的 Linux/Windows 模板镜像,并安装 VMTools 以获得完整的虚拟机内部监控;
- 需要双管理节点高可用时,参阅文档站的 HA 章节。
带完整截图的分步参考也可以在文档站的快速上手页面找到。
部署过程中遇到任何问题,欢迎到 GitHub Issues 提交问题,或在 GitHub Discussions 加入技术讨论。
加入社区
- 问题反馈:GitHub Issues
- 社区讨论:GitHub Discussions
- 社交媒体:
- YouTube:https://youtube.com/@ZSvirt
- LinkedIn:https://www.linkedin.com/in/zsvirt-community/
- X/Twitter:https://x.com/ZSvirt
- Reddit:https://www.reddit.com/r/ZSvirt/
- Email:community@zsvirt.io
129



被折叠的 条评论
为什么被折叠?



