企业官网建设流程全解析

Cephadm 部署全新 Ceph 集群完全指南：从 bootstrap 引导到生产级多主机扩展

【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/ceph

导读

本文基于 Ceph 官方运维文档 doc/cephadm/install.rst 展开，系统讲解如何用cephadm从一个空主机引导（bootstrap）出全新的 Ceph 集群，并逐步扩展到多主机、多 Monitor、多 OSD 的完整生产形态。读完本文，你将掌握 cephadm 的获取与安装、cephadm bootstrap全部核心参数、Ceph CLI 的启用方式、主机/监控/存储的添加方法，以及单主机、隔离环境（airgap）、自定义 SSH 密钥、CA 签名证书等特殊部署场景的完整实操命令。文中所有配置项与命令行为均与仓库源码 src/cephadm/cephadm.py 相互印证，确保可复制、可运行、可回溯。

一、部署前置要求（Requirements）

cephadm 采用容器化方式部署 Ceph 守护进程，因此对宿主机的要求非常轻量。在引导新集群之前，需要确认目标主机满足以下依赖：

• Python 3（具体而言需要 3.6 或更高版本，下文详述）
• Systemd（用于管理守护进程容器）
• Podman 或 Docker（作为容器运行时）
• 时间同步（如 Chrony 或传统的ntpd）
• LVM2（用于为存储设备做 provisioning）

任何现代 Linux 发行版基本都能满足这些条件，且 bootstrap 过程会自动安装依赖，无需手工逐个补齐。关于容器运行时的版本兼容性，可参考 doc/cephadm/compatibility.rst 中 Ceph 版本与 Podman 版本的兼容对照表——并非所有 Podman 版本都与 Ceph 兼容，这一点在选择运行时版本时需要特别留意。

另外，Docker 用户可关注 Live Restore 特性：它允许在不重启所有运行中容器的情况下重启 Docker Engine，cephadm 与 Docker Engine 的集成细节见 doc/cephadm/docker-live-restore.rst。

二、获取并安装 cephadm

安装 cephadm 分两个关键步骤：先获取一份初始的 cephadm，再确保其保持最新。获取初始 cephadm 有两条互斥的路径，同一系统上二者只能选其一，不可混用：

1. 发行版特定安装方式（distribution-specific installation）
2. 基于 curl 的安装方式（curl-based installation）

注意：较新版本的 cephadm 是以源码编译出的可执行文件分发的。与早期 Ceph 不同，直接从 git 树拷贝单个脚本已不再可行。若想运行开发版 cephadm，需要自行编译独立可执行文件，参见 doc/dev/cephadm/developing-cephadm.rst。

2.1 发行版特定安装

部分 Linux 发行版已内置较新的 Ceph 软件包，可直接安装 cephadm：

Ubuntu：

apt install -y cephadm

CentOS Stream：

dnf search release-ceph dnf install --assumeyes centos-release-ceph-<stable-release> dnf install --assumeyes cephadm

Fedora：

dnf -y install cephadm

SUSE：

zypper install -y cephadm

上例中的<stable-release>表示该发行版对应的 Ceph 稳定发布版本号，实际执行时请以 doc/releases/index.rst 中标注的当前活跃版本为准。

2.2 使用 curl 安装 cephadm

1. 先确定要安装的 Ceph 版本，可查看 doc/releases/index.rst 中的活跃版本列表（active releases）。例如当前活跃版本可能是18.2.x。

2. 用curl获取对应版本的 cephadm 构建产物：

CEPH_RELEASE=18.2.0 # 替换为当前活跃版本 curl --silent --remote-name --location https://download.ceph.com/rpm-${CEPH_RELEASE}/el9/noarch/cephadm

3. 赋予可执行权限：

chmod +x cephadm

此后即可从当前目录直接运行：

./cephadm <arguments...>

2.3 cephadm 需要 Python 3.6 或更高版本

cephadm要求 Python 3.6+。如果运行遇到困难，尤其是出现包含bad interpreter的错误信息，通常说明系统中没有 Python 或版本不正确。此时可以显式指定某个 Python 版本来运行：

python3.8 ./cephadm <arguments...>

2.4 在主机上正式安装 cephadm

