文档首页/ 对象存储服务 OBS/ 工具指南/ obsfs/ 操作指南/ 挂载对象存储桶
更新时间：2026-06-02 GMT+08:00
查看PDF
分享

挂载对象存储桶

通过obsfs使用OBS服务，需要将OBS桶挂载至您本地的文件系统上。挂载完成后，可以采用操作本地目录类似的方式操作OBS桶，比如保存某个文件至挂载目录，即上传对象至OBS。

obsfs通过公网挂载到华为云服务器ECS上时占用OBS流量，不占用华为云服务器ECS的流量。

约束与限制

  • 如果obsfs是2025年以前版本的，则不支持挂载OBS桶。
  • 挂载目录中的文件或文件夹不支持硬链接命令。
  • 桶名不能超过255个字符，挂载目录总层级路径不能超过1024个字符。
  • 桶级的桶策略和IAM策略对obsfs挂载方式生效。当前挂载对象桶，权限仅记录在对象元数据，而操作是不会被识别，也就无法区分本地文件系统单个挂载下的多用户权限控制，权限应当通过IAM细粒度策略以及桶策略方式实现子账户的隔离。

注意事项

  • 每次通过命令手动挂载的OBS桶，Linux重启后，都需要重新挂载。用户可以设置开机自动挂载OBS桶，相关操作可参考开机自动挂载并行文件系统。
  • obsfs的本地挂载不会准确显示OBS桶的总容量，用户可以通过OBS控制台查看桶容量情况。
  • 一个OBS桶支持挂载到多台云服务器，各挂载进程间互不感知，数据一致性需由用户自行维护，也不能通过OBS锁定文件。建议可通过分布式缓存服务（DCS）的Redis版本实现分布式锁，可避免出现多人对一个文件同时写入的情况。

    了解分布式缓存服务相关信息，请参见什么是分布式缓存服务。

  • obsfs无法感知OBS的多版本功能，也无法使用多版本接口。对于开启了多版本在控制的桶，obsfs只能识别当前版本对象和当前版本对象的删除标记，且无法对当前版本的对象真正做出修改（对象存储桶里的对象本身是不可修改的，只能覆盖当前版本对象，产生一个新的当前版本对象，原先的对象会变成历史版本对象）。了解多版本控制相关信息，请参见多版本控制。
  • 对于对象存储的多版本功能，obsfs无法感知到，也没有办法使用多版本的接口。对于多版本桶，obsfs只能识别当前版本对象和当前版本的删除标记，并且无法对当前版本的对象真正做出修改（对象存储桶里的对象本身是不可修改的，只能覆盖当前版本对象，产生一个新的当前版本对象，原先的对象会变成历史版本对象）。由于上层应用的一些探测性IO（如vim会产生.swp文件），用obsfs挂载会使得多版本桶里产生大量中间过程对象，且对象无法被obsfs删除（删除操作会追加删除标记，而不是真正删除）。了解删除对象相关信息，请参见删除对象。
  • 对象桶模式采用回写模式（write-back），读和写都会经过客户端本地的文件系统进行中转，通过tmpdir或use_cache参数控制临时文件目录所在的位置。在应用与obsfs的交互过程中，应用不直接与obsfs交互，而是先与FUSE交互。应用与FUSE的交互遵循POSIX语义，其中write() 只会写到本地文件系统的临时文件，需要在应用调用文件的close()操作时，修改才会真正的上传到OBS。这意味着：
    • 数据在 close() 返回成功之前不在 OBS 上。进程崩溃、断电、kill -9 等异常退出会导致未关闭文件的数据永久丢失。
    • close() 可能阻塞较长时间（取决于文件大小和网络带宽）。例如100GB 文件的 close 可能需要数分钟。大对象上传场景，可以通过max_dirty_data参数，在写满部分分段大小时就提前触发上传，以提升整体上传效率。
    • 启用 use_cache 时，已写入但未上传的数据保留在磁盘缓存文件中，下次打开同一文件时有机会恢复。未启用 use_cache 时，关闭后本地数据立即释放。

    基于以上模式，建议在关键数据写入后检查 close() 返回值，避免close()方法返回错误被吞噬；对持久性要求高的场景使用 fsync() 定期刷新（需权衡性能）；启用 use_cache 提供额外的数据恢复机会。

前提条件

  • 已成功获取obsfs，具体操作请参见下载并安装obsfs。
  • 已初始化obsfs，具体操作请参见初始化obsfs。
  • 本地挂载目录已存在。

    您也可以使用mkdir命令创建一个新目录用来挂载OBS桶。比如创建一个mountpoint目录，命令为：

    mkdir mountpoint
  • 已校准当前系统时间。如果当前系统时间与存储服务器时间相差过大，会导致请求鉴权失败。

