Ceph 生产环境搭建 | 第 3 天：Cephadm 部署工具详解与集群引导初始化

第 3/20 天 · Ceph 生产环境搭建系列

在上一篇中，我们完成了 Ubuntu 24.04 LTS 的内核调优与磁盘规划，为 Ceph 集群打下了坚实的系统基础。今天正式进入集群部署阶段——使用 Cephadm 工具完成集群的引导初始化。Cephadm 是自 Ceph Octopus (v15) 起官方推荐的部署管理工具，在最新的 Squid (v19) 版本中已成为绝对主力方案。理解它的设计理念与工作流程，是掌控整个 Ceph 生产集群生命周期（部署、扩容、升级、恢复）的钥匙。

一、Cephadm 架构与设计原理

1.1 为什么是 Cephadm

在 Ceph 的演进历史中，部署工具经历了多次迭代：早期是手动的 ceph-deploy，后来出现基于 Ansible 的 ceph-ansible，再到现在的 cephadm。它们的核心差异在于对 “服务生命周期管理” 的抽象方式不同。

维度	ceph-deploy	ceph-ansible	cephadm
部署模型	SSH 推送 RPM/DEB	Ansible Playbook	容器化（Podman/Docker）
服务管理	systemd 单元	systemd 单元	systemd + 容器
升级方式	手动逐节点	Playbook 驱动	编排式滚动升级
状态存储	各节点配置文件	Inventory 主机清单	集群 Mons 中的元数据
扩容体验	手动 SSH	修改 Inventory	`ceph orch` 一条命令
适用版本	Hammer~Nautilus	Jewel~Octopus	Octopus (v15) 及之后

Cephadm 的核心理念是：所有 Ceph 守护进程都以容器方式运行，由 systemd 管理容器生命周期，而集群状态（包括”哪些服务应该运行在哪些节点上”）由 Monitor 集群统一存储和仲裁。这使得部署、扩容、升级等操作都变成了对集群声明式状态的修改，由 ceph orch 编排器统一调度。

1.2 Cephadm 组件拓扑

Cephadm 的整体工作拓扑可以划分为三层：

💻 代码示例

┌─────────────────────────────────────────────────┐

│ 管理层 (CLI / Dashboard) │

│ ceph orch host add / ceph orch apply │

│ cephadm bootstrap / cephadm shell │

└──────────────────────┬──────────────────────────┘

│ 声明式状态

┌──────────────────────▼──────────────────────────┐

│ 编排层 (orchestrator / mgr module) │

│ – 解析 Service Spec │

│ – 调度守护进程到目标主机 │

│ – 驱动 cephadm CLI 在各节点执行 │

└──────────────────────┬──────────────────────────┘

│ SSH / cephadm binary

┌──────────────────────▼──────────────────────────┐

│ 节点层 (各物理/虚拟主机) │

│ systemd ──> ceph-<daemon>@<id> 服务 ││ └──> podman run ceph/daemon │

│ └──> 容器内运行 mon/mgr/osd/rgw/… │

└─────────────────────────────────────────────────┘

关键设计要点：

cephadm 二进制：一个用 Go 编写的单一可执行文件，无需依赖 Python 环境（这与旧版需要 ceph.conf + ceph 集群包的模型完全不同）。它在每个节点上以 ceph-<fsid>@<id> 形式注册为 systemd 服务，负责拉取镜像、启动容器、上报状态。
Service Spec（服务规格）：用 YAML 描述的声明式配置，例如”3 个 Monitor、3 个 Manager、每块裸盘一个 OSD”。编排器读取 Spec 后计算调度方案。
Cluster FSID：集群唯一标识（一个 UUID），在 bootstrap 阶段生成，所有守护进程容器名、systemd 单元名、数据目录都携带这个 FSID，做到多集群隔离。
MGR orchestrator 插件：ceph orch 命令的背后就是这个 Manager 模块，它是”大脑”，负责把 Spec 翻译成具体的容器调度动作。

1.3 引导（Bootstrap）的工作流程

Bootstrap 是整个集群的”第一推动力”，它在一个尚无任何 Ceph 组件的节点上完成以下事情：

生成集群 FSID（如不手动指定）。
拉取 Ceph 容器镜像并启动第一个 Monitor 容器。
生成 ceph.client.admin.keyring（管理员密钥环）。
启动第一个 Manager 守护进程。
将本机的 SSH 公钥分发到 ~/.ssh/authorized_keys，为后续向其他节点扩展做准备。
配置基础网络参数（public network / cluster network）。
（可选）启用 Ceph Dashboard Web 管理界面。

