文档

通过命令行工具快速使用云存储网关软件版

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

本文介绍如何通过命令行工具快速使用云存储网关软件版。

前提条件

  1. 已注册阿里云账号,并完成实名认证。具体操作,请参见注册阿里云账号

    说明

    建议您使用RAM用户登录云存储网关控制台进行相关操作。更多信息,请参见账号访问控制

  2. 已开通云存储网关服务。首次登录云存储网关控制台时,根据页面提示开通云存储网关服务。

  3. 已有可用的客户端机器。具体操作如下:

    1. 线上云存储网关软件版:在创建云存储网关软件版的地域,已有可用的云服务器ECS作为客户端机器。具体操作,请参见创建ECS实例

      说明
      • 线上云存储网关软件版当前支持的地域:cn-hangzhou,cn-shanghai,cn-qingdao,cn-beijing,cn-zhangjiakou,cn-huhehaote,cn-shenzhen,cn-heyuan,cn-chengdu,cn-hongkong。

      • 线上云存储网关软件版当前支持的操作系统如下:

        • Linux操作系统:CentOS 7、CentOS 8、Alibaba Cloud Linux 2、Alibaba Cloud Linux 3、Ubuntu 16.04、Ubuntu 18.04、Ubuntu 20.04、Ubuntu 22.04

        • Windows操作系统:Windows Server 2016、Windows Server 2019

    2. 线下云存储网关软件版:需要根据以下说明部署云存储网关软件版机器。

      说明
      • 操作系统:

        • Linux操作系统:CentOS 7、CentOS 8、Alibaba Cloud Linux 2、Alibaba Cloud Linux 3、Ubuntu 16.04、Ubuntu 18.04、Ubuntu 20.04、Ubuntu 22.04

        • Windows操作系统:Windows Server 2016、Windows Server 2019

      • 要求机器可以访问公网,或者可以通过阿里云专线等方式接入阿里云VPC。

  4. 已创建OSS Bucket。具体操作,请参见控制台创建存储空间

    说明

    云存储网关软件版支持标准(Standard)类型和低频访问(IA)类型的OSS Bucket。

  5. 已创建阿里云AccessKey信息,更多信息,请参见用户信息管理控制台

计费说明

目前云存储网关软件版处于公测阶段。公测期间激活使用云存储网关软件版不收取任何软件费用。

说明

OSS Bucket中存储的数据需要单独计费。

步骤一:下载云存储网关软件版安装包

当前最新版本:0.6.2。

Linux操作系统

下载链接:

Windows操作系统

下载链接:

Windows Server 2016、Windows Server 2019:CsgAgent-latest-win64.zip

步骤二:安装云存储网关软件版

说明

在安装线下云存储网关软件版时,如果部分依赖项无法下载导致安装失败,可以根据安装失败的提示,自行安装对应版本的依赖项。

CentOS和Alibaba Cloud Linux操作系统

以CentOS 7操作系统为例。

  1. 从官网下载安装包CsgAgent-latest-centos7.rpm至客户端。

  2. 执行下列命令进行安装:

    sudo rpm -i CsgAgent-latest-centos7.rpm
    sudo /usr/local/bin/Aliyun/csg/scripts/install.sh
  3. 您可以执行命令csgfsctl --help查看云存储网关软件版安装情况。

Ubuntu操作系统

以Ubuntu 16.04操作系统为例。

  1. 从官网下载安装包CsgAgent-latest-ubuntu1604.deb至客户端。

  2. 执行下列命令进行安装:

    sudo apt install -y ./CsgAgent-latest-ubuntu1604.deb
    sudo /usr/local/bin/Aliyun/csg/scripts/install.sh
  3. 您可以执行命令csgfsctl --help查看云存储网关软件版安装情况。

Windows操作系统

  1. 从官网下载安装包CsgAgent-latest-win64.zip至客户端,然后解压安装包。

    说明
    • 安装包中的文件需要处于同一目录下。

    • 建议解压文件时,保持压缩包内的文件目录结构不变。

  2. 用管理员权限运行install.bat进行安装。

  3. 您可以执行csgfsctl --help查看云存储网关软件版安装情况。

    说明

    如果安装失败,您可以检查一下您的客户端是否安装了杀毒软件。如果是,需要禁用杀毒软件。

步骤三:激活云存储网关软件版

云存储网关软件版安装完成后,需要对其进行激活才能正常使用。

说明