手动挂载对象存储桶

  1. 打开命令行终端。
  2. 使用cd命令进入obsfs所在目录。
  3. 按照以下格式执行挂载命令。 

    ./obsfs obs桶名 本地挂载目录 -o url=区域终端节点地址 -o passwd_file=密钥文件路径  -o bucket_type=object -o multipart_size=128 -o 其他挂载参数
    • obs桶名：输入待挂载的OBS桶名称。
      支持将obs桶中特定路径挂载到本地。用户使用此种方式挂载，进入本地挂载目录后，仅能访问OBS桶中的特定目录。挂载命令如下： 
      ./obsfs obs桶名:/路径名 本地挂载目录 -o url=区域终端节点地址 -o passwd_file=密钥文件路径  -o use_ino 其他挂载参数
    • 本地挂载目录：输入待挂载目录的绝对路径或相对路径。
    • 区域终端节点地址：根据待挂载OBS所在区域名称获取对应的终端节点地址，具体信息请参见地区和终端节点。
    • 挂载参数：挂载参数（除passwd_file、use_ino外）为可选项，根据需求选择合适的参数组合，格式为：-o 参数名称=参数值。在不需要设置参数值的情况下，直接使用-o 参数名称 即可。OBS支持的挂载参数及说明如表1所示。

      关于obsfs挂载时的参数设置，可执行./obsfs --help命令了解更多。

      表1 基本参数

      参数名称

      参数类型

      是否必选

      说明

      passwd_file

      string

      否

      参数解释：

      密钥文件路径，使用obsfs时将从此路径中获取AK和SK信息，以对用户身份进行验证。

      约束限制：

      为了认证信息安全，文件权限需要是600（其他group用户不可访问）才可以正常被obsfs读取。

      取值范围：

      根据初始化obsfs配置的密钥文件路径进行设置。

      默认取值：

      不涉及。

      url

      string

      是

      参数解释：

      指OBS服务终端节点地址，例如 https://obs.cn-north-4.myhuaweicloud.com。

      约束限制：

      必须带协议头http://或https://。

      取值范围：

      1~65535 个字符。

      默认取值：

      不涉及。

      bucket_type

      string

      否

      参数解释：

      指桶的类型。使用此参数会跳过桶类型探测，不会做head桶的请求。对象桶须设为 object。设置为 object 时自动禁用华为文件桶缓存（等效 nohwscache）。默认不填写时将会自动探测。

      约束限制：

      不涉及。

      取值范围：

      • object：挂载桶是对象桶
      • file：挂载并行文件系统

      默认取值：

      默认为空。

      bucket

      string

      否

      参数解释：

      桶名。通常通过命令行第一个位置参数传入（obsfs <bucket> <mountpoint>），无需使用 -o bucket=。如果携带此参数，则忽略命令行第一个位置的桶名参数，以此参数为准。

      约束限制：

      不涉及。

      取值范围：

      不涉及。

      默认取值：

      默认为空。

      nonempty

      boolean flag

      否

      参数解释：

      允许挂载目录非空。

      约束限制：

      不涉及。

      取值范围：

      不涉及。

      默认取值：

      false：关闭。

      allow_other

      boolean flag

      否

      参数解释：

      允许其他用户访问对象存储桶。

      约束限制：

      对于对象桶，此参数不生效。

      取值范围：

      不涉及

      默认取值：

      false：关闭。

      max_background

      int

      否

      参数解释：

      可配置后台最大等待请求数。FUSE内核模块的参数，此参数是直接传给内核的。

      约束限制：

      需要root才能设置超过默认值。

      取值范围：

      正整数，受到内核内存和/sys/fs/fuse/connections/<id>/max_background影响而变化。

      默认取值：

      不涉及。

      use_path_request_style

      boolean flag

      否

      参数解释：

      当采用路径式（使用legacy API 调用风格）访问OBS而非虚拟主机时，请使用该参数。

      约束限制：

      如果url是ip地址时，会自动切换成路径式访问。

      取值范围：

      不涉及。

      默认取值：

      false：关闭。

      umask

      int

      否

      参数解释：

      配置文件权限的掩码，使用此参数会覆盖对象存储桶内所有文件的权限。

      说明：
      使用umask配置后，挂载目录下文件权限会被覆盖为777 - umask，使用示例： 
      -o umask=xxx

      约束限制：

      对象桶挂载当前不支持权限读取，umask仅能记录到对象元数据，使用时不会读取和解析判断。

      取值范围：

      支持0000-0777

      • 当umask为777：文件系统中所有新创建文件权限为000，表示无人有权限；
      • 当umask为000：文件系统中所有新创建文件权限为777，表示所有人有读写执行权限；
      • 当umask为002：文件系统中所有新创建文件权限为775，表示其他用户组用户仅有读和执行权限，自己和同组内用户有读写执行权限。

      默认取值：

      0000
      表2 性能调优参数

      参数名称

      参数类型

      是否必选

      说明

      multipart_size

      int

      否

      参数解释：

      分段上传/下载的分段大小。增大此值可减少 HTTP 请求次数，提升大文件吞吐。分段大小同时影响 ensure_diskfree 的最小值。

      约束限制：

      此取值仅影响obsfs挂载对象桶后，由obsfs发起的io产生的最小分段大小。且最后一个段不受此控制。

      取值范围：

      ≥5（MB），总大小不超过5GB。

      默认取值：

      10

      parallel_count

      int

      否

      参数解释：

      并发上传分段线程数，别名为parallel_upload。与 multipart_size 配合控制上传带宽利用率。

      最大在途数据量 = multipart_size * parallel_count。

      约束限制：

      仅上传大文件时，此配置生效。

      取值范围：

      ≥1

      默认取值：

      5

      multireq_max

      int

      否

      参数解释：

      并发元数据请求上限，控制一次提交多少个curl handle。对象桶控制一次multipart上传下载的最大并发，如果parallel_count超过这个值，会分成多批下发io。

      约束限制：

      不涉及。

      取值范围：

      ≥1

      默认取值：

      20

      max_dirty_data

      int

      否

      参数解释：

      对象桶专用，流式 flush 阈值。在大文件上传的场景，当文件脏数据量超过此值时，自动触发流式分段上传（MixMultipart：CopyPart 干净区域 + UploadPart 脏区域），避免 close 时全量重传。

      约束限制：

      取值需大于multipart_size，才能起到预期的作用。

      取值范围：

      • 取值范围≥50（MB），推荐值：1024。例如，当上传100GB大文件时，建议设置参数值为1024。
      • 取值范围为-1，表示禁用流式flush。

      默认取值：

      5120（MB）

      streamread

      boolean flag

      否

      参数解释：

      启用流式读取模式。大文件按需读取，不预下载整个文件到本地缓存。适用于顺序读取大文件（视频、日志）的场景。大文件读取场景，适合开启流式读取模式。

      约束限制：

      需配合 streamread_window 使用。

      取值范围：

      不涉及

      默认取值：

      关闭。

      streamread_window

      int

      否

      参数解释：

      流式读取窗口大小。控制预读缓冲区容量，越大越适合高带宽顺序读。

      约束限制：

      需先开启 streamread，即启用流式读取模式。

      取值范围：

      24（MB）~ 4096（MB）

      默认取值：

      24MB
      表3 缓存参数

      参数名称

      参数类型

      是否必选

      说明

      use_cache

      string

      否

      参数解释：

      本地文件缓存目录。启用后读写数据会缓存到本地磁盘，显著提升重复读性能。不设置则仅使用内存缓存（默认）。建议指向高性能本地 SSD。在文件close后，再次open时，能优先走缓存目录读取。

      说明：
      • 关键数据写入后建议检查close()返回值，文件大小和网络情况会影响close()返回时长。
      • 对持久性要求高的场景可使用fsync()定期刷新。
      • 建议启用use_cache，提供数据恢复机会。

      约束限制：

      受磁盘空间限制。

      取值范围：

      不涉及。

      默认取值：

      默认不启用。

      tmpdir

      string

      否

      参数解释：

      匿名临时文件目录，用于分段上传/下载的中间数据存储。高吞吐场景建议指向独立的大容量磁盘。

      • 配置了use_cache目录，会使用use_cache的目录存放临时目录，tmpdir这时仅存储一些临时fd。
      • 不配置use_cache目录时，临时文件在close操作后释放。

      约束限制：

      配置了use_cache后，临时文件目录以use_cache指定的路径为准。

      取值范围：

      不涉及。

      默认取值：

      /tmp

      ensure_diskfree

      int

      否

      参数解释：

      磁盘最低可用空间保障。缓存目录可用空间低于此值时停止写入缓存。作用是保护磁盘空间不写满。

      约束限制：

      • 磁盘空间会受到其他进程占用，如果其他进程已经占用导致达到水位，即使本进程未使用，也无法继续写缓存。
      • 仅是一个软保护，写入大文件场景下，达到阈值后采用分段上传，仍然可以每个线程突破一个multipart_size

      取值范围：

      ≥multipart_size，无最大值限制，如果设置比磁盘分区还大，进程启动会直接失败。

      说明：

      有关multipart_size参数信息请参见表2。

      默认取值：

      默认等于 multipart_size。

      max_tmpdir_disk_usage

      int

      否

      参数解释：

      tmpdir或者use_cache的临时文件磁盘用量上限。超过上限后，新的写入会等待已有分段上传完成后再进行。

      说明：

      在高并发场景中，建议设置tmpdir磁盘容量告警阈值，避免因写满磁盘导致业务中断。有关tmpdir参数信息请参见表3。

      约束限制：

      不涉及。

      取值范围：

      ≥0（MB）

      默认取值：

      0：表示没有设置 tmpdir 磁盘用量的上限值。

      del_cache

      boolean flag

      否

      参数解释：

      卸载时删除本地缓存目录内容，失败打WARN日志。挂载时会先清空cache目录，失败会退出。默认不开启。临时挂载场景建议开启，避免磁盘残留。

      约束限制：

      前提已设置了use_cache，该参数相关说明请参见表3。

      取值范围：

      不涉及。

      默认取值：

      false：不开启。

      check_cache_dir_exist

      boolean flag

      否

      参数解释：

      挂载时校验缓存目录是否存在，不存在就退出。

      约束限制：

      前提是设置了use_cache，该参数相关说明请参见表3。

      取值范围：

      不涉及。

      默认取值：

      false：不校验。
      表4 元数据缓存参数

      参数名称

      参数类型

      说明

      max_stat_cache_size

      int

      参数解释：

      stat元数据缓存容量上限。每条约0.5-4KB取决于对象名长度等，典型值可能在1.5KB，缓存文件属性（大小、修改时间、header等）减少 HEAD 请求。

      约束限制：

      按照插入顺序淘汰最老的条目。

      取值范围：

      ≥0（条），当参数值为0时，表示禁用stat缓存。

      说明：

      当取值超过 100 万（条）时会打印内存警告。

      默认取值：

      1000

      stat_cache_expire

      int

      参数解释：

      stat缓存过期时间，对象桶专属配置，别名：stat_cache_interval_expire。多客户端并发访问时建议缩短（如 60–300 秒）。

      约束限制：

      不涉及。

      取值范围：

      ≥0（秒），当参数值为0时，表示stat缓存不自动过期。

      默认取值：

      900
      表5 日志与调试参数

      参数名称

      参数类型

      是否必选

      说明

      dbglevel

      string

      否

      参数解释：

      日志级别。生产环境推荐 warn 或 err；性能测试推荐 info。排查问题使用 debug。不区分大小写。

      约束限制：

      不涉及。

      取值范围：

      • crit / critical / silent：仅输出致命错误
      • err / error：输出一般错误+致命错误
      • warn / wan / warning：输出警告+一般错误+致命错误
      • info / inf / information ：输出信息+警告+一般错误+致命错误
      • debug / dbg：全量日志输出

      默认取值：

      warn

      -d / --debug

      boolean flag

      否

      参数解释：

      提升日志级别。首次使用(-d)从 crit 提升到 info；再次使用(-d -d)透传给 FUSE 启用 FUSE 调试。可以直接使用-o f2 输出最详细的日志。

      约束限制：

      不是通过-o 指定， 而是直接-d / --debug。

      取值范围：

      不涉及。

      默认取值：

      不开启

  4. 执行以下命令，检查挂载结果。 

    df -h

    当界面显示如下类似回显信息时，表示OBS桶挂载成功。

    Filesystem       Size         Used       Avail      Use%      Mounted on
obsfs            16T         0          256T       0%        /path/to/mountpoint

    对象存储桶的容量请以实际使用情况为准。

    如果没有显示以上类似回显信息，表示对象存储桶挂载失败。此时可在执行的挂载命令后面添加以下参数，用以在回显中输出挂载过程以及详细调试日志：

    -d -d -f -o f2 -o curldbg

    然后再根据具体的错误信息进行问题定位，常见异常处理可参考挂载OBS失败。

命令示例

此处以挂载一个华北-北京一区域的“filesystem001”obs桶、obsfs密钥文件路径为“/etc/passwd-obsfs”作为前提条件提供如下挂载命令示例，介绍挂载obs桶时的一些参数配置。

将obs桶“obs001”挂载至“/mnt/mount_path/”目录，并设置缓存目录： 
./obsfs obs001 /mnt/mount_path/ -o url=obs.cn-north-1.myhuaweicloud.com -o passwd_file=/etc/passwd-obsfs -use_cache=/data/cache_dir -o max_background=100
父主题： 操作指南

相关文档