简介AndroidFtp.rar是一份面向Android开发者的FTP功能实现示例工程基于Apache commons-net-3.7.jar封装了服务器连接、文件上传/下载、删除与目录管理等常用操作可用于应用资源更新、用户数据云端同步等场景。压缩包共477个文件约10.44MB包含Android工程常见的flat、json、xml资源与配置文件以及jar、dex、class等编译产物和少量png图标、gradle构建脚本整体结构完整便于直接导入参考。该资源已有421人学习下载。通过阅读其中代码可快速理解FTPClient被动模式连接、流式传输及completePendingCommand等关键细节并复用其封装逻辑到实际项目中适合具备一定Android基础、希望快速集成FTP功能的开发者参考。 先说一句实话我最初整理这份 AndroidFtp.rar起因非常简单——安卓设备上要常态化地把文件传到服务器、从 NAS 拉备份、跟工控网关交换数据网上散落着一堆客户端、代码片段、配置教程但没一个能直接拿来用。折腾了一周把踩过的坑、调通的代码、验证过的服务端配置全部归档成一个压缩包后来项目组几个人都从这份包里复制过方案索性把它整理成一篇文章把我最终沉淀下来的思路完整交代一次。这次分享不打算讲高深理论重点放在“在 Android 端把 FTP 真正用起来”这件事上从客户端选型、权限适配、服务端搭建到联调时的各种经典报错最后附一个资源包内容拆解。1. 单独说FTP移动终端上的文件传输到底选什么方案1.1 网盘和微信不够用做 Android 开发的人最熟悉的上传方式大概是 HTTPOkHttp 一发后端一个接口接收。多数场景下这没问题但碰到两类需求就很别扭。一类是设备端需要直接对接 Linux 服务器或 NAS 的共享目录你总不能求运维给每个目录都写个 HTTP 上传接口另一类是局域网内多台设备互相拷贝日志、固件、配置文件走网盘中转反而绕路内网速度还被打折扣。微信、QQ 传文件更适合点对点临时分享文件一多就乱而且经过聊天软件中转的文件命名、时间戳、目录结构都会丢失程序化处理基本做不了。USB 连接电脑又有个前提——你得有根线还得装驱动自动化批量同步也很难做。FTP 这种老协议在移动端反而有它不可替代的位置部署简单一个 vsftpd 就能撑起整个服务端客户端有现成开源库整个链路没有第三方中转文件在设备和服务器之间直接传输适合写脚本、跑定时任务。最重要的是 Android 设备在局域网内的访问路径和电脑端没有任何区别联调成本远低于自己写一套自定义协议。1.2 FTP能覆盖哪些场景边界在哪根据我实际用过的情况FTP 在 Android 端主要跑这几类任务日志/崩溃现场回传App 在发布后偶尔需要收集设备日志把日志文件打成 tar 包传到内部 FTP 比走 HTTP 上传接口更省事服务端不用开发对应接口运维直接看文件。配置下发智能硬件、工控主板的 App 端需要拉取配置文件FTP 批量下载目录比逐条轮询接口更高效而且支持断点续传。NAS 备份手机照片、录屏、文档定期备份到 NAS很多 NAS 系统自带 FTP 服务Android 客户端直接对接就行。嵌入式交叉编译环境里单片机、ARM 开发板之间互相传固件也有用 FTP 的这个后面单独展开。但要泼一盆冷水FTP 不适合做实时性要求高的业务接口也不适合跨公网大流量传输。明文传输的密码在公网上一抓一个准这种场景要上 FTPS 或 SFTP触发频率很高的单条数据上报还是老老实实用 HTTP/MQTT。FTP 的最佳定位是“批量文件传输的中转管道”而不是业务数据通道。2. Android端FTP开发客户端库、运行权限与文件URI那点事2.1 两个绕不开的库Apache Commons Net和ftp4jAndroid 上做 FTP 客户端绕不开两个 Java 库Apache Commons Net 和 ftp4j。两者都是纯 Java 实现集成进 Android Studio 不需要额外编译原生库对普通 Android 开发者是最省事的选择。Commons Net 是 Apache 开源项目功能非常全支持 FTP、FTPS、FTP over TLS而且接口风格比较底层控制连接、数据连接、文件类型都是手动管理适合对细节要求高的场景。我项目里最后用的就是它因为它对 FTPS 的支持比 ftp4j 完整证书校验、SSL 上下文都能自己控制。ftp4j 的 API 更友好几行代码就能完成上传下载适合快速Demo。但它维护不太活跃遇到一些定制需求反而要改源码。如果你只是临时传个文件可以选 ftp4j如果要做成长期维护的功能模块我更推荐 Commons Net。Android Studio 里接入 Commons Net 只需要在 build.gradle 加一行依赖implementation commons-net:commons-net:3.9.0注意 3.x 版本才支持 Android更老的 2.x 在某些 Android 版本上会有类冲突问题。另外这两个库都不推荐用最新版本里的多线程入口Android 这种资源受限环境最好还是自己控制连接池和线程数。2.2 权限与Android 11之后的共享文件夹访问Android 权限一向是 FTP 功能开发的第一道坎。上传文件你需要读文件需要READ_EXTERNAL_STORAGEAndroid 6.0 要动态申请Android 10 针对分区存储又改了一轮Android 11 之后连MANAGE_EXTERNAL_STORAGE都要求特殊授权。这套环境变化很多新手第一次接入 FTP 上传时都会撞上。大多数情况下我的方案是避免直接碰文件路径直接借助 Android 的content://URI 机制。系统文件选择器返回的是一个 Uri比如热门搜索里经常出现的content://com.baidu.searchbox.fileprovider/...或content://com.ss.android.uri.key/external_root/...这类 URI 不用申请完整的存储权限只要应用有ContentResolver访问权限就能读。拿到content://URI 之后的读取方式非常直白val inputStream contentResolver.openInputStream(uri)然后把InputStream交给 FTP 客户端的上传方法。这样做的好处是不用关心文件存储在哪个目录不用纠结分区存储权限系统文件管理器给什么就传什么代码在各种 ROM 上行为一致。如果确实需要扫描特定目录下的文件那就得在 Android 11 上处理分区存储限制建议优先用MediaStore查询而不是直接拼接路径。至于MANAGE_EXTERNAL_STORAGE除非是文件管理器类应用否则不建议申请应用商店审核时会遇到额外审查。2.3 代码骨架与线程注意事项这里给一份我实际在用的 Commons Net 上传代码骨架class FtpUploader( private val host: String, private val port: Int 21, private val username: String, private val password: String, ) { private val client FTPClient() fun connect() { client.connectTimeout 10_000 client.controlKeepAliveTimeout 30_000 client.connect(host, port) client.login(username, password) // 关键主动/被动模式 client.enterLocalPassiveMode() client.setFileType(FTP.BINARY_FILE_TYPE) client.setControlEncoding(UTF-8) } fun upload(uri: Uri, remotePath: String, contentResolver: ContentResolver): Boolean { val input: InputStream? contentResolver.openInputStream(uri) return input?.use { stream - client.storeFile(remotePath, stream) } ?: false } fun disconnect() { if (client.isConnected) { client.logout() client.disconnect() } } }有几个点容易踩坑单独提醒一下。enterLocalPassiveMode()是必须的。Android 设备通常不在公网 IP 上主动模式会导致客户端无法监听数据连接所以一律用被动模式。务必调用setFileType(FTP.BINARY_FILE_TYPE)。不用二进制模式传 zip、图片、APK 这类文件大概率会损坏。上传操作必须放在子线程。FTP 传输是阻塞 IO直接跑在主线程上轻则卡 UI重则触发NetworkOnMainThreadException。大量文件批量传输时控制连接不能断要设置controlKeepAliveTimeout。长时间不传数据服务端会断开控制连接你后面的指令就发不出去了。3. FTP服务端搭建从Windows开发机到Linux服务器的完整闭环3.1 开发期最省事的本地FTP开发阶段没必要直接上 Linux 服务器Windows 本机就能起一个 FTP 服务把代码联调通再说。Windows 上的方案很成熟IIS 自带 FTP 服务功能足够FileZilla Server 免费、界面友好、支持 TLSWing FTP Server 功能更强但商用有授权个人调试用会碰到启动失败的问题——最常见的两个原因一个是端口被占用另一个是安装服务时没有以管理员权限运行。所以我在资源包里的部署笔记第一步就写了安装时右键选择“以管理员身份运行”启动失败先查 21 端口的占用情况。开发机临时测试我的建议是最小化配置创建一个 Windows 本地用户不要用系统管理员作为 FTP 账号。指定一个独立的根目录比如D:\FTPRoot。开启权限选项开发阶段可以只给读写权限不用开浏览权限。确认 Windows 防火墙放行了 21 端口以及被动模式需要的高位端口段。这样配置过程不会超过五分钟足够支撑 Android 客户端的开发调试。3.2 Linux生产环境的vsftpd配置与TLS安全注意事项生产环境我用的是 CentOS 7 vsftpdUbuntu 16 的原理也一样就是包管理器的区别。云服务商给的 CentOS 7 镜像默认不自带 vsftpd需要手动装。yum install -y vsftpd systemctl enable vsftpd systemctl start vsftpd装好之后核心工作在/etc/vsftpd/vsftpd.conf。这里给出我的生产配置模板只保留关键选项anonymous_enableNO local_enableYES write_enableYES local_umask022 dirmessage_enableYES xferlog_enableYES xferlog_file/var/log/vsftpd.log connect_from_port_20YES chroot_local_userYES allow_writeable_chrootYES pasv_enableYES pasv_min_port30000 pasv_max_port31000解释一下两个比较关键的点。chroot_local_userYES会把用户限制在自家目录内他登录后只能看到自己的目录这是最基本的隔离手段。但注意如果用户主目录本身能被写vsftpd 会拒绝登录所以同时设置allow_writeable_chrootYES来降低这个限制或者把主目录的所有权调整为 root。pasv_enable和被动模式端口段是配合 Android 客户端的关键。Android 端用了被动模式之后服务端必须开放一段高位端口给数据连接只开 21 端口是不够的。这段端口范围同时要在防火墙里放行否则会看到一种很奇怪的故障——登录成功、列目录成功但一传大文件就卡死或者超时。很多运维文档都会提醒一件事如果你的 vsftpd 日志里出现了warning: ftp over tls is not enabled, users cannot securely log in.说明当前配置没有启用 TLS。这是 vsftpd 的编译特性提醒不是错误但如果你的 FTP 需要跨越公网使用建议认真配置 FTPS。生成自签名证书并启用 SSL 的参考方式如下openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \ -keyout /etc/vsftpd/vsftpd.pem \ -out /etc/vsftpd/vsftpd.pem然后在配置里追加ssl_enableYES allow_anon_sslNO force_local_data_sslYES force_local_logins_sslYES rsa_cert_file/etc/vsftpd/vsftpd.pem3.3 防火墙、SELinux与云安全组Linux 服务端搭好后连不上我一直建议按这个顺序排查服务进程是否在运行 → 本机防火墙是否放行 → SELinux 是否拦截 → 云服务商的安全组是否放行。CentOS 7 默认开 firewalld需要放行 FTP 服务和被动端口段firewall-cmd --permanent --add-serviceftp firewall-cmd --permanent --add-port30000-31000/tcp firewall-cmd --reloadSELinux 是最容易忽略的一层。很多 CentOS 7 服务器上 FTP 连不上就是 SELinux 默认策略里禁止了 FTP 读写用户目录。临时可以先关闭测试确认是不是它的锅setsebool -P allow_ftpd_full_access 1云服务器还有个额外的安全组——控制台的入方向规则里要放行 21 和 30000-31000 端口。这个在本地虚拟机里不存在但云服务器上了就一定要检查否则本机怎么测都通手机一到外网就死。4. 联调阶段高频报错ftp登录、Win10访问、乱码与缓存密码4.1 FTP客户端连不上先查主动被动模式“FTP 登录不上怎么办”是最常见的搜索词这个问题九成以上出在模式不匹配上。我之前见过一个案例Android 客户端连不上服务端日志里提示无法建立数据连接排查了很久才发现客户端代码用的是主动模式而服务器部署在 NAT 后面主动模式根本回不来数据。规则很简单客户端和服务端隔着 NAT 或者防火墙一律用被动模式。被动的含义是客户端先连服务器的 21 端口发命令服务器返回一个数据端口给客户端去连接。这样防火墙只需要放行 21 端口和服务器配置的高位端口段即可客户端不需要开放端口。如果你自己写客户端代码记得在登录前调用enterLocalPassiveMode()。如果你用第三方 FTP 工具在设置里选“被动模式”或者“PASV”。4.2 Windows资源管理器说找不到ftp://192.168.1.230这个问题我帮朋友排查过好几次现象一模一样浏览器能打开ftp://192.168.1.230但资源管理器地址栏输入同样的地址报“Windows 找不到 ftp://192.168.1.230。请检查拼写并重试。”在 Windows 10 上资源管理器默认走 WebDAV/WebClient 通道对 FTP 的支持很差。而且微软在 Win10 1803 之后默认禁用了资源管理器里的 FTP 功能。我的建议是别跟资源管理器较劲。Windows 下直接用 FileZilla Client 或者 WinSCP这两个工具功能完整、模式切换方便、编码设置直观比资源管理器强得多。你可以在系统设置里重新启用 FTP但意义不大——资源管理器的 FTP 性能、断点续传能力都很弱还会碰到被动模式连接失败的老毛病。4.3 中文乱码与文件名编码Android 客户端上传的中文文件名在 Windows 的 FTP 工具里看到一堆乱码这是老生常谈。原因很简单FTP 协议标准默认控制连接编码是 ASCII后来扩展支持 UTF-8但不同服务端和客户端对编码的适配不统一。vsftpd 默认使用 UTF-8 处理文件名而 Windows 资源管理器和部分老客户端默认用 GBK。解决方案分两头客户端在代码里调用client.setControlEncoding(UTF-8)并把文件名设置为 UTF-8 编码。服务端vsftpd 在 2.3.0 以后默认开启 UTF-8不需要额外设置。但如果你用的是 Windows 老牌 FTP 服务端建议手动把字符集改成 UTF-8。如果仍然乱码还有一个笨办法也是很多嵌入式项目在用的上传文件名统一用英文或拼音。跨平台传输的文件名编码问题用规避方案永远比逐项适配省心。4.4 删除“我的电脑”中保存的FTP密码Windows 资源管理器访问 FTP 时输过密码后系统会记住。时间一长忘记存了什么密码换账号之后又连不上就需要清理。清理步骤如下打开控制面板进入“用户账户”。点击“管理你的凭据”选择“Windows 凭据”。在列表里找到ftp://开头的凭据记录删除即可。如果看不到这个入口也可以在命令行运行rundll32.exe keymgr.dll, KRShowKeyMgr直接打开凭据管理器。删完之后重新连接Windows 就会重新弹出账号密码框。5. 拆开AndroidFtp.rar这份资源到底沉淀了什么5.1 包内结构与使用顺序既然标题是 AndroidFtp.rar最后拆个包把我归档时放进去的东西和顺序说清楚方便你对照自己的项目去整理。包里的核心目录是这么分的AndroidFtp/ ├── 01-Android客户端代码 │ ├── FtpUploader.kt │ ├── FtpConfig.kt │ └── build.gradle片段.txt ├── 02-服务端配置模板 │ ├── vsftpd-centos7.conf │ ├── vsftpd-ubuntu16.conf │ └── tls生成脚本.sh ├── 03-联调排错手册 │ ├── 主动被动模式说明.md │ ├── Windows10无法访问FTP.md │ └── 常见错误码对照表.md └── 04-工具与脚本 ├── FileZilla_Client安装包说明.txt └── ftp_upload.sh使用顺序也很简单先在 02 目录里找到适合你系统的 vsftpd 配置搭好服务端然后在 01 目录引入客户端代码改一下主机、账号、密码连不上就翻 03 目录的排错手册日常运维用 04 目录里的脚本。整个链路不需要再去搜索引擎里零散找资料。5.2 嵌入式设备与FPGA开发者能带走什么资源包里还留了一部分非 Android 的内容这也是很多人下到压缩包后问得最多的地方——为什么里面会有 ARM64 库编译笔记和单片机用 FTP 的说明。先说 ARM64 交叉编译。如果你的 Android 端需要自己编译 libcurl 或 openssl通常是为了给嵌入式设备提供 FTP 上传能力而设备本身是 ARM64 架构需要在宿主机上交叉编译。我的笔记里保留了当时在 aarch64 环境里编译 libcurl 的记录重点不是命令本身而是告诉你编译前要确认三件事交叉编译工具链版本、openssl 依赖路径、静态库还是动态库。这三件事错了任何一个编译出的库在目标板上跑起来都会出妖蛾子。单片机的 FTP 协议则是另一种用法。很多物联网网关、工控采集器没有 Android 系统但可以用裸机操作系统的 TCP/IP 协议栈实现简单的 FTP 客户端用于把采集数据传到服务器。这种做法不需要完整的 FTP 协议栈只需要实现USER、PASS、PASV、STOR几个命令和被动模式的数据连接逻辑。我在笔记里保留了一份最小命令状态机基本能应付常见上传需求。5.3 一些运维层面的经验补充最后再说一个容易被忽略的环节FTP 监控。很多项目上线后没人看 FTP 的日志结果磁盘被写满、上传失败堆积了几天才发现。建议至少做到两件事定期检查 vsftpd 日志/var/log/vsftpd.log里能看到每次登录、上传和失败记录。对关键目录做容量监控FTP 目录增长速度比你想象得快尤其是日志回传和设备截图这类场景。另外Android 11 之后对应用的网络访问控制变得更严格如果你在设备上遇到 FtpUploader 突然连不上服务器却没有任何代码改动建议先检查系统的网络权限设置里有没有给应用开启“允许网络访问”。这类配置问题有时候比代码问题更隐蔽。最后再补充一条我个人多次踩坑后形成的习惯凡是给甲方或团队交付的 FTP 方案我都会把客户端的连接超时设成 10 秒、读取超时设成 30 秒并且在 UI 上明确提示“传输完成后请退出应用”。因为 FTP 连接如果一直挂在后台Android 系统随时可能回收它等用户再回来上传时就会遇到连接已失效的诡异问题——提前断开连接反而比长连接更稳定。本文还有配套的精品资源点击获取