简介面向Java开发者的FTP文件传输资源包解决在服务器与本地之间上传、下载文件的常见需求适合正在学习Apache Commons Net或需要快速集成FTP/SFTP功能的项目人员。资源压缩后约106KB仅含2个文件一个Java源码文件和一个JSch运行库JAR包结构紧凑便于直接阅读代码、检查依赖并运行示例。目前已有251人学习下载内容覆盖FTPClient连接、登录验证、主动/被动模式切换、二进制传输类型、目录切换与列表获取、上传下载方法、断开连接以及IOException异常处理等核心知识点。特别地示例工程还使用JSch封装了工具类能够启发读者从FTP平滑扩展到SFTP安全传输源码中保留了清晰的FTP工具类和主调用类可当作Java网络编程的入门参考也能移植到实际业务中复用。1. 内网大文件传输FTP 依然是最稳的“老家伙”你手上有一台 Linux 服务器另一台也是中间隔着机房或者云厂商的内网需要把几十 GB 的日志、模型权重或者数据库备份搬过去。用 HTTP 下载大文件中途断一次就头皮发麻用网盘中转数据在内网环境里绕了一大圈还不一定合规。这时候FTP 反而是那个最省事、最不挑剔网络环境的方案。它协议老、命令简单、所有主流操作系统都自带客户端脚本化也方便适合日常做日志归档、数据同步、备份拉取这类重复性传输工作。这篇笔记就从最常用的命令行操作讲起覆盖 Python 脚本自动化、服务端账号权限配置再把连接超时、中文乱码、断点续传失败这些高频坑逐个拆开。读者是运维和做后端开发的同行新手能照着命令跑通第一条链路熟手则可以直接跳到避坑章节对号入座。2. 先弄清主动模式和被动模式FTP 排障的钥匙2.1 两种连接模型到底差在哪FTP 和 HTTP 最大的不同是它用两个通道一个是控制连接另一个是数据连接。控制连接始终是客户端主动连服务器的 21 端口而数据连接的模式决定了谁去连谁。主动模式下服务器主动往客户端的随机端口发连接。问题在于客户端通常躲在 NAT 或者防火墙后面服务器根本连不进来于是就有了被动模式。被动模式下客户端先通过控制连接告诉服务器“我要下数据”服务器返回一个随机端口客户端再主动去连这个端口。现代网络环境里被动模式是绝对主流内网环境也不例外。判断当前用的是哪种模式命令行下直接看客户端提示即可。以 lftp 为例连接成功后输入debug再执行传输命令能看到类似PASV或者PORT的指令字眼前者是被动模式后者是主动模式。绝大多数连不上、卡在227 Entering Passive Mode之后就没反应的问题根源都在被动模式的数据端口被防火墙拦截。2.2 打通被动模式的数据端口范围搭建 FTP 服务时如果服务器端没有限制被动模式的端口范围操作系统会随机分配高端口给数据连接。这在防火墙上几乎是没法放行的——要么全放要么一个都放不成。我一般会在服务端配置里把被动端口锁死在一个区间比如 40000 到 40100防火墙只放行这部分端口和 21 端口。这样既不用开放大范围高危端口又能保证数据连接稳定建立。客户端这边如果用的是 curl命令里显式加--ftp-method passive强制被动模式lftp 则是在交互环境里执行set ftp:passive-mode on。以下是 curl 下载文件到本地的第一份最小命令适合先验证链路通不通curl -u testuser:testpass --ftp-method passive \ -o /data/backup/mysql_20240101.sql.gz \ ftp://192.168.10.20/backup/mysql_20240101.sql.gz先看服务端返回的150 Opening data connection这一行它表示控制连接正常、服务器已准备好传输。如果卡在这里基本就是数据端口不通。curl 的命令里-o指定本地保存路径注意它不会自动创建目录路径下的目录必须预先存在--ftp-method passive显式声明被动模式排查防火墙问题时建议固定写上避免用默认策略导致行为不一致。上传的对称命令也一并给出curl -u testuser:testpass --ftp-method passive \ -T /data/backup/mysql_20240101.sql.gz \ ftp://192.168.10.20/backup/-T是上传参数后面跟本地文件路径FTP 的 URL 末尾指向目标目录。这里有个细节上传时目标目录不存在会直接报 550所以传之前要么手动创建目录要么在脚本里先调用MKD命令。2.3 lftp 更适合交互式排障curl 适合一条命令完成任务但排障阶段我更推荐 lftp。它支持 Tab 补全、断点续传、镜像同步而且对错误信息的提示比 curl 直观。先进入交互模式lftp -u testuser,testpass 192.168.10.20注意用户名和密码之间是逗号不是冒号。登录成功后先执行debug 10打开详细日志然后ls /backup看目录列表。如果ls正常但get卡住问题出在数据连接如果ls本身就超时控制连接或者被动模式的初始握手就有毛病。debug 10输出的代码块里重点看PASV这一行返回的 IP 和端口---- PASV --- 227 Entering Passive Mode (192,168,10,20,156,90)括号里最后两个数字是端口的高位和低位计算公式是 156 * 256 90 40026。拿这个端口号去服务器上执行ss -tlnp | grep 40026如果没看到监听说明配置的被动端口区间没生效如果外部telnet不通而本机能通基本可以断定被防火墙拦了。3. 用 Python 写一个能跑批量的上传下载脚本3.1 ftplib 的最小可用版本命令行适合手工操作但定时任务和批处理必须上脚本。Python 标准库自带的 ftplib 不依赖第三方包在绝大多数服务器上装完 Python 就能跑适合写定时任务。下面这份脚本覆盖了上传、下载、自动创建目录和异常重试四个基本盘import os from ftplib import FTP, error_perm import time HOST 192.168.10.20 USER testuser PASSWD testpass REMOTE_BASE /backup LOCAL_BASE /data/archive def ensure_remote_dir(ftp: FTP, remote_dir: str): 递归创建远端目录已存在则忽略 dirs remote_dir.strip(/).split(/) current for d in dirs: current / d try: ftp.mkd(current) except error_perm as e: # 550 说明目录已有其他错误直接抛出 if not str(e).startswith(550): raise def upload_file(ftp: FTP, local_path: str, remote_path: str): with open(local_path, rb) as f: ftp.storbinary(fSTOR {remote_path}, f) def download_file(ftp: FTP, remote_path: str, local_path: str): os.makedirs(os.path.dirname(local_path), exist_okTrue) with open(local_path, wb) as f: ftp.retrbinary(fRETR {remote_path}, f.write) ftp FTP() ftp.connect(HOST, 21, timeout30) ftp.login(USER, PASSWD) ftp.set_pasv(True) ftp.encoding utf-8 try: for name in os.listdir(LOCAL_BASE): local_file os.path.join(LOCAL_BASE, name) if not os.path.isfile(local_file): continue ensure_remote_dir(ftp, f{REMOTE_BASE}/{time.strftime(%Y%m%d)}) remote_file f{REMOTE_BASE}/{time.strftime(%Y%m%d)}/{name} upload_file(ftp, local_file, remote_file) print(fuploaded: {name}) finally: ftp.quit()这段代码里的三个自定义函数是核心。ensure_remote_dir按/逐级拆路径逐级建目录好处是第一次运行就能把20240101这种日期目录自动创建好不用手工去服务器上 mkdirupload_file用storbinary以二进制模式上传避免文本模式下换行符被转换导致压缩包损坏download_file先创建本地目录再下载配合os.makedirs(..., exist_okTrue)保证脚本可重复执行。ftp.encoding utf-8这一行不能省。Python 3 的 ftplib 默认使用 Latin-1 编码处理控制连接碰到中文文件名就会抛 UnicodeEncodeError。显示声明 UTF-8 之后前提是服务端也开启 UTF-8 支持vsftpd 默认打开Windows 的 IIS FTP 需要额外配置后文避坑章节还会再提。3.2 断点续传给脚本加上后悔药大文件传输最怕传一半断了重头再来。ftplib 没有直接的断点续传 API但 FTP 协议的 REST 命令可以指定从文件哪个偏移量开始传输。思路不复杂下载前先看本地已存在文件的大小用那个值作为偏移量传给服务器再把 FTP 的传输模式设成追加写入。上传同理先查远端文件大小把本地文件句柄 seek 到对应位置。from ftplib import FTP import os ftp FTP(192.168.10.20) ftp.login(testuser, testpass) ftp.set_pasv(True) ftp.encoding utf-8 remote_path /backup/big_model.bin local_path /data/archive/big_model.bin local_size os.path.getsize(local_path) # 切换到二进制模式并设置断点位置 ftp.voidcmd(TYPE I) resp ftp.sendcmd(fREST {local_size}) with open(local_path, ab) as f: ftp.retrbinary(fRETR {remote_path}, f.write, restlocal_size)注意这里open用了ab模式即追加二进制写入。restlocal_size是 ftplib 封装好的参数底层会先发 REST 命令再发 RETR。执行前可以做个校验动作先发一条SIZE /backup/big_model.bin命令对比远端大小如果本地已经和远端一致脚本直接跳过下载避免无意义的空跑。断点续传有个前提条件是服务端支持 REST 命令。vsftpd 默认支持但某些精简版 Linux 发行版上装的 mini-ftp 可能不支持特征是sendcmd返回 500 或者 502。处理办法是捕获异常后降级为全量下载同时在日志里打一条 warning 提示当前服务器不支持断点续传。3.3 目录批量下载的递归处理retrbinary只能下载单个文件目录批量下载需要自己递归遍历远端目录树。这里有个坑有些 FTP 服务端给NLST命令返回的只是文件名不带完整路径有些返回的又是完整路径。稳妥做法是每进入一个子目录就重新发一次cwd再nlst拿到文件名后拼出相对路径再切回上级目录。def download_tree(ftp: FTP, remote_dir: str, local_dir: str): os.makedirs(local_dir, exist_okTrue) ftp.cwd(remote_dir) for name in ftp.nlst(): if name in (., ..): continue remote_path f{remote_dir}/{name} local_path os.path.join(local_dir, name) try: # 尝试切换到该路径成功说明是目录递归处理 ftp.cwd(name) ftp.cwd(..) download_tree(ftp, remote_path, local_path) except error_perm: # 切换失败说明是文件直接下载 with open(local_path, wb) as f: ftp.retrbinary(fRETR {name}, f.write) ftp.cwd(..)这段递归有两个边界需要留意。一是.和..必须过滤否则会造成死循环二是判断目录用的是“尝试 cwd 再退回来”的办法如果有文件名恰好和目录名相同这种判断会误判。更可靠的替代方案是用MLSD命令获取文件类型标记但老式 FTP 服务端不一定支持所以上述代码走的是兼容性最好的路线。4. 服务端配置vsftpd 的账号权限与端口锁定4.1 用户隔离与目录权限的常用组合服务端我用得最多的是 vsftpd配置文件在/etc/vsftpd/vsftpd.conf。它能满足多数内网场景多用户隔离、限定目录、被动端口固定。下面是一份我常用的配置基线anonymous_enableNO local_enableYES write_enableYES local_umask022 # 锁定用户在家目录禁止越过边界 chroot_local_userYES allow_writeable_chrootYES # 被动模式端口区间防火墙只放行这里 pasv_enableYES pasv_min_port40000 pasv_max_port40100 # 限制客户端并发数和单线程速率 max_clients50 max_per_ip5 local_max_rate0 # 日志与编码 xferlog_enableYES xferlog_file/var/log/vsftpd.log utf8_enableYESchroot_local_userYES会把用户锁在自己的家目录下无论他怎么切换路径都出不去。这个配置配上allow_writeable_chrootYES是必须的否则当用户家目录本身可写时会报500 OOPS: vsftpd: refusing to run with writable root inside chroot()拒绝服务。如果你用的是旧版 vsftpd 没有这个选项就得把家目录权限改成 755去掉写权限。pasv_min_port和pasv_max_port就是前面说的被动端口区间。设置后记得执行systemctl restart vsftpd再验证/proc/net/tcp里有没有对应的监听端口。4.2 用系统用户还是虚拟用户vsftpd 直接复用系统用户是最省事的方案但有个安全边界FTP 用户能登录系统 shell 的话等于给了攻击者一个入口。所以我一般建议单独建一组仅用于 FTP 的系统用户登录 shell 指向/sbin/nologin家目录单独规划一个分区给足配额。useradd -d /data/ftp_data/uploader -s /sbin/nologin uploader passwd uploader chown uploader:uploader /data/ftp_data/uploader/sbin/nologin保证该用户无法通过 SSH 登录系统只能用于 FTP 认证。这一步是很多新手容易漏掉的建完用户不指定 shell默认是/bin/bash等于开了一个后门。chown必须执行否则用户对自己的家目录没有写权限上传任何文件都会被拒绝。如果要更细粒度地控制某个目录只读、某个目录可写常见做法是配合chroot和目录软链或者直接上虚拟用户配合数据库认证。虚拟用户比系统用户的隔离性更强密码不走系统的/etc/shadow但配置复杂度高一个量级内网小规模场景先不用急着上。4.3 验证服务端配置是否生效的三个命令配置改完别急着扔进生产先跑三个验证动作。第一ss -tlnp | grep ftp确认 21 端口在监听第二ss -tlnp | grep 4000确认被动端口区间已绑定第三用 lftp 客户端连一次执行ls看日志里有没有PASV成功记录。如果端口区间没绑定常见原因是配置文件语法错误vsftpd 直接回退到随机端口这个现象检查/var/log/messages里的vsftpd报错即可。5. 避坑指南FTP 实战中最常踩的 5 个坑5.1 防火墙放行了 21 端口却仍然连不上现象客户端执行连接后卡住直到超时telnet 服务器IP 21却是通的。原因被动模式下数据连接使用的是 40000-40100 区间的端口防火墙只放行了 21。解决在防火墙策略里把被动端口区间和 21 端口一起放行规则示例firewall-cmd --permanent --add-port21/tcp firewall-cmd --permanent --add-port40000-40100/tcp firewall-cmd --reload如果用的是云服务器还要去安全组里同步放行这个端口区间。这个坑的特点是“控制连接正常数据连接超时”记住这个现象就能和别的故障区分开。5.2 中文文件名乱码或上传报错现象ls看到的文件名是乱码或者 Python ftplib 上传中文名文件直接抛 UnicodeEncodeError。原因客户端和服务端编码不一致。vsftpd 的utf8_enableYES只保证控制连接的编码客户端侧如果强制使用 GBK两边就错位了。解决统一两边编码为 UTF-8。lftp 下执行set ftp:charset UTF-8显式指定Python 端设置ftp.encoding utf-8。注意 Windows 自带 FTP 命令不认 UTF-8碰到中文文件名建议直接用 Python 脚本或者 lftp别和系统自带命令行死磕。5.3 大文件传了一半断开重传发现比原来更大现象断点续传后文件大小超过源文件或者下载的文件校验不对。原因续传时本地文件偏移量和服务端文件的偏移量对应不上比如服务端在上次断开后重新生成了文件偏移量已经无效。另一种情况是上传续传时先发了 REST 命令但本地文件在 seek 之前被修改了。解决每次续传前先校验源文件和目标文件的元信息例如对比大小和修改时间。如果服务端支持 MD5 或 SHA1 命令优先做哈希校验不支持的话至少对比大小一致再跳过。习惯上我会在脚本里加一条规则本地文件大小已经等于远端时直接跳过避免反复重传。5.4 文件上传后在 Windows 上打开是乱码现象用二进制模式上传的文本文件在 Windows 上打开全是乱码或者一行行挤在一起。原因文本模式和二进制模式的换行符处理不同。FTP 的 TYPE A 模式文本模式会在传输时做换行符转换而storbinary用的是 TYPE I 模式二进制模式不会做转换。解决如果是脚本上传文本文件明确用storbinary保持字节原样服务器上和 Windows 上各放一份时统一换行符为\n如果必须用文本模式传输让服务端转换。最稳妥的是所有文件一律用二进制模式不做隐式转换宁可文件大一点也不能让它内容变化。5.5 红帽系服务器上上传目录没有写权限现象登录用户是 rootls -ld /upload也是 755 权限但上传文件时报 553 Permission denied。原因红帽系发行版默认开启 SELinuxftp 用户对/upload目录的访问被 SELinux 策略拦截传统权限位看不出来。解决先执行setsebool -P allow_ftpd_full_access on放行 FTP 写权限再执行restorecon -Rv /upload修复目录上下文。如果改了 SELinux 布尔值仍然不行检查/var/log/audit/audit.log里有没有avc: denied记录。这个坑的特征是权限位看着正常但实际操作被拒绝属于典型的环境因素。6. 进阶用法用 lftp mirror 做到增量同步如果项目里需要定期把服务器某个目录完整镜像到另一台机器与其写 Python 递归脚本不如直接用 lftp 自带的 mirror 命令。它支持增量传输、断点续传、自动删除远端多余文件是 FTP 场景的增量同步利器。以下是配套定时任务的最小脚本#!/bin/bash lftp -u testuser,testpass 192.168.10.20 \ -e mirror --only-newer --parallel4 --delete \ --verbose /backup /data/archive; quit--only-newer表示只下载比本地新的文件判断依据是时间戳--delete让本地删除远端已不存在的文件注意这个选项会真的删文件首次执行别加先看输出确认没问题再放行--parallel4开启 4 个并发数据连接文件数量多但单个文件小时能明显提速。配合 crontab 每天凌晨执行就实现了基本的准实时备份。还有一个参数值得单独提--transfer-all会忽略时间戳强制全量传输适合服务端文件时间戳被批量修改导致增量失效的场景。实际使用中我遇到过服务器迁移后所有文件 mtime 统一变了增量同步变成全量同步直接把带宽打满这种时候反而要主动用--only-newer配合--ignore-time按文件大小比较来决定是否传输。lftp 的 mirror 判断逻辑默认是“时间戳不同就传”所以生产环境一定要确认两边时钟同步否则每次定时任务都会做无意义的全量传输。这套方案适合运维日常备份但需要注意 mirror 本身不加 FTPS 加密传输过程中账号密码和数据都走明文。内网环境风险尚可接受一旦涉及跨公网传输还是建议在服务端开启显式 FTPS让客户端用lftp -u user,pass --ssl方式连接。我把这个作为习惯固定下来只要 FTP 服务监听在非内网专线环境一律先确认是否支持 TLS。真正吃透 FTP 不是背命令而是理解控制连接与数据连接的分工、知道三五种报错对应的底层原因。我最早踩防火墙端口坑的时候也以为是协议问题后来发现227后面那串数字换算出来就能定位这种经验不跑几遍生产环境是攒不下来的。希望这篇笔记能帮你少走几步弯路。本文还有配套的精品资源点击获取