简介：这份资源是面向Linux运维与云计算从业者的Ceph中文文档合集，适合正在搭建或维护Ceph存储集群的工程师、架构师以及需要为云平台提供对象存储、块设备或文件系统服务的技术人员参考。压缩包共收录482个文件，以346个rst文档为主体，辅以76个txt说明、9个conf配置样例、8个sh脚本及若干png、jpg图示，整体约4.04MB，涵盖集群部署、节点与网络规划、配置示例等模块，目录结构清晰便于按主题检索。已有422人学习下载，说明其在Ceph入门与实战场景中具备一定参考价值。读者可从中获取集群搭建的整体思路、配置文件写法与参数含义，并借助脚本与图示理解部署流程，适合作为日常查阅与排错时的辅助资料。
1. 拿到一份 Ceph 中文文档，先别急着翻目录
分布式存储这摊事，最怕的不是不会配，而是配完了不知道自己在配什么。Ceph 尤其典型：一套集群里 MON、OSD、MDS、MGR 各管一摊，CRUSH 规则、PG 数量、副本策略、存储池类型互相咬合，任何一个参数拍脑袋填，后面排查起来就是黑匣子。这份 linux-Ceph 中文文档资源，本质上就是把这套东西从「英文文档啃不动、社区帖子东一榔头西一棒子」的状态，拉回到一条能顺着读、能对着敲的主线上。它适合两类人：一类是刚接手 Ceph 集群、需要快速把部署和运维流程跑通的运维工程师；另一类是已经在用但总在 PG 状态、OSD 掉线、容量告警上反复翻车、想回头补底层逻辑的开发者。下面我按自己拆文档的习惯，把这份资源怎么用、哪些章节值得先啃、哪些参数容易踩坑，一条条摊开讲。
2. 文档结构与阅读路径：先建立集群心智模型
拿到一份中文文档，最忌讳从第一页顺序读到最后一页。Ceph 的知识是网状的，部署命令和底层概念强耦合，顺序读很容易在「什么是 CRUSH」还没吃透的时候就被一堆ceph osd命令淹没。我的做法是先花半小时把文档的章节骨架摸清楚，判断它覆盖的是部署层、运维层还是原理层，再决定从哪切入。
2.1 判断文档覆盖范围与版本对应关系
Ceph 的文档有个特点：不同大版本的命令差异不小，尤其是ceph-deploy退场、cephadm上位之后，老教程里的部署步骤直接照抄会翻车。所以拆文档第一步不是读内容，而是确认它讲的是哪条技术路线。常见做法是翻到部署章节，看它用的是ceph-deploy、ceph-ansible还是cephadm，这三个词基本能定位文档的年代和适用场景。
我一般会建一张对照表，把文档里出现的组件和命令归位，避免读到后面忘了前面：
| 组件 | 职责 | 文档里常见命令前缀 | 排查时先看什么 |
|---|---|---|---|
| MON | 维护集群地图与仲裁 | ceph mon | quorum 是否完整 |
| OSD | 实际存数据、管副本 | ceph osd | up/in 状态、磁盘健康 |
| MDS | 提供 CephFS 元数据 | ceph mds | active/standby 切换 |
| MGR | 收集指标、跑模块 | ceph mgr | 模块是否 enable |
| CRUSH | 决定数据落盘位置 | ceph osd crush | 规则与故障域层级 |
这张表不是让你背，而是读文档时随手对照。看到某个章节讲 OSD 扩容，就顺手确认它有没有提到 CRUSH 权重调整，因为加盘不加权重，数据分布照样歪。文档如果只给命令不给权重说明，那这一节就得打个问号，后面自己补。
2.2 用一条最小可用路径验证文档可复现性
文档写得再全，不跑一遍都是纸上谈兵。我的习惯是先挑一条最小路径：单机或三节点、最小副本数、跑通「建集群 → 建池 → 写对象 → 读回来」这条链路，验证文档里的命令在当前环境能不能对上。这一步不是为了搭生产环境，而是为了暴露文档和实际版本之间的偏差。
以常见的cephadm路线为例，最小验证大致是这样一串操作：
# 引导一个单节点集群，--skip-monitoring-stack 先跳过监控组件，减少干扰 cephadm bootstrap --mon-ip 192.168.1.10 --skip-monitoring-stack # 确认集群健康状态，HEALTH_OK 之前不要往下走 ceph -s # 建一个副本数为 2 的测试池，pg_num 先给小值 ceph osd pool create testpool 32 32 # 设置池的应用类型，不设会有 HEALTH_WARN ceph osd pool application enable testpool rbd # 写入一个测试对象再读回，验证数据通路 rados -p testpool put testobj /etc/hostname rados -p testpool get testobj /tmp/testobj.out这段命令的逻辑很直白：bootstrap负责把 MON、MGR 拉起来并生成密钥环，--skip-monitoring-stack是为了在验证阶段少装 Prometheus 那一套，避免端口冲突干扰判断；pool create的两个 32 分别是pg_num和pgp_num，测试环境给小值是为了快速达到 active+clean；application enable这步很多人漏掉，结果ceph -s一直挂一条警告，误以为是集群坏了。参数上唯一要留意的是--mon-ip，必须填本机真实可达的地址，填 127.0.0.1 在后续加节点时会直接卡住。
跑通这条链路，你就知道这份文档的部署章节能不能信。如果命令报「unrecognized argument」，大概率是文档对应的是旧版本，得按当前版本调整参数名，而不是怀疑自己环境坏了。
2.3 把运维章节当查询手册而非教程
文档里的运维部分，正确用法是当字典查，不是从头读。日常真正高频的就那么几类：集群健康、OSD 增删、PG 状态异常、容量与池配额。我一般会在文档里把这几个小节做上标记，出问题时直接跳过去对照命令，而不是每次从第一章翻。
比如 PG 一直卡在active+undersized+degraded，文档里通常会告诉你这是副本数不足，但不会告诉你先看哪。实际排查顺序是：先ceph osd tree看有没有 OSD 掉出，再ceph pg dump_stuck确认卡住的 PG 范围，最后才去动 CRUSH。这个顺序文档不一定写全，得靠经验补。把文档当查询入口、把排查顺序当自己的肌肉记忆，这份资源的价值才能落地。
3. 核心概念落地：把 CRUSH 和 PG 从名词变成可调参数
Ceph 文档里最容易被跳过的就是 CRUSH 和 PG 这两块，因为概念章节读起来枯燥，很多人直接跳到部署命令。但恰恰是这两块决定了集群稳不稳、扩容顺不顺。我见过太多集群，部署时一切正常，加了两块盘之后数据分布严重倾斜，回头查才发现 CRUSH 权重从来没调过。这一章就把这两个概念拆成能上手调的东西。
3.1 CRUSH 规则与故障域：数据到底落在哪
CRUSH 的本质是一套确定性哈希算法，输入是对象名和集群地图，输出是一组 OSD 编号。它的价值在于去中心化：客户端自己算，不需要问 MON 数据在哪。但这也意味着，规则一旦设错，数据分布就会以你意想不到的方式歪掉。
文档里讲 CRUSH 一般会提到 bucket 类型（host、rack、row、datacenter）和 rule。实际配置时，关键是先想清楚故障域层级。三台机器做副本，故障域设到 host 级别，意味着一份数据的三副本落在三台不同主机上，挂一台不影响可用性；如果故障域只设到 osd 级别，三副本可能全挤在一台机器上，那台机器一挂，数据直接不可用。
查看和调整的常用命令：
# 查看当前 CRUSH 地图的层级结构，确认 bucket 类型是否符合预期 ceph osd tree # 查看现有规则，重点看 step take 和 chooseleaf 的故障域类型 ceph osd crush rule dump # 新建一条以 host 为故障域的规则，供新池使用 ceph osd crush rule create-replicated host-rule default hostcreate-replicated的三个参数分别是规则名、根 bucket 名、故障域类型。这里default是根 bucket，host表示 chooseleaf 时按主机选。参数改动的边界在于：故障域类型必须和你的物理拓扑匹配，如果你的机器都在同一个机柜，却把故障域设成 rack，那 CRUSH 会认为所有 OSD 在同一 rack 下，副本照样可能挤在一起。所以配之前先osd tree看清楚层级，别对着文档抄参数。
3.2 PG 数量估算：一个公式和三个修正项
PG 数量是 Ceph 里最经典的「拍脑袋参数」。文档一般会给一个公式：PG 总数 = (OSD 总数 × 100) / 副本数，然后取最接近的 2 的幂。这个公式能用，但直接套会出问题，因为它是按目标每 OSD 约 100 个 PG 估的，实际还要看池的数量和未来扩容。
我一般按这个流程算：
# 假设 12 个 OSD，3 副本，先按公式估总 PG # (12 * 100) / 3 = 400，取 2 的幂为 512 # 如果集群要建 4 个池，512 是总数，单池约 128 ceph osd pool create pool_a 128 128 ceph osd pool create pool_b 128 128 # 建完后检查 PG 分布是否均衡 ceph osd df tree三个修正项要记住：第一，PG 总数是集群级的，不是单池的，多池要分摊；第二，pg_num调大容易调小难，扩容前宁可略大；第三，pgp_num要和pg_num同步调整，只改前者不改后者，PG 会卡在creating状态。文档如果只给公式不给这三条，照着做大概率会在扩容时踩坑。osd df tree的输出里看%USE那一列，如果各 OSD 差异超过 20%，说明 PG 分布或权重有问题，得回头查 CRUSH。
3.3 存储池类型与副本策略的选型
文档里会区分 replicated 池和 erasure coded 池。前者靠多副本保可靠，后者靠纠删码省空间。选型上没有绝对优劣，看场景：对写延迟敏感、数据量不大的，用副本池；对容量敏感、能接受一定计算开销的，用 EC 池。
实际配置时，副本池的关键参数是size和min_size。size是副本数，min_size是允许写入的最小副本数。常见误配是把min_size设成和size一样，结果挂一个 OSD 整个池就拒绝写入。合理做法是 3 副本配min_size 2：
# 设置池的副本数为 3，最小可用副本为 2 ceph osd pool set testpool size 3 ceph osd pool set testpool min_size 2 # 确认设置生效 ceph osd pool get testpool size ceph osd pool get testpool min_size这两个参数的含义要分清：size决定写几份，min_size决定低于几份就停止写入。设成 3/2 意味着允许一份副本暂时不可用但集群仍可写，这是可用性和一致性的折中。文档如果只讲size不讲min_size，那这一节是不完整的，得自己补上。
4. 避坑与排查：五个真实翻车现场
文档给的是正确路径，但实际运维里出问题的往往是路径之外的边角。这一章列五个我在 Ceph 上反复见到的坑，每个都按「现象 → 原因 → 解决」拆开，方便对照自己的集群。
4.1 集群一直 HEALTH_WARN，pool 没有 application 标签
现象：ceph -s显示HEALTH_WARN，提示application not enabled on X pool(s)，但集群能正常读写。
原因：新版本 Ceph 要求每个池声明用途（rbd、cephfs、rgw），没声明就挂警告。文档里建池命令如果没带application enable，照抄就会留这个尾巴。
解决：对每个池补一条ceph osd pool application enable <poolname> rbd，用途按实际填。补完警告消失，不需要重启任何服务。
4.2 OSD 加盘后数据倾斜，%USE 差异超过 30%
现象：新加两块盘，ceph osd df tree里新 OSD 使用率明显低于老 OSD，部分 PG 迟迟不重平衡。
原因：新 OSD 的 CRUSH 权重默认按容量算，但如果老集群权重是手工设过的固定值，新盘进来后权重比例不对，数据就不会按预期迁移。
解决：先ceph osd crush reweight <osd-id> <weight>按实际容量调整权重，再用ceph osd primary-affinity控制主副本分布。调整后观察ceph -w里的 recovery 进度，别一次性调太多，避免恢复流量打满。
4.3 PG 卡在 creating 状态不动
现象：新建池后ceph pg stat显示大量 PG 处于creating，长时间不转active+clean。
原因：pgp_num没跟上pg_num，或者 PG 数量设得过大导致创建过程本身耗时。文档里如果只写pg_num不写pgp_num，很容易漏。
解决：先确认ceph osd pool get <pool> pgp_num和pg_num一致，不一致就ceph osd pool set <pool> pgp_num <同值>。如果一致还卡，看ceph health detail有没有 OSD 相关告警，PG 创建依赖 OSD 可用。
4.4 MON quorum 丢失，集群命令全部超时
现象：任何ceph命令都返回超时，ceph -s卡住，日志里出现monclient(hunting)。
原因：MON 节点之间网络不通或时钟偏差过大，导致 quorum 无法形成。Ceph 对时间敏感，节点间时间不同步会直接破坏 MON 通信。
解决：先确认 MON 节点间网络可达，再检查时间同步状态。恢复 quorum 后，用ceph mon stat确认成员完整。这类问题文档里通常一笔带过，但实际是最容易让整个集群「失联」的坑。
4.5 删除池后空间没释放
现象：ceph osd pool delete执行完，ceph df显示容量没回来。
原因：池删除是异步的，底层 PG 和对象需要时间回收；另外如果开了mon_allow_pool_delete为 false，删除命令实际没生效但没报明显错误。
解决：先ceph config get mon mon_allow_pool_delete确认允许删除，再ceph osd pool delete <pool> <pool> --yes-i-really-really-mean-it强制删。删完用ceph pg stat观察 PG 数量下降，容量回收需要等后台完成，别急着判定失败。
5. 进阶用法：用文档里的监控章节搭一套可验证的健康基线
文档后半段通常会讲监控和告警，这部分很多人跳过，觉得集群能跑就行。但 Ceph 的问题往往是渐进的：今天一个 OSD 慢，明天两个 PG 降级，等到业务感知到延迟，已经积累了一堆连锁反应。我的做法是借文档里的监控章节，搭一套最小健康基线，让问题在早期就暴露。
具体来说，先确认 MGR 的 dashboard 和 prometheus 模块是否启用：
# 查看 MGR 已启用的模块 ceph mgr module ls # 启用 prometheus 模块，暴露指标端口 ceph mgr module enable prometheus # 确认端口，默认 9283 ceph mgr servicesmgr module ls会列出 enabled 和 disabled 两组，prometheus 在 disabled 里就手动 enable。ceph mgr services返回的 JSON 里能看到 prometheus 的监听地址，拿这个地址配采集就行。参数上唯一要注意的是 MGR 有多个实例时，prometheus 模块只在一个 active MGR 上跑，standby 不暴露端口，采集目标要指向 active 那个。
基线指标我一般盯四个：OSD up/in 数量、PG 非 active+clean 的比例、集群容量使用率、恢复流量。前两个反映可用性，后两个反映容量和性能压力。把这四个做成阈值告警，比等业务报障再查要主动得多。文档里如果给了 dashboard 截图但没给指标含义，就自己对着ceph -s的输出逐项对，把每个字段和告警条件挂上钩。
还有一个容易被忽略的点：文档里的调优参数不要照抄。比如osd_recovery_max_active调大能加快恢复，但会挤占前端 IO；osd_client_op_priority和osd_recovery_op_priority的比例决定读写和恢复谁优先。这些参数没有通用最优值，得按自己集群的负载类型试。我一般先在测试环境改一个参数、压一轮、看ceph osd perf的延迟变化，确认没有副作用再上生产。
从那以后我每次接手一个新集群，都会先把这份文档的监控章节过一遍，把四个基线指标配好再谈其他优化——没有基线的调优都是玄学。希望这份拆解能帮到你，少走几段我踩过的弯路。
本文还有配套的精品资源，点击获取
