欢迎光临
我们一直在努力
        找回密码
当前位置：171主机测评 > 服务器技术 > 正文

Alluxio 集成 CephFS 底层存储实战指南：cephfs 与 cephfs-hadoop 两种 UFS 配置、挂载与源码原理解析

2026-10-09 分类：服务器技术 阅读(10) 评论(0)
  • 存储
  • 分布式文件系统
  • 缓存
  • 大数据

【免费下载链接】alluxio

Alluxio, data orchestration for analytics and machine learning in the cloud

项目地址：
https://gitcode.com/gh_mirrors/al/alluxio

点击查看 免费下载

本指南介绍如何将 Alluxio 配置为以 CephFS 作为底层存储系统（Under Storage System, UFS），涵盖 Alluxio 官方支持的两种实现：基于 libcephfs 原生 Java API 的 cephfs 方案，以及基于 Hadoop CephFS 插件的 cephfs-hadoop 方案。读完本文，你将掌握两类方案的环境依赖安装、配置文件编写、命名空间挂载与本地联调验证的完整流程，并理解其底层实现差异与关键配置项在源码中的真实作用。

两种 CephFS UFS 实现概述

Alluxio 为 CephFS 提供了两套独立的底层存储实现，二者的 URI scheme 不同，加载路径也完全独立：

实现URI Scheme底层技术源码模块
cephfs cephfs:// libcephfs 的 Java 绑定（JNI），直接操作 CephMount underfs/cephfs
cephfs-hadoop ceph:// Hadoop FileSystem 插件（hadoop-cephfs.jar），以 HDFS 风格访问 underfs/cephfs-hadoop

这一划分在源码中非常明确：Constants.java 中分别定义了 HEADER_CEPHFS = "cephfs://" 与 HEADER_CEPHFS_HADOOP = "ceph://"（见 Constants.java），而两个工厂类 CephFSUnderFileSystemFactory.supportsPath() 与 CephfsHadoopUnderFileSystemFactory.supportsPath() 正是依据这两个前缀识别各自负责的路径（见 CephFSUnderFileSystemFactory.java 与 CephfsHadoopUnderFileSystemFactory.java）。

从源码结构看，二者的实现层次截然不同：

  • cephfs 方案：CephFSUnderFileSystem 直接继承 ConsistentUnderFileSystem 并实现 AtomicFileOutputStreamCallback，通过 com.ceph.fs.CephMount 的 JNI 接口完成文件系统操作，不经过 Hadoop 抽象层（见 CephFSUnderFileSystem.java）。
  • cephfs-hadoop 方案：CephfsHadoopUnderFileSystem 直接继承 HdfsUnderFileSystem，所有 IO 委托给 Hadoop 的 org.apache.hadoop.fs.ceph.CephFileSystem（见 CephfsHadoopUnderFileSystem.java），因此配置方式与 Alluxio 对接 HDFS 十分相似。

前置条件

1. 部署 Alluxio 二进制包

确保本机已具备 Alluxio 二进制环境。你可以选择从源码编译 Alluxio，也可以在本地直接下载并运行 Alluxio 二进制发行包。

2. 安装 Ceph 客户端依赖

根据 Ceph 官方软件包安装指引，需要安装以下三个软件包：

cephfs-java
libcephfs_jni
libcephfs2

其中 cephfs-java 提供 com.ceph.fs.CephMount 等 JNI 类（CephFSUnderFileSystem 的编译与运行都依赖它），libcephfs_jni 与 libcephfs2 分别提供 JNI 桥接库与 CephFS 用户态客户端库。

3. 创建符号链接

安装完成后，libcephfs_jni 与 libcephfs 的动态库通常带版本号后缀，需要创建无版本号的符号链接，同时把 libcephfs.jar 放入 JDK 的扩展目录：

$ ln -s /usr/lib64/libcephfs_jni.so.1.0.0 /usr/lib64/libcephfs_jni.so
$ ln -s /usr/lib64/libcephfs.so.2.0.0 /usr/lib64/libcephfs.so
$ java_path=`which java | xargs readlink | sed 's#/bin/java##g'`
$ ln -s /usr/share/java/libcephfs.jar $java_path/jre/lib/ext/libcephfs.jar

