wiki/存储/Ceph/知识库/00-Ceph-总览与快速上手.md

基于 Ceph 官方文档整理 | 文档版本：Tentacle v20.2.4 | 抓取日期：2026-09-17 | 源文：ceph/ceph@v20.2.4 doc/ 官网入口：https://docs.ceph.com/en/tentacle/

第 00 册 · Ceph 总览与快速上手

---

本册导读

本册是整套《Ceph 中文学习手册》的入口分册，回答三个问题：Ceph 是什么、怎么装、装完怎么确认它活着。

1. 本册覆盖的官方页面（共 22 页主输入）

#	官方页面（rst 相对路径）	逻辑页名	本册用途
1	index.rst	index	一句话定义、三种存储接口特性清单
2	foundation.rst	foundation	Ceph 基金会、会员等级、理事会
3	governance.rst	governance	社区治理结构（执行委员会 / 指导委员会 / 组件负责人）
4	start/index.rst	start/index	最小集群构成、五类守护进程职责
5	start/beginners-guide.rst	start/beginners-guide	面向新人的概念拆解、vstart 开发集群
6	start/hardware-recommendations.rst	start/hardware-recommendations	CPU/RAM/磁盘/网络建议、最低配置表
7	start/os-recommendations.rst	start/os-recommendations	内核要求、发行版支持矩阵、容器宿主矩阵
8	start/quick-rbd.rst	start/quick-rbd	块设备 5 分钟上手
9	start/get-involved.rst	start/get-involved	社区渠道（邮件列表 / IRC / Slack / Bug Tracker）
10	start/documenting-ceph.rst	start/documenting-ceph	文档贡献流程（本册只在"后续路径"引用）
11	install/index.rst	install/index	安装方式总览与推荐度
12	install/index_manual.rst	install/index_manual	手工安装索引树
13	install/get-packages.rst	install/get-packages	三种取包方式、仓库配置、镜像
14	install/get-tarballs.rst	install/get-tarballs	源码 tarball 下载
15	install/clone-source.rst	install/clone-source	克隆源码、子模块、分支选择
16	install/build-ceph.rst	install/build-ceph	从源码编译、打 deb/rpm 包
17	install/containers.rst	install/containers	官方容器镜像与 tag 语义
18	install/install-storage-cluster.rst	install/install-storage-cluster	APT/RPM 安装命令、优先级配置
19	install/install-vm-cloud.rst	install/install-vm-cloud	QEMU / libvirt 安装（云与虚拟化后端）
20	install/manual-deployment.rst	install/manual-deployment	纯手工部署 MON/OSD/MDS/RGW 全流程
21	install/manual-freebsd-deployment.rst	install/manual-freebsd-deployment	FreeBSD 上的手工部署差异
22	install/mirrors.rst	install/mirrors	全球镜像站、自建镜像规范

辅助引用（跨册但不展开）：releases/general.rst、releases/index.rst（第 03 章版本机制）、cephadm/install.rst（第 06 章快速上手主流程）、architecture.rst（第 02 章概念全景）。

2. 建议阅读顺序

1. 零基础读者：第 01 章 → 第 02 章 → 第 06 章 → 第 07 章。先建立概念，再跑通一个集群，最后学会判健康。
2. 要上生产的规划者：第 01 章 → 第 03 章（选版本）→ 第 04 章（盘硬件/OS）→ 第 05 章（选安装方式）→ 第 06/07 章。
3. 已有集群要排查的人：直接跳第 07 章（健康检查），再回第 02 章补齐组件交互模型。
4. 要参与社区/二次开发的人：第 08 章 → 第 09 章 → 第 05 章的"源码编译"分支。

3. 本册约定

• 命令、参数名、配置项、文件路径、默认值一律保留英文原文，不做翻译。
• 凡官方文档未写明、由本手册作者补充的经验，统一用 > 💡 补充： 标注。
• 凡官方文档本身没说清的点，统一收集到文末 ## 文档未明确项，不臆造数值。

引自：Welcome to Ceph

---

一、Ceph 是什么

1.1 一句话定义

Ceph delivers object, block, and file storage in one unified system. Ceph 在一个统一的系统里同时提供对象存储、块存储和文件存储。

官方首页紧接着给出三个定性词：highly reliable（高度可靠）、easy to manage（易于管理）、free（免费）。

拆开看这三个词在 Ceph 语境里的含义：

定性	官方如何支撑这个说法
高度可靠	数据以 RADOS object 形式存于逻辑 pool，副本数/纠删码策略在 pool 级别定义；OSD 之间互相心跳检测；MON 以 quorum（多数派）方式维持集群地图
易于管理	由 ceph-mgr 承载 dashboard、Prometheus 等模块；cephadm 提供 ceph orch 编排 API；配置可通过 ceph config 运行期下发
免费	开源项目，由 Ceph 基金会（Linux 基金会下属定向基金）支撑，见第 08 章

1.2 Ceph 解决什么问题

start/beginners-guide.rst 给了一个很朴素的解释：

Ceph is a computer program that stores data and uses a network to make sure that there is a backup copy of the data. Ceph 是一个存储数据的程序，并且利用网络确保数据存在一份备份副本。

拆成四个关键词（官方原文逐词解释）：

关键词	官方解释的要点	为什么需要
Storage Manager（存储管理器）	帮助存储资源（HDD、SSD、磁带等）存数据的软件	把裸设备的容量、IO、故障管理抽象成可消费的服务
Clustered（集群化）	不只装在单机上，而是装在若干台协同工作的机器上	单机容量与可靠性都有天花板
Distributed（分布式）	数据与支撑它的基础设施分散在多台机器，不是集中式	官方特别对比：它不是 iSCSI 那种"一个逻辑盘 1:1 映射暴露到网络"的系统
Data Redundancy（数据冗余）	在别处再放一份数据副本	单盘/单机故障时不丢数据

一句话总结 Ceph 的价值主张：用廉价通用硬件（commodity hardware）搭建 PB 级甚至 EB 级的存储池，且扩容、再平衡、故障恢复都由集群自己动态完成。

1.3 三种存储接口：特点与适用场景

官方首页用三栏并列给出了每个接口的能力清单，下表逐条转述：

（1）Ceph Object Store — 对象存储（radosgw，RGW）

官方列出的能力：

• RESTful Interface
• S3- and Swift-compliant APIs
• S3-style subdomains
• Unified S3/Swift namespace
• User management
• Usage tracking
• Striped objects
• Cloud solution integration
• Multi-site deployment
• Multi-site replication

维度	说明
是什么	通过 ceph-radosgw 守护进程提供的 RESTful 网关，把 RADOS 暴露成 S3 / Swift 兼容 API
典型场景	云原生应用的对象存储、备份归档、静态资源、数据湖；需要多站点（multisite）复制的地域级容灾
关键卖点	同一命名空间同时支持 S3 与 Swift；内建用户管理与用量统计（usage tracking）；支持多站点部署与多站点复制
注意	RGW 的 index/log pool 对介质要求高，官方建议放 SSD（见第 04 章）

（2）Ceph Block Device — 块设备（rbd，RBD）

官方列出的能力：

• Thin-provisioned
• Images up to 16 exabytes
• Configurable striping
• In-memory caching
• Snapshots
• Copy-on-write cloning
• Kernel driver support
• KVM/libvirt support
• Back-end for cloud solutions
• Incremental backup
• Disaster recovery (multisite asynchronous replication)

维度	说明
是什么	RADOS Block Device，把 RADOS 对象模拟成块设备镜像（image）
典型场景	虚拟机云盘（OpenStack / CloudStack / OpenNebula / Kubernetes）、数据库裸盘、需要快照与克隆的卷
关键卖点	精简置备、单个 image 最大 16 EB、快照 + 写时复制克隆、内核驱动与 KVM/libvirt 原生支持、增量备份、跨站点异步复制做容灾
注意	块设备 quick start 明确要求：操作前集群必须处于 active + clean 状态；ceph-client 节点不要与存储集群节点共用同一台物理机（用 VM 除外）

（3）Ceph File System — 文件系统（cephfs，CephFS）

官方列出的能力：

• POSIX-compliant semantics
• Separates metadata from data
• Dynamic rebalancing
• Subdirectory snapshots
• Configurable striping
• Kernel driver support
• FUSE support
• NFS/CIFS deployable
• Use with Hadoop (replace HDFS)

维度	说明
是什么	符合 POSIX 语义的分布式文件系统，元数据由 MDS 单独管理
典型场景	共享目录、HPC 与大数据分析（官方点名可替换 HDFS）、需要 NFS/CIFS 导出的传统应用
关键卖点	元数据与数据分离（这是 Ceph 加速 CephFS 的核心手段）、动态再平衡、子目录快照、内核驱动 + FUSE 双挂载方式
注意	MDS 是 CPU 密集型且单线程，选型看主频而非核数（见第 04 章）；元数据 pool 建议只用 SSD 介质

（4）三种接口的统一底座

start/beginners-guide.rst 有一句非常关键的话：

Deep down, though, all three of these are really RADOS object stores. CephFS and RBD are just presenting themselves as file systems and block devices. 说到底这三者其实都是 RADOS 对象存储，CephFS 和 RBD 只是把自己"伪装"成文件系统和块设备而已。

这句话是理解整个 Ceph 的钥匙：上层接口可变，底座永远是 RADOS。这也解释了为什么一个集群能同时跑三种接口，以及为什么调优的落脚点大多在 pool / PG / CRUSH / OSD 这一层。

1.4 什么情况不该用 Ceph

⚠️ 官方立场：本册范围内（index / start / install / foundation / governance）官方文档没有给出任何"不推荐使用 Ceph"的场景清单。 下面全部是本手册的经验性补充，官方原文中不存在对应表述，请按经验而非官方承诺对待。

💡 补充：以下为经验判断，非官方文档内容。

场景	为什么可能不合适	依据（来自本册范围内的官方表述）
只有 1~2 台机器、容量 < 几十 TB 的小团队	Ceph 的最小可用形态就需要 1 MON + 1 MGR + 多 OSD，且 OSD 数量不能少于对象副本数；固定运维成本高	start/index.rst 明确"至少需要 OSD 数量 ≥ 对象副本数"
单机本地盘延迟敏感型负载（如单实例 OLTP 数据库本地盘）	所有读写都要过网络与 RADOS 层，无法达到本地 NVMe 的延迟	官方强调 Ceph 是 "clustered and distributed"，且明确区别于 iSCSI 的 1:1 映射
只有 1 Gb/s 网络的环境	官方算出 1 Gb/s 下复制 1 TiB 需要 3 小时、10 TiB 需要 30 小时；恢复窗口过长会放大风险	start/hardware-recommendations.rst "Speed" 节
需要 Windows Server 原生生产级客户端	官方明确 Windows 客户端是 "best effort"，无全职维护者，未来不确定（截至 2025 年 7 月无移除计划）	start/os-recommendations.rst
强依赖 SMB 服务且使用 ARM 架构	官方注明截至 2025 年 12 月 ARM 架构容器只提供有限的守护进程集合，SMB 服务尚不支持	start/hardware-recommendations.rst 顶部 important 块
想拿便宜消费级 SSD 跑生产	官方明确警告消费级/杂牌 SSD 是"虚假经济"（false economy），会 cliffing（缓外性能断崖），且缺少掉电保护 PLP	start/hardware-recommendations.rst "Solid State Drives" 节

引自：Welcome to Ceph

---

二、核心概念全景图

2.1 组件 → 职责 → 交互（主表）

下表把"守护进程 / 逻辑概念 / 工具"三层放在一起。守护进程行来自 start/index.rst 与 install/manual-deployment.rst，逻辑概念行来自 architecture.rst 与 start/beginners-guide.rst。

A. 守护进程层

组件	守护进程 / 可执行文件	职责（官方原文要点）	与谁交互	数量建议（官方原文）
MON	ceph-mon（Ceph Monitor）	维护集群状态地图：monitor map、manager map、OSD map、MDS map、CRUSH map；负责守护进程与客户端之间的认证	向客户端与所有守护进程提供 cluster map；OSD 向 MON 报告自身与同伴 OSD 的状态	"At least three monitors are normally required for redundancy and high availability"；三个 MON 才能形成 quorum（quorum = 多数派 MON 处于 up）
MGR	ceph-mgr（Ceph Manager）	跟踪运行时指标与集群当前状态：存储利用率、性能指标、系统负载；托管 Python 模块（含 Web Dashboard）	从 OSD/MON 收集指标；对外暴露 dashboard / Prometheus 等模块端点	"At least two managers are normally required for high availability"；最佳实践是每个 MON 配一个 MGR（非强制）
OSD	ceph-osd（Ceph Object Storage Daemon）	存数据；处理数据复制、恢复、再平衡；通过检查其他 OSD 的心跳向 MON 和 MGR 汇报监控信息	与 peer OSD 心跳与复制；向 MON/MGR 汇报	"At least three Ceph OSDs are normally required for redundancy and high availability"；且 OSD 数 ≥ 对象副本数
MDS	ceph-mds（Ceph Metadata Server）	为 CephFS 存储元数据；让用户跑 ls、find 等基础命令时不给存储集群添负担	只服务 CephFS 客户端；元数据写在独立的 metadata pool	运行 CephFS 客户端时必需
RGW	ceph-radosgw（Ceph Object Gateway）	在应用与 Ceph 存储集群之间提供 RESTful 网关	前端接应用（S3/Swift API），后端走 RADOS	若资源充足，RGW 可与 MON/MGR 同机部署
RBD client	内核 rbd 驱动 / librbd / librados	把 RADOS 对象映射为块设备；librbd 经 librados 访问集群	通过 librados 与 OSD、MON 通信；QEMU/KVM 经 librbd 使用 RBD	属于客户端，不计入集群守护进程配额
cephadm	cephadm（编排工具）	引导（bootstrap）新集群、纳管主机、部署并管理各服务守护进程的生命周期	通过 SSH 登录各主机；通过容器运行时（Podman/Docker）拉起守护进程容器	每个集群一套；需 Python 3、systemd、Podman/Docker、时间同步、LVM2