独立的./cephadm足以引导集群，但最佳实践是把cephadm命令真正安装到宿主机（进入 PATH），这样后续运维更加顺手：

# 1. 添加仓库 ./cephadm add-repo --release <stable-release> # 2. 安装 cephadm ./cephadm install # 3. 验证 PATH which cephadm

which cephadm成功后会输出：

/usr/sbin/cephadm

三、引导（Bootstrap）一个新集群

3.1 引导前需要知道什么

创建新 Ceph 集群的第一步，是在集群的第一台主机上运行cephadm bootstrap。运行该命令会在这台主机上创建集群的第一个 Monitor 守护进程。因此必须把第一台主机的IP 地址传给命令，请提前确认该地址。

• ssh必须已安装且处于运行状态，bootstrap 过程才能成功；
• 如果主机有多个网络和网卡，请务必选择一个所有需要访问集群的主机都能访问到的网络。

3.2 运行 bootstrap 命令

cephadm bootstrap --mon-ip <mon-ip>

该命令会自动完成以下工作：

从源码结构看，bootstrap 的参数解析集中在 src/cephadm/cephadm.py#L5740-L5923：--mon-ip与--mon-addrv（如[v2:localipaddr:3300,v1:localipaddr:6789]）、--mon-net（CIDR 网段）构成一个互斥参数组（required 必填），三者按场景任选其一即可指定 mon 的监听地址。

3.3 bootstrap 高级选项详解

默认 bootstrap 流程对大多数用户已经足够，但如需精细化控制，可以运行cephadm bootstrap -h查看全部选项。以下为核心选项的逐一说明：

--log-to-file：传统日志文件模式

默认情况下，Ceph 守护进程把日志输出到 stdout/stderr，由容器运行时（Docker/Podman）捕获并（多数系统上）送入 journald。如果希望 Ceph 写传统日志文件到/var/log/ceph/$fsid，请在 bootstrap 时加上--log-to-file。源码中该选项会同时调整六项配置（src/cephadm/cephadm.py#L2853-L2859）：

global/log_to_file = true global/log_to_stderr = false global/log_to_journald = false global/mon_cluster_log_to_file = true global/mon_cluster_log_to_stderr = false global/mon_cluster_log_to_journald = false

--cluster-network：分离集群内部网络

较大规模的集群中，建议将（集群外部的）公共网络流量与（集群内部的）集群流量分离。内部集群流量承载 OSD 之间的复制、恢复与心跳。该参数必须是 CIDR 网段，例如10.90.90.0/24或fe80::/64：

cephadm bootstrap --mon-ip <mon-ip> --cluster-network 10.90.90.0/24

--output-dir：改变输出文件位置

cephadm bootstrap默认把访问新集群所需的文件写到/etc/ceph，这个集中位置方便宿主机上安装的 Ceph 软件包（如 cephadm CLI 相关包）找到这些文件。但 cephadm 部署的守护进程容器本身完全不需要/etc/ceph。若主机上已存在其他 Ceph 配置（无论是否 cephadm 管理），可用--output-dir <directory>把文件写到别的目录（例如.），避免冲突。源码中该参数默认值为/etc/ceph（src/cephadm/cephadm.py#L5759-L5761），同时还有--output-keyring、--output-config、--output-pub-ssh-key三个更细粒度的输出位置选项。

--config：注入初始配置

可以把任意初始 Ceph 配置放进标准 ini 风格配置文件，再用--config <config-file>传给新集群。例如：

cat <<EOF > initial-ceph.conf [global] osd_crush_chooseleaf_type = 0 EOF ./cephadm bootstrap --config initial-ceph.conf ...

--ssh-user：指定 SSH 用户

该选项指定 cephadm 连接主机时使用的 SSH 用户，对应的 SSH 密钥会被追加到~<user>/.ssh/authorized_keys。指定的用户必须具备免密 sudo 权限。源码中该参数默认值为root（src/cephadm/cephadm.py#L5816-L5819）。

--registry-json：私有镜像仓库登录

若容器镜像来自需要登录的 registry，可传--registry-json <path to JSON file>。JSON 文件内容格式如下：