注意：具体库文件名（如 libcephfs_jni.so.1.0.0）随 Ceph 发行版版本而异，请以实际安装路径为准；执行 readlink 前请确认 java 是软链接（多数发行版打包的 JDK 均是如此）。

4. 下载 CephFS Hadoop 插件 jar

若采用 cephfs-hadoop 方案，还需将 Hadoop 与 CephFS 的桥接插件放入 JDK 扩展目录，供 Hadoop 客户端加载：

$ curl -o $java_path/jre/lib/ext/hadoop-cephfs.jar -s https://download.ceph.com/tarballs/hadoop-cephfs.jar

基础配置

Alluxio 通过修改 conf/alluxio-site.properties 与 conf/core-site.xml 两个文件来对接 UFS。如果这两个文件尚不存在，先从模板创建：

$ cp conf/alluxio-site.properties.template conf/alluxio-site.properties
$ cp conf/core-site.xml.template conf/core-site.xml

对应模板位于仓库的 conf/alluxio-site.properties.template 与 conf/core-site.xml.template。

方案 A：配置 cephfs（libcephfs 原生方案）

在 conf/alluxio-site.properties 中加入以下配置：

alluxio.underfs.cephfs.conf.file=<ceph-conf-file>
alluxio.underfs.cephfs.mds.namespace=<ceph-fs-name>
alluxio.underfs.cephfs.mount.point=<ceph-fs-dir>
alluxio.underfs.cephfs.auth.id=<client-id>
alluxio.underfs.cephfs.auth.keyring=<client-keyring-file>

这些配置项在 PropertyKey.java 中有完整定义，除文档给出的 5 项外，该实现还支持以下可选项（全部为 Scope.SERVER 级别，Alluxio Master/Worker 端生效）：

配置项默认值源码中的描述
alluxio.underfs.cephfs.auth.id admin 用于认证的 Ceph 客户端 ID
alluxio.underfs.cephfs.conf.file /etc/ceph/ceph.conf Ceph 配置文件路径
alluxio.underfs.cephfs.conf.opts 无 CephFS 客户端额外配置项，格式为 key=value，多项用 ; 分隔
alluxio.underfs.cephfs.auth.key 无 CephX 认证密钥（Base64 编码）
alluxio.underfs.cephfs.auth.keyfile 无 CephX 认证密钥文件路径
alluxio.underfs.cephfs.auth.keyring /etc/ceph/ceph.client.admin.keyring CephX 认证 keyring 文件路径
alluxio.underfs.cephfs.mon.host 0.0.0.0 用于寻找 Ceph monitor 的主机或地址列表
alluxio.underfs.cephfs.mds.namespace 无 要挂载的 CephFS 文件系统名
alluxio.underfs.cephfs.mount.uid 0 CephFS 挂载的用户 ID
alluxio.underfs.cephfs.mount.gid 0 CephFS 挂载的组 ID
alluxio.underfs.cephfs.mount.point / 挂载到 CephFS 文件系统上的目录
alluxio.underfs.cephfs.localize.reads false 是否启用 Ceph 本地化读取（localized reads）特性

以监控主机地址与额外选项为例，实际配置可写为：

alluxio.underfs.cephfs.conf.file=/etc/ceph/ceph.conf
alluxio.underfs.cephfs.mds.namespace=cephfs
alluxio.underfs.cephfs.mount.point=/
alluxio.underfs.cephfs.auth.id=admin
alluxio.underfs.cephfs.auth.keyring=/etc/ceph/ceph.client.admin.keyring
alluxio.underfs.cephfs.conf.opts=client_mount_uid=0;client_mount_gid=0
alluxio.underfs.cephfs.mon.host=mon1,mon2,mon3

