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

挂载对象存储桶-obsfs1.0

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

  • 您可以通过输入以下命令判断obsfs的版本：如果返回Huawei Simple Storage Service File System V1.83，则为obsfs1.0；返回Huawei Simple Storage Service File System V2.0.0，则为obsfs2.0。 
    obsfs --version
  • obsfs通过公网挂载到ECS时占用OBS公网流量和ECS弹性网卡流量（不收费），若产生公网访问还会占用EIP流量。

约束与限制

表1 约束与限制

约束类型

约束说明

挂载与目录管理
  • 本地挂载目录可以不为空，但是挂载后此目录下原有的内容将不可用，取消挂载后即可恢复。建议使用空目录作为挂载目录。
  • Docker容器中挂载OBS桶需在docker run命令中添加--privileged参数。

文件读写操作
  • 不支持直接追加写文件中的内容。每次修改前，系统会将完整文件下载到本地，修改完成后再整体上传覆盖。
  • 每次调用fsync时，系统都会触发完整的文件上传。
  • 对象桶使用truncate截断文件时，仅限截断5MB（不包含5MB）以内的文件，并行文件系统没有该限制。
  • 上传请求若缺少分段字段，可能导致后续分片写入失败或数据不完整。

性能与缓存

由于系统对文件元数据（如文件大小、修改时间等）默认进行了本地缓存，当某个客户端修改文件后，其他客户端需要等待缓存过期或手动刷新后，才能看到最新的文件元数据。

数据一致性与可靠性
  • 目录写入或删除成功后不会立即可见，需等待秒级收敛，收敛后结果持久准确。
  • 文件被删除后，此前已打开的文件句柄读取结果不确定。
  • 文件重命名操作过程中，实际由逐文件"复制+删除"模拟实现。如果操作过程中有文件处于打开状态时，系统会将其缓存数据刷盘再进行。而一旦操作被中断（如网络异常、程序崩溃等），已复制的新对象与未被删除的旧对象将同时存在，且系统不会自动恢复原状。

元数据与属性
  • 文件的访问时间（atime）不支持自动更新，读取文件不会刷新该时间。
  • 在目录中创建、删除或重命名文件后，父目录的修改时间（mtime）不会自动更新。
  • 扩展属性（xattr）默认关闭，文件的扩展属性不会被存储或读取。

权限与安全
  • 不支持 Unix 权限，文件的读写执行（rwx）权限与属主、属组信息不生效。
  • 桶级和目录级的桶策略和IAM策略对obsfs挂载访问生效。当前挂载对象桶时，权限仅记录在对象元数据中，obsfs不会识别和执行权限控制，也就无法区分本地文件系统单个挂载下的多用户权限控制，权限应当通过IAM细粒度策略以及桶策略方式实现子账户的隔离。

功能支持限制

挂载目录中的文件或文件夹不支持硬链接命令。

命名与规格

桶名长度范围为3~63个字符，挂载目录总层级路径不能超过1024个字符。

异常处理与资源管理
  • obsfs挂载对象存储桶时，上传大文件采用多段上传（MPU）；若上传中途 obsfs进程异常退出（如崩溃、断电），已完成上传的分片会以未完成的多段上传形式残留在桶内，且这些残留不会形成可见对象（ls 不可见），但占用存储并持续计费。

注意事项

表2 注意事项

注意类型

注意说明

挂载与启动

每次通过命令手动挂载的OBS桶，Linux重启后，都需要重新挂载。用户可以设置开机自动挂载OBS桶，相关操作可参考开机自动挂载并行文件系统，然后将脚本中的并行文件系统名替换为obs桶名即可。

系统信息与监控

obsfs挂载对象桶时，df回显的容量为固定值（不反映桶的实际容量），请通过OBS控制台查看桶的实际容量。

功能限制
  • 不支持对非普通文件（FIFO、socket、字符/块设备、目录）进行mknod操作。
  • 对于对象存储的多版本功能，obsfs无法感知到，也没有办法使用多版本的接口。对于开启了多版本控制的桶，obsfs只能识别当前版本对象和当前版本的删除标记，并且无法对当前版本的对象真正做出修改（对象存储桶里的对象本身是不可修改的，只能覆盖当前版本对象，产生一个新的当前版本对象，原先的对象会变成历史版本对象）。由于上层应用的一些探测性IO（如vim会产生.swp文件），用obsfs挂载会使得多版本桶里产生大量中间过程对象，且对象无法被obsfs删除（删除操作会追加删除标记，而不是真正删除）。了解多版本控制与删除对象相关信息，请参见多版本控制和删除对象。

