挂载对象存储桶-obsfs2.0

约束与限制

• 本地挂载目录可以不为空，但是挂载后此目录下原有的内容将不可用，取消挂载后即可恢复。建议使用空目录作为挂载目录。
• 文件重命名操作过程中，实际由逐文件“复制 + 删除”模拟实现。如果操作被中断（如网络异常、程序崩溃等），已复制的新对象与未被删除的旧对象将同时存在，且系统不会自动恢复原状。
• 不支持直接追加写文件中的内容。每次修改前，系统会将完整文件下载到本地，修改完成后再整体上传覆盖。
• 每次调用fsync时，系统都会触发完整的文件上传流。
• 由于系统对文件元数据（如文件大小、修改时间等）默认进行了本地缓存，当某个客户端修改文件后，其他客户端需要等待缓存过期或手动刷新后，才能看到最新的文件元数据。
• 文件被删除后，此前已打开的文件句柄读取结果不确定：若缓存已失效，后续读取将返回失败；若缓存仍有效，可能短暂读到旧数据而不报错。
• 文件的访问时间（atime）不支持自动更新，读取文件不会刷新该时间。
• 上传请求若缺少分段字段，可能导致后续分片写入失败或数据不完整。
• 不支持 Unix 权限，文件的读写执行（rwx）权限与属主、属组信息不生效。
• 扩展属性（xattr）默认关闭，文件的扩展属性不会被存储或读取。
• 对象桶目录 rename 非原子(COPY+DELETE)；rename 含打开文件的目录会强制先 flush。
• 对象存储桶使用truncate截断文件时，仅限截断5MB（不包含5MB）以内的文件，并行文件系统没有该限制。
• obsfs挂载对象存储桶时，上传大文件采用多段上传(MPU)；若上传中途 obsfs进程异常退出(如崩溃、kill、断电)，已完成上传的分片会以未完成的多段上传形式残留在桶内——这些残留不会形成可见对象(ls 不可见)，但占用存储并持续计费。
• 挂载目录中的文件或文件夹不支持硬链接命令。
• 桶名长度范围为3~63个字符，挂载目录总层级路径不能超过1024个字符。
• 桶级和目录级的桶策略和IAM策略对obsfs挂载访问生效。当前挂载对象桶时，权限仅记录在对象元数据中，obsfs不会识别和执行权限控制，也就无法区分本地文件系统单个挂载下的多用户权限控制，权限应当通过IAM细粒度策略以及桶策略方式实现子账户的隔离。
• Docker容器中挂载OBS桶需在docker run命令中添加--privileged参数

注意事项

• 每次通过命令手动挂载的OBS桶，Linux重启后，都需要重新挂载。用户可以设置开机自动挂载OBS桶，相关操作可参考开机自动挂载并行文件系统，然后将脚本中的并行文件系统名替换为obs桶名即可。
• obsfs挂载对象桶时，df回显的容量为固定值（不反映桶的实际容量），请通过OBS控制台查看桶的实际容量。
• 文件重命名操作过程中，实际由逐文件"复制+删除"模拟实现。如果操作被中断（如网络异常、程序崩溃等），已复制的新对象与未被删除的旧对象将同时存在，且系统不会自动恢复原状。
• obsfs不支持对非普通文件进行mknod（FIFO、socket、字符/块设备、目录）。
• umask在obsfs上实际不生效，仅做展示使用。
• 对象一旦写入即不可变，不支持原地修改。如需变更内容，必须下载完整对象、本地修改后全量重新上传并覆盖原对象。若文件较大，建议采用分段上传，仅重新上传受影响的分片。
• obs协议挂载下，obsfs与s3协议行为保持一致，不会进行额外CRC32C字段的校验。
• 一个OBS桶支持挂载到多台云服务器，但obsfs不提供跨客户端的写冲突检测或分布式锁，各挂载进程间互不感知，当多台机器同时写入同一文件时，最后执行 close() 的客户端的数据覆盖其他客户端的修改，且先关闭的客户端不会收到任何错误提示。数据一致性需由用户自行维护，OBS不提供文件锁定功能。建议可通过分布式缓存服务（DCS）的Redis版本实现分布式锁，可避免出现多人对一个文件同时写入的情况。

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

