跳转至

04 FTP

作者：马亚丹　|　最后修改：2026-07-22

一、什么是 FTP

1.1 基本概念

FTP 协议

在 4G 物联网场景中，FTP 协议（File Transfer Protocol，文件传输协议）是一种基于 TCP/IP 的标准化文件传输技术。

FTP 协议包括两个组成部分，其一为 FTP 服务器，其二为 FTP 客户端.

FTP 服务器

FTP 服务器（File Transfer Protocol Server）是基于 FTP 协议提供文件存储、传输与管理服务的系统。简单来说，支持 FTP 协议的服务器就是 FTP 服务器， 用来存储文件，用户可以使用 FTP 客户端通过 FTP 协议访问位于 FTP 服务器上的资源.

FTP 客户端

FTP 客户端（FTP Client）是指用户端用于连接 FTP 服务器、并进行文件传输及管理操作的工具或软件。它是 FTP 通信中的 “发起方”，负责向 FTP 服务器发送连接请求、认证信息（如用户名和密码），并执行上传、下载、删除、移动文件等操作。

默认情况下 FTP 协议使用 TCP 端口中的 20 和 21 这两个端口，其中 20 用于传输数据，21 用于传输控制信息.但是，是否使用 20 作为传输数据的端口与 FTP 使用的传输模式有关：

如果采用主动模式，那么数据传输端口就是 20；

如果采用被动模式，要服务器端和客户端协商决定最终使用哪个端口.

FTP 作为成熟的文件传输协议，在 4G 物联网场景中承担 “标准化文件交互通道” 的角色，弥补了物联网中轻量级协议（如 MQTT）在大文件传输上的不足。

1.2 关键特性

  1. 基于 TCP 的可靠性：FTP 依赖 TCP 协议实现连接，通过三次握手建立连接、重传机制保障数据完整性，适合物联网中 “固件包”“监控录像” 等关键文件的传输，避免丢失或损坏。
  2. 双向文件操作：支持 “上传”（设备 → 服务器，如传感器日志上传）和 “下载”（服务器 → 设备，如固件更新），满足物联网设备与云端的双向数据交互需求。
  3. 适配 4G 网络特性：4G 的高带宽支持 FTP 传输较大文件；低延迟特性减少了 FTP 控制连接（端口 21）和数据连接（端口 20）的交互等待时间，提升传输效率。

1.3 典型应用场景

  1. 设备固件升级：物联网设备（如工业网关、智能摄像头）通过 4G 网络连接 FTP 服务器，下载最新固件包并完成升级，无需现场操作。
  2. 批量数据回传：部署在户外的传感器（如环境监测设备）定期将采集的日志文件（如温度、湿度历史数据）通过 FTP 上传至云端服务器，便于集中分析。
  3. 多媒体文件传输：车载终端、安防摄像头等设备通过 4G 网络将拍摄的视频、图片文件经 FTP 传输至后端平台，实现远程监控。

综上，4G 物联网中的 FTP 是一种依托 4G 高带宽、低延迟特性，实现设备与云端大文件可靠传输的成熟方案，广泛应用于固件升级、数据回传、多媒体传输等场景。

关于 FTP 更详细的理论知识说明，请参考:https://blog.csdn.net/HinsCoder/article/details/130911658

或者其他途径自行参考。

下面就跟着教程用合宙模组实际操作演示一下 FTP 协议的实际应用。

二、功能演示概述

本文演示合宙 4G 模组使用 LuatOS 开发时， 4G 通信中 ftp 网络协议的应用功能.

  1. 配置 FTP 客户端登录服务器的参数和文件路径
  2. 封装一个重试机制，在登录失败、上传文件失败或者下载文件失败时尝试重新执行操作
  3. 登录 FTP 服务器，通过重试机制确保登录成功
  4. ftp.push 上传本地文件到服务器，在本地新建文件并写入内容后上传到服务器指定路径，通过重试机制确保上传成功
  5. ftp.pull 从服务器下载文件，保存在本地指定路径，并读取文件长度，当长度小于指定字节时，读取文件内容，通常是设定 512 字节，如果文件太大，会消耗 ram,通过重试机制确保上传成功
  6. 主函数循环运行以下流程： 登录服务器、用 ftp.command 操作 ftp 服务器目录以及文件上传下载处理后关闭服务器。

三、准备硬件环境

1、Air8201H 开发板一块 + 可上网的 sim 卡一张 +4g 天线一根；