B. 逻辑概念层

概念	是什么	为什么需要	与谁关联
RADOS	Reliable Autonomic Distributed Object Store，可靠、自治的分布式对象存储，是整个 Ceph 存储集群的底座	用"每个节点自带的智能"来保证数据安全并提供给客户端；是三种接口（对象/块/文件）的共同底座	由 OSD + MON + MGR 共同实现
object（对象）	Ceph 存储集群收到数据后，一律存成 RADOS object。每个 object = 标识符（ID）+ 二进制数据 + 由 name/value 对组成的元数据	统一了上层三种接口的数据模型；对象 ID 在整个集群内唯一，而非只在本地文件系统内唯一	存在 OSD 上；OSD 在扁平命名空间（flat namespace，无目录层级）中存放对象
pool（存储池）	一个逻辑分区抽象，可被指定为 replicated（副本） 或 erasure coded（纠删码）。Ceph 的数据保护方式在 pool 级别设定，只支持这两种	让不同业务（如 CephFS 元数据、RGW index、RBD 卷）用不同的冗余策略与 CRUSH 规则	对象存在 pool 中；pool 内包含 PG
PG（Placement Group，归置组）	pool 的一部分；CRUSH 先算出对象应落在哪个 PG，再算出这个 PG 应由哪个 OSD 存放	把海量对象的寻址开销收敛到有限个 PG 上，使集群可扩展、再平衡、动态恢复	PG 属于 pool；PG 映射到 OSD
CRUSH	Controlled Replication Under Scalable Hashing 算法	客户端和 OSD 都用它计算对象位置，不依赖中心查找表，从而消除中心化瓶颈与单点故障	输入是 cluster map（尤其 CRUSH map）+ 对象 ID + pool，输出是 OSD
cluster map（集群地图）	由 5 张 map 组成的集合：Monitor Map、OSD Map、PG Map、CRUSH Map、MDS Map。MON 保存主副本	客户端与 OSD 必须有最新的拓扑信息才能正常工作；每张 map 都维护自身运行状态变更历史	由 MON 分发给客户端与 OSD

C. 数据写入路径（一次写入发生了什么）

应用/客户端
   │  (RBD: librbd → librados / RGW: S3 API / CephFS: kernel or FUSE)
   ▼
RADOS：对象 = ID + 二进制数据 + 元数据(name/value)
   │  ① 确定目标 pool（pool 决定 replicated 还是 erasure coded）
   │  ② CRUSH 计算：object → PG
   │  ③ CRUSH 计算：PG → 一组 OSD（依据 CRUSH map 的故障域层级与规则）
   ▼
OSD（通常一块盘一个 OSD，默认 BlueStore 后端）
   │  ④ 主 OSD 负责复制到副本 OSD；心跳检测 peer OSD
   ▼
MON 记录 cluster map 变更；MGR 采集指标

2.2 五张 map 速查（含查看命令）

来自 architecture.rst "Cluster Map" 一节，命令为官方原文给出：

Map	内容（官方要点）	查看命令
Monitor Map	集群 fsid、每个 monitor 的位置、名称、地址与 TCP 端口；当前 epoch、创建时间、最后修改时间	ceph mon dump
OSD Map	集群 fsid、创建与修改时间、pool 列表、副本大小列表、PG 编号列表、OSD 及其状态（如 up、in）	ceph osd dump
PG Map	PG 版本、时间戳、最后的 OSD map epoch、full ratios、每个 PG 的详情：PG ID、Up Set、Acting Set、PG 状态（如 active + clean）、各 pool 的数据使用统计	官方未在本册范围内给出单一命令（见"文档未明确项"）
CRUSH Map	存储设备列表、故障域层级（如 device、host、rack、row、room）、以及存数据时遍历该层级的规则	ceph osd getcrushmap -o {filename} 导出，再 crushtool -d {comp-crushmap-filename} -o {decomp-crushmap-filename} 反编译，然后用编辑器或 cat 查看
MDS Map	当前 MDS map epoch、创建时间、最后变更时间；存放元数据的 pool、元数据服务器列表、哪些 MDS 是 up 和 in	ceph fs dump

2.3 最小集群构成（官方硬约束）

start/index.rst 的原文约束，逐条列出：

1. 至少一个 Ceph Monitor（ceph-mon）。
2. 至少一个 Ceph Manager（ceph-mgr）——最佳实践是每个 MON 配一个 MGR，但不强制。
3. OSD 数量 ≥ 对象在集群中的副本数。官方举例：如果存 3 份副本，则集群至少要有 3 个 OSD。
4. 运行 CephFS 客户端时必须有 MDS，否则不需要。
5. 所有 Ceph 存储集群部署都从"设置每个 Ceph 节点"和"设置网络"开始。

💡 补充：把上面第 1、3 条与高可用建议合并看——一个"能上生产"的最小形态实为 3 MON + 2 MGR + 3 OSD（来自各组件自己的 HA 建议），而"能跑起来"的最小形态是 1 MON + 1 MGR + 1 OSD（单副本）。官方文档没有把这两个数字并排写在一处，此处为归并推断。

引自：Intro to Ceph

---

三、版本与发布机制

本章内容来自 releases/general.rst 与 releases/index.rst（两页不属于本册主输入清单，但第 00 册需要交代版本，故在此讲透）。

3.1 发布节奏

规则	官方原文要点
起点	从 Nautilus（14.2.0） 开始，每年有一个新的稳定发布周期，目标月份是 3 月
命名	每个稳定发布系列有一个名字（如 Mimic），取自**头足纲动物（cephalopod）**的一个物种，通常用俗名（拉丁名难记难读）
主版本号由来	主版本号来自名字首字母在字母表中的序号，如 Mimic 的 M 是第 13 个字母，所以是 13

3.2 版本号 x.y.z 的含义

段位	含义
x	发布周期（release cycle），如 13 代表 Mimic
y	发布类型：x.0.z = 开发版本；x.1.z = 发布候选（RC，给测试集群和勇敢的用户）；x.2.z = 稳定/缺陷修复版本（给用户）
z	该系列内的递增修订号

套用到本手册：Tentacle = 20.2.4，T 是第 20 个字母 → x=20；2 → 稳定/缺陷修复系列；4 → 该系列的第 4 个修订。

3.3 发布候选（x.1.z）与稳定版（x.2.z）

类型	节奏	定位	附加规则
Release candidate（x.1.z）	每 1–2 周一个 RC；在计划的首个稳定版发布前约 2 个月进入 feature freeze（功能冻结），此后只做稳定化与缺陷修复	用于最终测试与验证即将到来的稳定版	—
Stable（x.2.z）	稳定修订版每 4–6 周一个	面向生产部署	缺陷修复向后移植覆盖 2 个完整发布周期（2 年）；支持从最近两个稳定发布系列在线滚动升级（自 Luminous 起）；支持从先前的稳定修订版在线滚动升级

每个稳定版本还配套：定期运行的集成与升级测试（qa/suites）、由开发者分析的测试结果、master 分支上已修复 issue 的回溯排期、stable releases and backport team 发布的 point release。

3.4 生命周期与 EOL 策略

• 一个稳定发布系列的生命周期约为 24 个月（2 个 12 个月的发布周期），从该系列首次发布的那个月起算。
• 具体时长会因稳定版实际发布节奏而浮动。
• 官方举例：Mimic（13.2.z）在 Octopus（15.2.0）发布后不久 EOL。

3.5 Active 与 Archived 版本

releases/index.rst 把版本分成两类：

分类	定义	当前列出的版本（官方原文）
Active Releases	仍在积极维护，会周期性接收 backport 与安全修复	Squid (v19.2.*)、Reef (v18.2.*)
Archived Releases	更旧的版本，已不再维护（不再接收缺陷修复或 backport）	Quincy、Pacific、Octopus、Nautilus、Mimic、Luminous、Kraken、Jewel、Infernalis、Hammer、Giant、Firefly、Emperor、Dumpling、Cuttlefish、Bobtail、Argonaut（共 17 个）

⚠️ 矛盾点（必读）：本手册锁定的是 Tentacle v20.2.4，且 start/os-recommendations.rst 的平台支持表里 Tentacle（20.2.z）已作为一列出现；但 releases/index.rst 的 Active Releases 列表里只有 Squid 和 Reef，没有 Tentacle。这说明 releases 索引页相对本版本落后（详见文末"文档未明确项"）。选版本时请以官网 Active Releases 页面实时状态为准，不要以本表为准。

3.6 如何选版本（决策表）

💡 补充：官方没有给出"如何选版本"的明确决策流程，下表是基于 3.3–3.5 的官方规则做的经验性归并。

你的身份	建议	依据
新建生产集群	选当时 Active Releases 中最新的稳定系列，且直接取该系列最新的 x.2.z	x.2.z 是官方标注"Intended for production deployments"的类型；稳定修订每 4–6 周一版
已有生产集群（落后 1 个系列）	规划滚动升级到最新 Active 系列	官方支持"从最近两个稳定发布系列在线滚动升级"
已有生产集群（落后 ≥3 个系列）	不能一步跳，需按系列逐级升级，且要查目标系列的 upgrade 文档	滚动升级支持只覆盖最近两个系列
想在上线前验证新特性	用 x.1.z RC 搭测试集群	RC 官方定位就是"测试集群与勇敢用户"
想跟最新代码/做开发	用 main 分支源码编译	install/clone-source.rst：main 是不稳定的开发分支

3.7 源码分支与版本的关系

install/clone-source.rst "Choose a Branch" 一节给出三个分支语义：

分支名	含义
main	不稳定的开发分支（unstable development branch）
stable-release-name	稳定的 Active Release 名字，例如 Pacific
next	发布候选分支（release candidate branch）

克隆后默认就在 main 分支：

git checkout main

引自：Ceph Releases (general)

---

四、安装前准备

4.1 硬件建议总览

start/hardware-recommendations.rst 开篇就定了调：

Ceph is designed to run on commodity hardware（Ceph 设计运行在通用商用硬件上），这让构建和维护 PB 级数据集群既灵活又经济。

规划时要平衡三件事：故障域（failure domains）、成本（cost）、性能（performance）。两条通用原则：

1. 把 Ceph 守护进程和其他使用 Ceph 的进程分散到多台主机上；一般建议"为某一类守护进程专门配置主机"。
2. 使用数据集群的上层进程（OpenStack、OpenNebula、CloudStack、Kubernetes 等）应跑在独立主机上。

⚠️ 重要提示（官方原文）：截至 2025 年 12 月，ARM 架构的容器只提供有限的守护进程集合，例如 SMB 服务尚不支持。

4.1.1 CPU

角色	官方建议
MDS	CPU 密集型、单线程，因此**高主频（GHz）**比多核更重要；除非同机还托管其他服务（如 CephFS 元数据 pool 的 SSD OSD），否则不需要很多核
OSD	需要足够算力来跑 RADOS 服务、用 CRUSH 计算数据放置、复制数据、维护自己的 cluster map 副本
MON / MGR	CPU 需求不高， modest processor 即可。若同机还跑 OpenStack Nova 之类的 CPU 密集进程，建议把它们挪到别的主机，避免资源争用
RGW	若节点资源充足，RGW 守护进程可以与 MON、MGR 同机

核心指标的变化（官方明确说明）：早期 Ceph 版本按"每 OSD 核数"给建议，但这个指标已不再那么有用；现在更该看 cycles per IOP（每 IOP 的周期数） 和 IOPS per OSD。举例：NVMe OSD 在真实集群中可轻松吃满五六个核，在单 OSD 隔离测试中甚至能用到约十四个核。所以选型时按"每核 IOPS"来挑。

💡 补充：官方这里的"核（core）"在开启超线程时指的是线程（thread）；官方明确说超线程对 Ceph 服务器通常是有益的。

4.1.2 RAM

总原则：内存越大越好（more RAM is better）。

场景	官方建议值
中等规模集群的 MON/MGR 节点	64 GB 够用
数百个 OSD 的大集群	建议 128 GB
非常小的集群	32 GB 足够
最多约 300 个 OSD 的集群	64 GB
更大规模 / 还会继续增长的集群	配置 128 GB

OSD 内存（BlueStore 专用，关键）：

• BlueStore 用自己的内存做缓存，不依赖操作系统 page cache；通过 osd_memory_target 调整 OSD 尝试消耗的内存量。
• 官方建议：确保服务器总 RAM > (OSD 数量 × osd_memory_target × 2)，多出来的余量留给操作系统和其他 Ceph 守护进程。
• 举例：一台 1U 服务器带 8–10 个 OSD，配 128 GB 物理内存是"well-provisioned"的。
• 开启 osd_memory_target_autotune 有助于在高负载下、或非 OSD 守护进程迁到本节点时避免 OOM。
• 对 HDD OSD，有效的 osd_memory_target 至少 6 GiB 有助于缓解 slow requests。