• 对于对象存储的多版本功能，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 protocol=obs 其他挂载参数

   • OBS桶名：输入待挂载的OBS桶名称。
     支持将OBS桶中特定路径挂载到本地。用户使用此种方式挂载，进入本地挂载目录后，仅能访问OBS桶中的特定目录。挂载命令如下：

     ./obsfs obs桶名:/路径名 本地挂载目录 -o url=区域终端节点地址 -o passwd_file=密钥文件路径  -o protocol=obs 其他挂载参数

   • 本地挂载目录：输入待挂载目录的绝对路径或相对路径。
   • 区域终端节点地址：根据待挂载OBS所在区域名称获取对应的终端节点地址，具体信息请参见地区和终端节点。
   • 挂载参数：挂载参数（除passwd_file外）为可选项，根据需求选择合适的参数组合，格式为：-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://。 取值范围： 不涉及。 默认取值： 不涉及。
     bucket_type	String	否	参数解释： 指桶的类型。此参数用于向后兼容，在obsfs2.0中不生效。系统将根据实际挂载的桶类型自动识别，用户无需设置此参数。 约束限制： 不涉及。 取值范围： 不涉及 默认取值： 默认为空。
     bucket	String	否	参数解释： 桶名。通常通过命令行第一个位置参数传入（obsfs <bucket> <mountpoint>），无需使用 -o bucket=。如果携带此参数，则忽略命令行第一个位置的桶名参数，以此参数为准。 约束限制： 不涉及。 取值范围： 不涉及。 默认取值： 默认为空。
     allow_other	Boolean Flag	否	参数解释： 允许其他用户访问对象存储桶。 约束限制： 不涉及 取值范围： 不涉及 默认取值： false：关闭
     max_write	Int	否	参数解释： 单次写请求由内核送至 obsfs 进程时携带的最大字节数。 约束限制： 不涉及 取值范围： 正整数，4096～1048576（4B～1 MiB） 默认取值： 1048576（1MiB）
     max_background	Int	否	参数解释： 内核向obsfs进程派发后台最大等待请求数。 约束限制： 需要root用户权限才能设置超过10445，非root用户设置10446~65535则会被纠正为10445。 取值范围： root用户: 0~65535。 非root用户: 0~10445。 默认取值： 不涉及。
     nonempty	Boolean Flag	否	参数解释： 兼容obsfs1.0，现版本参数无效，默认支持挂载非空目录 约束限制： 不涉及。 取值范围： 不涉及。 默认取值： 开启。
     protocol	String	否	参数解释： 协议策略。 约束限制： obs和s3会跳过探测直接固定协议；negotiate在挂载时自动进行探测。 取值范围： obs：使用obs协议访问服务端 s3：使用s3协议访问服务端 negotiate：自动探测选择可以使用的协议访问服务端 默认取值： negotiate
     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：文件系统中所有文件权限被覆盖为000，表示无人有权限； 当umask为0000：文件系统中所有文件权限被覆盖为0777，表示所有人有读写执行权限； 当umask为0002：文件系统中所有文件权限被覆盖为0775，表示其他用户组用户仅有读和执行权限，自己和同组内用户有读写执行权限。 默认取值： 0000

     表2 性能调优参数

     参数名称	参数类型	是否必选	说明
     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）
     posix	String	否	参数解释： POSIX 语义模式。 约束限制： 文件桶（并行文件系统）始终使用强 PFS 语义（StrongPfs），此选项无效。 取值范围： weak：weak 模式下对象桶使用流式写入引擎（WeakObject） strong：strong 模式下保持强语义（StrongObject） 默认取值： strong
     storage_class	String	否	参数解释： 指定对象写入时携带的存储类别。 约束限制： obs协议支持：standard、warm、cold。 s3协议支持：standard、standard_ia、reduced_redundancy。 取值范围： standard：标准存储 standard_ia：低频访问存储 reduced_redundancy：低冗余存储 warm：低频访问存储 cold：归档存储 默认取值： standard
     performance_mode	Int	否	参数解释： 对象桶专用，控制 ls 列大目录时的速度与属主显示准确性的取舍。 开启后，ls 列目录只发一次请求拿回文件列表，直接用本地合成的属主信息（挂载用户）填充缓存，后续 ls -l不再逐个向服务端查询文件真实属主，大目录访问明显更快；但 ls -l 显示的文件属主/属组是挂载用户，而非文件真实的属主。 关闭时（默认），ls -l会对每个文件单独发一次请求查询真实属主，大目录首次访问较慢，但显示的属主信息准确。 约束限制： 仅对象桶有效，文件桶挂载时该参数不生效。 开启后 ls -l 显示的属主/属组不真实（显示为挂载用户），对桶内存在外部工具（其他客户端、OBS 控制台等）上传的自定义属主对象的场景不适用。 0 字节对象（如软链接占位）和目录对象的列表行为不受此参数影响，两种模式下行为一致。 取值范围： 0：关闭，精确模式。 1：开启，高性能模式。支持 -o performance_mode（等同 =1）或 -o performance_mode=0|1。 默认取值： 0

     表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指定的路径为准。 对象桶挂载或文件桶指定-o nocopyapi 挂载场景下要求目录类型为ext4、xfs、btrfs、tmpfs。 取值范围： 不涉及。 默认取值： /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 万（条）时会打印内存警告。 默认取值： 100000
     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          16T       0%        /path/to/mountpoint

   

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

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

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

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

命令示例

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

./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