1. 环境搭建与 Cephadm 引导
1.1 环境前提
在进行 Ceph 存储 的 Python 接入 之前，需明确目标环境与依赖。Ndmin 级别的 Ceph 集群通常先从单机演示开始，随后扩展为多节点架构。本文以使用 Cephadm 进行部署为主线，便于后续通过 RGW、CephFS 等接口对外暴露存储能力。为了确保稳定性，建议选择 Ubuntu 22.04LTS 及以上版本，并预装 Python 3、pip，以及 Docker/Podman 等容器运行时。
在搭建 Ceph 集群之前，需要准备一个可路由的网络环境，以及对节点的 ssh 无密码访问，便于 cephadm 在各节点上执行远程安装与配置。网络连通性、时间同步、以及对 /etc/hosts 的一致性都是关键要素。下面的步骤将引导你从环境准备到 Ceph 集群的初步搭建。
# 安装 cephadm 脚本（在管理节点执行）
curl -fsSL https://ceph.io/cephadm.sh -o cephadm.sh
sudo bash cephadm.sh# 验证 cephadm 版本
cephadm version
接下来通过 Cephadm 引导一个简单的监视器（Mon）/管理器（Mgr）集群。bootstrap 能在一台机器上快速启动一个初始集群，后续可逐步扩展。
# 使用单机示例启动 Ceph 集群（MON/Mgr/OSD 的初步配置示例）
cephadm bootstrap --mon-ip --initial-dashboard-user admin --initial-dashboard-password admin
ceph -s
2. Ceph RGW 与对象存储对接
2.1 RGW 部署与 S3 端点创建
要实现 Python 通过 S3 兼容接口访问 Ceph 存储，需要在 Ceph 集群上开启 RADOS 网关（RGW），并创建 S3 认证用户及端点。RGW 提供对外的对象接口，结合 boto3 等 Python 客户端即可实现对象存储的上传、下载、列举等操作。下面将给出常见的部署思路、创建用户的命令以及一个可直接运行的 Python 客户端示例。
启动 RGW 的过程通常包括启用 RGW 模块、部署网关实例，以及通过 radosgw-admin 创建 S3 用户。确保你的防火墙允许对外端口 80/443（HTTPS）或自定义端点端口。完成后，你将获得 access_key 与 secret_key，用于 Python 客户端的鉴权。
# 启用 RGW 模块
ceph mgr module enable rgw
# 为 RGW 创建网关（示例：在当前主机上）
ceph rgw create --rgw-name rgw.ceph --rgw-host localhost
# 使用 radosgw-admin 创建一个 S3 用户
radosgw-admin user create --uid=s3user --display-name="S3 User" --name="S3 User"
# 记录输出中的 access_key 与 secret_key
获取到密钥后，可以在 Python 客户端直接使用 S3 API 进行对象操作。下方给出一个完整的示例，展示如何通过 Python 连接到 Ceph RGW 的 S3 端点并进行基本操作。
import boto3# 替换为实际的 RGW 端点、AK/SK
endpoint = 'https://rgw.ceph.local'
access_key = 'YOUR_ACCESS_KEY'
secret_key = 'YOUR_SECRET_KEY's3 = boto3.client('s3',endpoint_url=endpoint,aws_access_key_id=access_key,aws_secret_access_key=secret_key,region_name='us-east-1'
)bucket = 'mybucket'# 创建桶（若已存在会抛出异常，此处忽略）
try:s3.create_bucket(Bucket=bucket)
except Exception:pass# 上传对象
s3.put_object(Bucket=bucket, Key='hello.txt', Body=b'Hello Ceph RGW')
# 下载对象并输出
obj = s3.get_object(Bucket=bucket, Key='hello.txt')
print(obj['Body'].read().decode())
3. CephFS 挂载与 Python 文件读写
3.1 CephFS 挂载到本地并进行文件操作
除了对象存储，CephFS 还提供 POSIX 兼容的分布式文件系统能力。通过 ceph-fuse 或内核客户端将 CephFS 挂载到本地路径后，Python 可以像操作常规文件一样对 CephFS 进行读写，降低了应用接入的门槛。下面展示常见的挂载方式以及简单的文件写入示例。
挂载后，可以将 CephFS 当作普通磁盘来使用，路径 /mnt/cephfs 将成为应用可访问的存储根目录。确保 CephFS 的 MDS 组件处于就绪状态，并且挂载时具有相应权限。
# 创建挂载目录
sudo mkdir -p /mnt/cephfs# 使用 ceph-fuse 挂载（示例，实际参数请参考 Ceph 集群配置）
sudo ceph-fuse -n client.admin /mnt/cephfs# 或通过内核客户端直接挂载（需要内核支持 CephFS）
# sudo mount -t ceph ceph-fs.node:/ /mnt/cephfs -o name=admin,secretfile=/path/to/secret
挂载成功后，利用 Python 进行文件写入与读取非常直观。以下示例演示在 CephFS 挂载点进行基本的文本文件写入和读取。
# 在 CephFS 挂载点进行文件操作
path = '/mnt/cephfs/project/readme.txt'
with open(path, 'w', encoding='utf-8') as f:f.write('CephFS 通过本地文件接口访问，Python 可直接写入。')with open(path, 'r', encoding='utf-8') as f:content = f.read()
print(content)
4. 应用接入的实战示例：从環境搭建到应用接入的完整流程
4.1 端到端对象存储接入示例（S3 兼容接口）
在完成 RGW 部署与 S3 用户创建后，结合 boto3 进行应用级对象操作成为最直接的实践路径。下面的示例展示了从连接配置、桶创建、对象上传到对象下载的完整流程。该流程对希望在 Python 应用中无缝使用 Ceph 存储的开发者尤其有用。
通过上述代码，你可以实现快速的对象存取能力，并在应用层面进行日志记录、错误处理与幂等控制。若要对接多租户场景，可以为不同租户分配不同的 S3 用户与 Bucket。
import boto3
endpoint = 'https://rgw.ceph.local'
access_key = 'YOUR_ACCESS_KEY'
secret_key = 'YOUR_SECRET_KEY's3 = boto3.client('s3',endpoint_url=endpoint,aws_access_key_id=access_key,aws_secret_access_key=secret_key,region_name='us-east-1'
)bucket = 'proj-logs'
try:s3.create_bucket(Bucket=bucket)
except Exception:pass# 上传日志文件
s3.put_object(Bucket=bucket, Key='logs/2025-08.log', Body=b'日志内容示例\\n行2')# 下载并输出内容
resp = s3.get_object(Bucket=bucket, Key='logs/2025-08.log')
print(resp['Body'].read().decode())
为了提升鲁棒性，建议在应用层实现重试策略和超时控制，异常处理、网络断线重连、以及对 bucket 的幂等写入策略都应在设计阶段考虑。
# 简单的重试示例（Python 伪代码，可根据实际库增强）
import time
for i in range(3):try:s3.put_object(Bucket=bucket, Key='health-check', Body=b'OK')breakexcept Exception as e:time.sleep(2)if i == 2:raise e
4.2 CephFS 持续集成与数据管线的接入
除了对象接口，CephFS 也可被数据处理管线直接使用。将 CephFS 挂载路径作为数据输入/输出网关，Python 应用可以通过标准库对数据进行读写，方便与现有 ETL、数据分析工具集成。下面是一个简单的数据写入示例，演示如何将日志或中间结果持久化到 CephFS。
path = '/mnt/cephfs/data/metrics.csv'
with open(path, 'a', encoding='utf-8') as f:f.write('timestamp,cpu,mem\\n')
将 CephFS 视作可扩展的分布式文件系统后，跨进程、跨节点的数据读取变得更加简单，性能监控、容量扩展、以及对齐现有云原生应用的存储接口都变得更加直接。
5. 监控、运维与性能调优
5.1 基础监控与指标
在 Ceph 部署完成后，使用 Ceph 自带的监控与 Dashboard 能够直观查看 集群状态、PG 进度、以及单点故障的风险。对于 Python 接入的应用，关注对象存储的吞吐量、延迟以及错误率尤为关键。
常用监控点包括 MON/OSD 的状态、RGW 的性能指标、以及 CephFS 的 IOPS 与吞吐。结合 Prometheus/Grafana 可以实现端到端的可观测性。
# 基本状态查看（示例）
ceph -s
ceph osd status
ceph df
5.2 适配与扩展建议
随着应用规模增长，扩大 RGW 复制组、提升 OSD 数量、以及优化对象分布策略都将提升性能。对 Python 客户端而言，建议实现并发上传/下载、分块传输、以及对大对象的分段处理，以充分利用 Ceph 存储的分布式特性。
另外，运行 Cephadm 的版本与组件组合要保持同步，定期应用安全更新以减小安全风险。