完成后，这个节点就拥有了第一个 Mon + Mgr，集群处于”最小可用”状态，后续的节点加入、OSD 创建都通过 ceph orch 完成。

二、部署实战：Cephadm 引导初始化

2.1 环境准备

假设我们有一个最小生产集群的三节点拓扑：

角色	主机名	IP (Public)	IP (Cluster)	数据盘
Mon/Mgr/OSD	ceph-node01	192.168.10.21	192.168.20.21	/dev/sdb
Mon/Mgr/OSD	ceph-node02	192.168.10.22	192.168.20.22	/dev/sdb
Mon/Mgr/OSD	ceph-node03	192.168.10.23	192.168.20.23	/dev/sdb

bootstrap 在 ceph-node01 上执行。首先安装前置依赖并获取 cephadm 工具：

💻 代码示例

# 1. 安装基础依赖（Ubuntu 24.04 LTS）

apt update && apt install -y lvm2 python3 podman curl chrony

# 2. 确认时间同步（Mon 对时钟漂移极敏感，漂移>0.05s 会触发告警）

timedatectl status

# 应输出: System clock synchronized: yes

# 3. 下载 cephadm 工具（Squid v19 稳定版）

curl –silent –remote-name –location

https://raw.githubusercontent.com/ceph/ceph/reef/src/cephadm/cephadm

chmod +x cephadm

mv cephadm /usr/local/sbin/

# 4. 验证 cephadm 可用

cephadm version

# 预期输出类似: cephadm version 19.x.x

踩坑提示：Ubuntu 24.04 默认未安装 podman，而 Ceph Squid 容器运行时默认使用 podman 而非 docker。若仅安装 docker，cephadm 会优先调用 podman，导致守护进程无法启动。务必显式安装 podman。

2.2 拉取 Ceph 容器镜像

由于生产环境往往无法直连公网 registry，建议提前在镜像仓库准备 Ceph 官方镜像，或在 bootstrap 节点提前 pull：

💻 代码示例

# 1. 查看 cephadm 默认镜像名

cephadm version

cephadm ls

# 2. 拉取 Squid (v19) 镜像

cephadm –image quay.io/ceph/ceph:v19 pull

# 3. 若使用内部 Harbor 镜像仓库，可指定镜像地址

# cephadm –image harbor.internal.corp/library/ceph:v19 pull

# 4. 验证镜像存在

podman images | grep ceph

# 预期输出:

# quay.io/ceph/ceph v19 … 约 1.2GB

镜像会通过 cephadm 的 --image 参数传递给 bootstrap。在生产环境中，强烈建议使用固定版本标签（如 v19.2.0），而非 latest，避免后续扩容时各节点拉到不同版本造成混乱。

2.3 执行 Bootstrap

以下是 bootstrap 的核心命令，包含生产环境必填的网络参数与安全参数：

💻 代码示例

# 在 ceph-node01 上执行

cephadm bootstrap

–mon-ip 192.168.10.21

–cluster-network 192.168.20.0/24

–public-network 192.168.10.0/24

–image quay.io/ceph/ceph:v19

–initial-dashboard-admin-password 'Ceph@Prod!2026#Strong'

–dashboard-password-noupdate

–allow-fqdn-hostname

–skip-monitor-stack # 若已有 Mon 可跳过，首次不跳过

注意：--skip-monitor-stack 仅在已有 Mon 的扩容场景使用。首次 bootstrap 不要加这个参数。上面示例中展示它只是为了说明含义，首次引导请去掉这一行。

命令执行后会看到类似如下输出：

💻 代码示例

Ceph Dashboard is now available at:

URL: https://ceph-node01:8443/

User: admin

Password: Ceph@Prod!2026#Strong

You can access the Ceph CLI with:

sudo /usr/local/bin/cephadm shell –fsid <fsid> -c /etc/ceph/ceph.conf -k /etc/ceph/ceph.client.admin.keyring

Bootstrap complete.

2.4 引导产出的关键文件

bootstrap 完成后，节点上会生成若干关键文件与配置：

💻 代码示例

# 1. 验证 ceph.conf 已生成

cat /etc/ceph/ceph.conf

# 内容包含: fsid / mon_host / public_network / cluster_network

# 2. 验证 admin keyring

ls -l /etc/ceph/ceph.client.admin.keyring

# -rw——- 1 root root … /etc/ceph/ceph.client.admin.keyring

# 3. 验证 SSH 公私钥（用于后续节点扩展）

