Skip to content
腾讯云对象存储(COS-V5)的FTP Server
Python
Branch: master
Clone or download

README.md

FTP SERVER 工具

COS FTP SERVER 支持通过FTP协议直接操作COS中的对象和目录,包括上传文件、下载文件、删除文件以及创建文件夹等。

开始使用

系统环境

操作系统:Linux,推荐使用腾讯CentOS系列CVM

Python解释器版本:Python 2.7

依赖包:

  • cos-python-sdk-v5 (>=1.6.5)
  • pyftpdlib (>=1.5.2)
  • psutil (>=5.6.1)

使用限制

适用于COS XML版本

安装运行

首先,运行setup.py安装ftp server及其相关的依赖库(需要联网):

python setup.py install   # 这里可能需要sudo或者root权限

然后,拷贝conf/vsftpd.conf.example 到 conf/vsftpd.conf,参考配置文件章节,正确配置bucket和用户信息;

最后,运行ftp_server.py启动cos-ftp-server:

python ftp_server.py

也可以使用nohup命令,以后台进程方式启动:

nohup python ftp_server.py >> /dev/null 2>&1 &

或使用screen命令放入后台运行(需要安装screen工具):

screen -dmS ftp
screen -r ftp
python ftp_server.py

Ctrl+A+D 			# 切回主screen即可

停止

Ctrl + C 即可取消server运行(直接运行,或screen方式放在后台运行)

ps -ef | grep python | grep ftp_server.py | grep -v grep | awk '{print $2}' | xargs -I{} kill {}

功能说明

上传机制:流式上传,不落本地磁盘,只要按照标准的FTP协议配置工作目录即可,不占用实际的磁盘存储空间。

下载机制:直接流式返回给客户端

目录机制:bucket作为整个FTP SERVER的根目录,bucket下面可以建立若干个子目录。

多bucket绑定*:支持同时绑定多个bucket。

删除操作限制:在新的ftp-server中可以针对每个ftp用户配置delete_enable选项,以标识是否允许该ftp用户删除文件。

*:多bucket绑定是通过不同的ftp server工作路径(home_dir)来实现,因此,指定不同的bucket和用户信息时必须保证home_dir不同。

支持的FTP Server命令

  • put
  • mput
  • get
  • rename
  • delete
  • mkdir
  • ls
  • cd
  • bye
  • quite
  • size

不支持FTP命令

  • append
  • mget (不支持原生的mget命令,但在某些Windows客户端下,仍然可以批量下载,如FileZilla)

说明:Ftp Server工具暂时不支持断点续传功能

配置文件

conf/vsftpd.conf.example为Ftp Server工具的配置文件示例,请copy为vsftpd.conf,并按照以下的配置项进行配置:

[COS_ACCOUNT_0]
cos_secretid = XXXXXX
cos_secretkey = XXXXXX
cos_bucket = bucketname1-123456789
cos_region = ap-xxx
cos_protocol = https                    # 连接COS或者自定义endpoint所使用的协议类型,默认为https
#cos_endpoint = ap-xxx.myqcloud.com
home_dir = /home/user0
ftp_login_user_name=user0
ftp_login_user_password=pass0
authority=RW
delete_enable=true					# true为允许该ftp用户进行删除操作(默认),false为禁止该用户进行删除操作

[COS_ACCOUNT_1]
cos_secretid = XXXX
cos_secretkey = XXXXX
cos_bucket = bucketname2-123456789
cos_region = ap-xxx
cos_protocol = https
#cos_endpoint = ap-xxx.myqcloud.com
home_dir = /home/user1
ftp_login_user_name=user1
ftp_login_user_password=pass1
authority=RW
delete_enable=false

[NETWORK]
masquerade_address = XXX.XXX.XXX.XXX        # 如果FTP SERVER处于某个网关或NAT后,可以通过该配置项将网关的IP地址或域名指定给FTP
listen_port = 2121					   # Ftp Server的监听端口,默认为2121,注意防火墙需要放行该端口

passive_port = 60000,65535             # passive_port可以设置passive模式下,端口的选择范围,默认在(60000, 65535)区间上选择

[FILE_OPTION]
# 默认单文件大小最大支持到200G,不建议设置太大
single_file_max_size = 21474836480