{"url":"REGISTRY_URL", "username":"REGISTRY_USERNAME", "password":"REGISTRY_PASSWORD"}

cephadm 会尝试登录该 registry 以拉取容器镜像，并将登录信息存入其配置数据库；后续加入集群的其他主机也能使用这个经过认证的容器 registry。源码中还提供了等价的三参数形式：--registry-url、--registry-username、--registry-password（src/cephadm/cephadm.py#L5890-L5900）。

其他常用开关（均来自 src/cephadm/cephadm.py#L5820-L5888）：

更丰富的 bootstrap 场景示例可参考文档末尾的部署场景章节。

四、启用 Ceph CLI

cephadm 不要求宿主机安装任何 Ceph 软件包，但我们强烈建议让ceph命令易于访问。有几种方式：

方式一：cephadm shell容器内执行

cephadm shell会在容器中启动一个装有全部 Ceph 软件包的 bash shell。默认情况下，如果宿主机/etc/ceph下存在配置与 keyring 文件，它们会被传入容器环境，使 shell 完全可用。在 Monitor 主机上执行时，cephadm shell会从 Monitor 容器推断 config而非使用默认配置。若传入--mount <path>，宿主机的<path>（文件或目录）会出现在容器内的/mnt下：

cephadm shell

方式二：直接执行单条 ceph 命令

cephadm shell -- ceph -s

方式三：安装ceph-common软件包

ceph-common包含全部 Ceph 工具，如ceph、rbd、mount.ceph（用于挂载 CephFS）等：

cephadm add-repo --release <stable-release> cephadm install ceph-common

验证ceph命令是否可用，以及能否连接集群并查看状态：

ceph -v ceph status

五、添加主机（Adding Hosts）

按 doc/cephadm/host-management.rst 的指引把所有主机加入集群。

默认情况下，所有带_admin标签的主机都会在/etc/ceph维护一份ceph.conf和client.adminkeyring 副本；该标签初始只打在 bootstrap 主机上。建议再给一台或多台主机添加_admin标签，以便在多个主机上方便地使用 Ceph CLI（例如通过cephadm shell）。添加标签的命令格式：

ceph orch host label add <host> _admin

六、添加更多 Monitor

典型 Ceph 集群会在不同主机上部署三或五个 Monitor守护进程。如果集群节点数达到五个或以上，建议部署五个 Monitor。绝大多数集群部署七个以上 Monitor 并无额外收益。

添加额外 Monitor 的详细步骤参见 doc/cephadm/services/mon.rst。

七、添加存储（OSD）与内存自动调优

7.1 添加存储

让 Ceph 消费所有可用且未使用的设备：

ceph orch apply osd --all-available-devices

更详细的 OSD 部署指令参见 doc/cephadm/services/osd.rst。

7.2 启用 OSD 内存自动调优

警告：默认情况下，cephadm 在 bootstrap 时即启用osd_memory_target_autotune，并将mgr/cephadm/autotune_memory_target_ratio设置为宿主机总内存的.7（即 70%）。这适用于**纯 Ceph（hyperconverged）**部署。

若集群硬件并非由 Ceph 独占（融合/混合基础设施，converged infrastructure），应降低 Ceph 的内存占用，例如将比例调至 0.2：

# converged only: ceph config set mgr mgr/cephadm/autotune_memory_target_ratio 0.2

然后启用内存自动调优：

ceph config set osd osd_memory_target_autotune true

关于osd_memory_target_autotune的完整机制与调优指导，见 doc/cephadm/services/osd.rst#L480-L520 中的_osd_autotune章节。值得一提的源码细节是，bootstrap 阶段会在 src/cephadm/cephadm.py#L2825-L2829 自动写入osd/osd_memory_target_autotune = true，且仅当用户未在配置文件中显式设置该项时才会写入，保证用户配置优先。

八、使用 Ceph 提供的服务

集群就绪后，可按需启用各上层服务：

• Ceph Filesystem（CephFS）：见 doc/cephadm/services/mds.rst
• Ceph Object Gateway（RGW）：见 doc/cephadm/services/rgw.rst
• NFS（NFS-Ganesha）：见 doc/cephadm/services/nfs.rst
• iSCSI：见 doc/cephadm/services/iscsi.rst