ls -l /etc/ceph/ceph.pub /etc/ceph/ceph.id_rsa.pub

# 4. 查看运行中的守护进程容器

cephadm ls

# 输出 JSON，包含 mon.ceph-node01 和 mgr.ceph-node01.xxxx

# 5. 使用 cephadm shell 进入带集群配置的容器

cephadm shell

# 在容器内可直接执行:

# ceph status

# ceph health

2.5 首次状态验证

进入 cephadm shell 后执行核心状态检查命令：

💻 代码示例

# 1. 集群整体状态

ceph status

# 期望输出:

# cluster:

# id: <fsid>

# health: HEALTH_WARN <- 首次启动通常为 WARN，因为只有 1 Mon

# …

# services:

# mon: 1 daemons, quorum ceph-node01 (age 2m)

# mgr: ceph-node01.xxxx(active, since 1m)

# osd: 0 osds: 0 up, 0 in <- 尚未创建 OSD

# 2. 健康详情（诊断 WARN 原因）

ceph health detail

# 3. 查看 Mon 仲裁状态

ceph mon stat

# 预期: 1 mons

# 4. 查看 MGR 模块状态

ceph mgr module ls

# 5. 确认 Dashboard 已启用

ceph mgr module ls | grep dashboard

# 应在 enabled_modules 中看到 "dashboard"

# 6. 查看 OSD 树（此时应为空）

ceph osd tree

2.6 配置参数详解

bootstrap 生成的 /etc/ceph/ceph.conf 是一个最小化配置，关键参数含义如下：

💻 代码示例

[global]

fsid = a1b2c3d4-….-…. # 集群唯一 ID，bootstrap 生成

mon_host = 192.168.10.21 # 初始 Mon IP，后续会自动扩展

# 以下参数由 –public-network / –cluster-network 注入

public_network = 192.168.10.0/24 # 客户端访问网络

cluster_network = 192.168.20.0/24 # OSD 复制/恢复网络（分离降低抖动）

# Cephadm 会自动注入以下容器相关参数

container_image = quay.io/ceph/ceph:v19

container_registry = quay.io

# 生产环境建议显式设置（bootstrap 不会自动加）

auth_cluster_required = cephx

auth_service_required = cephx

auth_client_required = cephx, none

重要：Cephadm 模式下，大部分配置不再通过编辑 ceph.conf 生效，而是通过 ceph config set <daemon> <key> <value> 写入 Monitor 数据库，集群范围内实时生效。ceph.conf 主要保留引导期参数。修改 ceph.conf 在 cephadm 集群中效果有限，生产环境请使用 ceph config set 命令式管理。

以下是通过命令式接口调整关键参数的示例：

💻 代码示例

# 1. 设置 OSD 恢复带宽上限（避免影响前台业务）

ceph config set osd osd_recovery_op_priority 1

ceph config set osd osd_max_backfills 1

ceph config set osd osd_recovery_max_active 3

# 2. 设置 Mon 时钟漂移容忍度

ceph config set mon mon_clock_drift_allowed 0.02

# 3. 设置公共网络绑定

ceph config set global public_network 192.168.10.0/24

# 4. 查看某守护进程的运行时配置

ceph config dump | grep osd

# 5. 查看某个 OSD 的实际生效配置

ceph config show osd.0

三、生产环境注意事项与踩坑提示

3.1 容器运行时选择

Ceph Squid 默认使用 podman，但部分生产环境只装了 docker。建议显式安装 podman，并通过 --container-image 一致指定。若必须用 docker，需执行：

💻 代码示例

# 通知 cephadm 使用 docker 而非 podman

ceph config set mgr mgr/cephadm/container_engine docker

# 然后重启 mgr 守护进程

ceph mgr failover

不建议混用。混用会导致守护进程在升级时容器引擎不一致，出现”能拉镜像但起不来”的诡异错误。

3.2 SSH 密钥分发

Cephadm 通过 SSH 远程管理各节点，bootstrap 生成的 /etc/ceph/ceph.pub 必须分发到所有未来加入集群的主机。标准做法：

💻 代码示例

# 1. 将公钥拷贝到目标节点（以 ceph-node02 为例）

ssh-copy-id -f -i /etc/ceph/ceph.pub root@ceph-node02

# 2. 验证可免密登录

ssh -i /etc/ceph/ceph.id_rsa root@ceph-node02 "hostname"

# 3. 在集群中添加该主机

ceph orch host add ceph-node02 192.168.10.22