权限与安全
  • umask在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 提供额外的数据恢复机会。

多客户端并发

一个OBS桶支持挂载到多台云服务器，但obsfs不提供跨客户端的写冲突检测或分布式锁，各挂载进程间互不感知。当多台机器同时写入同一文件时，最后执行 close() 的客户端的数据覆盖其他客户端的修改，且先关闭的客户端不会收到任何错误提示。数据一致性需由用户自行维护，OBS不提供文件锁定功能。建议可通过分布式缓存服务（DCS）的Redis版本实现分布式锁，可避免出现多人对一个文件同时写入的情况。

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

前提条件

  • 已成功获取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支持的挂载参数及说明如表3所示。

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

      表3 基本参数

      参数名称

      参数类型

      是否必选

      说明

      passwd_file

      String

      是

      参数解释：

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

      约束限制：

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

      取值范围：

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

      默认取值：

      不涉及。

      url

      String

      是

      参数解释：

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

      约束限制：

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

      取值范围：

      不涉及。

      默认取值：

      不涉及。

      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

      String

      否

      参数解释：

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

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

      约束限制：

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

      取值范围：

      支持0000-0777

      • 当umask为0777：文件系统中所有文件权限被覆盖为0000，表示无人有权限；
      • 当umask为0000：文件系统中所有文件权限被覆盖为0777，表示所有人有读写执行权限；
      • 当umask为0002：文件系统中所有文件权限被覆盖为0775，表示其他用户组用户仅有读和执行权限，自己和同组内用户有读写执行权限。

      默认取值：

      0000

      createbucket

      Boolean Flag

      否

      参数解释：

      挂载时自动创建桶的开关。启用后，obsfs 在挂载流程开始阶段向 OBS 发送一个创桶请求创建目标桶；桶创建成功（或桶已存在且属于当前账号）后继续挂载流程。用于不确定桶是否存在时，自动建桶再挂载，省去单独创建桶的步骤。

      约束限制：

      • 仅对对象桶有效。
      • 若目标桶名已被其他账号占用(全局唯一命名空间)，会导致挂载失败。

      取值范围：

      不涉及

      默认取值：

      不涉及
      表4 性能调优参数

      参数名称

      参数类型

      是否必选

      说明

      multipart_size

      Int

      否

      参数解释：

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

      约束限制：

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

      取值范围：

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

      默认取值：

      10（MB）

      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）

      默认取值：

      24（MB）
      表5 缓存参数

      参数名称

      参数类型

      是否必选

      说明

      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参数信息请参见表4。

      默认取值：

      默认等于 multipart_size。

      max_tmpdir_disk_usage

      Int

      否

      参数解释：

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

      说明：

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

      约束限制：

      不涉及。

      取值范围：

      ≥0（MB）

      默认取值：

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

      del_cache

      Boolean Flag

      否

      参数解释：

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

      约束限制：

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

      取值范围：

      不涉及。

      默认取值：

      false：不开启。

      check_cache_dir_exist

      Boolean Flag

      否

      参数解释：

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

      约束限制：

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

      取值范围：

      不涉及。

      默认取值：

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

      参数名称

      参数类型

      是否必选

      说明

      max_stat_cache_size

      Int

      否

      参数解释：

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

      约束限制：

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

      取值范围：

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

      说明：

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

      默认取值：

      100000

      stat_cache_expire

      Int

      否

      参数解释：

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

      约束限制：

      不涉及。

      取值范围：

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

      默认取值：

      900
      表7 日志与调试参数

      参数名称

      参数类型

      是否必选

      说明

      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          16T       0%        /path/to/mountpoint

    挂载对象桶时df回显中的容量为固定显示值（如16T），不代表桶的实际容量。桶的容量请以实际使用情况为准。

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

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

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

命令示例

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

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

相关文档