九、不同部署场景（Deployment Scenarios）

9.1 单主机部署（Single Host）

在单台主机上部署 Ceph 集群时，bootstrap 需加--single-host-defaults标志。此类集群一般不适合生产环境，典型用途见 doc/rados/troubleshooting/troubleshooting-pg.rst#L19-L40 中的 one-node-cluster 说明。

该标志会自动设置以下配置项：

global/osd_crush_chooseleaf_type = 0 global/osd_pool_default_size = 2 mgr/mgr_standby_modules = False

从源码 src/cephadm/cephadm.py#L2831-L2852 可以看到这三项的实际语义：

• osd_crush_chooseleaf_type = 0：副本在OSD 之间（而非主机之间）复制，这是单机多 OSD 场景所必需的；
• osd_pool_default_size = 2：默认副本数降为 2 份（2x 副本），单机场景避免资源浪费；
• mgr_standby_modules = false：允许同一主机上共存多个 mgr（禁用 standby 模块）。关于mgr_standby_modules的说明见 doc/mgr/administrator.rst 的 mgr 管理指南。

同时，源码逻辑保证：只有当用户配置文件中尚未显式设置这些项时才会自动写入，用户自定义值永远优先。

9.2 隔离环境（Airgap / 无外网）部署

在无法直连互联网的“隔离/气隙”（airgapped）环境中部署，需要借助自定义容器 registry，可以是（1）基于 Podman 或 Docker 的非安全（insecure）registry，或（2）安全（secure）registry。

前提：确保目标容器镜像已放入 registry，且你能访问所有计划加入集群的主机。

第 1 步：运行本地容器 registry

podman run --privileged -d --name registry -p 5000:5000 -v /var/lib/registry:/var/lib/registry --restart=always registry:2

第 2 步：配置 insecure registry（若使用）

在 Podman 或 Docker 中配置该 registry 的主机名与端口。注意：每个需要访问本地 insecure registry 的主机都要重复此步骤。

第 3 步：推送容器镜像到本地 registry

可接受的镜像类型包括：

• Ceph 容器镜像（见 doc/install/containers.rst）
• Prometheus 容器镜像
• Node Exporter 容器镜像
• Grafana 容器镜像
• AlertManager 容器镜像

第 4 步：创建临时配置文件，指定监控组件镜像

cat <<EOF > initial-ceph.conf [mgr] mgr/cephadm/container_image_prometheus = <hostname>:5000/prometheus mgr/cephadm/container_image_node_exporter = <hostname>:5000/node_exporter mgr/cephadm/container_image_grafana = <hostname>:5000/grafana mgr/cephadm/container_image_alertmanager = <hostname>:5000/alertmanager EOF

监控组件镜像配置项的完整说明见 doc/cephadm/services/monitoring.rst#L187-L220。

第 5 步：用临时配置文件和--image标志执行 bootstrap

cephadm --image <hostname>:5000/ceph/ceph bootstrap --mon-ip <mon-ip> --conf initial-ceph.conf

9.3 使用自定义 SSH 密钥部署

bootstrap 允许用户提供自己的私钥/公钥对，而不是让 cephadm 自动生成。将--ssh-private-key与--ssh-public-key传给 bootstrap，两个参数都要求指向密钥文件所在路径：

cephadm bootstrap --mon-ip <ip-addr> --ssh-private-key <private-key-filepath> --ssh-public-key <public-key-filepath>

这样可以使用在 bootstrap 之前就已分发到目标主机的密钥。但要注意：为了让 cephadm 能连接计划加入集群的其他主机，必须确保该密钥对的公钥已配置为所用 SSH 用户（通常是 root）的 authorized key。非 root 用户作为 SSH 用户的更多信息见上文 3.3 节的--ssh-user。

从源码 src/cephadm/cephadm.py#L3035-L3047 可以看到这组参数的强校验逻辑：--ssh-private-key必须与--ssh-public-key（标准公钥认证）或--ssh-signed-cert（CA 签名）搭配使用，三者全不传也可；而--ssh-public-key与--ssh-signed-cert互斥。

