{"id":19585860,"url":"https://github.com/tencentyun/cos-ftp-server-v5","last_synced_at":"2025-04-27T11:34:52.925Z","repository":{"id":48927594,"uuid":"102100040","full_name":"tencentyun/cos-ftp-server-V5","owner":"tencentyun","description":"腾讯云对象存储（COS-V5）的FTP Server","archived":false,"fork":false,"pushed_at":"2022-10-25T04:56:31.000Z","size":273,"stargazers_count":37,"open_issues_count":2,"forks_count":17,"subscribers_count":33,"default_branch":"master","last_synced_at":"2024-03-19T07:41:13.015Z","etag":null,"topics":["cos","ftp-server"],"latest_commit_sha":null,"homepage":"https://cloud.tencent.com/document/product/436/7214","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tencentyun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-01T10:01:01.000Z","updated_at":"2023-10-24T11:30:57.000Z","dependencies_parsed_at":"2023-01-20T09:04:50.618Z","dependency_job_id":null,"html_url":"https://github.com/tencentyun/cos-ftp-server-V5","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tencentyun%2Fcos-ftp-server-V5","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tencentyun%2Fcos-ftp-server-V5/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tencentyun%2Fcos-ftp-server-V5/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tencentyun%2Fcos-ftp-server-V5/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tencentyun","download_url":"https://codeload.github.com/tencentyun/cos-ftp-server-V5/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224069497,"owners_count":17250456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cos","ftp-server"],"created_at":"2024-11-11T07:57:27.910Z","updated_at":"2024-11-11T07:57:29.147Z","avatar_url":"https://github.com/tencentyun.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FTP SERVER 工具\n\nCOS FTP SERVER 支持通过FTP协议直接操作COS中的对象和目录，包括上传文件、下载文件、删除文件以及创建文件夹等。\n\n## 开始使用\n\n### 系统环境\n\n操作系统：Linux，推荐使用腾讯CentOS系列CVM\n\nPython解释器版本：Python 2.7\n\n依赖包：\n\n- cos-python-sdk-v5 (\u003e=1.6.5)\n- pyftpdlib (\u003e=1.5.2)\n- psutil (\u003e=5.6.1)\n\n\n### 使用限制\n\n适用于COS XML版本\n\n\n### 安装运行\n\n首先，运行setup.py安装ftp server及其相关的依赖库（需要联网）：\n\n```bash\npython setup.py install   # 这里可能需要sudo或者root权限\n```\n\n然后，拷贝conf/vsftpd.conf.example 到 conf/vsftpd.conf，参考**配置文件**章节，正确配置bucket和用户信息；\n\n最后，运行ftp_server.py启动cos-ftp-server：\n\n```bash\npython ftp_server.py\n```\n\n也可以使用nohup命令，以后台进程方式启动：\n\n```bash\nnohup python ftp_server.py \u003e\u003e /dev/null 2\u003e\u00261 \u0026\n```\n\n或使用screen命令放入后台运行(需要安装screen工具)：\n\n```bash\nscreen -dmS ftp\nscreen -r ftp\npython ftp_server.py\n\nCtrl+A+D \t\t\t# 切回主screen即可\n\n```\n\n### 停止\n\nCtrl + C 即可取消server运行（直接运行，或screen方式放在后台运行）\n\n```bash\nps -ef | grep python | grep ftp_server.py | grep -v grep | awk '{print $2}' | xargs -I{} kill {}\n```\n\n\n## 功能说明\n\n**上传机制**：流式上传，不落本地磁盘，只要按照标准的FTP协议配置工作目录即可，不占用实际的磁盘存储空间。\n\n**下载机制**：直接流式返回给客户端\n\n**目录机制**：bucket作为整个FTP SERVER的根目录，bucket下面可以建立若干个子目录。\n\n**多bucket绑定\u003csup\u003e*\u003c/sup\u003e**：支持同时绑定多个bucket。\n\n**删除操作限制**：在新的ftp-server中可以针对每个ftp用户配置`delete_enable`选项，以标识是否允许该ftp用户删除文件。\n\n\n*：多bucket绑定是通过不同的ftp server工作路径（`home_dir`）来实现，因此，指定不同的bucket和用户信息时必须保证`home_dir`不同。\n\n\n### 支持的FTP Server命令\n\n- put\n- mput\n- get\n- rename\n- delete\n- mkdir\n- ls\n- cd\n- bye\n- quite\n- size\n\n### 不支持FTP命令\n\n- append\n- mget (不支持原生的mget命令，但在某些Windows客户端下，仍然可以批量下载，如FileZilla)\n\n**说明**：Ftp Server工具暂时不支持断点续传功能\n\n\n## 配置文件\n\nconf/vsftpd.conf.example为Ftp Server工具的配置文件示例，请copy为vsftpd.conf，并按照以下的配置项进行配置：\n\n``` conf\n[COS_ACCOUNT_0]\ncos_secretid = XXXXXX\ncos_secretkey = XXXXXX\ncos_bucket = bucketname1-123456789\ncos_region = ap-xxx\ncos_protocol = https                    # 连接COS或者自定义endpoint所使用的协议类型，默认为https\nhome_dir = /home/user0\nftp_login_user_name=user0\nftp_login_user_password=pass0\nauthority=RW\ndelete_enable=true\t\t\t\t\t# true为允许该ftp用户进行删除操作(默认)，false为禁止该用户进行删除操作\n#cos_endpoint = cos.ap-xxx.tencentcos.cn # 设置访问域名，内网访问不需要设置 endpoint，外网访问需要设置成 cos.ap-xxx.tencentcos.cn 外网域名(注意替换xxx为存储桶所在region)\n\n[COS_ACCOUNT_1]\ncos_secretid = XXXX\ncos_secretkey = XXXXX\ncos_bucket = bucketname2-123456789\ncos_region = ap-xxx\ncos_protocol = https\nhome_dir = /home/user1\nftp_login_user_name=user1\nftp_login_user_password=pass1\nauthority=RW\ndelete_enable=false\n#cos_endpoint = cos.ap-xxx.tencentcos.cn\n\n[NETWORK]\nmasquerade_address = XXX.XXX.XXX.XXX        # 如果FTP SERVER处于某个网关或NAT后，可以通过该配置项将网关的IP地址或域名指定给FTP\nlisten_port = 2121\t\t\t\t\t   # Ftp Server的监听端口，默认为2121，注意防火墙需要放行该端口\n\npassive_port = 60000,65535             # passive_port可以设置passive模式下，端口的选择范围，默认在(60000, 65535)区间上选择\n\n[FILE_OPTION]\n# 默认单文件大小最大支持到200G，不建议设置太大\nsingle_file_max_size = 21474836480\n\n[OPTIONAL]\nconfig_check_enable = true\n\n# 以下设置，如无特殊需要，建议保留default设置  如需设置，请合理填写一个整数\nmin_part_size       = default\nupload_thread_num   = default\nmax_connection_num  = 512\nmax_list_file       = 10000                # ls命令最大可列出的文件数目，建议不要设置太大，否则ls命令延时会很高\nlog_level           = INFO                 # 设置日志输出的级别\nlog_dir             = log                  # 设置日志的存放目录，默认是在ftp server目录下的log目录中\n\n```\n\n如果要将每个用户绑定到不同的bucket上，则只需要添加`[COS_ACCOUNT_X]`的section即可。\n\n针对每个不同的`COS_ACCOUNT_X`的section有如下说明：\n\n1. 每个ACCOUNT下的用户名（`ftp_login_user_name`）和用户的主目录（`home_dir`）必须各不相同，并且主目录必须是系统中真实存在的目录；\n2. 每个COS FTP SERVER允许同时登录的用户数目不能超过100；\n3. `endpoint`和`region`不会同时生效，在腾讯云内网使用公有云COS服务只需要正确填写`region`字段即可，`endpoint`常用于外网访问和私有化部署环境中。当同时填写了`region`和`endpoint`，则会`endpoint`会优先生效。\n\n配置文件中的OPTIONAL选项是提供给高级用户用于调整上传性能的可选项，根据机器的性能合理地调整上传分片的大小和并发上传的线程数，可以获得更好的上传速度，一般用户不需要调整，保持默认值即可。\n\n这里提供最大连接数的限制选项：如果不想限制最大连接数，可以填写0，即表示不限制最大连接数目（不过需要根据您机器的性能合理评估）。由于每个ftp客户端和服务器之间会建立控制连接和数据连接，同时ftp server需要保留一个连接用于回复拒绝信息。因此，每个ftp server进程最大能够支持(max_connection_num - 1)/2个客户端同时连接。\n\n在最新版本的cos ftp server程序中提供了配置校验功能，程序会根据当前配置选项评估出运行所需的资源用量，并将其与当前系统可用资源进行对比。若当前系统的可用资源无法满足运行所需，则会拒绝启动cos ftp server进程。该功能可以尽力确保程序在启动后，始终处于资源可控的稳定运行状态。\n\n## FAQ\n**填写region后连接不通，怎么配置endpoint**\n\n答：从 2.2.0 版本后，Ftp Server 默认使用内网域名访问 COS，当 Ftp Server 部署在腾讯云 CVM 等内网环境时，只需要设置存储桶所在 region，即可通过内网访问 COS。\n当 Ftp Server 部署在外网环境时，需要手动设置`endpoint`字段为`cos.ap-xxx.tecentcos.cn`(其中`ap-xxx`需要替换为具体region)，才能通过外网域名访问 COS\n\n**配置文件中的masquerade_address这个选项有何作用？何时需要配置masquerade_address**\n\n答：当FTP Server运行在一个多网卡的Server，并且FTP Server采用了PASSIVE模式（一般地，FTP客户端位于一个NAT网关之后时，都需要启用PASSIVE模式），此时需要使用masquerade_address选项来唯一绑定一个passive模式下用于reply的IP。\n例如，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端获取任何数据回复。\n\n如果需要配置masquerade_address，建议指定为客户端连接Server所使用的那个IP地址。\n\n**上传大文件的时候，如果中途取消，为什么COS上会留有已上传的文件**\n\n答：由于新版的Ftp Server提供了完全的流式上传特性，如果用户的取消或者断开，都会触发大文件的上传完成操作，因此，COS会认为用户已经数据流上传完成，就会将已经上传的数据组成一个完整的文件。 如果，用户希望重新上传，可以直接以原文件名上传覆盖即可。也可以手动删除不完整的文件，重新上传。\n\n**为什么Ftp Server配置中要设置最大上传文件的限制？**\n\n答：由于COS的分片上传数目最大只能为10000块，且每个分片的大小限制为1MB ~ 5G。 这里设置最大上传文件的限制是为了合理计算一个上传分片的大小。默认支持200G以内的单文件上传，但是不建议用户设置过大，因为单文件大小设置越大，上传时的分片缓冲区也会相应的增大，这可能会耗费用户的内存资源。因此，建议用户根据自己的实际情况，合理设置单文件的大小限制。\n\n**如果上传的文件超过最大限制，会怎么样？**\n\n答：当实际上传的单文件大小超过了配置文件中的限制，则会抛出一个IOError的异常，并且在日志中标注错误信息。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftencentyun%2Fcos-ftp-server-v5","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftencentyun%2Fcos-ftp-server-v5","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftencentyun%2Fcos-ftp-server-v5/lists"}