Cloudpods 开源混合云管理系统部署指南

　　适用场景: 快速在多台服务器/虚拟机上搭建 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-virt

2、运行部署工具

./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-list

4、部署成功提示

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-list

2、 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

九、常见踩坑总结

掩码不一致（如 /23 vs /24） → 直接注册失败，宿主机不上线。
系统不干净 → k3s / containerd 冲突。
/opt 未单独挂载 → 磁盘很快爆满。
cloud-init 未禁用 → 重启后 IP 丢失或改变。
管理端 network 已存在但不匹配 → 出现 find_matched == false 错误。

结论： 一次性规划好 IP、主机名、掩码，使用干净系统 + 静态 IP + 统一网段，Cloudpods 安装成功率接近 100%。