9.4 使用 CA 签名 SSH 密钥部署

作为标准公钥认证的替代方案，cephadm 也支持CA 签名密钥部署。建议在 bootstrap 前，把 CA 公钥作为受信 CA 密钥安装到计划加入集群的主机上。以下以自建 CA 为例完整演示：

第 1 步：在 host1 生成 CA 密钥并使其受信

# 自任 CA，先生成 CA 密钥 [root@host1 ~]# ssh-keygen -t rsa -f ca-key -N "" # 在生成它的主机上让 CA 密钥受信 # 需在 /etc/sshd_config 中加一行标记该密钥为受信 [root@host1 ~]# cp ca-key.pub /etc/ssh [root@host1 ~]# vi /etc/ssh/sshd_config [root@host1 ~]# cat /etc/ssh/sshd_config | grep ca-key TrustedUserCAKeys /etc/ssh/ca-key.pub # 重启 sshd 使配置生效 [root@host1 ~]# systemctl restart sshd

第 2 步：把 CA 公钥分发到其他主机并同样配置

[root@host1 ~]# scp /etc/ssh/ca-key.pub host2:/etc/ssh/ # 在其他主机上做同样的 sshd_config 修改 [root@host2 ~]# vi /etc/ssh/sshd_config [root@host2 ~]# cat /etc/ssh/sshd_config | grep ca-key TrustedUserCAKeys /etc/ssh/ca-key.pub # 并重启 sshd [root@host2 ~]# systemctl restart sshd

第 3 步：创建主机访问密钥对并用 CA 签名

# 生成新的密钥对 [root@host1 ~]# ssh-keygen -t rsa -f cephadm-ssh-key -N "" # 对公钥签名，生成 cephadm-ssh-key-cert.pub # 此处使用用户 "root"；若用非 root 用户需相应调整 -I 与 -n 参数 # -V 参数表示证书的有效期 [root@host1 ~]# ssh-keygen -s ca-key -I user_root -n root -V +52w cephadm-ssh-key.pub [root@host1 ~]# ls ca-key ca-key.pub cephadm-ssh-key cephadm-ssh-key-cert.pub cephadm-ssh-key.pub # 验证签名密钥可用：把私钥与签名证书放同一目录，用私钥尝试 ssh [root@host1 ~]# ssh -i cephadm-ssh-key host2

第 4 步：将私钥与签名证书传给 bootstrap

[root@host1 ~]# cephadm bootstrap --mon-ip <ip-addr> --ssh-private-key cephadm-ssh-key --ssh-signed-cert cephadm-ssh-key-cert.pub

CA 签名方案的优势在于：不需要在集群节点上安装传给 bootstrap 的私钥对应的公钥。事实上，cephadm 会拒绝在传了--ssh-signed-cert的同时传--ssh-public-key——不是因为公钥会造成破坏，而是它完全不需要，这有助于 bootstrap 区分用户想要的是 CA 签名方案还是标准公钥认证方案。

这意味着SSH 密钥轮换变得极其简单：只需用同一 CA 再签一个新密钥，然后把新私钥和新签名证书交给 cephadm 即可。只要 CA 密钥作为受信密钥的初始配置完成，无论轮换多少个私钥/签名证书对，都无需再向集群节点分发任何密钥。

十、总结与延伸阅读

cephadm 的核心设计哲学是**“一条 bootstrap 命令 + 容器化守护进程”**：宿主机只需要容器运行时与 SSH，所有 Ceph 组件以容器方式由 systemd 管理，配置与密钥统一收敛在/etc/ceph，集群规模通过ceph orch编排层平滑扩展。本文所述的主机管理、监控栈、OSD 服务、升级与故障排查等内容，可继续阅读：

• 主机添加与管理：doc/cephadm/host-management.rst
• OSD 与自动调优：doc/cephadm/services/osd.rst
• 监控栈（Prometheus/Grafana/AlertManager）：doc/cephadm/services/monitoring.rst
• 日常运维：doc/cephadm/operations.rst
• 升级：doc/cephadm/upgrade.rst
• 故障排查：doc/cephadm/troubleshooting.rst
• cephadm 源码入口：src/cephadm/cephadm.py

【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/ceph