踩坑：若各节点 root 密码不同且无法用 ssh-copy-id，可手动将 ceph.pub 内容追加到目标节点 /root/.ssh/authorized_keys，但务必保证权限为 600。

3.3 镜像仓库与离线部署

生产环境通常无法直连 quay.io，建议搭建内部 Harbor 镜像仓库并预先同步：

💻 代码示例

# 1. 在 Harbor 中创建 ceph 项目

# 2. 使用 skopeo 同步镜像（无需 docker daemon）

skopeo copy –all

docker://quay.io/ceph/ceph:v19

docker://harbor.internal.corp/library/ceph:v19

# 3. bootstrap 时指定内部镜像

cephadm bootstrap

–image harbor.internal.corp/library/ceph:v19

…

离线环境下，所有后续扩容的节点都必须能拉到同一镜像。建议在每个节点提前 podman pull 好镜像，避免扩容时因网络不通而失败。

3.4 Dashboard 安全加固

bootstrap 默认启用了 Dashboard，但生产环境必须加固：

💻 代码示例

# 1. 设置强密码并锁定

ceph config set mgr mgr/dashboard/password_policy_enabled true

# 2. 启用 HTTPS（默认已启用自签证书）

# 生产建议替换为正式证书:

ceph dashboard set-ssl-certificate -i /path/to/cert.pem

ceph dashboard set-ssl-certificate-key -i /path/to/key.pem

# 3. 限制监听地址（只允许内网访问）

ceph config set mgr mgr/dashboard/server_addr 192.168.10.21

# 4. 关闭弱 TLS（默认已禁用，确认即可）

ceph config get mgr mgr/dashboard/ssl_verify

3.5 防火墙端口规划

Cephadm 启动的守护进程使用固定端口段，防火墙必须放通：

端口	协议	服务	说明
3300	TCP	Mon	新版 Mon 通信端口
6789	TCP	Mon	旧版 Mon 通信端口（兼容）
6800-7300	TCP	OSD/MGR	守护进程通信
9283	TCP	MGR	Prometheus exporter
8443	TCP	Dashboard	Web 管理
80/443	TCP	RGW	对象存储网关（后续篇）

💻 代码示例

# Ubuntu ufw 配置示例

ufw allow from 192.168.10.0/24 to any port 3300

ufw allow from 192.168.10.0/24 to any port 6789

ufw allow from 192.168.20.0/24 to any port 6800:7300 proto tcp

ufw allow from 192.168.10.0/24 to any port 8443

ufw reload

四、常见问题 FAQ

Q1：bootstrap 报错 “Failed to pull container image”

原因：节点无法访问 quay.io，或镜像名拼写错误。

解决：

💻 代码示例

# 1. 手动验证镜像可拉取

podman pull quay.io/ceph/ceph:v19

# 2. 若网络不通，使用本地镜像或内部仓库

cephadm bootstrap –image harbor.internal.corp/library/ceph:v19 …

# 3. 若完全离线，先用 skopeo 离线导入镜像到本地存储

skopeo copy –all

oci-archive:/data/ceph-v19.oci.tar

containers-storage:quay.io/ceph/ceph:v19

Q2：ceph status 显示 HEALTH_WARN，提示 “mon is allowing insecure global_id reclaim”

原因：Ceph 安全策略默认禁用了旧版不安全的 global_id 回收机制。

解决：生产环境不应关闭该安全特性。确认所有客户端均为新版本即可。若必须兼容旧客户端（不推荐）：

💻 代码示例

ceph config set mon mon_warn_on_insecure_global_id_reclaim_allowed false

# 仅作告警抑制，不真正放开安全限制

Q3：bootstrap 后 ceph 命令报 “unable to find keyring”

原因：admin keyring 未被拷贝到 /etc/ceph/ 或权限不对。

解决：

💻 代码示例

# 1. 通过 cephadm shell 操作（自动挂载配置）

cephadm shell — ceph status

# 2. 或手动拷贝 keyring（注意权限）

cp /var/lib/ceph/bootstrap/ceph.client.admin.keyring /etc/ceph/

chmod 600 /etc/ceph/ceph.client.admin.keyring

# 3. 验证

ceph -s

五、总结

本篇系统讲解了 Cephadm 的设计理念：以容器为核心、以声明式 Spec 为驱动、以 Monitor 元数据为单一真相源。我们完成了集群的 bootstrap 初始化，得到了第一个 Mon + Mgr 守护进程，并通过 ceph config set 了解了命令式配置管理的生产实践。关键要点：