2、TYPE-C USB 数据线一根；

TYPE-C USB 数据线直接插到板子的 TYPE-C USB 座子，另外一端连接电脑 USB 口；

四、准备软件环境

在开始实践本示例之前，先筹备一下软件环境：

1.烧录工具： Luatools 工具；

2.内核固件：Air8201G固件(基于Air780EGH)

3.LuatOS 需要的脚本和资源文件

脚本和资源文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air8201/demo/ftp

4.访问 ftp 服务器

以下准备了三种访问 ftp 服务器的方法

本文使用方法 1，通过 Windows 资源管理器访问，若无法访问，请尝试方法 2 或者方法 3:

测试服务器客户端配置参数，非 ssl 加密：

local server_ip = "121.43.224.154" -- 服务器 IP

local server_port = 21 -- 服务器端口号

local server_username = "ftp_user" -- 服务器登陆用户名

local server_password = "3QujbiMG" -- 服务器登陆密码

方法 1 Windows 资源管理器: - 打开“我的电脑”，在地址栏输入“ftp://121.43.224.154/”，按回车键。

在登录界面输入用户名和密码，点击登录，即可看到服务器上保存的文件。

方法 2 IE 浏览器访问: - 打开 IE 浏览器，在浏览器输入 121.43.224.154，回车，然后输入用户名和密码，点击登录，进入服务器。

方法 3 客户端软件：下载安装 Xftp 客户端软件，并配置好 ftp 服务器地址，端口号，用户名，密码等信息，即可登录，安装教程可自行上网查找。

注意选择 FTP 协议，如果新建会话后无法打开会话，可以再次检查登录信息是否正确。

五、API 接口说明

六、示例代码和功能展示

6.1 流程介绍

1、搭建好硬件环境

2、本示例使用的服务器参考第四章节 5. 访问 ftp 服务器，如果是自己的 ftp 服务器，在脚本代码 ftp_up_download.lua 的 config 表中按自己的服务器 IP，端口号，用户名，密码修改参数。

3、Luatools 烧录内核固件和修改后的 demo 脚本代码

4、烧录成功后，自动开机运行，查看打印日志，如果正常运行，会打印 ftp 登录成功，文件目录，上传下载文件结果等信息。

6.2 代码和 log

6.2.1 代码示例（点击查看 ftp 的完整 demo）

6.2.2 例程 log 打印如下：

[2025-09-03 19:02:43.349][000000001.712] I/user.netdrv_4g.ip_ready_func IP_READY 10.192.160.23 255.255.255.255 0.0.0.0 nil
[2025-09-03 19:02:43.357][000000001.713] I/user.ftp_login recv IP_READY 1 1
[2025-09-03 19:02:43.359][000000001.743] D/mobile TIME_SYNC 0
[2025-09-03 19:02:43.502][000000001.971] I/user.FTP登录成功
[2025-09-03 19:02:43.548][000000002.013] I/user.空操作，防止连接断掉 200 NOOP ok.

[2025-09-03 19:02:43.595][000000002.056] I/user.报告远程系统的操作系统类型 215 UNIX Type: L8

[2025-09-03 19:02:43.642][000000002.100] I/user.指定文件类型 200 Switching to Binary mode.

[2025-09-03 19:02:43.689][000000002.143] I/user.显示当前工作目录名 257 "/"

[2025-09-03 19:02:43.719][000000002.185] I/user.创建一个目录 目录名为QWER 257 "/QWER" created

[2025-09-03 19:02:43.765][000000002.227] I/user.改变当前工作目录为QWER 250 Directory successfully changed.

[2025-09-03 19:02:43.811][000000002.270] I/user.返回上一层目录 250 Directory successfully changed.