osd_memory_target 取值档位（官方逐档说明）：

取值	官方评价
< 2 GB	不推荐。Ceph 可能无法把内存占用压到 2 GB 以下，且极可能出现极慢的性能
2 GB ~ 4 GB	通常能跑，但性能可能下降：除非活跃数据集较小，否则 IO 时可能需要从磁盘读元数据
4 GB	当前默认值。为典型用例选择，意在平衡 RAM 成本与 OSD 性能
> 4 GB	当存在大量小对象、或处理大（每个 OSD 256 GB 或更多）数据集时可提升性能；在高速 NVMe OSD 上尤其明显

⚠️ 重要（官方原文）：OSD 内存管理是 best effort（尽力而为）。OSD 可以 unmap 内存让内核回收，但无法保证内核在特定时间内真的回收——尤其是老版本 Ceph 中透明大页（transparent huge pages）会阻止内核回收从碎片化大页中释放的内存。现代 Ceph 在应用层禁用了透明大页，但这仍不保证内核会立即回收。OSD 仍可能在某些时刻超出内存目标。官方建议：至少多预留 20% 内存，防止 OSD 在临时峰值或内核回收延迟期间 OOM。这个 20% 可能偏多也可能偏少，取决于具体配置。

其他两点：

• 不建议使用 swap：现代系统上为守护进程配置 swap 提供额外虚拟内存不被建议——可能降低性能，而且"一个崩溃的守护进程"往往比"一个慢到爬行的守护进程"对整个集群更友好。
• 旧 Filestore 后端使用 OS page cache 缓存数据，通常无需调优；BlueStore 不用 page cache，因此推荐使用 autotuner，确保 RAM 被充分且审慎地利用。
• MON/MGR 可考虑调优 mon_osd_cache_size 与 rocksdb_cache_size。
• MDS：内存占用取决于其缓存配置大小，官方建议最小值 1 GiB（见 mds_cache_memory_limit）。

4.1.3 数据存储

建议	官方原文要点
最小 OSD 容量	建议最小 1 TiB。比这小很多的话元数据会占用相当比例的容量；小于 100 GiB 的盘完全没有效果
SSD 强制场景	强烈建议（strongly suggested）至少为运行或可能运行 MON / MGR 的主机配备企业级 SSD
其他必须 SSD 的 pool	CephFS 元数据 pool、RGW 的 index pool 与 log pool——即便批量 OSD 数据用 HDD，这些 pool 也需要 SSD 才能在企业级规模下有效工作。RGW 部署尤其要注意：如果批量 bucket 数据用 HDD，那么其他所有 pool 都应放在 SSD 上
分离到不同物理盘的三样东西	① 操作系统 ② OSD 数据 ③ BlueStore WAL+DB（针对 HDD OSD）

HDD 注意事项（官方 tips 汇总）：

条目	官方结论
单块 SAS/SATA HDD 上放多个 OSD	NOT a good idea。除"大于 30 TB 的 SSD"这种例外，任何介质上一块盘应只配一个 OSD
OSD 与 MON/MGR/MDS 数据同盘	NOT a good idea
大容量 HDD 的接口瓶颈	SAS/SATA 接口在容量变大时越来越成为瓶颈；服务器背板的 expander 也常是性能瓶颈（尤其 24、36 甚至 100 盘的密集机箱）
前瞻性	SAS 与 SATA SSD 正在从厂商路线图上消失；三模（tri-mode）HBA 昂贵且挑剔；LFF（3.5"）机箱用适配器装 SFF（2.5"）盘空间效率低
32 TB HDD 的困境	今天的 32 TB HDD 用的还是 2014 年 3 TB HDD 就已经是瓶颈的那条 SATA 接口——数据多了十倍，通道还是一条。官方比喻：三层楼一部电梯 vs 三十二层楼还是一部电梯
结论	用 HDD 做 OSD 时，大于 8 TB 的盘可能最适合存放完全不关心性能的大文件/大对象；大规模部署中，算上机箱管理与机房空间后，SSD 的 TCO 常常更低

SSD 注意事项：

条目	官方结论
收益	随机访问时间与延迟显著降低、吞吐提高；访问时间至少比 HDD 快 100 倍；避免热点与瓶颈；按"每 IOPS 的摊销盘成本"算 SSD 更便宜；再平衡/恢复更快，从而缩短故障后的高风险窗口
投资前必做	强烈建议先审阅 SSD 性能指标，并在测试配置中实测
消费级/杂牌 SSD	false economy（虚假经济）。可能出现 cliffing——初始爆发后，一旦有限缓存写满，持续性能大幅下滑
耐久性	标称 0.3 DWPD 的盘对"顺序写入、读多写少"的 OSD 可以，但不适合给几百台 VM 服务的 RBD pool
企业级 SSD	最好：具备掉电保护（PLP），不会出现消费级（桌面级）型号那种剧烈 cliffing
OS + MON/MGR 共用的单盘（或镜像对）	最小 256 GB，建议至少 960 GB；建议选 1+ DWPD 或等效 TBW 的型号。工作负载一定时，比技术需求更大的 SSD 反而更耐用（等效超配更多）
QLC SSD	正在缩小与 HDD 的成本差距：密度更高、功耗更低、制冷耗电更少
HDD OSD 卸载 WAL+DB	可显著改善写延迟；多数 Ceph OSD 部署不需要超过 1 DWPD（"read-optimized"）的 SSD；3 DWPD 的 "mixed-use" SSD 常属过度配置且贵得多

分区对齐：SSD 上若分区，必须正确对齐；未对齐会降低性能与耐久性。（官方链接到 Werner Fischer 的分区对齐博文，本册不展开。）

CephFS 元数据分离：Ceph 通过把 CephFS 元数据与文件内容分开存储来加速 CephFS。Ceph 提供了默认的 metadata pool，你永远不必手工为 CephFS 元数据创建 pool；但你应该为 CephFS 元数据 pool 创建只包含 SSD 介质的 CRUSH map 层级（参见 CRUSH Device Class）。

控制器（HBA）：

条目	官方结论
建议	仔细选型，确保 HBA 不成为写吞吐瓶颈。RAID 模式（IR）HBA 的延迟可能高于更简单的 JBOD（IT）模式 HBA
是否需要 RAID 卡	不需要 RoC（RAID 能力）HBA。ZFS 或 Linux MD 软件镜像足够保障启动卷可靠性
成本	一张高端 RAID HBA + 板载缓存 + BBU/超级电容，打折后也轻易超过 1000 美元；用 NVMe SSD 时根本不需要任何 HBA
维护	免 HBA 的系统在买年度维保或延保时，每年可能再省几百美元

基准测试（官方给出的唯一具体命令）：

BlueStore 以 O_DIRECT 打开存储设备并频繁发起 fsync() 以确保数据落盘。可用 fio 评估盘的底层写性能，例如测 4 KiB 随机写：

# fio --name=/dev/sdX --ioengine=libaio --direct=1 --fsync=1 --readwrite=randwrite --blocksize=4k --runtime=300

写缓存（Write Caches）：

企业级盘带掉电保护与多级缓存，可在两种模式间切换：易失性缓存 + fsync 刷盘（Linux 用 "write back" 模式）或非易失性缓存同步写（"write through"）。两者通过启用/禁用易失性写缓存来切换。

• HDD 的默认配置（通常是启用缓存）可能并非最优；禁用写缓存可显著提升 OSD 性能（更高 IOPS、更低 commit latency）。
• 官方鼓励：先用 fio 实测，再持久化最优缓存配置。
• 查询方式（hdparm / sdparm / smartctl / sysfs）：

# hdparm -W /dev/sda
/dev/sda:
 write-caching =  1 (on)

# sdparm --get WCE /dev/sda
    /dev/sda: ATA       TOSHIBA MG07ACA1  0101
WCE           1  [cha: y]

# smartctl -g wcache /dev/sda
Write cache is:   Enabled

# cat /sys/class/scsi_disk/0\:0\:0\:0/cache_type
write back

• 禁用方式：

# hdparm -W0 /dev/sda
# sdparm --clear WCE /dev/sda
# smartctl -s wcache,off /dev/sda

• 若禁用后 cache_type 没有自动变成 "write through"，可直接写 sysfs（注意：部分盘每次重启都要重设，需确认能持久化）：

# echo "write through" > /sys/class/scsi_disk/0\:0\:0\:0/cache_type

• 批量设置的 udev 规则（官方给出两条，分别标注在 CentOS 8 与 CentOS 7 上测试过）：

# cat /etc/udev/rules.d/99-ceph-write-through.rules
ACTION=="add", SUBSYSTEM=="scsi_disk", ATTR{cache_type}:="write through"

# cat /etc/udev/rules.d/99-ceph-write-through-el7.rules
ACTION=="add", SUBSYSTEM=="scsi_disk", RUN+="/bin/sh -c 'echo write through > /sys/class/scsi_disk/$kernel/cache_type'"

• 用 sdparm 一次性查看/修改多块盘：

# sdparm --get WCE /dev/sd*
# sdparm --clear WCE /dev/sd*

4.1.4 网络

维度	官方建议
带宽下限	数据中心内至少 10 Gb/s——既包括 Ceph 主机之间，也包括客户端与集群之间
高负载集群	建议 25 Gb/s
密集节点	常常需要 100 Gb/s 链路
绑定	强烈推荐跨不同交换机做 active/active bonding，既提吞吐又容忍网络故障与维护；注意 bonding hash 策略要能把流量分散到各链路
TOR 交换机	到核心/骨干的上行链路也要快速且冗余，通常至少 40 Gb/s
VLAN	用 802.1q 的 VLAN 需要支持 VLAN 的 NIC 与交换机，硬件增加的成本可能被网络运维成本的节省抵消

速度换算（官方给出的具体数字，很有说服力）：

数据量	1 Gb/s 网络	10 Gb/s 网络
复制 1 TiB	3 小时	20 分钟
复制 10 TiB	30 小时	3 小时

💡 补充（官方知识点）：40 Gb/s 链路实际是 4 条 10 Gb/s 并行，100 Gb/s 链路是 4 条 25 Gb/s 并行。因此单个报文在 25 Gb/s 网络上的延迟反而略低于 40 Gb/s 网络——这条有点反直觉，但是在官方原文里的。

BMC（基板管理控制器）：

• 常见实现：iDRAC（Dell）、CIMC（Cisco UCS）、iLO（HPE）。
• 管理与部署工具（尤其走 IPMI 或 Redfish）会大量使用 BMC，需权衡带外网络的成本与安全收益。
• 截至 2025 年，BMC 很少提供超过 1 Gb/s 的网络连接，因此为 BMC 管理流量配便宜的 1 Gb/s 专用交换机，可以少浪费高速主机交换机上的昂贵端口。

4.1.5 故障域（Failure Domains）

定义：任何会导致一个或多个 OSD 或其他 Ceph 守护进程不可访问的组件失效，都可视为一个故障域。官方举例：主机上停止的守护进程、存储盘故障、OS 崩溃、NIC 故障、电源故障、网络中断、断电等。

规划原则：在"把过多职责塞进过少故障域所省下的成本"与"隔离每个潜在故障域所增加的成本"之间取得平衡。

其他注意事项（官方原文）：

• 单主机的 OSD 聚合吞吐不应超过服务客户端读写所需的网络带宽；算上内部复制流量，密集节点或 NVMe 节点可能打满 10 GE 甚至 25 GE 网卡。
• 更多、更小的节点能同时带来两个好处：更小的故障半径（blast radius / failure domain），以及更不容易打满网络接口。
• 关注单台主机占集群总容量的百分比：若某台主机占比很大，它一旦故障，集群常会出现"恢复过程导致 OSD 超过 full ratio，进而 Ceph 停止操作以防止数据丢失"这类问题。
• 单主机跑多 OSD 时，必须确保内核足够新（参见 OS 建议中关于 glibc 与 syncfs(2) 的说明）。

4.1.6 最低硬件建议表（官方原表逐格转述）

进程	维度	最低要求与推荐值
ceph-osd	Processor	最低 1 线程 / HDD OSD，推荐 3 线程；NVMe SSD OSD 分别为 4 和 6。附加说明：① 结果未计入复制开销；② 结果随 CPU 与磁盘型号、Ceph 配置（纠删码、压缩等）而变；③ ARM 处理器可能需要更多核才能达到同等性能；④ SSD OSD 尤其是 NVMe，会因每 OSD 更多核而受益；⑤ 实际性能取决于盘、网络、客户端吞吐与延迟等众多因素，强烈建议基准测试
	RAM	4 GB+ 每守护进程（越多越好）；2–4 GB 可以运行但会很慢；低于 2 GB 不推荐
	Storage Drives	大多数情况每个 OSD 一块存储盘；大于 30 TB 的 PCIe Gen 4+ SSD 拆成两个或更多 OSD 可能更好
	DB/WAL offload（可选）	每个 HDD OSD 一个 SSD 分区；SATA SSD 承载 4–5 个 HDD OSD 的 DB/WAL；NVMe SSD 承载 ≤ 15 个 HDD OSD 的 DB/WAL
	Network	1x 1 Gb/s（推荐绑定 25+ Gb/s）
ceph-mon	Processor	最低 2 核
	RAM	5 GB+ 每守护进程（大型/生产集群需要更多）
	Storage	100 GB 每守护进程，强烈建议 SSD
	Network	1x 1 Gb/s（推荐 10+ Gb/s）
