如何通过命令行工具快速使用云存储网关软件版_云存储网关(CSG)-阿里云帮助中心

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

前提条件

已注册阿里云账号，并完成实名认证。具体操作，请参见注册阿里云账号。
说明
建议您使用RAM用户登录云存储网关控制台进行相关操作。更多信息，请参见账号访问控制。
已开通云存储网关服务。首次登录云存储网关控制台时，根据页面提示开通云存储网关服务。
已有可用的客户端机器。具体操作如下：
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。
已创建OSS Bucket。具体操作，请参见控制台创建存储空间。
说明
云存储网关软件版支持标准（Standard）类型和低频访问（IA）类型的OSS Bucket。
已创建阿里云AccessKey信息，更多信息，请参见用户信息管理控制台。

计费说明

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

说明

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

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

当前最新版本：0.6.2。

Linux操作系统

下载链接：

Ubuntu 16.04：CsgAgent-latest-ubuntu1604.deb
Ubuntu 18.04：CsgAgent-latest-ubuntu1804.deb
Ubuntu 20.04：CsgAgent-latest-ubuntu2004.deb
Ubuntu 22.04：CsgAgent-latest-ubuntu2204.deb
Centos 7、Alibaba Cloud Linux 2：CsgAgent-latest-centos7.rpm
Centos 8、Alibaba Cloud Linux 3：CsgAgent-latest-centos8.rpm

Windows操作系统

下载链接：

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

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

说明

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

CentOS和Alibaba Cloud Linux操作系统

以CentOS 7操作系统为例。

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

执行下列命令进行安装：

sudo rpm -i CsgAgent-latest-centos7.rpm
sudo /usr/local/bin/Aliyun/csg/scripts/install.sh

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

Ubuntu操作系统

以Ubuntu 16.04操作系统为例。

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

执行下列命令进行安装：

sudo apt install -y ./CsgAgent-latest-ubuntu1604.deb
sudo /usr/local/bin/Aliyun/csg/scripts/install.sh

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

Windows操作系统

从官网下载安装包CsgAgent-latest-win64.zip至客户端，然后解压安装包。
说明
- 安装包中的文件需要处于同一目录下。
- 建议解压文件时，保持压缩包内的文件目录结构不变。
用管理员权限运行install.bat进行安装。
您可以执行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，查看是否升级成功。