企业官网建设流程全解析

Ceph cephadm 命令行工具完全指南：本地主机的容器化编排管理

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

cephadm 是 Ceph 分布式存储系统中用于管理本地主机的命令行工具，是 cephadm 编排器（orchestrator）在单台节点上的执行入口。它提供了一套面向单机的命令，用来检查、部署、调试和清理本机上与集群相关的各类守护进程容器。读完本文，你将掌握 cephadm 的全部全局选项与 20 余个子命令的用法，能够在引导集群、排查守护进程、迁移旧部署、配置自定义镜像仓库等真实场景中直接上手操作，并结合仓库源码理解每个命令背后的实现机制。

cephadm 是什么：定位与适用场景

cephadm 是一个 Python 3 实现的命令行工具，其核心实现位于仓库 src/cephadm/cephadm.py（单文件、约六千余行），配套的常量定义与子模块位于 src/cephadm/cephadmlib。

它面向 cephadm orchestrator 管理本地主机，主要用途包括：

• 调查某个特定守护进程的状态（如容器是否在运行、版本是多少）；
• 修改当前主机的状态（如部署、移除守护进程，操作 systemd 单元）；
• 进入容器执行调试命令、查看日志。

需要特别说明的是：cephadm并非要求部署在所有主机上，但当你需要调查某个守护进程时，它是最直接的工具。集群层面的编排操作（如ceph orch apply）通常由 Manager 模块通过 SSH 在远端主机上调用 cephadm 完成，这与本文聚焦的"本地单机管理"视角相互补充。

全局命令行语法（Synopsis）

cephadm 的完整调用形式如下，全局选项位于子命令之前：

cephadm [-h] [--image IMAGE] [--docker] [--data-dir DATA_DIR] [--log-dir LOG_DIR] [--logrotate-dir LOGROTATE_DIR] [--unit-dir UNIT_DIR] [--verbose] [--timeout TIMEOUT] [--retry RETRY] [--no-container-init] {version,pull,inspect-image,ls,list-networks,list-rdma,adopt,rm-daemon,rm-cluster,remove-file,deploy-file,run,shell,enter,ceph-volume,unit,logs,bootstrap,deploy,check-host,prepare-host,prepare-host-sudo-hardening,setup-ssh-user,add-repo,rm-repo,install,list-images,update-osd-service} ...

每个子命令又有自己的参数，例如：

cephadm pull cephadm --image IMAGE_NAME inspect-image cephadm ls [-h] [--no-detail] [--legacy-dir LEGACY_DIR] cephadm list-networks cephadm list-rdma cephadm bootstrap [-h] [--config CONFIG] [--mon-id MON_ID] ... cephadm deploy --name NAME --fsid FSID [--config CONFIG] ... cephadm shell [--fsid FSID] [--name NAME] [--config CONFIG] [--keyring KEYRING] --mount [MOUNT ...] [--env ENV] [--] [command ...] cephadm unit [--fsid FSID] --name NAME command cephadm logs [--fsid FSID] --name NAME [command ...] cephadm registry-login [--registry-url URL] [--registry-username USER] [--registry-password PASS] [--registry-json FILE] [--fsid FSID]

全局选项（Options）

下表汇总了作用于所有子命令的全局选项，括号中为文档声明的默认值：

这些默认值在源码中有对应定义。从 src/cephadm/cephadmlib/constants.py 可以看到：DATA_DIR = '/var/lib/ceph'、LOG_DIR = '/var/log/ceph'、LOGROTATE_DIR = '/etc/logrotate.d'、UNIT_DIR = '/etc/systemd/system'、CEPH_DEFAULT_CONF = '/etc/ceph/ceph.conf'，且目录权限掩码被设置为DATA_DIR_MODE = 0o700、LOG_DIR_MODE = 0o770，这解释了守护进程数据目录权限收紧（仅属主可读写）而日志目录允许组访问的设计。另外CONTAINER_INIT = True表明默认情况下容器会以 PID 1 init 进程启动，这也是--no-container-init存在的原因。

集群引导：bootstrap

bootstrap是使用 cephadm 部署新集群的起点命令。它在本地主机上引导出一个全新集群：部署一个 Monitor 和一个 Manager，随后自动在该主机上部署监控栈（Prometheus、Grafana、Alertmanager、Node Exporter），并调用ceph orch host add $(hostname)把本机登记为集群主机。

