适用场景: 快速在多台服务器/虚拟机上搭建 KVM 私有云及多云纳管平台
技术栈: Cloudpods v3.11.12 + 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）角色划分：
| 角色 | 说明 |
|---|---|
| 管理节点（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地址，所有节点掩码、网关一致。
3、 配置静态 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-62、 运行部署工具
./ocboot.sh run.py virt 192.168.20.24
# 其中 192.168.20.24 为管理节点的 IP 地址。说明：
- 脚本会自动安装 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、虚拟机管理
2、虚拟机管理
更多见文档 https://www.cloudpods.org/docs/onpremise/guides/vminstance/create
六、节点管理与故障排查
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
七、常见踩坑总结
- 掩码不一致（如 /23 vs /24） → 直接注册失败，宿主机不上线。
- 系统不干净 → k3s / containerd 冲突。
- /opt 未单独挂载 → 磁盘很快爆满。
- cloud-init 未禁用 → 重启后 IP 丢失或改变。
- 管理端 network 已存在但不匹配 → 出现
find_matched == false错误。
结论： 一次性规划好 IP、主机名、掩码，使用干净系统 + 静态 IP + 统一网段，Cloudpods 安装成功率接近 100%。