@electerm/ftp-srv

现代、可扩展的 FTP 服务器（TypeScript 版本）。

本项目是 ftp-srv 的 TypeScript 重构版本，同时发布 ESM 和 CJS 格式——并修复了原版中的安全漏洞。API 与原版 ftp-srv 向后兼容。

原始实现的全部功劳归于原作者 Tyler Stewart。详见 CREDITS 文件。

安装

npm install @electerm/ftp-srv

使用

// ESM
import FtpServer from '@electerm/ftp-srv';

// CJS
const { FtpServer } = require('@electerm/ftp-srv');

// 向后兼容别名（兼容原始 ftp-srv 包）
const { FtpSrv } = require('@electerm/ftp-srv');

基本示例

import FtpServer from '@electerm/ftp-srv';

const server = new FtpServer({
  url: 'ftp://0.0.0.0:21',
  anonymous: false,
});

server.on('login', ({ connection, username, password }, resolve, reject) => {
  if (username === 'admin' && password === 'secret') {
    return resolve({ root: '/srv/ftp' });
  }
  return reject(new Error('用户名或密码无效'));
});

await server.listen();
console.log('FTP 服务器已在 21 端口启动');

// 优雅关闭
await server.close();

按用户设置根目录

const server = new FtpServer({
  url: 'ftp://0.0.0.0:2121',
  pasv_min: 10000,
  pasv_max: 10100,
  anonymous: false,
});

server.on('login', ({ username, password }, resolve, reject) => {
  if (username === 'alice' && password === 'pass') {
    return resolve({
      root: '/home/alice',
      cwd: '/uploads',  // 初始工作目录（相对于 root）
    });
  }
  return reject(new Error('凭据无效'));
});

await server.listen();

匿名访问

const server = new FtpServer({
  url: 'ftp://0.0.0.0:21',
  anonymous: true,   // 接受任意用户名/密码
  root: '/srv/ftp',  // 所有连接的默认根目录
});

server.on('login', (_, resolve) => resolve({}));

await server.listen();

TLS（FTPS）

import fs from 'fs';

const server = new FtpServer({
  url: 'ftps://0.0.0.0:990',
  tls: {
    key: fs.readFileSync('server.key'),
    cert: fs.readFileSync('server.crt'),
  },
});

配置了 tls 后两种方式都支持：

• 隐式 FTPS —— url: 'ftps://...'，控制连接从第一个字节起就是 TLS。
• 显式 FTPS（FTPES） —— url: 'ftp://...'，客户端发 AUTH TLS 后控制连接就地升级（RFC 4217）， 传输前再 PBSZ 0 / PROT P。数据连接同样加密。FEAT 只在配置了 tls 时才通告 AUTH TLS / PBSZ / PROT；没配 tls 时直接回 502，不会假装升级成功。

安全说明

• FTP bounce 防护 —— 只有当 PORT / EPRT 给出的地址就是客户端自己（控制连接的对端地址）时才接受； 被动数据连接来自其他主机时一律回 550 并断开。两个命令都要求已登录。
• 被动端口会释放 —— 重复发送 PASV / EPSV 会先关闭上一个监听，空闲 30s 的被动监听也会自动关闭， 客户端连进来却不传输也吃不满端口段。
• 数据通道加密 —— 配置 tls 后，被动/主动数据连接同样是 TLS，不只是控制连接。

API

new FtpServer(options)

server.listen() → Promise<string>

启动服务器并开始接受连接。

server.close() → Promise<void>

优雅关闭所有连接并停止服务器。

事件

login

客户端尝试登录时触发。必须监听此事件并调用 resolve 或 reject。

server.on('login', ({ connection, username, password }, resolve, reject) => {
  // 使用每用户选项 resolve：
  resolve({
    root: '/srv/ftp/alice',  // 本次会话的根目录
    cwd: '/',                // 初始工作目录（相对于 root）
    fs: customFsInstance,    // 自定义 FileSystem 实例（可选）
    blacklist: ['DELE'],     // 每连接命令黑名单
    whitelist: [],           // 每连接命令白名单
  });

  // 或拒绝登录：
  reject(new Error('凭据无效'));
});

connect

新客户端 socket 连接时触发（登录前）。

server.on('connect', ({ connection, id, newConnectionCount }) => {});

disconnect

客户端断开连接时触发。

server.on('disconnect', ({ connection, id, newConnectionCount }) => {});

client-error

客户端连接发生错误时触发。

server.on('client-error', ({ connection, context, error }) => {});

server-error

底层 TCP 服务器发生错误时触发。

server.on('server-error', ({ error }) => {});

closing / closed

调用 close() 时及关闭完成后触发。

server.on('closing', () => {});
server.on('closed', () => {});

自定义文件系统

继承 FileSystem 可覆盖服务器读写文件的方式。

import { FileSystem } from '@electerm/ftp-srv';

class MyFileSystem extends FileSystem {
  async list(dirPath = '.') {
    // 返回带有 name 属性的 fs.Stats 类对象数组
    const entries = await super.list(dirPath);
    return entries.filter(e => !e.name.startsWith('.'));  // 隐藏点文件
  }

  async get(fileName) {
    return super.get(fileName);
  }
}

server.on('login', (_, resolve) => {
  resolve({ fs: new MyFileSystem(connection, { root: '/srv/ftp' }) });
});

可覆盖的方法：

导出

import FtpServer, {
  FtpServer,       // 具名导出（同一个类）
  FtpSrv,          // 向后兼容别名，兼容原始 ftp-srv 包
  FileSystem,
  FtpConnection,
  errors,
} from '@electerm/ftp-srv';

命令行

npx electermftpsrv ftp://0.0.0.0:9876 --root ~/Documents

License

MIT