STM32F4-Base/docs/测试说明/FTP_Test_Guide.md

# 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 文件传输。

---

## 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）。
- **启动时序（2026-09-21 现行实现，取代旧文档的 `osDelay(7000)`）**：`netTask` 完成 `net_init()` + PHY 稳定后置 `SYS_EVT_NET_READY`；`defaultTask` 挂载卷 + 加载配置后置 `SYS_EVT_STORAGE_READY`；`ftpTask` 以 `osEventFlagsWait(两位, osFlagsWaitAll | osFlagsNoClear)` 等**两位同时就绪**再 `lftpd_start`。串口出现 `[FTP] waiting for connection...` 即可连接（实测：上电后约 0.5~1s，取决于存储挂载耗时）。
- ⚠ **就绪位等待必须带 `osFlagsNoClear`**（2026-09-21 实证，详见 §8.6）：`osEventFlagsWait` 默认**消费**所等待的位，若被其它等待者清掉，`ftpTask` 的 `WaitAll(两位)` 永不成立 → FTP 静默不监听。
- **单客户端**：监听 socket 与数据通道复用，同一时刻只服务 1 个会话；上一个会话未 `QUIT` 就断开时，服务端约 30s 后才丢弃旧会话并重新 listen，期间新连接被拒（`WinError 10061`）。脚本已内置连接重试；**不要用裸 TCP 工具探测 21 端口**（探测本身会占掉唯一会话，见 §8.7）。

### 2.2 软件

- Python 3.x（脚本位于 `test/`）。
- 可选 GUI 客户端：FileZilla / MobaXterm / lftp。

---

## 3. 编译与运行（固件侧）

- **默认构建即可提供 FTP Server**，无需切换测试套件。
- 任何改动后必须执行 `@build`（即 `keil-build` skill：`.dsh/skills/keil-build/scripts/keil_build.py`），确认 **0 Error(s) 0 Warning(s)** 再烧录（遵循 AGENTS.md 铁律）。
- 若需跑**自动化 FTP 文件传输用例**：在 `test/board/test_config.h` 选择 `TEST_SUITE_CH395F`，并在 `test/board/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/` 目录运行；`ftp_up_dl_test.py` / `ftp_speed_test.py` 内置**连接重试**（单客户端：旧会话未释放时自动等待重试，默认 6 次 × 3s）。
推荐入口：`& '.venv\Scripts\python.exe' test/host/ftp_up_dl_test.py`（功能闭环：登录/TYPE I/PASV/STOR/LIST/RETR/比对/DELE/QUIT）与 `& '.venv\Scripts\python.exe' test/host/ftp_speed_test.py --size 128`（大文件 + 吞吐）；后者同时是 **ftpTask 栈水位测量**的负载（见 `docs/内存管理/RAM使用分析与优化方案.md` §0.6）。

### 4.1 冒烟测试：`ftp_test.py`

- 用途：验证连接、登录、`PWD`、`PASV`、`LIST` 基本链路。
- 命令：`python ./test/host/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/host/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/host/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`（缺此行 → 见 §8.6）。
- [ ] `ftp_test.py` 冒烟 PASS（连接 / 登录 / PASV / LIST）。
- [ ] `ftp_up_dl_test.py` 上传下载比对 `MATCH`（10 项全 PASS）。
- [ ] `ftp_speed_test.py` 大文件 `MATCH` + 记录速度基线；同时用 `scripts/stack_report.py` 复核 ftpTask 栈余量（内存方案 §0.6）。
- [ ] （可选）GUI 客户端手动上传/下载成功。
- [ ] （可选）阶段 8 自动化 `TC-NET-801/802/803` PASS。

---

## 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 从不监听（21 端口一直拒绝）

- 现象：串口无 `[FTP] waiting for connection...`、无 `[LFT_INET]` 报错，`[STACK]` 行里 ftpTask 峰值极低（实测 156 B，仅为任务入口），21 端口始终 `connection refused`。
- 根因（2026-09-21 定位并修复）：`osEventFlagsWait` 默认**消费**所等待的位，而 `SYS_EVT_NET_READY` / `SYS_EVT_STORAGE_READY` 是**状态位**。`netTask` 等 `STORAGE_READY` 时清掉 bit1，`uiTask` / `timeSyncTask` 等 `NET_READY` 时清掉 bit0 → `ftpTask` 的 `WaitAll(bit0|bit1)` 条件永不成立，任务永久阻塞在内核等待队列（无日志、无报错、静默失效）。
- 修复：**所有就绪位等待加 `osFlagsNoClear`**（`Src/freertos.c` 的 ftpTask、`App/task/ui_task.c`、`App/sync/time_sync.c`、`App/task/net_task.c`、`test/board/ch395f_test_task.c`）；命令位（`SYS_EVT_CFG_SAVE` / `SYS_EVT_NET_RECONFIG`）保持消费型等待不变。
- 验证：修后串口出现 `[FTP] waiting for connection...`、21 端口可连；ftpTask 的 `[STACK]` 峰值握手后升到 ~2.5KB、128KB 传输后升到 ~3.4KB（该值曾触发余量告警，已在 2026-09-21 把 lftpd 大局部变量静态化后降到 **1184 B / 4096 B，余量 71%**——见内存方案 §1.4/§0.6）。

### 8.7 单客户端限制：端口"通"但随后连接被拒（旧会话未释放）

- **FTP 仅接受 1 个并发客户端**：上一个会话未 `QUIT` 前，新连接会被拒；每次测完务必 `QUIT` / 断开。
- 现象：用 `Test-NetConnection` / `nc` 探测 21 端口显示可达，紧接着 FTP 脚本却 `10061 connection refused`。
- 根因：探测本身完成了一次 TCP 握手 → 占用了 CH395F 唯一的会话 socket；服务端进入控制通道等待，直到读超时（约 30s）才打印 `[ERR] [FTP] error reading next command` 并回到 `waiting for connection...`。
- 处理：**别用裸 TCP 工具探测 21 端口**；用 FTP 脚本（已内置重试：默认 6 次 × 3s）。若已被占用，等约 30s 或复位设备。

### 8.8 吞吐远低于基线（本次实测 ~50~60 KB/s @128KB）

- 本次 128KB STOR/RETR 实测上/下行约 49 / 60 KB/s，明显低于阶段 5 记录的 300~450 KB/s（`CH395F_Test_Guide.md`）。
- 已知差异：FTP 路径每次读 512B 经 FatFs→FTL→NAND 写/读，而阶段 5 基线是裸 socket 吞吐；小文件（128KB）还叠加了会话建立/关闭开销。
- 待办：如需吞吐结论，用 `ftp_speed_test.py --size 512`~`2048` 复测并与阶段 5 基线对齐；必要时再查 `WRITE_SEND_BUF` 分帧与 `net_poll` 周期。

### 8.9 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/board/test_config.h` 改 `TEST_SUITE_CH395F` / `TEST_SUITE_GD5F` / `TEST_SUITE_STORAGE`（三选一，互斥）。

---

## 10. 参考文档

- `docs/测试说明/CH395F_Test_Guide.md` —— 网络测试总说明（含阶段 8 文件传输、FTP 陷阱清单）
- `[计划]` FTP / PASV Socket 改造方案（尚未创建）
- `docs/问题记录/CH395F_Trap_Records.md` —— CH395F 已知陷阱
- `docs/网络/BSD_Socket_API_使用指南.md` —— BSD Socket API 用法