参数详解

源码视角：bootstrap 的执行流程

从 src/cephadm/cephadm.py 的command_bootstrap实现可以看出引导过程的典型步骤：

1. 若未显式指定输出文件，则把ceph.conf、ceph.keyring、公钥分别写到--output-dir下的默认文件名；若目标文件已存在且未传--allow-overwrite，直接报错拒绝覆盖；
2. 校验 SSH 私钥/公钥/签名证书参数的配对关系（私钥必须与公钥或 CA 签名证书二选一搭配）；
3. 校验 FSID 合法性，并在--data-dir/<fsid>已存在时抛出ClusterAlreadyExists避免误建重复集群；未指定 FSID 时会自动生成；
4. 非 root 的--ssh-user会先做 SSH 连通性检查；除非--skip-prepare-host，否则先执行主机准备（command_prepare_host）；
5. 检查主机名是否含.（FQDN），默认拒绝、需显式--allow-fqdn-hostname；
6. 默认先拉取镜像（_pull_image），再通过容器运行ceph --version校验镜像与 cephadm 自身的 release 是否匹配；
7. 从镜像中提取 ceph 用户的 uid/gid，生成 mon/mgr/admin 密钥与 bootstrap 密钥环，创建初始 monmap，随后按序部署 mon、mgr 等守护进程。

典型的引导命令示例：

sudo cephadm bootstrap --mon-ip 192.168.1.10 --initial-dashboard-user admin \ --initial-dashboard-password 'my-secret' --ssh-user cephadm

镜像管理：pull / inspect-image / list-images / registry-login

pull

拉取 Ceph 容器镜像到本地：

cephadm pull

默认使用--image指定的镜像或CEPHADM_IMAGE环境变量；从仓库常量看，镜像默认值定义于 src/cephadm/cephadmlib/constants.py 的DEFAULT_IMAGE。

inspect-image

检查本地 Ceph 容器镜像的元数据。从 Reef 版本起，必须用--image显式指定要检查的镜像：

cephadm --image IMAGE_NAME inspect-image

list-images

以 ini 格式列出所有服务的默认容器镜像。输出可以被修改（换成自定义镜像）后通过--config参数传给bootstrap，从而定制整个集群各服务使用的镜像版本。

registry-login

向 cephadm 提供需要认证的镜像仓库的登录信息（URL、用户名、密码），cephadm 会尝试把调用主机登录到该仓库：

cephadm registry-login --registry-url [REGISTRY_URL] --registry-username [USERNAME] --registry-password [PASSWORD]

也可以使用 JSON 文件传递登录信息，单仓库格式如下：

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

需要同时登录多个仓库时，使用如下格式：

{ "registry_credentials": [ { "url": "REGISTRY_URL1", "username": "REGISTRY_USERNAME1", "password": "REGISTRY_PASSWORD1" }, { "url": "REGISTRY_URL2", "username": "REGISTRY_USERNAME2", "password": "REGISTRY_PASSWORD2" } ] }

然后通过--registry-json提交：

cephadm registry-login --registry-json [JSON FILE]

参数：--registry-url（仓库 URL，如 docker.io、quay.io）、--registry-username、--registry-password、--registry-json、--fsid。该命令与bootstrap的--registry-*参数互补：引导时既可直接传 URL/用户名/密码，也可用同格式的 JSON 文件。

主机检查与准备

check-host

检查主机配置是否适合承载 Ceph 集群：

cephadm check-host [--expect-hostname EXPECT_HOSTNAME]

--expect-hostname用于校验主机名是否与期望值一致。

prepare-host

为 cephadm 的使用准备主机，--expect-hostname可设定期望的主机名。

prepare-host-sudo-hardening

为 sudo 加固准备主机：授权 SSH 密钥、安装/升级 cephadm 包，并配置受限的 sudoers 权限：

cephadm prepare-host-sudo-hardening --ssh-user cephadm --ssh-pub-key <key>

该命令依次执行三步：

