FineFTP-Server 轻量级 C++ 跨平台 FTP 服务器指南

3.2.核心 API 概览

权限选项(可组合)：

• Permission::Read：读取文件 / 目录
• Permission::Write：写入 / 修改文件
• Permission::Delete：删除文件 / 目录
• Permission::All：所有权限

3.3.连接测试

客户端连接：

使用 FileZilla 或其他 FTP 客户端，连接至服务器 IP (或 localhost)，端口 2121，使用配置好的用户名和密码 (或匿名方式) 登录即可进行文件操作。

4.实现完善断点续传功能

fineftp-server 原生已预留 REST 命令框架，但部分版本存在「偏移量未生效」「文件覆盖而非续传」等问题，需通过源码修改强化处理逻辑。以下基于 fineftp-server v1.1.0 版本（最新稳定版），聚焦 REST 命令解析、STOR/RETR 偏移应用、文件打开模式优化三大核心点，提供完整修改方案。

4.1.核心修改思路

1. 会话级偏移存储：为每个 FTP 连接（FtpSession）添加续传偏移量变量，仅对当前连接有效；
2. REST 命令完善：解析偏移量参数，校验合法性，返回标准响应；
3. STOR 命令适配：续传时以「追加 + 定位」模式打开文件，而非覆盖；
4. RETR 命令适配：续传时从偏移量开始读取文件，更新响应头中的文件大小；
5. 边界处理：偏移量超文件大小、文件不存在等异常场景返回标准 FTP 错误码。

4.2.具体源码修改步骤

步骤 1：定位核心文件

需修改 2 个关键文件（fineftp-server 源码根目录 /src 下）：

• ftp_session.h：会话类头文件（添加偏移量成员）；
• ftp_session.cpp：会话逻辑实现（处理 REST/STOR/RETR 命令）。

步骤 2：修改 ftp_session.h（添加偏移量成员）

在 FtpSession 类中添加「续传偏移量」和「偏移量是否有效」标记，用于存储当前连接的续传位置：

// ftp_session.h
#include <cstdint> // 需包含该头文件以支持 uint64_t

class FtpSession {
private:
    // 新增以下 2 个成员变量（放在私有成员区域）
    uint64_t rest_offset_ = 0; // 续传偏移量（默认 0，即从头传输）
    bool rest_offset_valid_ = false; // 偏移量是否有效（避免 REST 后未执行 STOR/RETR）
    // 其他原有成员（如 m_server、m_socket 等）...
public:
    // 新增重置偏移量的接口（可选，用于后续优化）
    void resetRestOffset() { rest_offset_ = 0; rest_offset_valid_ = false; }
    // 其他原有接口（如 start、handleCommand 等）...
};

步骤 3：修改 ftp_session.cpp（完善命令处理逻辑）

1) 处理 REST 命令（解析偏移量）

找到 handleCommand 函数中处理 REST 命令的分支（若无则新增），解析客户端传入的偏移量，校验合法性并存储：

// ftp_session.cpp
void FtpSession::handleCommand(const std::string& cmd, const std::string& args) {
    // 其他命令处理（如 USER、PASS、PASV 等）...
    // 新增/修改 REST 命令处理分支
    else if (cmd == "REST") {
        if (args.empty()) {
            sendResponse(501, "REST command requires an offset parameter");
            return;
        }
        // 解析偏移量（支持十进制数字）
        try {
            uint64_t offset = std::stoull(args);
            rest_offset_ = offset;
            rest_offset_valid_ = true;
            sendResponse(350, "Restart position accepted (" + std::to_string(offset) + ")");
        } catch (const std::invalid_argument&) {
            sendResponse(501, "Invalid offset value (must be a non-negative integer)");
        } catch (const std::out_of_range&) {
            sendResponse(501, "Offset value too large");
        }
    }
    // 其他命令处理（如 STOR、RETR 等）...
}

2) 修改 STOR 命令（上传续传：从偏移量写入）

找到 handleStor 函数（处理文件上传），修改文件打开模式，添加偏移量定位逻辑：

// ftp_session.cpp
void FtpSession::handleStor(const std::string& filename) {
    // 1. 拼接完整文件路径（原有逻辑保留）
    std::string filePath = getAbsolutePath(filename);
    if (!checkFileAccess(filePath, Permission::Write)) {
        sendResponse(550, "Permission denied");
        return;
    }
    // 2. 优化文件打开模式（关键修改）
    std::ios_base::openmode openMode = std::ios::binary | std::ios::out;
    if (rest_offset_valid_) {
        // 续传：以「读写 + 追加」模式打开，避免覆盖
        openMode |= std::ios::in | std::ios::app;
    } else {
        // 正常上传：覆盖已有文件
        openMode |= std::ios::trunc;
    }
    // 3. 打开文件
    std::ofstream file(filePath, openMode);
    if (!file.is_open()) {
        sendResponse(550, "Failed to open file for writing");
        resetRestOffset(); // 打开失败，重置偏移量
        return;
    }
    // 4. 续传偏移量定位（关键修改）
    if (rest_offset_valid_) {
        // 定位到续传起始位置
        file.seekp(rest_offset_, std::ios::beg);
        // 校验定位是否成功
        if (file.tellp() != static_cast<std::streamoff>(rest_offset_)) {
            sendResponse(550, "Failed to seek to restart position");
            file.close();
            resetRestOffset();
            return;
        }
        sendResponse(150, "Opening data connection for file upload (restart at " + std::to_string(rest_offset_) + ")");
    } else {
        sendResponse(150, "Opening data connection for file upload");
    }
    // 5. 数据传输（原有逻辑保留，无需修改）
    transferDataToFile(file);
    file.close();
    // 6. 传输完成后重置偏移量（关键：避免影响后续传输）
    resetRestOffset();
    sendResponse(226, "File upload completed successfully");
}