ceph-mds	Processor	最低 2 核；高主频比多核更有价值
	RAM	8+ GiB 每守护进程
	Network	1x 1 Gb/s（推荐 10+ Gb/s）

💡 补充（官方 tip）：OSD 节点只有一块存储盘时，也要为 OSD 创建独立于 OS 分区的分区；官方推荐 OS 与 OSD 存储使用各自的物理盘。

引自：Hardware Recommendations

4.2 操作系统与内核要求

4.2.1 通用原则

一般规则：我们推荐把 Ceph 部署在较新的 Linux 发行版上，并且推荐部署在**有长期支持（long-term support）**的版本上。

4.2.2 Linux 内核要求

场景	官方要求
使用内核客户端（映射 RBD 块设备或挂载 CephFS）	一般建议：在客户端主机上使用 kernel.org 或你的发行版提供的 "stable" 或 "longterm maintenance" 内核系列
RBD（跟踪 longterm 内核）	建议至少基于 4.19 的 "longterm maintenance" 内核系列；能用更新的 stable/longterm 系列就用更新的
RBD（image features 支持）	要对 RBD image features 有合理支持，最低需要内核 5.3 或 CentOS 8.2
CephFS	内核版本指引需参考 "Mounting CephFS using Kernel Driver" 页面（本册范围内未给出具体数字，见"文档未明确项"）
老内核客户端的代价	可能不支持你的 CRUSH tunables profile 或集群的其他新特性，从而迫使存储集群禁用这些特性
MS Windows 客户端	Ceph 的 Windows 原生客户端支持是 "best effort"，没有全职维护者；截至 2025 年 7 月没有移除计划，但未来不确定

4.2.3 发行版平台支持矩阵

官方明确声明：Ceph 不要求特定的 Linux 发行版，可以运行在任何包含"受支持内核 + 受支持启动框架（如 sysvinit 或 systemd）"的发行版上；Ceph 有时被移植到非 Linux 系统，但核心 Ceph 团队不支持这些移植。

平台	Tentacle (20.2.z)	Squid (19.2.z)	Reef (18.2.z)
Centos 9	A	A	A
Debian 12	C	C	C
Ubuntu 20.04	—	—	A
Ubuntu 22.04	A	A	A
MS Windows	D	D	D

图例（官方定义）：

标记	含义
A	Ceph 提供软件包，并且对其中的软件做了全面测试
B	Ceph 提供软件包，并且对其中的软件做了基础测试
C	Ceph 仅提供软件包，未对这些版本做过测试
D	客户端软件包来自外部站点，核心 Ceph 团队既不维护也不测试

4.2.4 容器宿主（Container Hosts）支持矩阵

平台	Tentacle (20.2.z)	Squid (19.2.z)	Reef (18.2.z)
Centos 9	H	H	H
Ubuntu 22.04	H	H	H

图例：H = Ceph 把该发行版作为容器宿主做过测试。

引自：OS Recommendations

4.3 安装前检查清单（可执行）

💡 补充：官方没有提供一个统一的"安装前检查清单"，下表是把第 04 章各节的硬性约束归并而成的可执行清单。

# 1. 确认 OS 与内核（对照 4.2.3 / 4.2.2 的矩阵）
cat /etc/os-release
uname -r

# 2. 确认时间同步（cephadm 要求项）
systemctl status chronyd || systemctl status ntpd

# 3. 确认 systemd 存在（cephadm 要求项）
ps -p 1 -o comm=

# 4. 确认 Python 3（cephadm 要求 Python 3.6+）
python3 --version

# 5. 确认容器运行时（cephadm 要求 Podman 或 Docker）
podman --version || docker --version

# 6. 确认 LVM2（cephadm 用于置备存储设备）
lvm version

# 7. 确认 ssh 已安装并运行（cephadm bootstrap 前置条件）
systemctl status sshd

# 8. 确认可用的数据盘（OSD 最小 1 TiB；小于 100 GiB 无效）
lsblk -o NAME,SIZE,TYPE,ROTA,MODEL

# 9. 确认网络带宽（生产建议 10 Gb/s 起）
ethtool <iface> | grep -i speed

# 10. 关闭/确认 swap（官方不建议为守护进程配置 swap）
swapon --show

引自：Hardware Recommendations

---

五、安装方式对比

5.1 官方推荐的方法

（1）cephadm（首选）

install/index.rst 把 cephadm 放在推荐方法第一位：

特性	官方说明
定位	用于安装和管理 Ceph 集群的工具
版本支持	仅支持 Octopus 及更新版本
集成度	与 orchestration API 完全集成，完全支持用于管理集群部署的 CLI 与 dashboard 特性
依赖	需要容器支持（Podman 或 Docker）与 Python 3
其他依赖	需要 systemd

（2）Rook（Kubernetes 场景首选）

特性	官方说明
定位	在 Kubernetes 中部署和管理 Ceph 集群，同时支持通过 Kubernetes API 管理存储资源与置备
官方推荐语	"We recommend Rook as the way to run Ceph in Kubernetes or to connect an existing Ceph storage cluster to Kubernetes."
版本支持	仅支持 Nautilus 及更新版本
集成度	支持 orchestrator API；CLI 与 dashboard 的管理特性全部支持

5.2 其他方法

工具	官方说明
ceph-ansible	用 Ansible 部署和管理 Ceph 集群；广泛部署（widely deployed）；未与 Nautilus 与 Octopus 引入的 orchestrator API 集成，因此这两个版本引入的管理特性与 dashboard 集成不可用
ceph-deploy	用于快速部署集群的工具，已废弃（deprecated）。官方 IMPORTANT：不再积极维护；未在比 Nautilus 更新的 Ceph 版本上测试；不支持 RHEL8、CentOS 8 或更新的操作系统
ceph-salt	用 Salt 和 cephadm 安装 Ceph
jaas.ai/ceph-mon	用 Juju 安装 Ceph
github.com/openstack/puppet-ceph	用 Puppet 安装 Ceph
OpenNebula HCI clusters	在各种云平台上部署 Ceph
手动安装	Ceph 也可以手动安装（install-manual）
Windows	需查阅 Windows installation guide（该页在本版 rst 中不存在，见"文档未明确项"）

5.3 五种路径横向对比

💡 补充：官方并没有给出下面这张对比表，本表是基于 5.1/5.2 的官方描述，加上第 05 章各安装页面的事实，做的经验性归并。"适用人群"一列为主观判断。

安装方式	优点（官方依据）	缺点 / 限制（官方依据）	适用人群
cephadm	官方首选；与 orchestration API 完全集成；CLI 与 dashboard 全支持；bootstrap 自动安装依赖；支持 airgapped 部署与自定义 SSH key	仅支持 Octopus+；需要容器运行时（Podman/Docker）+ Python 3 + systemd + 时间同步 + LVM2；部分 Podman 版本不兼容（官方另有兼容性表）	绝大多数新集群；想用 dashboard 与 ceph orch 编排的团队
Rook	Kubernetes 上跑 Ceph 的首选；支持 orchestrator API；CLI/dashboard 全支持；可连外部已有集群	仅支持 Nautilus+；必须已有 Kubernetes	K8s 原生栈；云原生团队
手动安装（包管理器 / 源码）	完全可控；不依赖容器；官方提供从 MON bootstrap 到 OSD/MDS/RGW 的完整步骤；可 FreeBSD 部署	官方定位是给写 Chef/Juju/Puppet 部署脚本的人做范例；无 orchestrator 集成；步骤长、易出错	部署工具开发者；需要精细控制或特殊 OS（如 FreeBSD）的场景
容器镜像	官方镜像（quay.io/ceph/ceph）；tag 语义清晰（vRELNUM / vRELNUM.2 / vRELNUM.Y.Z / vRELNUM.Y.Z-YYYYMMDD）	官方明确不鼓励使用 :latest tag——无法保证各主机上是同一个镜像，升级可能失败；legacy 镜像（Docker Hub 的 ceph/daemon-base、ceph/daemon）即将/已经边缘化	已有容器平台、想自己编排的团队
源码编译	能拿最新代码、能打自己的 deb/rpm 包；是参与开发的必经路径	debug 构建约需 40 GB；在 VM 中构建建议总磁盘至少 60 GB；耗时长（官方作者在 i7 NUC 上跑了 3 小时以上，共 2289 步）	Ceph 开发者、QA、需要打私有包的人
虚拟机/云镜像（QEMU + libvirt）	让 Ceph 块设备成为 VM 与云平台的后端；QEMU 经 librbd 直连 Ceph	这不是"安装 Ceph"的方式，而是为使用块设备准备客户端；需要先有运行中的集群	用 Ceph 做 OpenStack / CloudStack / OpenNebula 后端的场景

5.4 各安装方式的关键命令入口

5.4.1 取包：三条路径（install/get-packages.rst）

方式	说明	前置条件
Cephadm	cephadm 可根据发布名或具体 Ceph 版本帮你配置仓库	集群中每个 Ceph 节点都必须能访问互联网
手工配置仓库	手工配置包管理工具去取 Ceph 包及其依赖	每个 Ceph 节点都必须能访问互联网
手工下载包	在节点不能上网的环境下最方便	需在离线环境预先取好包（含全部依赖）

用 cephadm 取包：

curl --silent --remote-name --location https://download.ceph.com/rpm-|stable-release|/el9/noarch/cephadm
chmod +x cephadm

按发布名配置仓库：

./cephadm add-repo --release |stable-release|

Octopus（15.2.0）及以后可指定具体版本：

./cephadm add-repo --version 15.2.1

开发包可指定分支名：

./cephadm add-repo --dev my-branch

安装包（用包管理器，或用 cephadm 包装命令）：

./cephadm install ceph-common

5.4.2 加钥匙（官方推荐步骤）

APT：

wget -q -O- 'https://download.ceph.com/keys/release.asc' | sudo tee /etc/apt/trusted.gpg.d/ceph.asc

RPM：

sudo rpm --import 'https://download.ceph.com/keys/release.asc'

官方说明：主要发布（如 luminous、mimic、nautilus）与开发发布（release-name-rc1、release-name-rc2）都使用 release.asc 钥匙。若不装钥匙，可能遇到安全警告。

5.4.3 仓库地址规则

类别	地址模板
Debian/Ubuntu（按发布名）	https://download.ceph.com/debian-{release-name}
CentOS/RHEL 等（按发布名）	https://download.ceph.com/rpm-{release-name}
Debian/Ubuntu（按具体版本 x.y.z，Octopus+）	https://download.ceph.com/debian-{version}
RPM（按具体版本，Octopus+）	https://download.ceph.com/rpm-{version}
Debian 开发仓库	https://download.ceph.com/debian-testing/
RPM 开发包直下	https://download.ceph.com/rpm-testing

Debian/Ubuntu 添加仓库：

sudo apt-add-repository 'deb https://download.ceph.com/debian-|stable-release|/ {codename} main'

早期发行版可用：

echo deb https://download.ceph.com/debian-|stable-release|/ $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list

用 lsb_release -sc 取得短代号替换 {codename}。

RHEL/CentOS 的 /etc/yum.repos.d/ceph.repo（注意 priority=2 是官方特意强调的）：

[ceph]
name=Ceph packages for $basearch
baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/$basearch
enabled=1
priority=2
gpgcheck=1
gpgkey=https://download.ceph.com/keys/release.asc

[ceph-noarch]
name=Ceph noarch packages
baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/noarch
enabled=1
priority=2
gpgcheck=1
gpgkey=https://download.ceph.com/keys/release.asc

[ceph-source]
name=Ceph source packages
baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/SRPMS
enabled=0
priority=2
gpgcheck=1
gpgkey=https://download.ceph.com/keys/release.asc

官方说明：某些 Ceph 包（如 EPEL）必须优先于标准包，因此必须设置 priority=2。

其他发行版：

# openSUSE Leap 15.1
zypper ar https://download.opensuse.org/repositories/filesystems:/ceph/openSUSE_Leap_15.1/filesystems:ceph.repo

# openEuler（20.03-LTS 含 Ceph 12.2.8；22.03-LTS 含 Ceph 16.2.7，无需另加仓库）
sudo yum -y install ceph

openSUSE Tumbleweed：最新主版本已在常规 Tumbleweed 仓库中，无需手动添加。

5.4.4 开发包（shaman）

# Debian/Ubuntu
curl -L https://shaman.ceph.com/api/repos/ceph/{BRANCH}/latest/ubuntu/$(lsb_release -sc)/repo/ | sudo tee /etc/apt/sources.list.d/shaman.list

# RPM（示例为 CentOS 8）
curl -L https://shaman.ceph.com/api/repos/ceph/{BRANCH}/latest/centos/8/repo/ | sudo tee /etc/yum.repos.d/shaman.repo

两个警告（官方原文）：

1. 若仓库尚未就绪，会返回 HTTP 504。
2. 开发仓库在两周后就不可用了。

URL 中的 latest 表示"取最近一次构建成功的 commit"，也可指定具体 sha1。

5.4.5 手工下载包（离线环境）

# Debian
wget -q https://download.ceph.com/debian-{release}/pool/main/c/ceph/ceph_{version}{distro}_{arch}.deb

# 先装 EPEL
sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

# 再装 release 包（示例 el8）
su -c 'rpm -Uvh https://download.ceph.com/rpm-|stable-release|/el8/noarch/ceph-release-1-0.el8.noarch.rpm'