这些配置如何生效？CephFSUnderFileSystem.createInstance() 在初始化时依次执行以下步骤（见 CephFSUnderFileSystem.java）：

  • 以 auth.id 构造 CephMount 实例；
  • 若指定 conf.file 且文件存在，调用 mount.conf_read_file() 读取 Ceph 配置；
  • 解析 conf.opts（以 ; 分隔、= 划分键值），逐个调用 mount.conf_set() 设置额外选项，格式非法时抛出 IllegalArgumentException；
  • 依次设置 auth.key、auth.keyfile、auth.keyring 三项认证凭据；
  • 从 UFS URI 的 authority 解析 monitor 地址列表（monHost = ufsUri.getAuthority()），为空时回退到 mon.host 配置项；
  • 设置 mds.namespace（对应 Ceph 选项 client_mds_namespace）与 mount.uid/mount.gid（对应 client_mount_uid/client_mount_gid）；
  • 以 mount.point 为根目录调用 mount.mount(root) 真正挂载 CephFS；
  • 若开启 localize.reads，调用 mount.localize_reads(true)。

    • 值得注意的实现细节：初始化完成后，CephFS 根目录即由 mount.point 决定，Alluxio 命名空间内所有文件都相对该目录读写；而所有路径操作在进入 JNI 之前都会经过 stripPath() 去掉 cephfs:// scheme 前缀（见 CephFSUnderFileSystem.java）。

    方案 B：配置 cephfs-hadoop（Hadoop 插件方案）

    在 conf/alluxio-site.properties 中指定 Hadoop 配置文件：

    alluxio.underfs.hdfs.configuration=${ALLUXIO_HOME}/conf/core-site.xml

    随后在 conf/core-site.xml 中按 Hadoop 惯例配置 CephFS：

    <configuration>
    <property>
    <name>fs.default.name</name>
    <value>ceph://mon1,mon2,mon3/</value>
    </property>
    <property>
    <name>fs.defaultFS</name>
    <value>ceph://mon1,mon2,mon3/</value>
    </property>
    <property>
    <name>ceph.data.pools</name>
    <value>${data-pools}</value>
    </property>
    <property>
    <name>ceph.auth.id</name>
    <value>${client-id}</value>
    </property>
    <property>
    <name>ceph.conf.options</name>
    <value>client_mount_gid=${gid},client_mount_uid=${uid},client_mds_namespace=${ceph-fs-name}</value>
    </property>
    <property>
    <name>ceph.root.dir</name>
    <value>${ceph-fs-dir}</value>
    </property>
    <property>
    <name>ceph.mon.address</name>
    <value>mon1,mon2,mon3</value>
    </property>
    <property>
    <name>fs.AbstractFileSystem.ceph.impl</name>
    <value>org.apache.hadoop.fs.ceph.CephFs</value>
    </property>
    <property>
    <name>fs.ceph.impl</name>
    <value>org.apache.hadoop.fs.ceph.CephFileSystem</value>
    </property>
    <property>
    <name>ceph.auth.keyring</name>
    <value>${client-keyring-file}</value>
    </property>
    </configuration>

    其中占位符的含义如下：

    • ${data-pools}：Ceph 数据池名称；
    • ${client-id}：Ceph 客户端 ID；
    • ${gid} / ${uid}：挂载使用的组 ID 与用户 ID；
    • ${ceph-fs-name}：CephFS 文件系统名（即 MDS namespace）；
    • ${ceph-fs-dir}：CephFS 内的根目录；
    • ${client-keyring-file}：客户端 keyring 文件路径。

    fs.AbstractFileSystem.ceph.impl 与 fs.ceph.impl 两项是 Hadoop 插件方案的关键：前者注册 Ceph 的 AbstractFileSystem 实现，后者注册 FileSystem 实现，二者共同保证 ceph:// 协议可被 Hadoop 客户端解析。

    本地运行 Alluxio 并验证 CephFS

    启动 Alluxio

    格式化并本地启动 Alluxio（单机模式下同时拉起 Master 与 Worker）：

    $ ./bin/alluxio format
    $ ./bin/alluxio-start.sh local

    启动后可在浏览器访问 Alluxio Master Web UI：http://localhost:19999。

    通过 CLI 挂载 CephFS 到 Alluxio 命名空间

    CephFS 位置可以被挂载到 Alluxio 命名空间的某个嵌套目录下，从而在一个命名空间内统一访问多个底层存储系统。Alluxio 的命令行接口（CLI）即可完成这一操作。

    cephfs 方案（URI 使用 cephfs://）：

    $ ./bin/alluxio fs mkdir /mnt/cephfs
    $ ./bin/alluxio fs mount /mnt/cephfs cephfs://mon1\\;mon2\\;mon3/

    cephfs-hadoop 方案（URI 使用 ceph://）：

    $ ./bin/alluxio fs mkdir /mnt/cephfs-hadoop
    $ ./bin/alluxio fs mount /mnt/cephfs-hadoop ceph://mon1\\;mon2\\;mon3/

    在 Shell 命令行中，多个 monitor 地址之间的分号需要转义为 \\;，避免被 shell 当作命令分隔符。

    运行示例程序验证读写

    执行 Alluxio 自带的功能测试，直接以 CephFS URI 作为写入目标路径：

    $ ./bin/alluxio runTests –path cephfs://mon1\\;mon2\\;mon3/

    （cephfs-hadoop 方案可执行 ./bin/alluxio runTests –path ceph://mon1\\;mon2\\;mon3/，两者验证逻辑一致。）

    运行结束后，可分别从 CephFS 侧与 Alluxio 侧检查测试产物是否落盘：

    • CephFS 侧：可用 ceph-fuse 挂载或以 POSIX API 挂载后查看，预期能看到类似路径：

    ${ceph-fs-dir}/default_tests_files/Basic_CACHE_THROUGH

    • Alluxio 侧：通过 Alluxio CLI 查看命名空间内的嵌套目录：

    /mnt/cephfs/default_tests_files/Basic_CACHE_THROUGH

    （cephfs-hadoop 方案对应路径为 /mnt/cephfs-hadoop/default_tests_files/Basic_CACHE_THROUGH。）

    两边文件一一对应，即说明 CephFS 已成功作为 Alluxio 的底层存储正常工作。

    源码视角：读写路径与容错设计

    写入与原子性

    CephFSUnderFileSystem 实现了 AtomicFileOutputStreamCallback：当创建文件要求原子写（ensureAtomic）时，写入会先落到临时文件，最终提交阶段通过原子重命名发布（见 CephFSUnderFileSystem.java）；非原子场景则直接调用 createDirect()，以 O_WRONLY | O_CREAT | O_TRUNC 标志打开文件描述符并包装为 CephOutputStream。

    读取与随机访问

    读取路径上，CephFSUnderFileSystem.open() 以 O_RDONLY 打开文件、通过 fstat 获取大小，返回 CephSeekableInputStream。后者实现了 SeekableUnderFileInputStream，支持随机定位（seek/getPos），因此 Alluxio 可以对 CephFS 上的数据块做高效的按位置读取（见 CephSeekableInputStream.java）。

    失败重试

    CephFSUnderFileSystem 对 createDirect、deleteDirectory、deleteFile、mkdirs、open、rename 等关键操作统一使用 CountingRetry(MAX_TRY)（MAX_TRY = 5）的有限重试策略，每次失败打印告警日志（见 CephFSUnderFileSystem.java），在一定程度上缓解了网络抖动或瞬时错误带来的偶发失败。

    权限与配额

    从源码结构看，该实现保留了 CephFS 自身的语义特征：setOwner 是空操作（Ceph 对 owner/group 的支持方式不同），目录创建通过 mkdirs 逐级进行以规避 umask 干扰，getSpace 通过 statfs 返回整个集群的容量信息（总空间/已用/可用）。

    常见问题与排错要点

  • JNI 库加载失败：确认 libcephfs_jni.so 与 libcephfs.so 符号链接已创建，且 libcephfs.jar 位于 JDK 扩展目录（jre/lib/ext）下；版本号不匹配时需以本机实际安装的 .so 文件为准调整链接。
  • monitor 地址解析失败：cephfs 方案默认从 URI authority 取 monitor 列表，URI 为空时才会回退到 alluxio.underfs.cephfs.mon.host；请确保挂载 URI 中正确填写 monitor 地址。
  • 认证失败：检查 auth.id 与 auth.keyring/auth.key 是否匹配 Ceph 集群中该客户端真实凭据；默认 keyring 路径为 /etc/ceph/ceph.client.admin.keyring。
  • 配置文件未生效：cephfs 方案的 conf.file 只在文件存在且为常规文件时才会被读取（mount.conf_read_file）；若路径错误会被静默跳过，建议先确认文件路径。
  • Shell 转义：执行 alluxio fs mount 或 runTests 时，monitor 之间的分号务必写成 \\;，否则会被 shell 拆分为多条命令。

    • 小结

    CephFS 作为 Alluxio 的底层存储，提供了两种互补的接入方式：cephfs 方案轻量、直接基于 libcephfs JNI，配置集中在 alluxio-site.properties；cephfs-hadoop 方案复用 Hadoop 生态的 ceph:// 插件，配置分散于 alluxio-site.properties 与 core-site.xml。无论选择哪种，均可通过 alluxio fs mount 将 CephFS 挂入 Alluxio 统一命名空间，并用 runTests 快速验证端到端读写链路。相关实现源码可在仓库的 underfs/cephfs 与 underfs/cephfs-hadoop 模块中进一步研读。

    赞

    分享

    • 存储
    • 分布式文件系统
    • 缓存
    • 大数据

    【免费下载链接】alluxio

    Alluxio, data orchestration for analytics and machine learning in the cloud

    项目地址：
    https://gitcode.com/gh_mirrors/al/alluxio

    点击查看 免费下载

    相关推荐

    • Alluxio 集成 CephFS 作为底层存储：两种 UFS 模式的配置、挂载与本地验证指南

      Alluxio 集成 CephFS 作为底层存储：两种 UFS 模式的配置、挂载与本地验证指南 本指南面向需要将 Alluxio 与 CephFS 底层文件系统

      存储
      分布式文件系统
      缓存
      大数据

    • CephFS 日志急救指南：cephfs-journal-tool 全面剖析与实战

      CephFS 日志急救指南：cephfs journal tool 全面剖析与实战 当 CephFS 的元数据日志（mdlog）因异常断电、对象丢失或人为误操作

      存储
      分布式文件系统
      对象存储
      后端
      高可用

    • CephFS 用户态性能基准工具 cephfs-tool 完全指南：构建、配置与源码级原理

      CephFS 用户态性能基准工具 cephfs tool 完全指南：构建、配置与源码级原理 cephfs tool 是 Ceph 仓库中一个独立的 C++ 工具

      存储
      分布式文件系统
      对象存储
      后端
      高可用

    上一篇：
    如何在30分钟内用AI代理搭建智能预订机器人

    下一篇：
    终极指南：5步掌握网易云音乐API集成全流程

    创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

    赞(0)
    未经允许不得转载：171主机测评 » Alluxio 集成 CephFS 底层存储实战指南：cephfs 与 cephfs-hadoop 两种 UFS 配置、挂载与源码原理解析
    分享到： 更多 (0)

    相关推荐

    评论 抢沙发

    取消

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址

    热门标签

    #人工智能(64635)#python(21535)#开发语言(17916)#java(16482)#运维(16225)#linux(15694)#大数据(15368)#服务器(13701)#算法(12342)#前端(11715)#ai(10357)#网络(9944)#数据库(9558)#c++(8703)#学习(7194)#课程设计(7039)#机器学习(7025)#区块链(6067)#后端(5573)#OpenClaw(5419)#spring boot(5324)#深度学习(5296)#c语言(4566)#安全(4522)#毕业设计(4403)#数据结构(4345)#架构(4194)#docker(4128)#javascript(3993)#大模型(3942)

    热门文章

    最新文章

    归档

    分类