对于Windows云存储网关软件版,需要使用管理员权限运行cmd.exe,才能使用csgfsctl工具。

  • 线上云存储网关软件版:执行csgfsctl activate --ak=xxx --sk=xxx进行激活。

    说明

    激活云存储网关软件版需要您提供账户AccessKey和AccessKey Secret信息。可以使用RAM账户AccessKey和AccessKey Secret,账户需要具备AliyunHCSSGWFullAccess权限。

  • 线下云存储网关软件版:执行csgfsctl activate --region=xxx --ak=xxx --sk=xxx进行激活。

    说明

    激活云存储网关软件版需要您提供Region(这里的Region和线上云存储网关软件版支持的地域是一致的。以北京地域为例,region为cn-beijing)、用户AccessKey以及AccessKey Secret信息。可以使用RAM用户AccessKey和AccessKey Secret,用户需要具备AliyunHCSSGWFullAccess权限。

激活成功后,您可以登录云存储网关控制台,选择对应的地域,查看对应的云存储网关软件版信息。

步骤四:创建挂载

以一个在北京地域的阿里云ECS客户端上创建挂载点为例。

  • Linux操作系统:/mnt/test为挂载点路径,/root/cache为缓存路径,使用的Bucket名称为beijing,缓存大小设置为50 GB,数据缓存设置为40 GB(其余10 GB为元数据缓存),Bucket子目录设置为test,其命令行如下:

    sudo csgfsctl create --mp=/mnt/test --cd=/root/cache --ak=xxx --sk=xxx --ep=oss-cn-beijing-internal.aliyuncs.com --bucket=beijing -c=50 --dc=40 --prefix=test --work-mode=standard
  • Windows操作系统:D:\test为挂载点路径,D:\cache为缓存路径,使用的Bucket名称为beijing,缓存大小设置为50 GB,数据缓存设置为40 GB(其余10 GB为元数据缓存),Bucket子目录设置为test,其命令行如下:

    csgfsctl create --mp=D:\test --cd=D:\cache --ak=xxx --sk=xxx --ep=oss-cn-beijing-internal.aliyuncs.com --bucket=beijing -c=50 --dc=40 --prefix=test --work-mode=standard
警告

创建挂载点成功之后,请确保不要修改或删除缓存路径cache-dir中的文件,否则可能会造成挂载点不可用等后果。

您可以执行csgfsctl create --help查看创建挂载点的使用说明。具体的参数配置,请参见下表。

参数

是否必选

说明

--mountpoint(简写:-mp)

挂载点路径,例如:/mnt/test/。

说明
  • 配置挂载时,需要确保挂载点路径下无任何数据。

  • Windows操作系统:

    • 挂载点路径请不要使用已有磁盘的根目录。

    • 挂载点可以是一个新的磁盘符,如Z:\。

--cache-dir(简写:-cd)

缓存路径,包括元数据缓存和数据缓存等。

警告
  • 配置挂载时,需要确保缓存路径下无任何数据。

  • Windows操作系统:缓存路径请不要使用已有磁盘的根目录。

  • 创建挂载点完成之后,请确保不要在缓存目录下创建新的文件或者目录。删除挂载点时,会将缓存目录清空。

--access-key(简写:-ak)

输入具有OSS Bucket读写权限的AccessKey,可以是RAM用户AccessKey。

--access-key-secret(简写:-sk)

账户AccessKey Secret。

--endpoint(简写:-ep)

OSS Bucket Endpoint。

说明

如果您使用的是线上机器(阿里云ECS):

  • 如果您需要跨地域访问(客户端和OSS Bucket不在一个地域),那么您必须使用公网Endpoint。

  • 如果您不需要跨地域访问,由于公网传输速度较慢,建议您使用阿里云内网Endpoint(oss-xxx-xxx-internal.aliyuncs.com)。

--bucket(简写:-b)

OSS Bucket名称。

--prefix(简写:-p)

Bucket子目录。

说明

若为空,则挂载点以OSS Bucket为根目录。若不为空,则挂载点以该子目录为根目录。

--cache-size-gb(简写:-c)

Cache预留的磁盘空间,单位:GB。

说明
  • 可选区间为:20~32768(或磁盘剩余空间)。

  • 建议实际空间比设置的CacheGB大2 GB。

--data-cache-size-gb(简写:-dc)

数据Cache预留的磁盘空间,单位:GB。

说明
  • Cache预留的磁盘空间=数据Cache预留的磁盘空间+元数据Cache预留的磁盘空间。

  • 如果不设置此参数,数据Cache预留的磁盘空间=Cache预留的磁盘空间 *70%。

  • 14 GB<=数据Cache预留的磁盘空间<=(Cache预留的磁盘空间-4 GB)。

--work-mode(简写:-wm)

读写模式。默认为async-write(异步写模式,利用内存加速小IO的读写,内存占用更大)。其他可选项为:

  • standard(标准模式,小IO速度会变慢,内存占用更少)

  • seq-write(顺序写模式)

  • read-only(只读模式)

--allow-rename-dir

是否允许重命名文件夹。可能值为:

  • true:允许(默认值)

  • false:不允许

说明

由于对象存储没有重命名的语义,因此重命名文件夹实际是将文件夹下的所有对象重新拷贝一份,体验感较差。如果没有重命名文件夹的需求,建议设置为false。

