9.0 KiB
9.0 KiB
FTP 功能测试指导
适用对象：STM32F4-Base 上基于
lftpd的 FTP Server 功能验证。 配套源码：Drivers/BSP/NET/lftpd/、App/task/net_task.c、Src/freertos.c（StartFtpTask）。 关联文档：CH395F_Test_Guide.md（网络测试总说明·阶段 8）、NET_Socket_FTP_Support_Plan.md（PASV 改造方案）、CH395F_Trap_Records.md。
1. 概述
- FTP Server（
lftpd）在默认固件构建中即常驻运行：Src/freertos.c的StartFtpTask（默认__weak实现）直接调用lftpd_start("/", 21, &ftp)，与测试套件选择无关。 - 监听端口 21，根目录
/（即 NAND 上的 FatFS 卷），匿名登录（USER anonymous/PASS任意）。 - 仅支持 1 个并发客户端（控制通道 Socket0 + PASV 数据通道动态 Socket2，backlog=1）。
- 测试分两类：
- PC 端手测（推荐，覆盖真实 FTP 行为）：用
test/下 Python 脚本或 GUI 客户端。 - 固件自动化（TEST_SUITE_CH395F 阶段 8）：TC-NET-801/802/803 文件传输。
- PC 端手测（推荐，覆盖真实 FTP 行为）：用
2. 测试环境
2.1 硬件与网络
- CH395F 网口经以太网连接到 PC 或同一台交换机。
- PC 网卡与固件 IP 同网段。固件默认静态 IP 192.168.1.100（掩码 255.255.255.0）；PC 可设 192.168.1.x（如 192.168.1.77）。
- 启动时
netTask完成net_init()+ PHY 稳定（约 >2s），ftpTask另有osDelay(7000)等待后才listen；若open_socket失败会vTaskDelay(3000)重试（最多 3 次）。客户端应在上电约 7s 后、串口出现[FTP] waiting for connection...再连接。
2.2 软件
- Python 3.x（脚本位于
test/）。 - 可选 GUI 客户端：FileZilla / MobaXterm / lftp。
3. 编译与运行（固件侧）
- 默认构建即可提供 FTP Server，无需切换测试套件。
- 任何改动后必须执行
@build（即MDK-ARM/build.bat），确认 0 Error(s) 0 Warning(s) 再烧录（遵循 AGENTS.md 铁律）。 - 若需跑自动化 FTP 文件传输用例：在
test/test_config.h选择TEST_SUITE_CH395F，并在test/ch395f_test.h打开ENABLE_PHASE8_TESTS（文件传输阶段），重新编译烧录。 - 烧录后打开串口（115200bps）观察：
net_init完成、PHY link up；[FTP] waiting for connection...（约 3 次重试足够 PHY 稳定）；- 客户端连接后进入 FTP 会话（控制通道 220 欢迎）。
4. PC 端脚本手测（主要手段）
所有脚本支持 --host（默认 192.168.1.100）、--port（默认 21），在 test/ 目录运行。
4.1 冒烟测试：ftp_test.py
- 用途：验证连接、登录、
PWD、PASV、LIST基本链路。 - 命令：
python ./test/ftp_test.py --host 192.168.1.100 - 预期：
- 连接成功并读到
220欢迎； USER anonymous/PASS返回230；PASV返回227并解析出数据端口（或回退EPSV）；LIST返回目录列表；QUIT正常关闭。
- 连接成功并读到
- 判据：全程无
[NO RESPONSE]/CONNECT FAILED，且 LIST 返回226即 PASS。空卷下 LIST 数据通道为 0 字节属正常（新格式化卷无文件），不必要求有目录列表输出。
4.2 上传 / 下载 / 比对：ftp_up_dl_test.py
- 用途：验证
STOR/RETR/DELE与数据一致性（TYPE I二进制 +PASV）。 - 命令：
python ./test/ftp_up_dl_test.py --host 192.168.1.100 - 流程：登录 →
TYPE I→STOR up_test.dat→LIST校验存在 →RETR up_test.dat→ 逐字节比对 →DELE清理 →QUIT。 - 预期：
*** MATCH! Upload/Download success. ***，且 LIST 中出现up_test.dat。 - 判据：上传/下载字节数相等且内容逐字节一致。
4.3 速度与大数据量：ftp_speed_test.py
- 用途：测量上传/下载吞吐，作回归基线，同时验证大文件不丢字节。
- 命令：
python ./test/ftp_speed_test.py --host 192.168.1.100 --size 512（默认 512KB，--size可调）。 - 预期：上传/下载均返回
226，回读MATCH!，打印 KB/s。 - 注意：脚本使用 8.3 文件名
SPEEDTST.DAT（FTP 仅支持 8.3 短文件名，见 §8.3）；以回读比对（MATCH）为最终判据，中间打印的 Sent 字段仅供参考。 - 判据：size 一致 + MATCH + 速度稳定（受 SPI2 分频 8 限制，通常约 300~450 KB/s，参见
CH395F_Test_Guide.md阶段 5 吞吐基线）。
4.4 抓包辅助：ftp_capture.py
- 用途：连接/传输过程中抓包，分析 PASV 端口、命令/数据通道交互，用于疑难排查。
- 用法参见脚本内
--help/ 注释。
5. GUI 客户端手测（可选）
- FileZilla：主机
192.168.1.100，端口 21，用户anonymous，密码任意；可拖拽上传/下载、浏览目录。 - 要点：使用二进制模式传输；文件名遵守 8.3；一次只连一个客户端。
6. 自动化测试（TEST_SUITE_CH395F 阶段 8）
- 入口：
ENABLE_PHASE8_TESTS→ 文件传输阶段（100KB 文件）。 - 用例：
TC-NET-801：100KB 文件上发（MCU→PC）；TC-NET-802：100KB 文件下发（PC→MCU）；TC-NET-803：round-trip（可选）。
- 详见
docs/CH395F_Test_Guide.md阶段 8。
7. 测试清单（Checklist）
- 默认构建烧录，串口见
[FTP] waiting for connection。 ftp_test.py冒烟 PASS（连接 / 登录 / PASV / LIST）。ftp_up_dl_test.py上传下载比对MATCH。ftp_speed_test.py大文件MATCH+ 记录速度基线。- （可选）GUI 客户端手动上传/下载成功。
- （可选）阶段 8 自动化
TC-NET-801/802/803PASS。
8. 常见失败与排查（基于已知陷阱）
8.1 连接被拒 / 长时间无欢迎
- 确认 PC 与固件同网段、IP 正确；上电后等待约 7s（PHY 稳定 +
ftpTask延迟）再连。 - 若反复
open_socket失败：见 TRAP-09（PHY 未稳定；固件已做 3 次重试 + 7s 延迟，仍失败检查网线/交换机）。
8.2 PASV 失败 / 数据通道连不上
- 确认 PC 防火墙未阻断高端口（PASV 动态端口）。
- 数据通道必须先
connect再发命令（如LIST/STOR），顺序反了会失败（脚本已遵循）。 - TRAP-11：
net_accept_locked在ESTABLISHED状态导致 PASV 失败——需校验ESTABLISHED。
8.3 STOR 报 FR_INVALID_NAME (err=6)
- 8.3 文件名限制：
upload_test.dat（11+3）超过 8.3 →FR_INVALID_NAME。改用短名如UPLOAD.DAT/SPEEDTST.DAT。这是 FatFS LFN/8.3 约束，非驱动 bug。
8.4 大文件传输中途 RST / 速度抖动
- TRAP-13 / 设计约束：CH395F
WRITE_SEND_BUF芯片侧吞吐限制，单帧 >1KB 才稳定；TCP 背压会"堵一会儿"，属正常流控，不丢数据。 - 接收侧
recv_len首包可能较大、次包可能为 0，必须循环读直到连接关闭（脚本已处理）。 - 若持续 RST：检查 SPI 分频 = 8（PCB 设计限制）、
net_poll()周期（10ms）是否正常、中断是否统一在net_poll()中经GET_GLOB_INT_STATUS处理。
8.5 路径问题
- TRAP-12：FatFS 根路径
/前缀由to_fatfs_path()统一处理；客户端用绝对路径（如/UPLOAD.DAT）即可。
8.6 单客户端限制
- FTP 仅接受 1 个并发客户端；上一个会话未
QUIT前，新连接会被拒。每次测完务必QUIT/ 断开。
8.7 LIST/STOR/RETR 全部 550：卷未挂载 / 无 FAT 文件系统
- 根因：FTP 服务的是 NAND 上的 FatFS 卷。固件在
StartDefaultTask启动期执行f_mount(&fs, "", 1)（会触发disk_initialize→nand_ftl_init），使卷可用。 - 首启自动建卷：若
f_mount返回FR_NO_FILESYSTEM（如坏块重建/恢复测试后卷被清空），固件会自动f_mkfs（FM_FAT32、无分区表，参数与存储测试一致）再挂载。该过程上电会多花数秒（格式化），串口可见[FS] no FAT volume, formatting NAND...→[FS] FATFS mounted。 - 若串口见
[FS] f_mount failed (fr=...)且非首次（已建卷仍失败）：检查f_mkfs是否报错（[FS] f_mkfs failed），或 NAND 是否存在物理/ECC 错误；必要时用TEST_SUITE_STORAGE跑一次确认磁盘健康。
9. 诊断手段（沿用前期测试经验）
- 串口日志 +
DBG_*：在lftpd.c/net_socket关键路径加DBG_ERROR/INFO打印（注意编码安全铁律——只用 Edit 改中文源文件，禁止用Get/Set-Content整文件重写）。 - 抓包：
ftp_capture.py或 Wireshark 过滤tcp.port==21。 - 编译验证：
@build必须 0/0 再烧录（AGENTS.md 铁律）。 - 套件切换：
test/test_config.h改TEST_SUITE_CH395F/TEST_SUITE_GD5F/TEST_SUITE_STORAGE（三选一，互斥）。
10. 参考文档
docs/CH395F_Test_Guide.md—— 网络测试总说明（含阶段 8 文件传输、FTP 陷阱清单）docs/NET_Socket_FTP_Support_Plan.md—— FTP / PASV Socket 改造方案docs/CH395F_Trap_Records.md—— CH395F 已知陷阱docs/BSD_Socket_API_使用指南.md—— BSD Socket API 用法