1. 为指定用户授权提供的 SSH 公钥；
2. 安装或升级 cephadm 包到与集群版本一致（该包内含cephadm_invoker.py，其实现位于 src/cephadm/cephadm_invoker.py）；
3. 为cephadm_invoker.py配置受限的 sudoers 权限。

参数：--ssh-user（用于密钥授权的 SSH 用户，默认 root）、--ssh-pub-key（要授权的公钥）、--cephadm-version（指定要安装的 cephadm 版本）。

setup-ssh-user

配置带免密 sudo 和 SSH 密钥授权的 SSH 用户：

cephadm setup-ssh-user --ssh-user cephadm --ssh-pub-key <public_key>

执行步骤：

1. 校验用户已存在于系统中；
2. 为该用户设置免密 sudo（root 用户跳过）；
3. 把 SSH 公钥加入用户的authorized_keys。

该命令会被ceph cephadm set-user自动调用，用于在集群所有主机上配置 SSH 用户。参数：--ssh-user（必填）、--ssh-pub-key（必填）。

list-networks / list-rdma

• list-networks：列出主机的 IP 网络；
• list-rdma：列出 RDMA 设备及其对应的 netdev 接口。

这两个命令在排查网络规划、确认 mon 监听地址或 RDMA 网卡归属时非常实用。

守护进程管理：ls / deploy / run / unit / logs / enter

ls

列出当前主机上 cephadm 已知的守护进程实例，输出为 JSON 数组：

