# node-sftp

**Repository Path**: taixd/node-sftp

## Basic Information

- **Project Name**: node-sftp
- **Description**: 基于node.js 的sftp cli 工具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-28
- **Last Updated**: 2025-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SFTPX - 交互式 SFTP 上传/下载 CLI 工具

[![npm version](https://badge.fury.io/js/sftpx.svg)](https://badge.fury.io/js/sftpx)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

SFTPX 是一个功能强大的交互式 SFTP 客户端工具，支持密码和私钥认证，提供直观的命令行界面进行文件上传和下载操作。

## 主要功能

- 🚀 **快速文件传输** - 支持单个文件和批量文件的上传/下载
- 📁 **批量操作** - 支持通配符模式匹配多个文件
- 🔐 **多种认证方式** - 支持密码和私钥认证
- 📊 **进度显示** - 实时显示传输进度和速度
- ✅ **完整性验证** - 支持文件哈希校验确保传输完整性
- ⏸️ **断点续传** - 支持大文件的断点续传
- ⚙️ **配置管理** - 安全存储和管理多个服务器配置
- 🔌 **SSH配置集成** - 可导出配置到SSH客户端

## 安装

### 全局安装

```bash
npm install -g sftpx
```

### 本地安装

```bash
npm install sftpx
```

## 快速开始

### 1. 添加服务器配置

```bash
# 使用密码认证
sftpx set-auth name:myserver username password host port

# 示例
sftpx set-auth name:myserver admin password123 example.com 22
```

### 2. 连接到服务器

```bash
sftpx -ssh myserver
```

### 3. 上传文件

```bash
# 上传单个文件
sftpx upload local/path/file.txt /remote/path/

# 批量上传
sftpx upload "local/path/*.txt" /remote/path/
```

### 4. 下载文件

```bash
# 下载单个文件
sftpx download /remote/path/file.txt local/path/

# 批量下载
sftpx download "/remote/path/*.txt" local/path/
```

## 命令参考

### 配置管理

- `sftpx set-auth name:配置名 用户名 密码 [主机] [端口]` - 添加服务器配置
- `sftpx get-auth 配置名` - 查看配置信息
- `sftpx remove-auth 配置名` - 删除配置

### 连接操作

- `sftpx -ssh 配置名` - 使用配置连接服务器
- `sftpx --check 配置名 远程路径` - 检查远程目录是否存在

### SSH配置管理

- `sftpx --export-ssh 配置名 [别名]` - 导出配置到SSH客户端
- `sftpx --export-all-ssh` - 导出所有配置到SSH客户端
- `sftpx --list-ssh` - 列出已导出的SSH配置
- `sftpx --remove-ssh 别名` - 移除SSH配置

### 其他命令

- `sftpx -v/--version` - 显示版本信息
- `sftpx -h/--help` - 显示帮助信息

## 高级用法

### 使用私钥认证

```javascript
// 在配置中指定私钥路径
const config = {
  host: 'example.com',
  port: 22,
  username: 'user',
  authType: 'key',
  privateKeyPath: '/path/to/private/key',
  passphrase: 'optional-passphrase'
};
```

### 批量传输选项

```javascript
// 上传选项
const uploadOptions = {
  preserveStructure: true,    // 保持目录结构
  maxConcurrent: 3,           // 最大并发数
  verifyIntegrity: true,      // 验证文件完整性
  integrityAlgorithm: 'md5',  // 哈希算法
  resume: true,               // 支持断点续传
  filter: (file) => {         // 文件过滤器
    return !file.includes('test');
  },
  onProgress: (progress) => { // 进度回调
    console.log(`进度: ${progress.completed}/${progress.total}`);
  }
};
```

### 环境变量配置

可以通过环境变量设置默认配置：

```bash
export SFTPX_CONFIG_PATH=/custom/path/to/config
export SFTPX_DEFAULT_HOST=example.com
export SFTPX_DEFAULT_PORT=22
```

## 配置文件

配置文件默认存储在 `~/.sftpx/config.json`，使用AES-256-CBC加密存储敏感信息。

### 配置示例

```json
{
  "servers": {
    "myserver": {
      "host": "example.com",
      "port": 22,
      "username": "admin",
      "authType": "password",
      "password": "encrypted_password"
    },
    "keyserver": {
      "host": "example.com",
      "port": 22,
      "username": "user",
      "authType": "key",
      "privateKeyPath": "/path/to/private/key",
      "passphrase": "encrypted_passphrase"
    }
  }
}
```

## API 使用

```javascript
import SFTPClient from 'sftpx/src/sftp/sftpClient.js';

const client = new SFTPClient();

// 连接
await client.connect({
  host: 'example.com',
  port: 22,
  username: 'user',
  password: 'password'
});

// 上传文件
await client.uploadFile('local.txt', '/remote/remote.txt', {
  verifyIntegrity: true,
  resume: true
});

// 批量上传
await client.uploadFiles(['*.txt'], '/remote/path/', {
  maxConcurrent: 5,
  preserveStructure: true
});

// 下载文件
await client.downloadFile('/remote/file.txt', 'local.txt', {
  verifyIntegrity: true,
  resume: true
});

// 批量下载
await client.downloadFiles(['/remote/*.txt'], 'local/path/', {
  maxConcurrent: 5,
  preserveStructure: true
});

// 列出远程文件
const files = await client.listFiles('/remote/path/');

// 获取文件信息
const info = await client.getFileInfo('/remote/file.txt');

// 删除文件
await client.deleteFile('/remote/file.txt');

// 断开连接
await client.disconnect();
```

## 项目结构

```
node-sftp/
├── bin/                    # 可执行文件
│   └── sftpx.js           # CLI入口点
├── src/                   # 源代码
│   ├── cli.js             # CLI主逻辑
│   ├── index.js           # 主入口文件
│   ├── config/            # 配置管理
│   │   ├── configManager.js
│   │   └── sshConfigManager.js
│   ├── menus/             # 交互式菜单
│   │   ├── configMenu.js
│   │   ├── connectionMenu.js
│   │   ├── fileTransferMenu.js
│   │   └── mainMenu.js
│   ├── sftp/              # SFTP客户端
│   │   ├── batchTransfer.js
│   │   └── sftpClient.js
│   └── utils/             # 工具函数
│       ├── configHelper.js
│       ├── errorHandler.js
│       ├── logger.js
│       ├── pathUtils.js
│       ├── progressBar.js
│       ├── sessionLog.js
│       └── sftpHelper.js
├── test/                  # 测试文件
└── package.json
```

## 系统要求

- Node.js >= 16.0.0
- 支持的操作系统: Windows, macOS, Linux

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v1.0.6

- 优化上传下载功能一致性，统一缓冲区策略
- 修复断点续传功能，提高大文件传输可靠性
- 统一错误处理和日志格式，提升用户体验
- 优化文件完整性验证流程，支持多种哈希算法
- 改进进度显示和传输速度计算

### v1.0.5

- 修复 isConnected 方法与属性的命名冲突问题
- 添加 _formatFileSize 方法用于格式化文件大小显示
- 修复 _calculateRemoteFileHash 方法中的 this.sftp.get 问题
- 添加 deleteFile 方法用于删除远程文件
- 优化批量传输性能和错误处理

### v1.0.4

- 添加批量文件上传/下载功能
- 支持文件完整性验证
- 添加断点续传功能
- 优化进度显示和错误处理

### v1.0.3

- 添加SSH配置导出功能
- 改进配置管理界面
- 优化连接稳定性

### v1.0.2

- 添加私钥认证支持
- 改进错误处理机制
- 优化用户界面

### v1.0.1

- 添加快速命令支持
- 改进配置加密存储
- 优化文件传输性能

### v1.0.0

- 初始版本发布
- 基本文件上传/下载功能
- 交互式命令行界面