配置成功后,您可以像操作本地目录一样操作共享目录。

说明

云存储网关软件版的共享目录与OSS Bucket之间进行了数据同步,您对共享目录的操作实际也是对OSS进行操作。

其他相关操作

获取挂载点信息

您可以执行sudo csgfsctl get查询创建的挂载点的状态。具体的参数配置,请参见下表。

您也可以执行csgfsctl get --help查看获取挂载点信息的使用说明。

参数

是否必选

说明

--mountpoint(简写:-mp)

挂载点路径。

说明

如果不指定mountpoint,则获取所有挂载点信息,否则获取指定的挂载点信息。

下表介绍get命令返回的部分参数。

参数

说明

RemainingMetaSpace

剩余元数据空间。

说明
  • 当剩余元数据空间不足2 GB时,会有Warning,建议调用set命令扩充Cache空间,具体操作见“修改挂载点配置”的cache-size-gb参数。

  • 剩余元数据空间过低时,可能会导致访问挂载点文件系统出错。

State

挂载点同步状态。

说明

可能值:

  • dirty:当前挂载点有数据需要同步到OSS Bucket中,此时无法直接删除该挂载点,具体操作见“删除挂载点”。

  • clean:当前挂载点无数据同步到OSS Bucket中。

Healthy

挂载点工作状态。可能值:

  • true:当前挂载点工作正常。

  • false:当前挂载点工作异常,不可用。

修改挂载点配置

  • Linux操作系统:以挂载点/mnt/test为例,打开反向同步功能,并将反向同步间隔时间设置为600秒,其命令行如下:

    sudo csgfsctl set --mountpoint=/mnt/test --reverse-sync=true --rs-interval=600
  • Windows操作系统:以挂载点D:\test为例,打开反向同步功能,并将反向同步间隔时间设置为600秒,其命令行如下:

    csgfsctl set --mountpoint=D:\test --reverse-sync=true --rs-interval=600

您可以执行csgfsctl set --help查看修改挂载点配置的使用说明。具体的参数配置,请参见下表。

参数

是否必选

说明

--mountpoint(简写:-mp)

挂载点路径。

--reverse-sync(简写:-rs)

反向同步功能。可能值:

  • true:打开反向同步。

  • false:关闭反向同步。

说明

开启反向同步功能,云存储网关软件版可以将OSS Bucket中的元数据信息同步到本地。云存储网关软件版的性能会有一定损耗。

--rs-interval(简写:-rsi)

反向同步间隔时间,单位:秒(s)。

说明
  • 仅当反向同步打开时生效。取值区间为:10~36000,默认值为300。

  • 在反向同步时间间隔内,访问同一个目录只会触发一次反向同步。

  • 当文件夹下文件数目较多(上万级别),建议把反向同步时间设置为300s以上。

--ignore-delete

忽略删除。可能值:

  • true:打开忽略删除。

  • false:关闭忽略删除。

说明

删除操作仅针对于本地缓存,不会同步到OSS Bucket。

--oss-direct-read

直读OSS,非必要不建议开启此功能。可能值:

  • true:打开直读OSS。

  • false:关闭直读OSS。

说明

默认情况下,收到一个读请求时,如果数据缓存未命中,云存储网关软件版会去OSS Bucket下载数据并且存储到本地磁盘缓存,会有一定的数据预读。但是如果您的读请求完全是随机请求,并且设置的缓存容量远小于对应的OSS Bucket容量,这时数据预读并落盘可能会效果不佳,可以考虑开启这个功能。

--allow-rename-dir

是否允许重命名文件夹。可能值为:

  • true:允许

  • false:不允许

说明

由于对象存储没有重命名的语义,因此重命名文件夹实际是将文件夹下的所有对象重新拷贝一份,体验感较差。建议非必要不打开此选项。

--upload-delay

同步延迟,本地缓存同步到OSS Bucket的延迟时间,单位:秒(s)。

说明
  • 取值区间为:0~120,默认值为2。

  • 在关闭文件后会延迟一段时间上传数据至OSS,防止频繁的本地修改操作产生OSS碎片。

--upload-bandwidth-limit

上传带宽限流,单位:MB/s。

--rw-bandwidth-limit

读写带宽限流,单位:MB/s。

--download-bandwidth-limit

下载带宽限流,单位:MB/s。

--cache-size-gb(简写:-c)

扩容后Cache缓存空间大小,单位:GB。

说明
  • 扩容后的Cache缓存空间大小比现有的Cache缓存空间(可以通过get命令查询)大时才会生效。

  • 扩容的空间均用于元数据缓存,暂时不支持扩容数据缓存。

--endpoint(简写:-ep)

如果当前挂载点的endpoint失效,可以修改endpoint为设置的值。

