适用场景: 快速在多台服务器/虚拟机上搭建 KVM 私有云及多云纳管平台
技术栈: Cloudpods v3.11 / v4.0.2 + Ubuntu 22.04 LTS
文档说明: 本文整理自官方文档并结合实战踩坑经验，旨在提供一份可长期复用的标准化部署流程
一、系统简介
Cloudpods 是一款开源的混合云管理平台，支持统一纳管多种公有云和私有云资源，提供虚拟机、容器、存储、网络等一体化管理能力。
项目地址：
- 官网：https://www.cloudpods.org/
- GitHub：https://github.com/yunionio/cloudpods
支持的私有云/虚拟化： VMware、OpenStack、Proxmox VE (PVE) ，等以及 Cloudpods 自身。
二、整体部署架构建议
１、 环境准备
（1）注意事项：
- 操作系统 Ubuntu 22.04 LTS 需为干净版本，不要提前安装任何服务，支持多个Linux发行版，可自行查看。
- 最低配置要求：CPU 8核、内存 8GiB、存储 200GiB。
- 建议为
/opt单独设置挂载点，虚拟机和服务存储默认使用该目录。 - 如在虚拟机上部署，需打开“硬件虚拟化”功能。
（2）角色划分（Node数量多少要看自己情况，1个也可以）：
| 角色 | 说明 |
|---|---|
| 管理节点（Mgmt） | 控制面 + k3s + Web UI |
| 计算节点（Node） | 运行 KVM 虚拟机 |
2、 配置主机名与 hosts 及ip规划（可选）
（1）设置主机名（每台节点执行）：
hostnamectl set-hostname cloud-mgmt-20-24
hostnamectl set-hostname cloud-node1-20-71
hostnamectl set-hostname cloud-node2-20-21
hostnamectl set-hostname cloud-node3-20-43（2）统一 hosts 配置（所有节点执行）：
cat >> /etc/hosts <<EOF
192.168.20.24 cloud-mgmt-20-24
192.168.20.71 cloud-node1-20-71
192.168.20.21 cloud-node2-20-21
192.168.20.43 cloud-node3-20-43
EOF（3）强烈建议（避免宿主机注册失败）：
- 不要混用
/23、/24等不同掩码。 - 使用静态ip地址，所有节点掩码、网关一致。
- 提前规划好主机名及IP信息，安装结束后不能改。
3、 配置静态 IP（可选，总之ip不能随意变更）
（1）禁用 cloud-init 网络配置：
cat > /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg <<EOF
network: {config: disabled}
EOF（2）配置 netplan（假设网卡为 ens160，提前查看自己的网卡，如写错会导致网络异常）：
sudo tee /etc/netplan/01-static.yaml > /dev/null <<'EOF'
network:
version: 2
renderer: networkd
ethernets:
ens160:
dhcp4: false
addresses:
- 192.168.20.21/23
routes:
- to: default
via: 192.168.20.1
nameservers:
search: []
addresses:
- 114.114.114.114
- 8.8.8.8
EOF（3） 应用配置：
mv /etc/netplan/50-cloud-init.yaml /etc/netplan/50-cloud-init.yaml.bak
chmod 600 /etc/netplan/01-static.yaml
netplan apply三、部署 Cloudpods管理端（All in one）
1、 下载 Ocboot 部署工具
wget https://github.com/yunionio/ocboot/archive/refs/tags/master-v3.11.12-6.tar.gz
tar xf master-v3.11.12-6.tar.gz
cd ocboot-master-v3.11.12-6
# 目前v4.0 已发布，支持容器及ai云，建议安装最新版，方法基本相同
# 官方文档：https://www.cloudpods.org/docs/onpremise/getting-started/quickstart-virt2、 运行部署工具
./ocboot.sh run.py virt 192.168.20.24
# 其中 192.168.20.24 为管理节点的 IP 地址。*************以下命令无需求可忽略************* ./ocboot.sh run.py ai 192.168.20.24 （不用ai云，请忽略） # 默认部署已支持虚拟化和容器云，如需支持ai云，等上面普通部署任务结束后，再执行ai部署命令（可能会有一些报错，可忽略） kubectl -n onecloud patch oc default --type merge -p '{"spec":{"productVersion":"FullStack"}}' （不用ai云，请忽略） # 装了ai云后，虚拟机菜单被隐藏，用该命令切换回来，ai和虚拟机都能使用） climc feature-config-pod --switch on （不用容器，请忽略） # 部署完成后，使用容器时，如发现403，需打开容器特性 /opt/yunion/bin/climc （备用命令） # 如果后续操作提示climc命令未找到，新开ssh窗口，或者加上路径
说明：
- 脚本会自动安装 k3s。
- 默认从阿里云镜像仓库拉取镜像。
- 耗时 30~60 分钟属于正常。
- 失败可以重复执行脚本，支持断点恢复。
3、 查看部署状态
# 查看 Pod 状态
kubectl get pods -n onecloud -w
# 查看已注册的 Host
climc host-list4、 部署成功提示
Initialized successfully!
Web page: https://192.168.20.24
User: admin
Password: admin@123首次登录后修改密码，并根据业务需求配置存储、网络及计算资源。
四、添加计算节点
1、 环境要求
- 操作系统 Ubuntu 22.04 LTS 干净，未安装 K8s/容器相关组件。
- 最低配置：8核心、8GB内存、200GB硬盘。
- 建议为
/opt单独挂载。
2、 添加节点步骤（在管理端执行）
（1）确认 SSH 配置（在计算节点）：
确保 /etc/ssh/sshd_config 包含：
PermitRootLogin yes
PubkeyAuthentication yes（2） 配置免密登录（从管理端）：
ssh-copy-id -i ~/.ssh/id_rsa.pub root@192.168.20.21
ssh root@192.168.20.21 "hostname"（3）执行添加计算节点（从管理端）：
./ocboot.sh add-node 192.168.20.24 192.168.20.21预计半小时左右，安装完成后登录控制台查看“宿主机”并“启用”节点。
五、创建虚拟机
创建虚拟机之前，需要提前创建好IP子网，上传虚拟机镜像，启用宿主机等操作。
1、通过前端创建
在 主机 菜单，选择 虚拟机，选择 新建。在此界面输入主机名，选择镜像和IP子网，创建虚拟机。
2、虚拟机管理
更多见文档 https://www.cloudpods.org/docs/onpremise/guides/vminstance/create
六、创建AI 人工智能
1、快速创建 AI 实例
进入 “人工智能” 菜单快速创建 AI 应用的操作如下，请根据自己的需求参考对应的文档。
| 用 | 类型 | 定位 | GPU 依赖 |
|---|---|---|---|
| OpenClaw | AI应用 | 开源自托管的个人智能体助手 | 不需要 |
| Dify | AI应用 | LLM 应用开发与工作流编排平台（可对接推理服务） | 不需要 |
| ComfyUI | AI应用 | 图像生成与节点式工作流应用 | 需要 |
| Ollama | AI推理 | 轻量本地推理服务 | 需要 |
2、登录使用OpenClaw
七、节点管理与故障排查
1、 管理端查看节点状态
# 查看所有 Host Pod
kubectl -n onecloud get pod | grep default-host
# 查看主机列表
climc host-list2、 Host 服务说明
Host 服务由 K8s 的 onecloud 命名空间下的 DaemonSet default-host 定义，每个节点运行一个 default-host-xxxxx 容器，包含三个容器：
| 容器名称 | 功能说明 |
|---|---|
host |
主服务进程，负责与控制器通信、管理虚拟机、存储和网络 |
ovn-controller |
OVN 控制进程，同步网络配置到本地 OVS |
sdnagent |
实现安全组、流控及 VPC 网络功能 |
3、 常用排查命令
# 查看所有 Host Pod
kubectl -n onecloud get pod | grep default-host
# 根据 IP 查找特定 Host Pod
kubectl -n onecloud get pods -o wide | grep 192.168.20.21
# 重启 Host 服务（删除 Pod 会自动重建）
kubectl -n onecloud delete pod <default-host-xxxxx>
# 查看 Host 主容器日志
kubectl -n onecloud logs <default-host-xxxxx> -c host --since 10m -f
八、多云管理
1、查看支持的云厂商
climc --help | grep feature-config
官方文档
https://www.cloudpods.org/docs/cmp/introduction/
https://www.cloudpods.org/docs/onpremise/operations/hidden-feature-config/
2、开、关 某云厂商 的纳管功能
climc feature-config-huawei --switch on
climc feature-config-qcloud --switch on
climc feature-config-jdcloud --switch on
climc feature-config-aliyun --switch on
climc feature-config-huawei --switch off
# 打开公有云菜单
climc feature-config-public --switch on
九、其它
1、新磁盘挂载
第1步，Linux 系统层，比如 创建新目录new_disk，并挂载到 /opt/cloud/workspace/new_disk
然后编辑计算节点 /etc/yunion/host.conf
在 local_image_path 追加新磁盘挂载目录
local_image_path:
– /opt/cloud/workspace/disks
– /opt/cloud/workspace/new_disk
第2步，重启该节点的 default-host 容器（管理端执行）：
kubectl -n onecloud get pods -o wide | grep 192.168.20.46 | grep default-host
kubectl -n onecloud delete pod default-host-n6p8h –force –grace-period=0
第3步，等待 Pod 重建为 1/1 Running，Cloudpods 即可识别该本地存储，可以在【管理控制台/宿主机/存储】中看到。
详细见：https://www.cloudpods.org/docs/onpremise/guides/storage/blockstorage/add-storage/
2、禁用大页
第1步，在所有计算节点编辑 /etc/yunion/host.conf
确保 / 添加如下配置
hugepages_option: disable
第2步，管理节点删除对应节点的 default-host Pod（同上面磁盘步骤里的删除命令），重建后配置立即生效。
详细见：https://www.cloudpods.org/docs/onpremise/guides/vminstance/hugepage/
大页作用：普通内存按小页分配，大页是把多块小内存合并成大块连续内存，减少内存寻址开销，提升虚拟机读写性能。
- disable 关闭大页，虚拟机全部使用默认小内存页，兼容性最好，而且可以超售。
- transparent（默认） 开启系统自动管理的透明大页。无需手动配置，系统会自动合并内存为大页；不支持 1G 超大页，也不能保证虚拟机全程都用大页。
- native 手动预分配专属大页内存池，虚拟机必须从池中取内存。支持 1G 大页，内存连续性最强、性能最优；缺点是需要提前规划内存，配置繁琐。
十、常见踩坑总结
- 掩码不一致（如 /23 vs /24） → 直接注册失败，宿主机不上线。
- 系统不干净 → k3s / containerd 冲突。
- /opt 未单独挂载 → 磁盘很快爆满。
- cloud-init 未禁用 → 重启后 IP 丢失或改变。
- 管理端 network 已存在但不匹配 → 出现
find_matched == false错误。
结论： 一次性规划好 IP、主机名、掩码，使用干净系统 + 静态 IP + 统一网段，Cloudpods 安装成功率接近 100%。