[2025-09-03 19:02:44.045][000000002.508] I/user.获取当前工作目录下的文件名列表 
[2025-09-03 19:02:44.050][000000002.508] drwx------    2 ftp      ftp          4096 Apr 29 08:43 080307100000002
drwx------    2 ftp      ftp          4096 Apr 11 01:22 080307100000003
drwx------    2 ftp      ftp          4096 Apr 11 01:22 080307100000004
drwx------    2 ftp      ftp          4096 Apr 11 01:22 080307100000005
drwx------    2 ftp      ftp          4096 Apr 11 01:23 080307100000006
drwx------    2 ftp      ftp          4096 Apr 30 06:16 080307100000022
drwx------    2 ftp      ftp          4096 Apr 30 06:16 080307100000023
drwx------    2 ftp      ftp          4096 Apr 30 06:16 080307100000024
drwx------    2 ftp      ftp          4096 Apr 30 06:16 080307100000025
drwx------    2 ftp      ftp          4096 Apr 30 06:16 080307100000026
drwx------    2 ftp      ftp          4096 Jul 25 10:40 080307100000027
drwx------    2 ftp      ftp          4096 Jul 25 10:04 080307100000028
-rw-------    1 ftp      ftp            62 Sep 01 01:31 1222.txt
-rw-------    1 ftp      ftp         27588 Jun 03 07:04 12222.mp4
-rw-------    1 ftp      ftp             0 Sep 01 01:04 12222.txt
-rw-------    1 ftp      ftp        174016 Jun 02 15:43 122224.mp4
-rw-------    1 ftp      ftp             0 Aug 27 02:58 12224.txt
drwx------    2 ftp      ftp          4096 Apr 19 04:49 23543121001
drwx------    2 ftp      ftp          4096 Sep 01 01:40 CAMERA
drwx------    2 ftp      ftp          4096 Aug 31 10:11 MT_T
drwx------    2 ftp      ftp          4096 Sep 03 11:02 QWER
drwx------    3 ftp      ftp          4096 Jul 09 08:02 Test
drwx------    2 ftp      ftp          4096 Apr 19 04:45 YKZ
-rw-------    1 ftp      ftp       1186492 Apr 19 06:12 data.dat
-rw-------    1 ftp      ftp        189943 Aug 29 08:23 ftp_test.mp4
-rw-------    1 ftp      ftp            62 Sep 01 01:36 test1222.txt
-rw-------    1 ftp      ftp            29 Sep 03 11:01 uploaded_by_luatos.txt

[2025-09-03 19:02:44.058][000000002.513] I/user.本地文件/ftp_upload.txt创建成功，并写入文件内容: Luatos FTP上传测试数据 
[2025-09-03 19:02:44.065][000000002.514] I/user.开始上传文件:/ftp_upload.txt
[2025-09-03 19:02:44.437][000000002.898] I/user.本地文件上传成功，保存在服务器路径: /uploaded_by_luatos.txt
[2025-09-03 19:02:44.443][000000002.898] I/user. 开始下载文件:/1222.txt
[2025-09-03 19:02:44.732][000000003.197] I/user.服务器上文件/1222.txt下载成功，保存在本地路径: /ftp_download.txt 大小: 62 字节
[2025-09-03 19:02:44.740][000000003.198] I/user.下载文件内容长度小于512字节，内容是: 23noianfdiasfhnpqw39fhawe;fuibnnpw3fheaios;fna;osfhisao;fadsfl
[2025-09-03 19:02:44.794][000000003.258] I/user.删除测试目录QWER 250 Remove directory operation successful.

[2025-09-03 19:02:44.840][000000003.301] I/user.FTP连接关闭结果: 221 Goodbye.

[2025-09-03 19:02:44.845][000000003.302] I/user.meminfo内存信息 3213352 113952 120640

6.2.3 luatools 页面显示如下：

6.2.4 ftp 服务器查看上传的文件

七、总结

本文档主要介绍 4G 通信中 FTP 通信的应用。

结合 demo 例程讲解了 FTP 基本原理，介绍了 FTP 主要 API,旨在最简单的快速上手 Air780EGH 的 LuatOS 的 FTP 开发.

八、常见问题

8.1 关于不支持主动模式：

模块 ftp 默认是被动模式，不支持主动模式，无法设置主动模式，公网下要想模块正常连接服务器，服务器肯定不能设置为主动模式，否则哪家模块都不能用.

8.2 ftp 服务器用 vsftpd

vsftpd 是一个 FTP 服务器软件， 是一个 UNIX 类操作系统上运行的服务器的名字，vsftpd 是 very secure FTP daemon 的缩写，安全性是它的一个最大的特点，它可以运行在诸如 Linux、BSD、Solaris、 HP-UNIX 等系统上面，是一个完全免费的、开放源代码的 ftp 服务器软件，负责搭建和提供文件存储、访问服务（相当于 “文件仓库”）,通过监听网络端口（默认 21 端口）接收客户端的连接请求，并根据配置允许用户上传、下载文件。

AI问答/AI搜索