ESP32调用AppendFile函数向FTP服务器追加文件时出现425连接错误

问题现象 #

使用ESP32连接QNAP TS-251的QuFTP Service 1.3.1服务器，创建并写入文件操作正常，但关闭文件后调用AppendFile()再执行Write()时，串口输出错误：

FTP error: 425 Unable to build data connection: Connection refused

使用代码 #

#include "Arduino.h"
#include <WiFi.h>
#include <WiFiClient.h> 
#include <ESP32_FTPClient.h>

const char* ssid = "";
const char* password = "";

char ftp_server[] = "";
char ftp_user[]   = "";
char ftp_pass[]   = "";

ESP32_FTPClient ftp (ftp_server,ftp_user,ftp_pass);

void setup()
{
  Serial.begin( 115200 );

  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
    Serial.println("Connessione Wi-Fi in corso...");
  }
  Serial.println("");
  Serial.print("IP address: ");
  Serial.println(WiFi.localIP());

  Serial.print("\nMax Free Heap: ");
  Serial.println(ESP.getMaxAllocHeap());
  Serial.println("");

  ftp.OpenConnection();

  //Change directory
  ftp.ChangeWorkDir("/Web/W.Station/Data/");

  ftp.InitFile("Type A");
  ftp.NewFile("helloworld.txt");
  ftp.Write("Hi, I'm a new file");
  ftp.CloseFile();


  ftp.AppendFile("helloworld.txt");
  ftp.Write("\nWriting with AppendFile");
  ftp.CloseFile();
  ftp.CloseConnection();
}

服务器日志 #

需求与疑问 #

希望通过AppendFile()重新打开文件并追加文本，但相关资料匮乏，不确定是否函数使用方式错误，寻求可行解决方法。

解决思路与修正代码 #

核心原因 #

1. FTP模式问题：默认主动模式下，ESP32需要开放端口供服务器发起连接，容易被路由器防火墙或QNAP的安全策略拦截，导致数据连接建立失败（425错误）。
2. 库函数调用逻辑：AppendFile()未自动重新初始化数据连接，需要手动再次调用InitFile()来建立新的数据通道。

修正后的代码 #

#include "Arduino.h"
#include <WiFi.h>
#include <WiFiClient.h> 
#include <ESP32_FTPClient.h>

const char* ssid = "";
const char* password = "";

char ftp_server[] = "";
char ftp_user[]   = "";
char ftp_pass[]   = "";

ESP32_FTPClient ftp (ftp_server,ftp_user,ftp_pass);

void setup()
{
  Serial.begin( 115200 );

  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
    Serial.println("Connessione Wi-Fi in corso...");
  }
  Serial.println("");
  Serial.print("IP address: ");
  Serial.println(WiFi.localIP());

  Serial.print("\nMax Free Heap: ");
  Serial.println(ESP.getMaxAllocHeap());
  Serial.println("");

  ftp.OpenConnection();
  // 切换为被动模式，避免主动模式的端口拦截问题
  ftp.PassiveMode();

  //Change directory
  ftp.ChangeWorkDir("/Web/W.Station/Data/");

  ftp.InitFile("Type A");
  ftp.NewFile("helloworld.txt");
  ftp.Write("Hi, I'm a new file");
  ftp.CloseFile();

  // 追加文件前重新初始化文件类型，建立新的数据连接
  ftp.InitFile("Type A");
  ftp.AppendFile("helloworld.txt");
  ftp.Write("\nWriting with AppendFile");
  ftp.CloseFile();
  ftp.CloseConnection();
}

关键修改点 #

• 连接后添加ftp.PassiveMode();：切换到FTP被动模式，由服务器开放数据端口，ESP32主动发起连接，规避端口拦截问题。
• 调用AppendFile()前重新执行ftp.InitFile("Type A");：重新初始化数据连接通道，确保追加操作能正常建立数据链路。

内容的提问来源于stack exchange，提问作者4n3s1-2525