5.4.6 源码：克隆 → 编译 → 打包

克隆（默认 main 分支）：

git clone --recursive https://github.com/ceph/ceph.git
cd ceph
git status

只想克隆、不提交代码，可用 HTTPS 免 SSH key 的方式（官方 tip）。

子模块过期时的修复（官方原文顺序）：

git submodule update --force --init --recursive --progress
git clean -fdx
git submodule foreach git clean -fdx

若某个子模块目录仍有问题，用 rm -rf [directory name] 删掉该目录，再跑 git submodule update --init --recursive --progress。

编译（cmake + ninja）：

cd ceph
./do_cmake.sh
cd build
ninja

安装到用户空间：

sudo ninja install

官方说明：ninja 会把可执行文件放到 usr/local/bin；可以把 Ceph 配置文件也放到该目录，从而从单一目录运行 Ceph。

编译前置（来自 start/beginners-guide.rst 的 vstart 流程，也适用于开发集群）：

git clone git@github.com:ceph/ceph
git submodule update --init --recursive --progress
./install-deps.sh
apt install python3-routes
cd ceph
./do_cmake.sh
cd build
ninja -j3
ninja install
ninja vstart
../src/vstart.sh --debug --new -x --localhost --bluestore

⚠️ 官方 note：ninja -j3 这一步耗时很长，共 2289 步；作者在 2024 年 9 月用一台 i7 的 Intel NUC 跑了三个多小时。../src/vstart.sh 必须在 ceph/build 目录内执行。

打包：

# Debian/Ubuntu
sudo apt-get install debhelper
sudo dpkg-buildpackage

# RPM
yum install rpm-build rpmdevtools
rpmdev-setuptree
wget -P ~/rpmbuild/SOURCES/ https://download.ceph.com/tarballs/ceph-<version>.tar.bz2
# 或从 EU 镜像
wget -P ~/rpmbuild/SOURCES/ http://eu.ceph.com/tarballs/ceph-<version>.tar.bz2
tar --strip-components=1 -C ~/rpmbuild/SPECS/ --no-anchored -xvjf ~/rpmbuild/SOURCES/ceph-<version>.tar.bz2 "ceph.spec"
rpmbuild -ba ~/rpmbuild/SPECS/ceph.spec

官方 tip：多核 CPU 上用 -j，数值取核数 × 2（例如双核用 -j4）。

磁盘空间：debug 构建约 40 GB；若在 VM 中构建，请确保 VM 总磁盘至少 60 GB。另注意 CentOS 等发行版默认用 LVM，可能预留大量磁盘空间给操作系统。

5.4.7 容器镜像 tag 语义

官方镜像地址：https://quay.io/repository/ceph/ceph、https://hub.docker.com/r/ceph

ceph/ceph 的 tag：

Tag	含义
vRELNUM	该系列的最新发布（如 v14 = Nautilus）
vRELNUM.2	该稳定系列的最新稳定发布（如 v14.2）
vRELNUM.Y.Z	一个具体的发布（如 v14.2.4）
vRELNUM.Y.Z-YYYYMMDD	一个具体的构建（如 v14.2.4-20191203）

legacy 镜像（Docker Hub）：ceph/daemon-base（与 ceph/ceph 基本相同，tag 不同；所有 -devel tag 与 latest-master tag 基于 shaman.ceph.com 上未发布、基本未测试的包；官方注明该镜像即将成为 ceph/ceph 的别名）、ceph/daemon（= daemon-base + 一批 BASH 脚本，供 ceph-nano 与 ceph-ansible 使用）。

legacy tag：latest-master、latest-master-devel、latest-RELEASE-devel。

开发构建：ceph-ci/ceph，位于 https://quay.ceph.io/organization/ceph-ci，tag 为 BRANCH、BRANCH-SHORTSHA1-BASEOS-ARCH-devel、SHA1。官方留有 TODO：去掉 wip-* 限制、也为 ceph.git 分支构建。

官方 important：不要用 :latest。它是相对 tag、移动靶，无法保证每台主机上是同一个镜像，升级可能不正常工作。应改用显式 tag 或 image ID，例如：

podman pull ceph/ceph:v15.2.0

5.4.8 镜像站

地区	地址
EU: Netherlands	http://eu.ceph.com/
AU: Australia	http://au.ceph.com/
SE: Sweden	http://se.ceph.com/
DE: Germany	http://de.ceph.com/
FR: France	http://fr.ceph.com/
UK: UK	http://uk.ceph.com
US-Mid-West: Chicago	http://mirrors.gigenet.com/ceph/
US-West: US West Coast	http://us-west.ceph.com/
CN: China	http://mirrors.ustc.edu.cn/ceph/

可把所有 download.ceph.com 的 URL 替换为任意镜像，例如把 http://download.ceph.com/tarballs/ 换成 http://eu.ceph.com/tarballs/。

自建镜像的三条准则（官方原文）：① 选离你近的镜像；② 同步间隔不要短于 3 小时；③ 避免在整点第 0 分钟同步，用 0–59 之间的某个值。

引自：Installing Ceph

---

六、快速上手：最小步骤

本章主线是 cephadm（官方推荐），末尾附带 RBD 块设备 quick start 与手工部署最小路径。

6.1 路线 A：cephadm（推荐，最短路径）

步骤 0：确认前置条件（cephadm 官方 Requirements）

要求	说明
Python 3	必须
Systemd	必须
Podman 或 Docker	用于运行容器
时间同步	如 Chrony 或传统的 ntpd
LVM2	用于置备存储设备

官方补充："Any modern Linux distribution should be sufficient."（任何现代 Linux 发行版都够用。）下述 bootstrap 过程会自动安装依赖。

⚠️ 官方 important：ssh 必须已安装且正在运行，否则 bootstrap 会失败。 ⚠️ 关于 Podman：不是每个 Podman 版本都与 Ceph 兼容，官方另有兼容性表（见 cephadm/compatibility）。

步骤 1：获取 cephadm（两种互斥方式，官方强调只能选一种）

⚠️ 官方 important：两种安装方式互斥。请二选一，不要在同一系统上同时使用。

方式 A：发行版包管理器

# 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

方式 B：curl 下载独立可执行文件

CEPH_RELEASE=18.2.0 # replace this with the active release
curl --silent --remote-name --location https://download.ceph.com/rpm-${CEPH_RELEASE}/el9/noarch/cephadm
chmod +x cephadm
./cephadm <arguments...>

⚠️ 官方 note：新版 cephadm 是从源码编译出的可执行文件。与早期 Ceph 不同，从 git 树里拷一个脚本跑是不够的。若要运行开发版 cephadm，需自行构建。

若遇到 bad interpreter 之类错误，可能是 Python 版本问题（cephadm 要求 Python 3.6+），可显式指定：

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

步骤 2（可选但推荐）：把 cephadm 装到宿主机上

虽然独立 cephadm 已足以 bootstrap，但官方建议把 cephadm 命令装到宿主机：

./cephadm add-repo --release |stable-release|
./cephadm install
which cephadm

成功时 which cephadm 返回：

/usr/sbin/cephadm

步骤 3：bootstrap 新集群

前置：必须知道第一台主机的 IP 地址。官方提醒——若存在多个网络与接口，务必选择所有需要访问集群的主机都能连通的那个。

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

这条命令会做以下七件事（官方逐条列出）：

1. 在本地主机上为新集群创建 Monitor 守护进程与 Manager 守护进程。
2. 为 Ceph 集群生成新的 SSH key，并把它加入 root 用户的 /root/.ssh/authorized_keys。
3. 把公钥写入 /etc/ceph/ceph.pub。
4. 把一个最小配置文件写入 /etc/ceph/ceph.conf（与 Ceph 守护进程通信必需）。
5. 把 client.admin 管理（特权！）密钥写入 /etc/ceph/ceph.client.admin.keyring。
6. 给 bootstrap 主机加上 _admin label。默认任何带此 label 的主机都会（也）拿到 /etc/ceph/ceph.conf 与 /etc/ceph/ceph.client.admin.keyring 的副本。

bootstrap 的常用可选参数：

参数	作用
--log-to-file	Ceph 守护进程默认把日志输出到 stdout/stderr（由容器运行时收走，多数系统送到 journald）。加此选项则改为写传统日志文件到 /var/log/ceph/$fsid
--cluster-network *<cidr>*	分离 public network 与 cluster network（后者承载复制、恢复、OSD 间心跳）。必须是 CIDR 表示的子网，如 10.90.90.0/24 或 fe80::/64
--output-dir *<directory>*	把 /etc/ceph 下那些文件写到别的目录（如 .），避免与同主机上已有的 Ceph 配置冲突。注：cephadm 部署的守护进程容器本身完全不需要 /etc/ceph
--config *<config-file>*	传入初始 Ceph 配置（标准 ini 风格文件）
--ssh-user *<user>*	指定 cephadm 用来连主机的 SSH 用户；对应 SSH key 会加入 ~<user>/.ssh/authorized_keys。该用户必须有无密码 sudo 权限
--registry-json *<path>*	访问需要登录的镜像仓库时使用
--single-host-defaults	单主机部署（详见下文）
--ssh-private-key / --ssh-public-key	使用自定义 SSH 密钥对
--ssh-signed-cert	使用 CA 签名的 SSH 证书

传入初始配置的例子（官方原文）：

$ cat <<EOF > initial-ceph.conf
[global]
osd crush chooseleaf type = 0
EOF
$ ./cephadm bootstrap --config initial-ceph.conf ...

需要登录的私有仓库 JSON 内容格式（官方原文）：

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

cephadm 会登录该仓库拉取容器，并把登录信息存入自己的配置库；后续加入集群的其他主机也能使用这个已认证的仓库。

查看全部选项：

cephadm bootstrap -h

步骤 4：启用 Ceph CLI（三种方式）

cephadm 本身不要求在宿主机安装任何 Ceph 包，但官方推荐让 ceph 命令好用：

# 方式 1：进入带全套 Ceph 包的容器 bash
cephadm shell

# 方式 2：直接执行单条 ceph 命令
cephadm shell -- ceph -s

# 方式 3：安装 ceph-common 包（含 ceph、rbd、mount.ceph 等全部命令）
cephadm add-repo --release |stable-release|
cephadm install ceph-common

官方补充：cephadm shell 默认会把宿主机 /etc/ceph 下的配置与 keyring 传进容器；在 MON 主机上执行时，它会从 MON 容器推断 config 而不是用默认配置；--mount <path> 可把宿主机路径挂到容器内的 /mnt。

验证：

ceph -v
ceph status

步骤 5：添加主机

默认只有 bootstrap 主机带 _admin label。官方建议再给一到多台主机加 _admin label，以便在多台主机上都能方便地用 cephadm shell 访问 CLI：

ceph orch host label add *<host>* _admin

添加主机的完整步骤参见 cephadm/host-management（本册不展开）。

步骤 6：添加更多 MON

官方建议：典型集群有 3 个或 5 个 Monitor 守护进程，分布在不同主机上；若集群有 5 个或更多节点，建议部署 5 个 MON；绝大多数集群用不到 7 个或更多 MON。

步骤 7：添加存储（OSD）

让 Ceph 吃掉所有可用且未使用的设备：

ceph orch apply osd --all-available-devices

步骤 8：OSD 内存自动调优（重要警告）

⚠️ 官方 warning：默认情况下，cephadm 在 bootstrap 时会启用 osd_memory_target_autotune，并把 mgr/cephadm/autotune_memory_target_ratio 设为宿主机总内存的 .7（即 70%）。

若集群硬件不是 Ceph 独占（融合基础设施 / converged infrastructure），应先降低 Ceph 内存占用：

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

然后启用自动调优：

ceph config set osd osd_memory_target_autotune true

步骤 9：开始使用三种接口

想用	命令/入口
Ceph Filesystem（CephFS）	参见 orchestrator-cli-cephfs
Ceph Object Gateway（RGW）	参见 cephadm-deploy-rgw
NFS	参见 deploy-cephadm-nfs-ganesha
iSCSI	参见 cephadm-iscsi

场景变体：单主机集群

cephadm bootstrap --mon-ip *<mon-ip>* --single-host-defaults

该 flag 会设置以下三个配置项：

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

官方明确：这类集群一般不适合生产环境。

场景变体：隔离环境（airgapped）

1. 起一个本地容器仓库：

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

2. 若用非安全（insecure）仓库，在 Podman/Docker 里配置其主机名与端口——每台访问该仓库的主机都要重复此步。

3. 推送所需镜像：Ceph 容器镜像、Prometheus、Node exporter、Grafana、Alertmanager。

4. 写一个临时配置文件指定监控镜像：