[OPTIONAL]
config_check_enable = true

# 以下设置,如无特殊需要,建议保留default设置  如需设置,请合理填写一个整数
min_part_size       = default
upload_thread_num   = default
max_connection_num  = 512
max_list_file       = 10000                # ls命令最大可列出的文件数目,建议不要设置太大,否则ls命令延时会很高
log_level           = INFO                 # 设置日志输出的级别
log_dir             = log                  # 设置日志的存放目录,默认是在ftp server目录下的log目录中

如果要将每个用户绑定到不同的bucket上,则只需要添加[COS_ACCOUNT_X]的section即可。

针对每个不同的COS_ACCOUNT_X的section有如下说明:

  1. 每个ACCOUNT下的用户名(ftp_login_user_name)和用户的主目录(home_dir)必须各不相同,并且主目录必须是系统中真实存在的目录;
  2. 每个COS FTP SERVER允许同时登录的用户数目不能超过100;
  3. endpointregion不会同时生效,使用公有云COS服务只需要正确填写region字段即可,endpoint常用于私有化部署环境中。当同时填写了regionendpoint,则会endpoint会优先生效。

配置文件中的OPTIONAL选项是提供给高级用户用于调整上传性能的可选项,根据机器的性能合理地调整上传分片的大小和并发上传的线程数,可以获得更好的上传速度,一般用户不需要调整,保持默认值即可。

这里提供最大连接数的限制选项:如果不想限制最大连接数,可以填写0,即表示不限制最大连接数目(不过需要根据您机器的性能合理评估)。由于每个ftp客户端和服务器之间会建立控制连接和数据连接,同时ftp server需要保留一个连接用于回复拒绝信息。因此,每个ftp server进程最大能够支持(max_connection_num - 1)/2个客户端同时连接。

在最新版本的cos ftp server程序中提供了配置校验功能,程序会根据当前配置选项评估出运行所需的资源用量,并将其与当前系统可用资源进行对比。若当前系统的可用资源无法满足运行所需,则会拒绝启动cos ftp server进程。该功能可以尽力确保程序在启动后,始终处于资源可控的稳定运行状态。

FAQ

配置文件中的masquerade_address这个选项有何作用?何时需要配置masquerade_address

答:当FTP Server运行在一个多网卡的Server,并且FTP Server采用了PASSIVE模式(一般地,FTP客户端位于一个NAT网关之后时,都需要启用PASSIVE模式),此时需要使用masquerade_address选项来唯一绑定一个passive模式下用于reply的IP。 例如,FTP Server有多个IP地址,如内网IP为10.XXX.XXX.XXX,外网IP为123.XXX.XXX.XXX。 客户端通过外网IP连接到FTP Server,同时客户端使用的是PASSIVE模式传输,此时,若FTP Server未指定masquerade_address具体绑定到外网IP地址,则Server在passive模式下,reply时,有可能会走内网地址。就会出现客户端能连接上Ftp server,但是不能从Server端获取任何数据回复。

如果需要配置masquerade_address,建议指定为客户端连接Server所使用的那个IP地址。

上传大文件的时候,如果中途取消,为什么COS上会留有已上传的文件

答:由于新版的Ftp Server提供了完全的流式上传特性,如果用户的取消或者断开,都会触发大文件的上传完成操作,因此,COS会认为用户已经数据流上传完成,就会将已经上传的数据组成一个完整的文件。 如果,用户希望重新上传,可以直接以原文件名上传覆盖即可。也可以手动删除不完整的文件,重新上传。

为什么Ftp Server配置中要设置最大上传文件的限制?

答:由于COS的分片上传数目最大只能为10000块,且每个分片的大小限制为1MB ~ 5G。 这里设置最大上传文件的限制是为了合理计算一个上传分片的大小。默认支持200G以内的单文件上传,但是不建议用户设置过大,因为单文件大小设置越大,上传时的分片缓冲区也会相应的增大,这可能会耗费用户的内存资源。因此,建议用户根据自己的实际情况,合理设置单文件的大小限制。

如果上传的文件超过最大限制,会怎么样?

答:当实际上传的单文件大小超过了配置文件中的限制,则会抛出一个IOError的异常,并且在日志中标注错误信息。

You can’t perform that action at this time.