# 挂载对象存储桶
通过obsfs使用OBS服务，需要将OBS桶挂载至您本地的文件系统上。挂载完成后，可以采用操作本地目录类似的方式操作OBS桶，比如保存某个文件至挂载目录，即上传对象至OBS。
![](https://support.huaweicloud.com/fstg-obs/public_sys-resources/note_3.0-zh-cn.png)
- obsfs通过公网挂载到ECS时占用OBS公网流量和ECS弹性网卡流量（不收费），若产生公网访问还会占用EIP流量。
 
#### 约束与限制
- 本地挂载目录可以不为空，但是挂载后此目录下原有的内容将不可用，取消挂载后即可恢复。建议使用空目录作为挂载目录。
- 文件重命名操作过程中，如果操作被中断（如网络异常、程序崩溃等），文件可能会停留在"新旧名字的文件都存在"的状态且系统不会自动恢复原状。建议提前备份再进行重命名操作。
- 不支持直接追加写文件中的内容。每次修改前，系统会将完整文件下载到本地，修改完成后再整体上传覆盖。
- 每次调用fsync时，系统都会触发完整的文件上传。
- 由于系统对文件元数据（如文件大小、修改时间等）默认进行了本地缓存，当某个客户端修改文件后，其他客户端需要等待缓存过期或手动刷新后，才能看到最新的文件元数据。
- 文件被删除后，此前已打开的文件句柄读取结果不确定。
- 目录写入或删除成功后不会立即可见，需等待秒级收敛，收敛后结果持久准确。
- 文件的访问时间（atime）不支持自动更新，读取文件不会刷新该时间。
- 在目录中创建、删除或重命名文件后，父目录的修改时间（mtime）不会自动更新。
- 上传请求若缺少分段字段，可能导致后续分片写入失败或数据不完整。
- 不支持 Unix 权限，文件的读写执行（rwx）权限与属主、属组信息不生效。
- 扩展属性（xattr）默认关闭，文件的扩展属性不会被存储或读取。
- 文件重命名操作过程中，实际由逐文件"复制+删除"模拟实现。如果操作过程中有文件处于打开状态时，系统会将其缓存数据刷盘再进行。而一旦操作被中断（如网络异常、程序崩溃等），已复制的新对象与未被删除的旧对象将同时存在，且系统不会自动恢复原状。
- 对象桶使用truncate截断文件时，仅限截断5MB（不包含5MB）以内的文件，并行文件系统没有该限制。
- obsfs挂载对象存储桶时，上传大文件采用多段上传（MPU）；若上传中途 obsfs进程异常退出（如崩溃、断电），已完成上传的分片会以未完成的多段上传形式残留在桶内，且这些残留不会形成可见对象（ls 不可见），但占用存储并持续计费。
- 挂载目录中的文件或文件夹不支持硬链接命令。
- 桶名长度范围为3\~63个字符，挂载目录总层级路径不能超过1024个字符。
- 桶级和目录级的桶策略和IAM策略对obsfs挂载访问生效。当前挂载对象桶时，权限仅记录在对象元数据中，obsfs不会识别和执行权限控制，也就无法区分本地文件系统单个挂载下的多用户权限控制，权限应当通过IAM细粒度策略以及桶策略方式实现子账户的隔离。
- Docker容器中挂载OBS桶需在docker run命令中添加--privileged参数。
 
#### 注意事项
- 每次通过命令手动挂载的OBS桶，Linux重启后，都需要重新挂载。用户可以设置开机自动挂载OBS桶，相关操作可参考[开机自动挂载并行文件系统](https://support.huaweicloud.com/fstg-obs/obs_12_0008.html#obs_12_0008__section111413338417)，然后将脚本中的并行文件系统名替换为obs桶名即可。
- obsfs挂载对象桶时，df回显的容量为固定值（不反映桶的实际容量），请通过OBS控制台查看桶的实际容量。
- obsfs不支持对非普通文件（FIFO、socket、字符/块设备、目录）进行mknod----obsfs仅支持创建普通文件（如字节、带其）。
- umask在obsfs上实际不生效，仅做展示使用。
- 对象一旦写入即不可变，不支持原地修改。如需变更内容，必须下载完整对象、本地修改后全量重新上传并覆盖原对象。若文件较大，建议采用分段上传，仅重新上传受影响的分片。
- 一个OBS桶支持挂载到多台云服务器，但obsfs不提供跨客户端的写冲突检测或分布式锁，各挂载进程间互不感知。当多台机器同时写入同一文件时，最后执行 close() 的客户端的数据覆盖其他客户端的修改，且先关闭的客户端不会收到任何错误提示。数据一致性需由用户自行维护，OBS不提供文件锁定功能。建议可通过分布式缓存服务（DCS）的Redis版本实现分布式锁，可避免出现多人对一个文件同时写入的情况。 了解分布式缓存服务相关信息，请参见[什么是分布式缓存服务](https://support.huaweicloud.com/productdesc-dcs/dcs-pd-200713001.html)。
  
- 对于对象存储的多版本功能，obsfs无法感知到，也没有办法使用多版本的接口。对于开启了多版本控制的桶，obsfs只能识别当前版本对象和当前版本的删除标记，并且无法对当前版本的对象真正做出修改（对象存储桶里的对象本身是不可修改的，只能覆盖当前版本对象，产生一个新的当前版本对象，原先的对象会变成历史版本对象）。由于上层应用的一些探测性IO（如vim会产生.swp文件），用obsfs挂载会使得多版本桶里产生大量中间过程对象，且对象无法被obsfs删除（删除操作会追加删除标记，而不是真正删除）。了解多版本控制与删除对象相关信息，请参见[多版本控制](https://support.huaweicloud.com/usermanual-obs/zh-cn_topic_0045829098.html)和[删除对象](https://support.huaweicloud.com/usermanual-obs/obs_03_0726.html)。
- 对象桶模式采用写回模式（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](https://support.huaweicloud.com/fstg-obs/obs_12_0004.html)。
- 已初始化obsfs，具体操作请参见[初始化obsfs](https://support.huaweicloud.com/fstg-obs/obs_12_0006.html)。
- 本地挂载目录已存在。 您也可以使用**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所在区域名称获取对应的终端节点地址，具体信息请参见[地区和终端节点](https://console.huaweicloud.com/apiexplorer/#/endpoint/OBS)**。**
   
   - **挂载参数** ：挂载参数（除passwd_file、use_ino外）为可选项，根据需求选择合适的参数组合，格式为：**-o *参数名称*=** ***参数值*** 。在不需要设置参数值的情况下，直接使用**-o** ***参数** **名称*** 即可。OBS支持的挂载参数及说明如[表1]所示。
     ![](https://support.huaweicloud.com/fstg-obs/public_sys-resources/note_3.0-zh-cn.png)
     关于obsfs挂载时的参数设置，可执行**./obsfs --help**命令了解更多。
      表1基本参数 
     | 参数名称                 | 参数类型             | 是否必选 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
     |:---|:---|:---|:---|
     | passwd_file        | String          | 是   | **参数解释：** 密钥文件路径，使用obsfs时将从此路径中获取AK和SK信息，以对用户身份进行验证。 **约束限制：** 为了认证信息安全，文件权限需要是600（其他group用户不可访问）才可以正常被obsfs读取。 **取值范围：** 根据[初始化obsfs](https://support.huaweicloud.com/fstg-obs/obs_12_0006.html)配置的密钥文件路径进行设置。 **默认取值：** 不涉及。                                                                                                                                                                                                                                                                                                                                                    |
     | 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 发送一个创桶请求创建目标桶；桶创建成功（或桶已存在且属于当前账号）后继续挂载流程。用于不确定桶是否存在时，自动建桶再挂载，省去单独创建桶的步骤。 **约束限制：** - 仅对对象桶有效。  - 若目标桶名已被其他账号占用(全局唯一命名空间)，会导致挂载失败。   **取值范围：** 不涉及 **默认取值：** 不涉及                                                                                                                                                                                                                                               |
        
      表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）                                                                                                                                                                                                                                                                     |
        
      表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 万（条）时会打印内存警告。 **默认取值：** 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
   ```
   ![](https://support.huaweicloud.com/fstg-obs/public_sys-resources/note_3.0-zh-cn.png)
   挂载对象桶时df回显中的容量为固定显示值（如16T），不代表桶的实际容量。桶的容量请以实际使用情况为准。
   如果没有显示以上类似回显信息，表示对象存储桶挂载失败。此时可在执行的挂载命令后面添加以下参数，用以在回显中输出挂载过程以及详细调试日志：
   ```
   -d -d -f -o f2 -o curldbg
   ```
   然后再根据具体的错误信息进行问题定位，常见异常处理可参考[挂载OBS失败](https://support.huaweicloud.com/fstg-obs/obs_12_0014.html)。
   
   
 
#### 命令示例
此处以挂载一个华北-北京一区域的"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
```