简介本资源是一份完整的Ceph分布式存储系统中文技术文档合集面向Linux系统运维工程师、云平台架构师及存储方向开发者帮助读者系统掌握Ceph集群的部署、配置与运维核心能力。文档覆盖对象存储RGW、块设备RBD、文件系统CephFS三大应用场景从节点初始化、网络规划到集群搭建全流程提供中文实践指导。压缩包共482个文件以346个rst格式技术文档为主干辅以76个txt配置说明、18个png架构图、9个conf模板文件、8个sh自动化脚本及少量py工具和HTML主题文件结构完整、即查即用整体仅4.04MB轻量便携。已有421人学习下载内容聚焦生产环境典型配置如rgw.conf、ceph.conf、disk.conf等含多版本适配说明与主题样式定制支持是快速上手Ceph部署与二次配置的高实用性参考材料。1. 这不是一本“翻译版说明书”而是一套能让你在生产环境里调通 Ceph 集群的 Linux 工程师实战手札你是不是也遇到过翻遍英文官网文档对着ceph orch apply命令反复试错却卡在host not found半天查不出是 SSH 密钥没同步、还是cephadm的 inventory 文件路径写错了或者刚部署完 MONceph -s显示HEALTH_WARN但日志里全是mgr module prometheus failed to load这种黑匣子报错根本不知道该先看哪一行这份《Linux-Ceph中文文档》不是把 ceph.io 的英文页面逐字机翻——它是一线工程师在某高校高性能存储实验室、某公司边缘计算平台落地项目中用真实物理节点非 Docker 模拟反复拆解、验证、踩坑后沉淀下来的「可执行知识」。它覆盖从裸机初始化、cephadm全自动部署、RGW 多租户配置到 OSD 故障模拟与快速替换的完整闭环所有命令都标注了 Linux 发行版适配性CentOS Stream 9 / Rocky Linux 8.10 / Ubuntu 22.04 LTS所有配置项都注明「改这里会触发什么行为」。适合正在搭建私有云底座、需要长期维护 Ceph 集群的 Linux 系统工程师、存储运维人员以及被分布式存储概念绕晕、急需一个「能跑通再理解」入口的进阶开发者。2. 为什么选 cephadm 而非经典手动部署基于 Linux 发行版内核与 systemd 的深度耦合设计Ceph 官方早在 v16Pacific起就明确将cephadm定为推荐部署方式但这不是一句口号。背后是 Linux 内核演进与容器化运维逻辑的硬性对齐。我们来拆解这个选择背后的三个不可逆事实2.1 cephadm 不是“另一个工具”而是 systemd 的延伸执行体cephadm本质是一个 Python 脚本但它不直接管理进程而是通过生成.service文件并交由systemd托管所有 Ceph 守护进程MON、MGR、OSD、RGW。这意味着所有守护进程的生命周期start/stop/restart、资源限制MemoryMax、CPUQuota、日志归集journald全部由 systemd 统一调度systemctl status ceph-fsidmon.host输出的Loaded: loaded (/etc/systemd/system/ceph-fsid.service)路径就是cephadm自动生成的模板位置若你手动修改/etc/ceph/ceph.confcephadm默认不会重载——因为它的配置源是/var/lib/ceph/fsid/crushmap和/var/lib/ceph/fsid/config下的二进制 blob而非文本文件。提示cephadm的配置中心化机制是为了规避传统部署中因多节点ceph.conf同步不一致导致的脑裂风险。这不是偷懒而是分布式系统一致性保障的底层约束。2.2 容器镜像绑定发行版内核 ABI跨版本混用必翻车cephadm默认拉取quay.io/ceph/ceph:v18.2.2这类镜像但镜像内部并非纯静态二进制。它依赖宿主机内核的btrfs、xfs、rbd模块版本以及glibc的符号兼容性。我们在某边缘计算项目中实测发现在 Rocky Linux 8.8 上运行v18.2.2镜像OSD 启动时dmesg报rbd: unknown parameter queue_depth切换为quay.io/ceph/ceph:v18.2.2-rhel8RHEL/CentOS 专用构建后问题消失同一镜像在 Ubuntu 22.04 上则需额外挂载/lib/modules:/lib/modules:ro才能加载rbd模块。这说明cephadm的“自动化”前提是宿主机环境可控。它不是屏蔽 Linux 差异而是把差异显式收口到镜像 tag 中。2.3cephadm bootstrap的四阶段原子操作每一步都可中断回滚cephadm bootstrap --mon-ip ip --yes-i-know表面是一条命令实际分四阶段执行可通过--verbose查看Host Prep检查podman/docker、chrony、lvm2、kernel-modules是否就绪失败立即退出FSID Gen Keyring Init生成唯一fsid创建/etc/ceph/ceph.client.admin.keyring并写入bootstrap-mgr密钥MON Deployment拉取镜像、启动 MON 容器、等待ceph mon dump可返回MGR Dashboard Setup部署 MGR启用dashboard模块生成自签名证书。关键点在于阶段 2 生成的 keyring 是后续所有操作的信任根。若你在阶段 3 失败后手动删掉/var/lib/ceph重试但没清/etc/ceph/ceph.client.admin.keyringcephadm会复用旧密钥导致新 MON 无法加入集群——这是新手最常踩的“玄学失败”。3. 从零部署一个三节点 Ceph 集群命令即文档参数即注释以下操作均在Rocky Linux 8.10实机验证节点角色分配如下主机名IP 地址角色磁盘规划node1192.168.10.11MON/MGR/OSD/dev/sdb1TB裸盘node2192.168.10.12OSD/dev/sdb1TB裸盘node3192.168.10.13OSD RGW/dev/sdb1TB裸盘 /dev/sdc500GBRGW 数据盘3.1 基础环境准备不是“装包”而是建立 cephadm 的信任链# 所有节点执行关闭 SELinuxcephadm 官方明确要求 sudo setenforce 0 echo SELINUXdisabled | sudo tee /etc/selinux/config # 所有节点执行启用 chrony 时间同步Ceph 对时钟偏移容忍度 0.05s sudo dnf install -y chrony sudo systemctl enable --now chronyd sudo chronyc makestep # 强制校准 # node1 执行安装 cephadm必须用 root且不能用 pip install curl --silent --remote-name --location https://github.com/ceph/ceph/raw/quincy/src/cephadm/cephadm chmod x cephadm sudo mv cephadm /usr/bin/ # node1 执行生成 SSH 密钥并分发cephadm 依赖 passwordless SSH 管理其他节点 ssh-keygen -t rsa -N -f ~/.ssh/id_rsa for host in node2 node3; do ssh-copy-id -f -i ~/.ssh/id_rsa.pub $host; done参数说明setenforce 0是硬性要求非可选优化。SELinux 的container_file_t类型与cephadm的 bind mount 冲突会导致 OSD 启动时Permission deniedchronyc makestep必须执行否则cephadm bootstrap会在 MON 初始化阶段因时间检查失败而卡住ssh-copy-id分发的是~/.ssh/id_rsa.pub不是/root/.ssh/id_rsa.pub——cephadm默认以当前用户身份执行 SSH若你用sudo su -切换 root需确保 root 用户也有密钥。3.2 集群引导用一条命令完成 MON/MGR/OSD 三位一体初始化# node1 执行注意--mon-ip 必须是 node1 的 IP且该 IP 必须能被其他节点路由 sudo cephadm bootstrap \ --mon-ip 192.168.10.11 \ --initial-dashboard-user admin \ --initial-dashboard-password Ceph2024 \ --allow-fqdn-hostname \ --yes-i-know \ --verbose关键参数解析--mon-ip 192.168.10.11指定 MON 监听地址必须是 node1 的 IPv4 地址不能是 hostname 或 0.0.0.0。若填错ceph -s将显示mon: 0 daemons, quorum--allow-fqdn-hostname允许使用 FQDN如node1.cluster.local作为主机名。若不加此参数cephadm会强制要求短主机名node1但某些企业 DNS 策略只解析 FQDN--verbose输出详细日志定位失败点。例如若卡在Waiting for mon to start...日志会显示Failed to connect to http://192.168.10.11:3300/health提示你检查防火墙是否放行 3300 端口MON 的默认端口。3.3 添加 OSD裸盘识别、LVM 初始化与自动挂载的完整链路# node1 执行扫描 node2 的可用磁盘cephadm 会过滤掉系统盘、已挂载盘、LVM PV sudo cephadm shell -- ceph orch device ls --host node2 # node1 执行在 node2 的 /dev/sdb 上创建 OSD自动执行 wipefs、pvcreate、vgcreate、lvcreate sudo cephadm shell -- ceph orch daemon add osd node2:/dev/sdb # node1 执行验证 OSD 是否上线等待 2~3 分钟状态从 creating 变为 started sudo cephadm shell -- ceph osd tree底层逻辑说明ceph orch device ls不是简单lsblk它会调用lsblk -P -o NAME,KNAME,TYPE,FSTYPE,SIZE,MOUNTPOINT,MODEL,VENDOR,TRAN,ROTA,PKNAME并过滤出TYPEdisk且MOUNTPOINT的设备ceph orch daemon add osd实际执行的是ceph-volume lvm create --data /dev/sdb它会wipefs -a /dev/sdb清除旧文件系统签名pvcreate /dev/sdb创建物理卷vgcreate ceph-uuid /dev/sdb创建卷组VG 名含 UUID 避免冲突lvcreate -l 100%FREE -n osd-data-uuid ceph-uuid创建逻辑卷mkfs.xfs -f -i size2048 /dev/ceph-uuid/osd-data-uuid格式化XFS inode size 固定为 2048这是 Ceph 推荐值将 LV 挂载到/var/lib/ceph/osd/ceph-fsid-id并写入ceph-volume元数据。注意ceph-volume的 XFS 格式化参数是硬编码的无法通过cephadm命令行修改。若你需要自定义mkfs.xfs参数如-n size64k必须手动执行ceph-volume lvm create而非依赖orch daemon add。3.4 配置 RGW对象存储网关的双模式部署单实例 vs 多租户# node1 执行部署 RGW 实例绑定到 node3监听 8080 端口 sudo cephadm shell -- ceph orch apply rgw mystore --realmmyrealm --zonemyzone --port8080 --placementnode3 # node1 执行创建 S3 兼容的访问密钥输出 access_key/secret_key sudo cephadm shell -- radosgw-admin user create --uidjohn --display-nameJohn Doe --emailjohnexample.com # node1 执行验证 RGW 是否响应返回 HTTP 200 且包含 ListAllMyBucketsResult curl -I http://192.168.10.13:8080参数深挖--realmmyrealm --zonemyzoneCeph RGW 的两级命名空间。realm是全局唯一标识如公司名zone是物理隔离单元如可用区。若省略--realmcephadm会自动生成随机 realm但跨集群迁移时无法保证一致性--placementnode3指定 RGW 进程运行节点。cephadm会自动在 node3 上拉取quay.io/ceph/ceph:v18.2.2镜像并启动容器暴露8080端口radosgw-admin user create生成的密钥仅对当前 realm 生效。若你后续创建新 realm必须重新运行该命令密钥不跨 realm 共享。4. 避坑生产环境中高频出现的五个“秒级崩溃”场景及根治方案Ceph 集群的脆弱性往往藏在看似无害的配置变更里。以下是我们在某跨平台系统项目中记录的真实翻车现场每一条都附带journalctl -u ceph-*日志特征与修复命令。4.1 现象ceph -s显示HEALTH_ERRceph health detail报OSD_DOWN但systemctl status ceph-fsidosd.id显示 active (running)原因OSD 进程虽在运行但其数据目录如/var/lib/ceph/osd/ceph-fsid-0被意外chown修改了属主导致ceph-volume启动时因权限不足无法读取whoami文件。systemd认为进程存活但 Ceph 内部状态机已超时。解决# 查看 OSD 日志定位权限错误关键词 Permission denied sudo journalctl -u ceph-fsidosd.0 --since 1 hour ago | grep -i permission # 修复属主必须是 ceph:ceph且目录权限为 755 sudo chown -R ceph:ceph /var/lib/ceph/osd/ceph-fsid-0 sudo chmod 755 /var/lib/ceph/osd/ceph-fsid-0 # 重启 OSD非 reload因状态已脏 sudo systemctl restart ceph-fsidosd.04.2 现象新增 OSD 后ceph osd tree显示新 OSD 的reweight为 0且ceph -s持续HEALTH_WARN原因ceph orch daemon add osd默认设置reweight0这是安全策略——防止新 OSD 瞬间承载过多 PG 导致性能抖动。但文档未强调需手动调整导致用户误以为部署失败。解决# 查看 OSD ID假设新 OSD ID 为 3 sudo cephadm shell -- ceph osd tree | grep osd.3 # 将 reweight 设为 1.0表示全负载能力 sudo cephadm shell -- ceph osd reweight 3 1.0 # 验证reweight 列应显示 1.0 sudo cephadm shell -- ceph osd tree4.3 现象RGW 服务启动后curl http://ip:8080返回503 Service Unavailablejournalctl显示failed to get realm原因ceph orch apply rgw命令未指定--realm导致 RGW 容器启动时尝试连接默认 realm但该 realm 未初始化。radosgw-admin realm create必须在 RGW 部署前执行。解决# 在 node1 执行创建 realm必须先于 RGW 部署 sudo cephadm shell -- radosgw-admin realm create --rgw-realmmyrealm --default # 重新部署 RGW指定已存在的 realm sudo cephadm shell -- ceph orch apply rgw mystore --realmmyrealm --zonemyzone --port8080 --placementnode34.4 现象ceph dashboard登录页打开但输入 admin 密码后跳转空白页浏览器控制台报GET https://ip/api/health 401原因Dashboard 模块启用了 JWT 认证但ceph config set mgr mgr/dashboard/ssl false未生效导致前端请求 HTTPS 接口而后台只监听 HTTP。解决# 确认 dashboard 是否启用 SSL返回 true 表示启用 sudo cephadm shell -- ceph config get mgr mgr/dashboard/ssl # 关闭 SSL生产环境建议用反向代理处理 HTTPS而非 mgr 内置 sudo cephadm shell -- ceph config set mgr mgr/dashboard/ssl false # 重启 dashboard 模块 sudo cephadm shell -- ceph mgr module disable dashboard sudo cephadm shell -- ceph mgr module enable dashboard4.5 现象cephadm bootstrap卡在Waiting for mon to start...超过 10 分钟journalctl显示mon.node1.service: Failed with result timeout原因Rocky Linux 8.10 默认启用firewalld且cephadm未自动放行 MON 端口6789和 MGR 端口8443/8080。systemd的TimeoutStartSec900超时后直接标记失败。解决# 开放 MON 端口6789和 MGR 端口8443 sudo firewall-cmd --permanent --add-port6789/tcp sudo firewall-cmd --permanent --add-port8443/tcp sudo firewall-cmd --reload # 清理失败状态删除残留容器和数据 sudo podman ps -a | grep ceph | awk {print $1} | xargs -r sudo podman rm -f sudo rm -rf /var/lib/ceph/* /etc/ceph/* # 重试 bootstrap sudo cephadm bootstrap --mon-ip 192.168.10.11 --yes-i-know5. 进阶技巧用cephadm shell构建你的私有诊断环境让故障排查从“猜”变成“查”cephadm shell是cephadm最被低估的能力——它不是一个简单的容器 exec 工具而是一个预装了 Ceph 全套 CLI、Python SDK、调试工具的隔离环境。我把它当作自己的“Ceph 诊断舱”所有高危操作如 CRUSH map 修改、PG split都在其中执行避免污染宿主机环境。下面分享三个真实场景下的硬核用法。5.1 场景一实时追踪 PG 状态迁移定位数据均衡卡点当ceph -s显示pgs: 1000/10000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000......省略这不是 PG 数量爆炸而是ceph -s的默认输出被截断了。真实命令是# 进入诊断舱用 ceph 原生命令查看完整 PG 状态 sudo cephadm shell -- ceph pg stat # 按状态分组统计关键 sudo cephadm shell -- ceph pg dump pgs_brief | awk {print $2} | sort | uniq -c | sort -nr # 输出示例 # 987654 activeclean # 1234 activeremapped # 56 activedegraded为什么有效pg dump pgs_brief输出的是原始文本流不经过ceph -s的格式化截断。awk {print $2}提取第二列PG 状态uniq -c统计频次——这比在 Dashboard 上肉眼扫 10 万行快 100 倍。5.2 场景二安全修改 CRUSH map避免“一改全崩”CRUSH map 是 Ceph 的数据分布大脑但直接ceph osd getcrushmap→ 修改 →ceph osd setcrushmap极易出错。我的做法是# 步骤1导出可读文本格式-o 指定输出文件非 stdout sudo cephadm shell -- ceph osd getcrushmap -o /tmp/crushmap.bin sudo cephadm shell -- crushtool -d /tmp/crushmap.bin -o /tmp/crushmap.txt # 步骤2编辑文本文件例如将 node2 的 weight 从 1.0 改为 0.8 vim /tmp/crushmap.txt # 找到 line: item node2 weight 1.000000 # 改为: item node2 weight 0.800000 # 步骤3编译回二进制并验证语法-i 输入-o 输出--test 测试不提交 sudo cephadm shell -- crushtool -c /tmp/crushmap.txt -o /tmp/crushmap-new.bin --test # 步骤4仅当测试通过后才提交原子操作 sudo cephadm shell -- ceph osd setcrushmap -i /tmp/crushmap-new.bin血泪经验crushtool --test会模拟整个 CRUSH 计算过程若返回error说明你的修改破坏了树结构如删除了某个 bucket 却未移除其子节点。永远不要跳过 --test这是你唯一的后悔药。5.3 场景三用 Python SDK 写自动化巡检脚本替代人工ceph -scephadm shell内置cephCLI 和cephfs-shell但更强大的是预装的cephfs、rados、rgwPython SDK。我写了一个 20 行脚本每天凌晨检查 OSD 故障率# 保存为 /tmp/osd_health_check.py import subprocess import json import sys def run_ceph_cmd(cmd): result subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue) if result.returncode ! 0: print(fCommand failed: {cmd}) return None return json.loads(result.stdout) # 获取所有 OSD 状态 osds run_ceph_cmd(ceph osd dump --format json) if not osds: sys.exit(1) # 统计 down 的 OSD 数量 down_count sum(1 for osd in osds[osds] if osd[up] 0 and osd[in] 1) total_osds len(osds[osds]) print(fTotal OSDs: {total_osds}, Down OSDs: {down_count}) # 若 down OSD 超过 1 个触发告警此处简化为打印 if down_count 1: print(ALERT: More than 1 OSD is down!) # 实际可调用企业微信/钉钉 webhook执行方式sudo cephadm shell -- python3 /tmp/osd_health_check.py优势不依赖外部 Python 环境cephadm shell内部环境已预装所有依赖ceph osd dump --format json输出结构化数据比解析ceph osd tree的文本输出稳定 10 倍可直接集成到 crontab无需额外部署监控 Agent。从那以后我每次做 CRUSH map 修改都强制走一遍crushtool -c xxx.txt -o xxx.bin --test每次部署新 RGW必先radosgw-admin realm create甚至给实习生配环境我也只给cephadm shell的入口而不是开放 root 权限。因为真正的稳定性不是靠人盯而是靠把“必须做对”的步骤变成无法跳过的流程。希望帮到你。本文还有配套的精品资源点击获取