--seq-mode

顺序写模式。可能值:

  • true:由标准模式切换至顺序写模式。

  • false:由顺序写模式切换至标准模式。

说明
  • 如果希望使用顺序写模式,建议在create时,work-mode设置为seq-write。

  • 在设置SeqMode选项时,由于涉及到云存储网关软件版写模式的转变,因此请确保设置时挂载点没有IO。

  • 在SeqMode没有设置成功之前,新的IO请求均会返回失败。

  • 在标准模式下,如果挂载点IO刚结束,同时有很多文件正在上传,那么设置SeqMode选项时,可能会耗时较久,甚至超时。

--silent(简写:-s)

切换写模式时,用户需手动输入y或者N,决定是否继续。可以在命令中加入此参数跳过提示,自动执行。

删除挂载点

警告
  • 请确保当前无进程正在占用挂载点或缓存路径,包括检查是否有终端的当前路径为挂载点或缓存路径。否则可能会导致无法卸载,或有卸载残留。

  • 请确保不要在缓存目录下创建新的文件或者目录。删除挂载点时,会将缓存目录清空。

您可以执行csgfsctl remove --help查看删除挂载点的使用说明。具体的参数配置,请参见下表。

参数

是否必选

说明

--mountpoint(简写:-mp)

挂载点路径。

--force

  • 当挂载点仍有数据未同步到OSS Bucket中(通过csgfsctl get命令,查看State为dirty)时,无法直接删除挂载点。

  • 开启force选项可以跳过对当前挂载点是否有数据正在上传的检查,强制删除挂载点。

  • 如果当前State为dirty,通过force选项删除挂载点,请务必确保当前待上传的文件有备份。

日志功能

您可以执行csgfsctl log一键收集日志。

说明
  • Linux操作系统:生成的日志位于/usr/local/bin/Aliyun/csg/路径下。

  • Windows操作系统:生成的日志位于C:\Program Files\Aliyun\csg\bin路径下。

卸载云存储网关软件版

请务必使用下面提供的脚本卸载云存储网关软件版,否则可能会造成服务不可用、持续计费、卸载失败等问题。

  • Linux操作系统:您可以执行sudo /usr/local/bin/Aliyun/csg/scripts/uninstall.sh卸载云存储网关软件版。

  • Windows操作系统:您可以用管理员权限执行uninstall.bat卸载云存储网关软件版。

警告
  • 卸载云存储网关之前需要您手动删除所有挂载点,否则会造成卸载失败。

  • 请确保当前无进程正在占用挂载点或缓存路径,包括检查是否有终端的当前路径为挂载点或缓存路径。否则可能会导致无法卸载,或有卸载残留。

升级云存储网关软件版

如果您当前的云存储网关软件版的版本号低于最新版,您可以进行升级。

  • 您可以通过csgfsctl -v查看您的云存储网关软件版的版本号。

  • 升级无需删除挂载点,升级完成后会自动恢复挂载点。

  • 升级过程中,挂载点会出现暂时不可用的情况,建议您在业务流量低谷期进行升级。

警告

请确保当前没有进程(Linux系统csg_agent进程除外)正在占用挂载点或缓存路径,包括没有终端的当前路径为挂载点或缓存路径,否则可能会导致无法升级。

检查方法:Linux系统可以通过执行命令lsof <挂载点路径>检查。

  • CentOS和Alibaba Cloud Linux操作系统(以CentOS 7操作系统为例)

    1. 在官网下载最新的云存储网关软件版安装包:CsgAgent-latest-centos7.rpm。

    2. 执行下列命令进行升级:

      sudo rpm -iU CsgAgent-latest-centos7.rpm
      sudo /usr/local/bin/Aliyun/csg/scripts/upgrade.sh
    3. 执行完成之后,您可以执行命令csgfsctl -v,查看是否升级成功。

  • Ubuntu操作系统(以Ubuntu 16.04操作系统为例)

    1. 在官网下载最新的云存储网关软件版安装包:CsgAgent-latest-ubuntu1604.deb。

    2. 执行下列命令进行升级:

      sudo apt install --only-upgrade -y ./CsgAgent-latest-ubuntu1604.deb
      sudo /usr/local/bin/Aliyun/csg/scripts/upgrade.sh
    3. 执行完成之后,您可以执行命令csgfsctl -v,查看是否升级成功。

  • Windows操作系统

    1. 在官网下载最新的云存储网关软件版安装包:CsgAgent-latest-win64.zip,然后解压安装包。

      说明
      • 安装包中的文件需要处于同一目录下。

      • 建议解压文件时,保持压缩包内的文件目录结构不变。

    2. 使用管理员权限运行upgrade.bat进行升级。

    3. 执行完成之后,您可以执行命令csgfsctl -v,查看是否升级成功。

  • 本页导读 (1)
文档反馈