[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/alertmanger

5. 用 --image 指定镜像启动 bootstrap：

cephadm --image *<hostname>*:5000/ceph/ceph bootstrap --mon-ip *<mon-ip>*

6.2 路线 B：RBD 块设备 quick start

⚠️ 官方前置条件：确认你的 Ceph 存储集群处于 active + clean 状态，然后再操作块设备。 官方 note：Ceph Block Device 也称 RBD 或 RADOS Block Device。 官方建议：ceph-client 节点可以用虚拟机，但不要在与 Ceph 存储集群节点相同的物理机上执行下述步骤（除非用 VM）。

第 1 步：创建块设备 pool 并初始化

在 admin 节点上用 ceph 工具创建 pool（官方推荐命名为 rbd），然后用 rbd 工具初始化：

rbd pool init <pool-name>

第 2 步：在 ceph-client 节点上创建块设备镜像

rbd create foo --size 4096 --image-feature layering [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring] [-p {pool-name}]

第 3 步：把镜像映射为块设备

sudo rbd map foo --name client.admin [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring] [-p {pool-name}]

第 4 步：在块设备上创建文件系统

sudo mkfs.ext4 -m0 /dev/rbd/{pool-name}/foo

官方注明：这一步可能需要一些时间。

第 5 步：挂载并使用

sudo mkdir /mnt/ceph-block-device
sudo mount /dev/rbd/{pool-name}/foo /mnt/ceph-block-device
cd /mnt/ceph-block-device

第 6 步（可选）：开机自动映射挂载

参见 rbdmap manpage（官方指向 man/8/rbdmap）。

💡 补充：--size 4096 的单位与 layering 之外可选的 image-feature 清单，在 start/quick-rbd.rst 里没有展开，属于 rbd 分册范围。

6.3 路线 C：手工部署最小路径（不使用 cephadm 等工具）

官方定位：手工部署流程"主要是为了给用 Chef、Juju、Puppet 等写部署脚本的人做范例"。

⚠️ 官方前置：所有 Ceph 集群都至少需要 1 个 monitor，以及不少于对象副本数的 OSD。bootstrap 初始 monitor 是部署的第一步；monitor 部署同时也为整个集群设定了重要参数（pool 副本数、每 OSD 的 PG 数、心跳间隔、是否需要认证等）。这些值大多有默认值，投产前值得了解。

示例拓扑：mon-node1 做 MON，osd-node1、osd-node2 做 OSD 节点。

C1. Bootstrap MON 需要准备的六样东西

项目	说明
Unique Identifier（fsid）	集群唯一标识。名字来自"Ceph 存储集群主要用于 Ceph 文件系统"的年代（File System ID）；如今 Ceph 已支持原生接口、块设备、对象网关，所以 fsid 算是个"用词不当"（misnomer）
Cluster Name	不含空格的简单字符串，默认是 ceph。多集群（尤其 multisite 配置，如 us-west、us-east）时改写很有用。CLI 上用 ceph --cluster {cluster-name} 指定；配置文件名体现集群名（ceph.conf、us-west.conf…）
Monitor Name	集群内每个 monitor 实例有唯一名字。惯例是用主机名（官方建议：每台主机一个 MON，且不要与 OSD 混布）。用 hostname -s 取短主机名
Monitor Map	bootstrap 需要生成 monitor map，它需要 fsid、集群名（或用默认）、至少一个主机名及其 IP
Monitor Keyring	MON 之间通过密钥通信，必须生成含 monitor secret 的 keyring
Administrator Keyring	要用 ceph CLI，必须有 client.admin 用户：生成该用户与 keyring，并把它加入 monitor keyring

另有 Configure Cephx（可选，也可建集群后再做）：monmap 会用最安全的默认密码套件，若要支持老客户端可放宽。

💡 官方建议（best practice）：虽然上述要求不强制创建配置文件，但建议创建 Ceph 配置文件并填入 fsid、mon initial members、mon host。配置文件里只需包含要覆盖默认值的那些设置。

C2. 具体命令序列（官方原顺序）

# 1) 登录初始 monitor 节点
ssh mon-node1

# 2) 确认有配置目录（装 ceph 时安装程序会自动创建 /etc/ceph）
ls /etc/ceph

# 3) 创建配置文件，加入 [global] 行
sudo vim /etc/ceph/ceph.conf

# 4) 为集群生成唯一 ID
uuidgen

# 5) 把唯一 ID 写入配置文件
#    fsid = a7f64266-0894-4f1e-a635-d0aeaca0e993

# 6) 写入初始 monitor
#    mon_initial_members = mon-node1

# 7) 写入初始 monitor 的 IP 并保存
#    mon_host = 192.168.0.1

官方 note：可以使用 IPv6 地址，但必须把 ms_bind_ipv6 设为 true。

# 8) 为集群创建 keyring 并生成 monitor 密钥
sudo ceph-authtool --create-keyring /tmp/ceph.mon.keyring --gen-key -n mon.

# 9) 生成管理员 keyring、client.admin 用户并加入 keyring
sudo ceph-authtool --create-keyring /etc/ceph/ceph.client.admin.keyring --gen-key -n client.admin --cap mon 'allow *' --cap osd 'allow *' --cap mds 'allow *' --cap mgr 'allow *'

# 10) 生成 bootstrap-osd keyring 与 client.bootstrap-osd 用户
sudo ceph-authtool --create-keyring /var/lib/ceph/bootstrap-osd/ceph.keyring --gen-key -n client.bootstrap-osd --cap mon 'profile bootstrap-osd' --cap mgr 'allow r'

# 11) 把生成的 key 导入 ceph.mon.keyring
sudo ceph-authtool /tmp/ceph.mon.keyring --import-keyring /etc/ceph/ceph.client.admin.keyring
sudo ceph-authtool /tmp/ceph.mon.keyring --import-keyring /var/lib/ceph/bootstrap-osd/ceph.keyring

# 12) 修改 ceph.mon.keyring 属主
sudo chown ceph:ceph /tmp/ceph.mon.keyring

官方 note（第 8 步）：mon. 这个凭证不需要任何 capabilities；所有 MON 共用这一把 key。

Cephx 密码套件（可选项，若需支持老客户端）：

# 允许较老的不安全密码套件
AUTH_SETTINGS="--auth-allowed-ciphers=aes,aes256k"

# 若还想让新 key 默认用较老（且不安全）的 aes 套件
AUTH_SETTINGS="$AUTH_SETTINGS --auth-preferred-cipher=aes"

# 服务套件类型一般不需要配，除非集群里要跑老版本服务守护进程
AUTH_SETTINGS="$AUTH_SETTINGS --auth-service-cipher=aes"

官方 note：客户端不解密也无需解密 service cipher。

# 13) 用主机名、IP、fsid 生成 monitor map，存为 /tmp/monmap
monmaptool --create $AUTH_SETTINGS --add mon-node1 192.168.0.1 --fsid a7f64266-0894-4f1e-a635-d0aeaca0e993 /tmp/monmap

# 14) 在 monitor 主机上创建默认数据目录
sudo -u ceph mkdir /var/lib/ceph/mon/ceph-mon-node1

# 15) 用 monitor map 与 keyring 填充 monitor 守护进程
sudo -u ceph ceph-mon --mkfs -i mon-node1 --monmap /tmp/monmap --keyring /tmp/ceph.mon.keyring

# 16) 启动 monitor
sudo systemctl start ceph-mon@mon-node1

# 17) 用 firewalld 开放 ceph-mon 端口
sudo firewall-cmd --zone=public --add-service=ceph-mon
sudo firewall-cmd --zone=public --add-service=ceph-mon --permanent

最小配置文件示例（官方给出）：

[global]
fsid = a7f64266-0894-4f1e-a635-d0aeaca0e993
mon_initial_members = mon-node1
mon_host = 192.168.0.1
public_network = 192.168.0.0/24

通用形式：

[global]
fsid = {cluster-id}
mon_initial_members = {hostname}[, {hostname}]
mon_host = {ip-address}[, {ip-address}]
public_network = {network}[, {network}]
cluster_network = {network}[, {network}]

官方 note：作为运维人员，应该优先通过 ceph config API 做配置变更，而不是改 ceph.conf 文件。

C3. 添加 OSD：短格式（Short Form，推荐）

ceph-volume 工具能准备逻辑卷、磁盘或分区供 Ceph 使用，会递增生成 OSD ID，并自动把新 OSD 加入该 host 下的 CRUSH map。执行 ceph-volume -h 看 CLI 详情。

# 先把 monitor 节点上的 bootstrap-osd keyring 复制到 OSD 节点
scp -3 root@mon-node1:/var/lib/ceph/bootstrap-osd/ceph.keyring root@osd-node1:/var/lib/ceph/bootstrap-osd/ceph.keyring

ssh osd-node1
sudo ceph-volume lvm create --data /dev/hdd1

也可以拆成 prepare + activate 两步：

ssh osd-node1
sudo ceph-volume lvm prepare --data /dev/hdd1

# 查看 prepared OSD 的 ID 与 FSID
sudo ceph-volume lvm list

# 激活（示例）
sudo ceph-volume lvm activate 0 a7f64266-0894-4f1e-a635-d0aeaca0e993

C4. 添加 OSD：长格式（Long Form，无辅助工具时）

官方 note：此流程不涉及基于 dm-crypt、使用 dm-crypt 'lockbox' 的部署。

# 1) 连到 OSD 主机并提权
ssh {node-name}
sudo bash

# 2) 为 OSD 生成 UUID
UUID=$(uuidgen)

# 3) 为 OSD 生成 cephx key
OSD_SECRET=$(ceph-authtool --gen-print-key)

# 4) 创建 OSD（若需复用已销毁的 OSD id，可把 OSD ID 作为附加参数传给 ceph osd new）
ID=$(echo "{\"cephx_secret\": \"$OSD_SECRET\"}" | \
    ceph osd new $UUID -i - \
    -n client.bootstrap-osd -k /var/lib/ceph/bootstrap-osd/ceph.keyring)

# 5) 创建新 OSD 的默认目录
mkdir /var/lib/ceph/osd/ceph-$ID

# 6) 若 OSD 用的是非 OS 盘，格式化并挂载
mkfs.xfs /dev/{DEV}
mount /dev/{DEV} /var/lib/ceph/osd/ceph-$ID

# 7) 把 secret 写入 OSD keyring 文件
ceph-authtool --create-keyring /var/lib/ceph/osd/ceph-$ID/keyring \
     --name osd.$ID --add-key $OSD_SECRET

# 8) 初始化 OSD 数据目录
ceph-osd -i $ID --mkfs --osd-uuid $UUID

# 9) 修正属主
chown -R ceph:ceph /var/lib/ceph/osd/ceph-$ID

# 10) 启动 OSD（systemd 发行版）
systemctl enable ceph-osd@$ID
systemctl start ceph-osd@$ID

第 4 步官方补充：也可以在 JSON 里带 crush_device_class 属性，把初始 class 设为默认值（依据自动探测的设备类型得出的 ssd 或 hdd）以外的值。

C5. 添加 MDS 与 RGW

MDS：参见 manual-mds（本册不展开）。

RGW（官方给出的手工安装步骤）：

# 1) 在将作为 RGW 节点的机器上安装 radosgw 包

# 2) 在 monitor 节点或有 admin 权限的节点上执行
ceph auth get-or-create client.$(hostname -s) mon 'allow rw' osd 'allow rwx'

# 3) 在其中一台 RGW 节点上：
#    a) 创建 ceph 属主的目录
install -d -o ceph -g ceph /var/lib/ceph/radosgw/ceph-$(hostname -s)

#    b) 进入该目录，创建 keyring 文件，并把上一步得到的 key 填进去
touch /var/lib/ceph/radosgw/ceph-$(hostname -s)/keyring
$EDITOR /var/lib/ceph/radosgw/ceph-$(hostname -s)/keyring

#    c) 每台 RGW 节点重复 a/b

# 4) 启动 RADOSGW 服务
systemctl start ceph-radosgw@$(hostname -s).service

💡 补充：官方在此处附了一个 ceph-users 邮件列表线程的链接，说明这只是"简版流程"。

C6. FreeBSD 上的差异

• 官方定位：基本是常规手工部署的副本，差异只有两处——底层磁盘格式与工具用法。
• 当前实现工作在 ZFS pool 上。
• 路径约定：所有 Ceph 数据在 /var/lib/ceph；日志在 /var/log/ceph；PID 文件在 /var/log/run。
• 每个 OSD 分配一个 ZFS pool：

gpart create -s GPT ada1
gpart add -t freebsd-zfs -l osd.1 ada1
zpool create -m /var/lib/ceph/osd/osd.1 osd.1 gpt/osd.1

• 可挂 cache 与 log（ZIL）。官方强调：这与 Ceph 的 journal 完全不同，cache 和 log 对 Ceph 完全透明，只是帮助文件系统保持一致性与提升性能。假设 ada2 是 SSD：

gpart create -s GPT ada2
gpart add -t freebsd-zfs -l osd.1-log -s 1G ada2
zpool add osd.1 log gpt/osd.1-log
gpart add -t freebsd-zfs -l osd.1-cache -s 10G ada2
zpool add osd.1 log gpt/osd.1-cache

• 注意：UFS2 不支持大的扩展属性（xattribs）。
• 配置路径：FreeBSD 上额外软件默认装到 /usr/local/，所以 /etc/ceph.conf 的实际默认位置是 /usr/local/etc/ceph/ceph.conf。官方建议从 /etc/ceph 软链到 /usr/local/etc/ceph：

ln -s /usr/local/etc/ceph /etc/ceph

引自：Block Device Quick Start

---

七、验证安装成功

7.1 主命令：ceph -s / ceph status

官方在手工部署流程里给出的首个成功信号就是 sudo ceph -s，并附了完整预期输出。

命令：

sudo ceph -s

官方给出的输出样例（这是 bootstrap 完 MON、尚未添加 OSD 时的状态）：

cluster:
  id:     a7f64266-0894-4f1e-a635-d0aeaca0e993
  health: HEALTH_OK

services:
  mon: 1 daemons, quorum mon-node1
  mgr: mon-node1(active)
  osd: 0 osds: 0 up, 0 in

data:
  pools:   0 pools, 0 pgs
  objects: 0 objects, 0 bytes
  usage:   0 kB used, 0 kB / 0 kB avail
  pgs:

逐字段解读：

字段	含义	你该看到的
cluster: id	集群 fsid	应与你写入 ceph.conf 的 fsid 一致（上例为 a7f64266-0894-4f1e-a635-d0aeaca0e993）
cluster: health	集群健康状态	此阶段官方样例为 HEALTH_OK
services: mon	MON 守护进程数与 quorum 成员	1 daemons, quorum mon-node1——"quorum" 后面必须列出 MON 名，说明该 MON 已进入多数派
services: mgr	MGR 守护进程	mon-node1(active)——有且应有一个 active
services: osd	OSD 上下线统计	此阶段为 0 osds: 0 up, 0 in；添加并启动 OSD 后应变为实际数量
data: pools	pool 与 PG 数量	此阶段 0 pools, 0 pgs
data: objects	对象数与字节数	此阶段 0 objects, 0 bytes
data: usage	已用 / 可用容量	此阶段 0 kB used, 0 kB / 0 kB avail
data: pgs	PG 明细列表	此阶段为空

7.2 三个必须知道的"预期告警"

现象	官方解释	处置
启动 MON 后看到 placement groups are stuck inactive 的健康错误	官方原文："you should see a health error indicating that placement groups are stuck inactive"	正常。官方明确：添加并启动 OSD 后，所有 PG 健康错误都会消失
启用了 legacy cipher 后 MON 报健康告警	官方原文："If you have enabled legacy cipher types then the Monitors may raise health warnings"	可 mute 这些告警（参见 muting health checks）；告警含义参见 health-checks 文档
集群无法达到 active + clean	官方在 RBD quick start 里强调：操作块设备之前集群必须处于 active + clean	通常是因为 OSD 数量少于对象副本数。官方举例：osd_pool_default_size = 2 至少要两个 OSD

关于 active + clean 的含义：architecture.rst 说明 PG Map 里每个 PG 都带一个 state，例如 active + clean；start/hardware-recommendations.rst 也把"PG 从 degraded 恢复到 active + clean"作为恢复速度的目标。

7.3 持续观察与拓扑查看

# 持续观察 PG peering 过程（官方原文：watch the placement groups peer）
ceph -w

# 查看 OSD 树
ceph osd tree

ceph osd tree 的官方样例输出：

# id	weight	type name	up/down	reweight
-1	2	root default
-2	2		host osd-node1
0	1			osd.0	up	1
-3	1		host osd-node2
1	1			osd.1	up	1

列含义：id（负数 id 是 CRUSH 层级中的桶，如 root / host）、weight（容量权重）、type name（类型与名称）、up/down（OSD 是否在线）、reweight（CRUSH 权重微调值）。

7.4 验证清单（可执行）

💡 补充：官方没有给出一张统一的验收清单，下表是把本章与第 06 章的官方描述归并为可执行步骤。

# 1. 集群整体状态（最核心的一条）
ceph status

# 2. 确认 ceph 命令可用且版本正确
ceph -v

# 3. 查看 MON quorum 与成员
ceph mon dump
ceph mon stat

# 4. 查看 OSD 树与 up/in 情况
ceph osd tree
ceph osd stat

# 5. 查看 pool 与 PG 分布
ceph osd dump
ceph osd pool ls
ceph pg stat

# 6. 查 CRUSH map（导出 + 反编译后查看）
ceph osd getcrushmap -o /tmp/crushmap.bin
crushtool -d /tmp/crushmap.bin -o /tmp/crushmap.txt
cat /tmp/crushmap.txt

# 7. 若使用 CephFS，查看 MDS map
ceph fs dump

# 8. 持续观察（排障时）
ceph -w

判定"装成功了"的四条硬标准（全部来自官方表述）：

1. ceph -s 能返回且 services 段里 MON 后面带 quorum。
2. 有 至少一个 active 的 MGR。
3. OSD 数量 ≥ 对象副本数，且 up / in 数量与预期一致。
4. 集群健康状态为 HEALTH_OK（或仅有已知的、已 mute 的 legacy cipher 告警）；不再有 "placement groups stuck inactive"。

引自：Manual Deployment

---

八、Ceph 基金会与社区治理

8.1 Ceph 基金会（Ceph Foundation）

使命：让行业成员能够协作并汇聚资源来支持 Ceph 项目社区；为项目利益相关者提供一个开放、协作、中立的家园，以协调他们在 Ceph 生态中的开发与社区投入。

组织形式：作为 **Linux 基金会下属的定向基金（directed fund）**运作。

会员制度： Premier 与 General 会员组织按年缴费入会；Associate 会员是教育机构或政府组织，被邀请免费加入。

更多信息：https://ceph.com/foundation

会员名单（官方原文，按等级）

等级	成员
Diamond	45Drives、Bloomberg、IBM
Platinum	Clyso、Samsung Electronics
Premier	OVH
Gold	42on
Silver	Canonical、CloudFerro、croit、ISS、Intel、OSNexus
Associate	Boston University、Center for Research in Open Source Systems (CROSS)、CERN、FASRC、grnet、Monash University、NRF SARAO、Open Infrastructure Foundation、Science & Technology Facilities Councel (STFC)、SWITCH、University of Michigan

💡 补充：原文中 "Science & Technology Facilities Councel" 的 "Councel" 疑为 "Council" 的拼写错误；此处照原文保留等级与名称。

理事会（Governing Board）

构成：所有 Premier 会员 + 一名 General 会员代表 + 一名 Associate 会员代表 + 一名来自 Ceph Leadership Team（技术治理机构）的代表。

职责（官方逐条）：

• 制定并批准用于支持 Ceph 项目的年度预算
• 设立临时（ad-hoc）委员会应对项目当前需求
• 协调外联或市场推广
• 定期开会讨论基金会事务、Ceph 项目状态与整体项目战略
• 对提交到理事会的任何决策或事项进行表决

关键边界（官方原文强调）：

The Ceph Foundation board is not responsible for and does not have any direct control over the technical governance of Ceph. 基金会理事会不负责也无权直接控制 Ceph 的技术治理。开发与工程活动通过传统的开源流程管理，由 **Ceph Steering Committee（指导委员会）**监督。

理事会成员（官方原文）

姓名	所属 / 角色
Brett Kelly	45Drives
Carlos Maltzahn	UCSC — Associate 会员代表
Dan van der Ster	Clyso — Ceph Council 代表
Joachim Kraftmayer	Clyso
Josh Durgin	IBM — Ceph Council 代表
Matthew Leonard	Bloomberg
Mike Perez	IBM — Ceph 社区经理（community manager）
Neha Ojha	IBM — Ceph Council 代表
Steven Umbehocker	OSNexus — General 会员代表
Pawel Sadowski	OVH
Sungmin Lee	Samsung Electronics
Vincent Hsu	IBM

加入方式：联系 membership@linuxfoundation.org。

引自：Ceph Foundation

8.2 社区治理（Governance）

8.2.1 四条核心原则（Key principles）

1. 决策由参与者以共识驱动（consensus-driven by those who participate）。
2. 领导角色主要由责任定义，而非声望或资历。
3. 这些角色交接给他人是正常且健康的。
4. 每个人的角色最终都是为用户服务，参与是自愿的。

💡 补充：官方原文中第 3 条句末缺少句号，属原文的标点瑕疵。

8.2.2 三个治理机构

（1）Ceph Executive Council（执行委员会）

项目	内容
职责	① 在无法通过共识达成决策时担任仲裁者；② 在他们之间或向他人分配关键职责；③ 项目的联络点；④ 出席 Ceph 基金会理事会会议的代表；⑤ 确保事情被做成
人数	3 人
产生方式	由 steering committee（指导委员会）选举产生；候选人自我提名或由其他成员提名；由指导委员会进行排序选择投票（ranked-choice vote）
任期	2 年；其中一名在偶数年改选，另两名在奇数年改选
退出与替补	成员可随时辞职；指导委员会可投票任命替补者完成剩余任期
硬性约束	成员必须来自 >1 个雇主（members must involve >1 employer）

现任成员：

• Dan van der Ster dan.vanderster@clyso.com
• Josh Durgin jdurgin@redhat.com
• Neha Ojha nojha@redhat.com

（2）Ceph Steering Committee（指导委员会）

项目	内容
职责	① 选举执行委员会；② 以绝对多数票（supermajority vote）修订治理模型；③ 定期开会讨论并决定战术与战略项目及改进；④ 举行年度选举
成员构成	开发者、用户、社区成员
加入/移除	由现有成员通过 supermajority 投票提名并加入/移除
旁听	任何人都可以作为无投票权的参与者参加指导委员会会议
过渡安排	现有 Ceph Leadership Team 成员被"祖父条款"保留（grandfathered in）
名单体现	通过邮件列表、Ceph 官网与文档体现

官方 note："supermajority" 指某一事项上 2/3 的多数票；弃权不影响投票结果（Abstaining does not bias a vote）。

现任成员（官方列出 37 人）：Adam King、Casey Bodley、Dan van der Ster、David Orman、Ernesto Puerta、Gregory Farnum、Haomai Wang、Ilya Dryomov、Igor Fedotov、Jeff Layton、Josh Durgin、João Eduardo Luis、Ken Dreyer、Mark Nelson、Matt Benjamin、Mike Perez、Myoungwon Oh、Neha Ojha、Patrick Donnelly、Sam Just、Vikhyat Umrao、Xie Xingguo、Yehuda Sadeh、Yingxin Cheng、Yuri Weinstein、Zac Dover、Laura Flores、Venky Shankar、Guillaume Abrioux、Anthony D'Atri、Joseph Mundackal、Gaurav Sitlani、Afreen Misbah、Radoslaw Zarzynski、Matan Breizman、Yaarit Hatuka、Adam C. Emerson。

（3）Component Team Leads（组件团队负责人）

项目	内容
职责	① 管理 Ceph 中的一个 component team；② 确保 PR 被 review 并合并；③ 确保严重缺陷修复被 backport；④ 主持 standups；⑤ 缺陷分诊（triage）、scrubs 等
产生方式	由执行委员会选定，通常基于团队成员与即将卸任负责人的推荐
轮转	官方鼓励在团队成员之间定期轮转负责人职责

组件团队列表见：https://ceph.io/en/community/team/

8.2.3 基金会与治理的关系

官方原文：Ceph 基金会作为 Linux 基金会下属的定向基金，任务是支持 Ceph 项目社区与生态；除了在协作开发过程中提供反馈与输入之外，它对 Ceph 开源项目的技术方向没有直接控制权（has no direct control over the technical direction ... beyond offering feedback and input）。

8.2.4 参与社区的渠道（start/get-involved.rst）

渠道	说明	联系方式
Blog	定期查看 Ceph 博客以跟踪进展与重要公告	https://ceph.io/en/news/blog/
Planet Ceph	博客聚合。注意：2023 年起不再更新	https://old.ceph.com/category/planet/
Wiki	社区与开发相关主题，含 blueprints、meetups、Ceph Developer Summits 等	http://wiki.ceph.com/
IRC	开发者常在美国太平洋时区白天在线。#ceph 适合集群运维者与用户；另有 #ceph-devel、#ceph-dashboard、#cephfs 面向开发者	域：irc.oftc.net；频道：#ceph、#ceph-devel、#ceph-dashboard、#cephfs
Slack	自 2023 年起，上游 Ceph 社区维护了 Slack 社区	Ceph Slack Invite（官方给出的邀请链接）
User List	用户问题问答邮件列表	订阅：ceph-users@ceph.io（https://lists.ceph.io/postorius/lists/ceph-users.ceph.io/）
Devel List	开发者活动	订阅：dev@ceph.io（https://lists.ceph.io/postorius/lists/dev.ceph.io/）
Kernel Client List	Linux 内核相关流量，含内核补丁与实现讨论	通过 majordomo@vger.kernel.org 订阅/退订（body 分别为 subscribe ceph-devel / unsubscribe ceph-devel）；存档：https://www.spinics.net/lists/ceph-devel/
Commit List	提交通知邮件	ceph-commit@ceph.com（加入/退出：ceph-commit-join@lists.ceph.com / ceph-commit-leave@lists.ceph.com）
QA List	质量保证相关活动	ceph-qa-join@lists.ceph.com / ceph-qa-leave@lists.ceph.com
Community List	Ceph User Committee 及社区话题	ceph-community-join@lists.ceph.com / ceph-community-leave@lists.ceph.com
Bug Tracker	提交与跟踪缺陷、提出特性请求	https://tracker.ceph.com/projects/ceph
Source Code	参与开发、修缺陷、拿最新代码	https://github.com/ceph/ceph ；https://download.ceph.com/tarballs/
Ceph Calendar	了解即将到来的 Ceph 活动	https://ceph.io/contribute/

引自：Governance

---

九、常用索引与后续学习路径

9.1 官方顶层目录树（index.rst 的 toctree）

官方首页隐藏目录树列出了文档的全部分册，也是本套手册分册划分的直接依据：

顺序	官方条目	对应本手册分册（建议）
1	start/index	本册（第 00 册）
2	install/index	本册（第 00 册）
3	cephadm/index	第 01 册 · cephadm 部署与运维
4	rados/index	第 02 册 · RADOS 核心与运维
5	cephfs/index	第 0X 册 · CephFS
6	rbd/index	第 0X 册 · RBD 块设备
7	radosgw/index	第 0X 册 · RGW 对象网关
8	mgr/index	第 0X 册 · MGR 模块与编排
9	mgr/dashboard	第 0X 册 · Dashboard
10	monitoring/index	第 0X 册 · 监控
11	api/index	第 0X 册 · API
12	architecture	本册第 02 章已覆盖主干
13	dev/developer_guide/index	第 0X 册 · 开发者指南
14	dev/internals	第 0X 册 · 内部实现
15	governance	本册第 08 章
16	foundation	本册第 08 章
17	ceph-volume/index	第 0X 册 · ceph-volume
18	releases/general	本册第 03 章
19	releases/index	本册第 03 章
20	security/index	第 0X 册 · 安全
21	hardware-monitoring/index	第 0X 册 · 硬件监控
22	glossary	第 0X 册 · 术语表
23	jaegertracing/index	第 0X 册 · 链路追踪

💡 补充：api/index 在抓到的 512 页 rst 中并不存在（本版 raw 目录下没有 api/ 目录），属目录树与实际页面不一致。

9.2 本册知识点 → 后续分册对照

你在本册学到的	下一步去哪一分册深挖
组件职责（MON/MGR/OSD/MDS/RGW）	cephadm/index（部署运维）、rados/index（OSD/MON 内部与运维）、mgr/index（MGR 模块）
RADOS / pool / PG / CRUSH / object	rados/index（尤其 rados/operations/pools、placement-groups、crush-map、pg-states）
三种存储接口	rbd/index、cephfs/index、radosgw/index
硬件与 OS 选型	rados/configuration/*（具体配置参数）、hardware-monitoring/index
安装方式	cephadm/index（install / host-management / services / upgrade / troubleshooting）
手工部署 OSD	ceph-volume/index（lvm / simple / zfs 各子命令）
健康检查	rados/operations/health-checks、monitoring/index
磁盘与 BlueStore	rados/configuration/bluestore-config-ref、rados/operations/devices

9.3 常用命令速查（本册出现过的全部）

分类	命令	出处
集群状态	ceph -s / ceph status	manual-deployment / cephadm-install
版本	ceph -v	cephadm-install
持续观察	ceph -w	manual-deployment
MON map	ceph mon dump	architecture
OSD map	ceph osd dump	architecture
OSD 树	ceph osd tree	manual-deployment
CRUSH map 导出	ceph osd getcrushmap -o {filename}	architecture
CRUSH map 反编译	crushtool -d {comp} -o {decomp}	architecture
MDS map	ceph fs dump	architecture
配置下发	ceph config set <who> <option> <value>	cephadm-install
主机 label	ceph orch host label add <host> _admin	cephadm-install
添加 OSD	ceph orch apply osd --all-available-devices	cephadm-install
cephadm 引导	cephadm bootstrap --mon-ip <mon-ip>	cephadm-install
cephadm shell	cephadm shell -- ceph -s	cephadm-install
仓库配置	./cephadm add-repo --release <release> / --version x.y.z / --dev <branch>	get-packages
装包	./cephadm install ceph-common	get-packages
创建块设备	rbd create foo --size 4096 --image-feature layering	quick-rbd
初始化 RBD pool	rbd pool init <pool-name>	quick-rbd
映射块设备	sudo rbd map foo --name client.admin	quick-rbd
短格式建 OSD	sudo ceph-volume lvm create --data {data-path}	manual-deployment
长格式建 OSD	ceph osd new $UUID -i - -n client.bootstrap-osd -k ...	manual-deployment
生成 monmap	monmaptool --create --add {host} {ip} --fsid {uuid} /tmp/monmap	manual-deployment
初始化 MON	sudo -u ceph ceph-mon --mkfs -i {hostname} --monmap /tmp/monmap --keyring /tmp/ceph.mon.keyring	manual-deployment
启动 MON	sudo systemctl start ceph-mon@{hostname}	manual-deployment
启动 OSD	systemctl enable ceph-osd@$ID && systemctl start ceph-osd@$ID	manual-deployment
开放 MON 端口	firewall-cmd --zone=public --add-service=ceph-mon [--permanent]	manual-deployment
磁盘基准	fio --name=/dev/sdX --ioengine=libaio --direct=1 --fsync=1 --readwrite=randwrite --blocksize=4k --runtime=300	hardware-recommendations
查询写缓存	hdparm -W /dev/sda、sdparm --get WCE /dev/sda、smartctl -g wcache /dev/sda、cat /sys/class/scsi_disk/.../cache_type	hardware-recommendations
关闭写缓存	hdparm -W0 /dev/sda、sdparm --clear WCE /dev/sda、smartctl -s wcache,off /dev/sda	hardware-recommendations
编译	./do_cmake.sh && cd build && ninja	build-ceph
安装构建	sudo ninja install	install-storage-cluster
启动 vstart	../src/vstart.sh --debug --new -x --localhost --bluestore	beginners-guide

9.4 关键配置项速查（本册出现过的）

配置项	默认值 / 出现值	含义	出处
osd_memory_target	4 GB（当前默认值）	BlueStore OSD 尝试消耗的内存量	hardware-recommendations
osd_memory_target_autotune	cephadm bootstrap 时默认启用	OSD 内存自动调优	cephadm-install
mgr/cephadm/autotune_memory_target_ratio	.7（即宿主机总内存的 70%）	自动调优的目标占比	cephadm-install
mon_osd_cache_size	文档未在本册给出默认值	MON/MGR 大集群可考虑调优	hardware-recommendations
rocksdb_cache_size	文档未在本册给出默认值	MON/MGR 大集群可考虑调优	hardware-recommendations
mds_cache_memory_limit	官方建议最小 1 GiB	MDS 缓存内存上限	hardware-recommendations
osd_pool_default_size	--single-host-defaults 时设为 2	pool 默认副本数	cephadm-install
osd_crush_chooseleaf_type	--single-host-defaults 时设为 0	CRUSH chooseleaf 的 bucket 类型	cephadm-install
mgr_standby_modules	--single-host-defaults 时设为 False	MGR standby 模块	cephadm-install
ms_bind_ipv6	用 IPv6 时必须设为 true	是否绑定 IPv6	manual-deployment
fsid	由 uuidgen 生成	集群唯一标识	manual-deployment
mon_initial_members	—	初始 MON 主机名列表	manual-deployment
mon_host	—	初始 MON IP 列表	manual-deployment
public_network	—	公共网络（CIDR）	manual-deployment
cluster_network	—	集群内部网络（CIDR），cephadm 用 --cluster-network 传	manual-deployment
priority	RPM 仓库必须设 2	YUM 仓库优先级	get-packages / install-storage-cluster

引自：Welcome to Ceph

---

文档未明确项

以下各条均属于本册范围内官方文档没有写清楚、或前后不一致、或已明显过时的点。逐条列出，不做臆测填补。

A. 内容缺失（官方确实没写）

1. "什么情况不该用 Ceph"完全没有官方清单。 本册第 1.4 节的表格是经验补充，官方 index / start / install 页面里没有任何对应的负面场景说明。
2. CephFS 所需的最低内核版本号未给出。 start/os-recommendations.rst 只说"参见 Mounting CephFS using Kernel Driver 页面"，本册范围内的 rst 没有给出具体数字（RBD 倒是给了 5.3 / CentOS 8.2）。
3. PG Map 的查看命令未给出。 architecture.rst 对 Monitor Map、OSD Map、CRUSH Map、MDS Map 都给了命令，唯独 PG Map 只描述内容、没给命令。
4. cephadm 使用的默认网络端口未在本册范围内出现。 抓到的 install/* 全部 12 页里没有提到 6789（msgr v1）或 3300（msgr v2）。这两个数字只出现在 man/8/monmaptool.rst、cephfs/mount-using-kernel-driver.rst、cephadm/troubleshooting.rst 等本册范围外的页面。
5. mon_osd_cache_size 与 rocksdb_cache_size 的默认值未给出。 hardware-recommendations.rst 只把它们列为"可以考虑调优"的项。
6. rbd create --size 4096 的单位未说明。 start/quick-rbd.rst 没写 4096 是 MB 还是其他单位；也没给出 --image-feature 除 layering 之外的可选项。
7. osd_pool_default_size 的系统默认值只在 --single-host-defaults 场景下出现（=2）。 非单主机场景下的默认副本数，本册范围内的 rst 未给出。
8. install/index_manual.rst 的 "Upgrade Software" 一节是个空 toctree。 该小节只有一句说明文字和一个空的 .. toctree::，没有链接任何页面。

B. 前后矛盾 / 疑似过时

9. Tentacle 未出现在 Active Releases 列表里（最严重）。 本手册版本是 Tentacle v20.2.4，start/os-recommendations.rst 的平台矩阵也已经有 "Tentacle (20.2.z)" 这一列，但 releases/index.rst 的 Active Releases 只列了 Squid (v19.2.*) 与 Reef (v18.2.*)，Tentacle 既不在 Active 也不在 Archived。同时 releases/ 目录下只有 general.rst 和 index.rst 两个文件，没有 tentacle.rst、也没有 releases.yml（而 index.rst 里多处引用了 releases.yml）。结论：releases 索引页相对本版本明显滞后，选版本请以官网实时页面为准。
10. install/index.rst 的 Windows 链接指向一个不存在的页面。 该页说"For Windows installations, consult this document: Windows installation guide"，链接目标是 ./windows-install，但抓到的 rst 里没有 install/windows-install.rst（只有 rbd/rbd-windows.rst 与 dev/developer_guide/tests-windows.rst）。这是一个断链。
11. cephadm/install.rst 的 curl 示例用的是旧版本号。 示例里写的是 CEPH_RELEASE=18.2.0 # replace this with the active release（18.2.0 是 Reef），而 start/os-recommendations.rst 已把 Tentacle（20.2.z）列为当前版本。示例与当前版本不一致。
12. start/quick-rbd.rst 的示意图里还在用 ceph-deploy。 图中 Admin Node 上标的是 ceph-deploy，但 install/index.rst 明确说 ceph-deploy 已废弃、不再积极维护、不支持比 Nautilus 更新的版本。图与文矛盾，图已过时。
13. governance.rst 把技术治理机构同时称为 "Ceph Leadership Team" 与 "Ceph Steering Committee"。 foundation.rst 里写的是"来自 Ceph Leadership Team（技术治理机构）的代表"，而 governance.rst 里的机构名是 "Ceph Steering Committee"，并说明"现有 Ceph Leadership Team 成员被祖父条款保留"。两个名称混用，虽可理解为改名过渡，但文档未明确说明。
14. governance.rst 的 Ceph Executive Council 描述存在内部张力。 "Membership" 小节写 Discussion of how roles/responsibilities may be delegated（讨论职责如何委派），与同级别的"产生方式/任期"条目性质不同，更像是遗留的会议议题而非规则；且 "members must involve >1 employer" 一句的准确含义（是"三人不能同属一个雇主"还是"整体需跨雇主"）文档未进一步界定。
15. start/beginners-guide.rst 里 MANAGER 的职责描述与其他页面不一致。 该页写 "The manager balances the data in the Ceph cluster, distributing load evenly..."（manager 负责均衡数据、分摊负载），而 start/index.rst 说 MGR 的职责是"跟踪运行时指标与集群状态、托管 Python 模块（含 dashboard）"。数据均衡实际由 OSD 通过 CRUSH 完成（同页 OSD 条目即写了 "handles data replication, recovery, rebalancing"）。beginners-guide 这句关于 manager 的表述疑似错误。
16. start/beginners-guide.rst 里"三个 MON 才能形成 quorum"的表述与架构页不完全等价。 该页说 "Three monitors are required to reach quorum"，而 start/index.rst 只说 "At least three monitors are normally required for redundancy and high availability"，architecture.rst 则说单 MON 也能工作只是有单点故障。严格说 quorum 需要的是"多数派"，1 个或 2 个 MON 也能形成 quorum，只是不冗余——beginners-guide 的说法容易误解。

C. 遗留内容 / 拼写瑕疵（照原文保留，未擅自修正）

17. start/os-recommendations.rst 平台矩阵里 "Ubuntu 20.04" 一行在 Tentacle 与 Squid 列为空，只有 Reef 列为 A；但没有出现 Ubuntu 24.04 这一行，说明矩阵未覆盖较新的 LTS。
18. install/get-packages.rst 提到 openEuler 只支持到 Ceph 12.2.8（20.03-LTS）与 16.2.7（22.03-LTS），均为很旧的版本，与当前 Tentacle 差距极大。
19. install/containers.rst 里 ceph/daemon-base 的说明写作 :note: This image will soon become an alias to *ceph/ceph*.（:note: 不是合法的 Sphinx 指令，应为 .. note::），且 "soon" 没有时间点。
20. foundation.rst 中 "Science & Technology Facilities Councel (STFC)" 的 "Councel" 疑似 "Council" 拼写错误。
21. install/index_manual.rst 的 toctree 使用了制表符缩进混合空格（Get Packages <get-packages> 等行以 tab 开头），在严格 Sphinx 构建下可能告警。
22. start/hardware-recommendations.rst 中 "Memory" 与 "RAM" 两节内容重叠（都讲 osd_memory_target），且 "Monitors and Managers (ceph-mon and ceph-mgr)" 是 "RAM" 下的子节，而 "Metadata Servers (ceph-mds)" 也在其下——章节层级略有混乱。

---

本册完。下一册：第 01 册 · cephadm 部署与运维（基于 cephadm/ 目录下 23 页 rst）。