$ cephadm ls [ { "style": "cephadm:v1", "name": "mgr.storage-14b-1.ysubfo", "fsid": "5110cb22-8332-11ea-9148-0894ef7e8bdc", "enabled": true, "state": "running", "container_id": "8562de72370a3836473ecfff8a22c9ccdd99815386b4692a2b30924fb5493c44", "container_image_name": "quay.io/ceph/ceph:v20", "container_image_id": "bc83a388465f0568dab4501fb7684398dca8b50ca12a342a57f21815721723c2", "version": "20.2.3", "started": "2020-04-21T01:16:41.831456", "created": "2020-04-21T01:16:41.775024", "deployed": "2020-04-21T01:16:41.415021", "configured": "2020-04-21T01:16:41.775024" }, ...

每个条目包含部署风格（style）、守护进程名（type.id格式）、FSID、systemd 是否启用（enabled）、运行状态、容器 ID、镜像名与镜像 ID、Ceph 版本，以及 started/created/deployed/configured 四个时间戳，可用于判断守护进程的生命周期。参数：--no-detail（不包含守护进程状态）、--legacy-dir（legacy 守护进程数据的基目录）。

deploy

在本地主机上部署一个守护进程，通常由 orchestrator CLI 在后台调用：

cephadm shell -- ceph orch apply <type> ...

参数：

• --name NAME：守护进程名（type.id，必填）；
• --fsid FSID：集群 FSID（必填）；
• --config CONFIG, -c CONFIG：新守护进程的配置文件；
• --config-json CONFIG_JSON：JSON 格式的附加配置信息；
• --keyring KEYRING：新守护进程的密钥环；
• --key KEY：新守护进程的密钥；
• --osd-fsid OSD_FSID：创建 OSD 容器时的 OSD UUID；
• --skip-firewalld：不配置 firewalld；
• --tcp-ports TCP_PORTS：需要在主机防火墙中放行的 TCP 端口列表；
• --reconfig：重新配置之前已部署的守护进程；
• --allow-ptrace：允许守护进程容器启用SYS_PTRACE。

run

在前台、以容器方式运行一个 Ceph 守护进程。参数：--name NAME（必填）、--fsid FSID（必填）。适合手动前台调试某个守护进程的启动过程。

unit

对守护进程对应的 systemd 单元执行操作：

cephadm unit --fsid <fsid> --name <name> start

位置参数command是 systemd 命令（start、stop、restart、enable、disable等，必填）；参数为--fsid与--name。从源码看，systemd 单元默认安装在--unit-dir（即/etc/systemd/system），与 src/cephadm/cephadmlib/systemd.py 中的封装逻辑对应。

logs

打印守护进程容器的 journald 日志，等价于对 systemd 单元执行journalctl：

cephadm logs --name mgr.myhost.ysubfo

等价于：

journalctl -u mgr.myhost.ysubfo

可以在--之后追加 journalctl 的参数：

cephadm logs --name mgr.myhost.ysubfo -- -n 20 # 只看最后 20 行 cephadm logs --name mgr.myhost.ysubfo -- -f # 持续跟踪日志

位置参数为可选的 journal 参数；参数：--fsid、--name（必填）。

enter

进入一个正在运行的守护进程容器，得到交互式 shell：

cephadm enter --name mgr.myhost.ysubfo

位置参数command为容器内要执行的命令；参数：--fsid、--name（必填）。从 src/cephadm/cephadm.py 的command_enter实现看，它会根据守护进程名推断 FSID 与容器身份，然后以交互模式（-i）进入容器。与shell相比，enter严格绑定某个已运行的守护进程容器，而shell是启动一个独立的临时容器。

交互式容器：shell / ceph-volume

shell

启动一个交互式 shell：

cephadm shell

或者在容器内执行单条命令后退出：

cephadm shell -- ceph orch ls

位置参数command可选；参数：

• --fsid FSID：集群 FSID；
• --name NAME, -n NAME：守护进程名（type.id）；
• --config CONFIG, -c CONFIG：传入容器的ceph.conf；
• --keyring KEYRING, -k KEYRING：传入容器的ceph.keyring；
• --mount MOUNT, -m MOUNT：把文件或目录挂载到容器内的/mnt下；
• --env ENV, -e ENV：设置容器环境变量。

shell是排查集群问题最常用的入口。从 src/cephadm/cephadm.py 的command_shell实现可以看到若干值得注意的细节：

• 容器以privileged（特权）方式运行，便于执行网络、存储相关的调试操作；
• 未指定--name时使用shell类型的一套精简挂载；指定--name时会按该守护进程的 identity 挂载对应数据目录；
• 默认会把宿主机的/var/lib/ceph只读挂载到容器内的/srv/ceph（ro,z），z标记适配 SELinux；
• --mount 源:目标支持显式指定容器内目标路径；不指定目标时默认挂到/mnt/<文件名>；
• 未传入命令时默认进入bash，并设置自定义PS1提示符（CUSTOM_PS1），且把/var/lib/ceph/<fsid>/home作为容器内 root 的 home 目录（首次进入时从/etc/skel复制 bash 配置）。

ceph-volume

在容器内运行 ceph-volume 命令，例如：

cephadm ceph-volume inventory

位置参数command为 ceph-volume 子命令（必填）；参数：--fsid、--config-json（含配置与client.bootstrap-osd密钥的 JSON 文件）、--config/-c（ceph.conf文件）、--keyring/-k（传入容器的ceph.keyring）。crape-volume 的完整用法可参考仓库中的 ceph-volume(8) 手册。OSD 部署场景下，--config-json通常由 orchestrator 生成，内含 OSD 引导所需的配置与 bootstrap-osd 密钥环。

文件操作：remove-file / deploy-file

这两个命令用于编排器在主机间安全地传递配置文件。

remove-file

删除本地主机上的一个普通文件，路径不存在时静默忽略：

cephadm remove-file --fsid <fsid> --path /absolute/path

参数：--fsid、--path（要删除文件的绝对路径，必填）。

deploy-file

向本地主机写入或替换一个文件。整个文件内容从标准输入按原始字节读取（不做任何编码或换行转换），这对保持配置文件的字节级一致性很重要：

cat /path/to/config | cephadm deploy-file --path /etc/ceph/ceph.conf

参数：--fsid、--path（目标绝对路径，必填）、--mode（八进制文件权限，如644或0644）、--uid（属主数字 UID，必须与--gid同时给出）、--gid（属组数字 GID，必须与--uid同时给出）。该命令的实现在 src/cephadm/cephadm.py 的command_deploy_file，从源码结构看它要求 uid/gid 成对出现，以避免只改属主或只改属组造成权限不一致。

守护进程/集群清理：rm-daemon / rm-cluster

rm-daemon

移除某个具体的守护进程实例：

cephadm rm-daemon --name mgr.myhost.ysubfo --fsid <fsid>

参数：--name（type.id，必填）、--fsid（必填）、--force（即使可能销毁有价值数据也继续）、--force-delete-data（直接删除有价值数据而非先做备份）。

从 src/cephadm/cephadm.py 的command_rm_daemon实现可以推断：默认情况下 cephadm 会把待删除守护进程的数据备份到本地目录，而--force-delete-data会跳过备份直接删除，因此日常操作应优先使用不带该参数的版本。

rm-cluster

移除某个集群的所有守护进程：

cephadm rm-cluster --fsid <fsid>

参数：--fsid（必填）、--force（即使可能销毁有价值数据也继续）。

包与仓库管理：add-repo / rm-repo / install

add-repo

把 Ceph 软件仓库追加到本地包仓库配置中：

cephadm add-repo --release octopus # 使用命名发布版最新版本 cephadm add-repo --version 17.2.5 # 使用特定上游版本 x.y.z

参数：

• --release RELEASE：使用某个命名发布版的最新版本（如octopus）；
• --version VERSION：使用特定上游版本（x.y.z）；
• --dev DEV：使用来自指定 git 分支或 tag 的 bleeding-edge 构建；
• --dev-commit DEV_COMMIT：使用来自指定 git commit 的 bleeding-edge 构建；
• --gpg-url GPG_URL：指定备用的 GPG 公钥地址；
• --repo-url REPO_URL：指定备用的仓库地址。

rm-repo

移除包仓库配置：

cephadm rm-repo

install

安装 Ceph 软件包：

cephadm install ceph-common cephadm

位置参数packages为要安装的包名列表（可多个）。

旧部署迁移：adopt

adopt用于把由其他部署工具部署的守护进程迁移到 cephadm 管理之下：

cephadm adopt --name mon.a --style legacy --cluster <cluster-name>

参数：

• --name NAME, -n NAME：守护进程名（type.id，必填）；
• --style STYLE：部署风格（如legacy，必填）；
• --cluster CLUSTER：集群名；
• --legacy-dir LEGACY_DIR：legacy 守护进程数据的基目录；
• --config-json CONFIG_JSON：JSON 格式的附加配置信息；
• --skip-firewalld：不配置 firewalld；
• --skip-pull：采纳前不拉取最新镜像。

从源码看，adopt 针对不同守护进程类型有专门的处理逻辑（command_adopt_ceph、command_adopt_prometheus、command_adopt_grafana、command_adopt_alertmanager等，位于 src/cephadm/cephadm.py），覆盖 ceph 系守护进程与监控栈组件的迁移场景。

配置查找顺序（重要）

adopt 在启动 shell 时按以下顺序查找配置，只使用最先找到的值：

1. 用户显式指定的配置文件路径（-c/--config选项）；
2. 由--name指定的守护进程配置文件（/var/lib/ceph/<fsid>/<daemon-name>/config）；
3. /var/lib/ceph/<fsid>/config/ceph.conf（若存在）；
4. mon 守护进程的配置文件（/var/lib/ceph/<fsid>/mon.<mon-id>/config，若存在）；
5. 最后回退到默认文件/etc/ceph/ceph.conf。

这套查找逻辑与 src/cephadm/cephadmlib/context_getters.py 中get_config_and_keyring等函数的设计一致：优先使用守护进程专属配置，其次使用集群级配置，最终回退到传统/etc/ceph目录，从而兼容从 legacy 部署迁移过来的场景。

其他命令速查

可用性与延伸阅读

cephadm 是 Ceph（大规模可扩展的开源分布式存储系统）的组成部分。若要继续深入，建议阅读仓库中的以下资料：

• cephadm 实现源码：全部子命令的入口函数、容器封装（CephContainer）、SSH 与 systemd 交互逻辑；
• cephadmlib 子模块：常量、容器引擎封装、systemd 单元生成、防火墙（firewalld）配置等基础组件；
• cephadm 编排器文档：cephadm orchestrator 的完整使用指南（集群部署、主机管理、升级、运维）；
• ceph-volume(8) 手册：OSD 容器内卷管理命令的参考。

通过本文的全局选项、命令参数与源码对应关系，你可以在任意 Ceph 节点上快速完成"查状态（ls/logs）— 进容器（shell/enter）— 改配置（deploy-file/remove-file）— 清清理（rm-daemon/rm-cluster）"的完整排查闭环，为基于 cephadm 的集群运维打下坚实基础。

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