3) 修改 RETR 命令（下载续传：从偏移量读取）

找到 handleRetr 函数（处理文件下载），添加偏移量定位和文件大小修正逻辑：

// ftp_session.cpp
void FtpSession::handleRetr(const std::string& filename) {
    // 1. 拼接完整文件路径（原有逻辑保留）
    std::string filePath = getAbsolutePath(filename);
    if (!checkFileAccess(filePath, Permission::Read)) {
        sendResponse(550, "Permission denied");
        return;
    }
    // 2. 打开文件（只读二进制模式）
    std::ifstream file(filePath, std::ios::binary | std::ios::in);
    if (!file.is_open()) {
        sendResponse(550, "File not found or cannot be opened");
        resetRestOffset();
        return;
    }
    // 3. 获取文件总大小（原有逻辑保留）
    file.seekg(0, std::ios::end);
    uint64_t fileSize = static_cast<uint64_t>(file.tellg());
    file.seekg(0, std::ios::beg);
    // 4. 续传偏移量处理（关键修改）
    if (rest_offset_valid_) {
        // 校验偏移量是否合法（不超过文件大小）
        if (rest_offset_ > fileSize) {
            sendResponse(550, "Restart offset exceeds file size (" + std::to_string(fileSize) + ")");
            file.close();
            resetRestOffset();
            return;
        }
        // 定位到续传起始位置
        file.seekg(rest_offset_, std::ios::beg);
        // 修正响应中的文件大小（剩余待传输大小）
        uint64_t remainingSize = fileSize - rest_offset_;
        sendResponse(150, "Opening data connection for file download (restart at " + std::to_string(rest_offset_) + ", remaining " + std::to_string(remainingSize) + " bytes)");
    } else {
        sendResponse(150, "Opening data connection for file download (size " + std::to_string(fileSize) + " bytes)");
    }
    // 5. 数据传输（原有逻辑保留，无需修改）
    transferFileToData(file);
    file.close();
    // 6. 传输完成后重置偏移量
    resetRestOffset();
    sendResponse(226, "File download completed successfully");
}

4) 优化偏移量重置逻辑（避免残留影响）

在「传输取消」「命令切换」时重置偏移量，确保后续传输不受之前 REST 命令影响。在 ftp_session.cpp 中添加以下场景的重置：

• 每次执行 STOR/RETR 后（已在上述代码中添加 resetRestOffset()）；
• 执行 ABOR（取消传输）命令时：

// 在 handleCommand 中找到 ABOR 命令分支，添加重置
else if (cmd == "ABOR") {
    // 原有取消传输逻辑...
    resetRestOffset(); // 新增：取消后重置偏移量
    sendResponse(226, "Transfer aborted");
}

• 执行 QUIT（断开连接）命令时：

else if (cmd == "QUIT") {
    resetRestOffset(); // 新增：断开前重置偏移量
    sendResponse(221, "Goodbye");
    m_running = false;
}

5）客户端验证步骤

• 使用 FileZilla 客户端：连接服务器 → 上传大文件 → 中途暂停 / 断开 → 右键「继续上传」，观察文件从断点位置续传，无覆盖；
• 使用自定义客户端：发送 REST 65536（偏移量 64KB）→ 发送 STOR test.bin，服务器会从 1KB 位置写入文件。

4.3.关键注意事项

1. 在 windows 上发送 REST 指令的时候，偏移大小一定要是 64K 的整数倍。 那是因为 fineftp-server 内部读取文件是用的内存映射，函数 MapViewOfFile 的文件偏移量未对齐，偏移量必须是 64KB (0x10000) 的整数倍，这是 Windows 内存映射的基本粒度要求。

错误示例：

// 偏移量 12345 不是 64KB 倍数，会导致 1132 错误
MapViewOfFile(hMap, FILE_MAP_READ, 0, 12345, 0);

修正偏移量对齐问题

// 正确方式：确保偏移量是 64KB 的倍数
#define FILE_OFFSET_ALIGN 0x10000 // 64KB
// 计算正确的偏移量
DWORD dwFileOffset = desiredOffset & ~(FILE_OFFSET_ALIGN - 1);
// 使用正确的偏移量调用 MapViewOfFile
MapViewOfFile(hMap, FILE_MAP_READ, (DWORD)(dwFileOffset >> 32), // 高 32 位
              (DWORD)(dwFileOffset & 0xFFFFFFFF), // 低 32 位
              dwNumberOfBytesToMap);

4.4.系统 bug

断点续传上传文件的时候，服务器是追加文件，当上传到服务器的文件超过 4G 字节大小后，客户端再次上传文件就会报错，原因在下面地方：

应该修改为：

if (INVALID_HANDLE_VALUE != handle_ && (mode & std::ios::app) == std::ios::app) {
    LARGE_INTEGER offset = { 0, 0};
    offset.LowPart = ::SetFilePointer(handle_, 0, &offset.HighPart, FILE_END);
    if ((INVALID_SET_FILE_POINTER == offset.LowPart) && (GetLastError() != NO_ERROR)) {
        close();
    }
}

4.5.Linux 移植经验

同样的代码在 Windows 编译链接，运行没有问题；但是移植到 ubuntu 下面，ftp 服务开启正常，但是用 FileZilla 客户端连接不上，在 ubuntu 上面用 ss 命令查看端口占用情况，看到 tcp 端口正常监听。

用 telnet 命令测试 tcp 端口是否可连，结果如下图：

说明 ftp 的端口是打开了的，通过 wireshark 抓包，tcp 三次握手，可以正常建立 tcp 连接，那为什么进入不了 ftp 的相关逻辑流程，即进入不了 asio::ip::tcp::acceptor 的函数 async_accept 设置的异步回调函数中。

于是再用 strace 跟踪进程的系统调用，直接看到内核层面发生了什么：

sudo strace -f -p 你的进程 PID -e trace=accept,read,write

根本没有打印出 accept,read,write 相关的信息，说明进程根本没有这几个 accept,read,write 的函数调用。最上面的图中 Recv-Q 为 1 也可以证明这点，Recv-Q 为 1 意思是内核收到了 tcp 连接数据，应用层没有读取这个数据。

再想办法，把代码中一些可疑之处修改了一下：

1. 给 async_accept 回调加全量异常捕获，确保就算业务代码抛异常，也能重新发起 async_accept，保证循环不中断：

// 若你修改了 fineftp 的 accept 逻辑，必须按这个格式写
acceptor_.async_accept(socket_, [this](boost::system::error_code ec) {
    try {
        if (!ec) {
            // 处理新连接，创建 FTP 会话
            std::make_shared<FtpSession>(std::move(socket_))->start();
        }
    } catch (...) {
        // 捕获所有异常，绝对不能让回调异常退出
    }
    // 【核心】无论是否出错，必须重新发起 async_accept
    start_accept();
});

2. 给 io_context 加 work_guard 保活。

3. 给 fineftp 设置更大的 listen backlog

ftp_server.setListenBacklog(1024);

发现都不行，最后把 fineftp 的整个代码移植到工程中，通过源码集成；启动 ftp 服务，结果 FileZilla 客户端可以连接了，问题解决了，但是还是不知道具体什么原因。

5.与其他开源 FTP 服务器对比

5.1.功能特性对比表

5.2.详细对比分析

vsftpd：Linux 服务器首选，以 "安全、高效、轻量" 著称，拥有最小代码库减少攻击面，默认启用 chroot 隔离，支持 TLS 加密和虚拟用户。适合高安全要求的生产环境。与 fineftp-server 相比，它是独立守护进程而非库，配置更灵活但复杂度较高。

ProFTPD：提供 Apache 风格配置，支持虚拟主机、LDAP 认证、带宽限制等高级特性，适合需要高度定制化的企业环境。与 fineftp-server 相比，它功能更全面但资源占用更高，配置更复杂。

Pure-FTPd：设计简单易用，提供多种认证方式和配额管理，支持 TLS 加密和虚拟用户。与 fineftp-server 相比，它是独立服务器，提供更完善的管理功能和安全性。

fineftp-server 独特优势：

• 嵌入式集成：以库形式提供，可无缝融入 C++ 项目，无需单独运行进程
• 极简 API：几行代码即可完成 FTP 服务集成，无需学习复杂配置语法
• 零依赖(除 asio)：减少外部依赖，简化部署
• 代码级控制：所有配置通过 API 完成，便于动态调整服务行为

6.总结与建议

fineftp-server 是轻量级 FTP 解决方案，特别适合需要在 C++ 应用中快速集成 FTP 服务的场景。它的极简设计和 API 使其成为嵌入式系统、测试环境和内部网络文件共享的理想选择。

使用建议：

• 仅在信任网络环境中使用 (无加密)
• 如需安全传输，考虑在应用层添加 TLS/SSL 包装
• 对性能要求高的场景，可考虑 vsftpd 等专门优化的独立服务器
• 对需要复杂权限管理的企业环境，建议使用 ProFTPD 或 Pure-FTPd