@itriton/sftp

基于 ssh2-sftp-client 的项目部署工具，支持密钥证书登录和配置文件管理。

✨ 特性

• 🚀 简单易用 - 一键初始化配置，一键部署项目
• 🔐 安全认证 - 支持密码和私钥两种认证方式
• ⚙️ 灵活配置 - 支持多环境配置管理
• 📁 智能过滤 - 支持文件/目录排除规则
• 🔍 试运行模式 - 安全预览将要上传的文件
• 📊 详细日志 - 完整的上传过程记录
• 🎯 TypeScript - 完整的类型定义支持
• 🗜️ 压缩传输 - 支持压缩包传输，大幅提升大量文件的传输效率
• 🚀 智能模式 - 自动根据文件数量选择最优传输方式

📦 安装

npm install -g @itriton/sftp

或者在项目中使用：

npm install @itriton/sftp --save-dev

🚀 快速开始

使用方式快速参考

| 使用场景 | 安装方式 | 使用命令 | 说明 | |---------|---------|---------|------| | 项目中使用（推荐） | npm install @itriton/sftp --save-dev | itriton-sftp 或 npx itriton-sftp | 在 package.json scripts 中使用 | | 临时使用 | 无需安装 | npx @itriton/sftp | 直接使用，注意是包名 | | 全局使用 | npm install -g @itriton/sftp | itriton-sftp | 在任何地方都能使用命令 |

重要提醒：

• 📦 包名：@itriton/sftp （用于 npm install 和 npx）
• 🔧 命令名：itriton-sftp （用于 package.json scripts 和全局命令）

1. 初始化配置

# 交互式创建配置文件
itriton-sftp init

# 指定配置名称
itriton-sftp init --name production

# 使用默认模板（需要手动编辑配置文件）
itriton-sftp init --no-interactive

2. 运行部署

# 使用默认配置运行
itriton-sftp run

# 指定配置名称
itriton-sftp run --config production

# 试运行（不实际上传）
itriton-sftp run --dry-run

# 显示详细日志
itriton-sftp run --verbose

3. 管理配置

# 列出所有配置
itriton-sftp list

# 查看配置详情
itriton-sftp config

# 查看指定配置
itriton-sftp config production

⚙️ 配置文件

运行 itriton-sftp init 后，会在项目根目录生成 .sftp.json 配置文件：

{
  "version": "1.0.0",
  "default": "default",
  "configs": {
    "default": {
      "name": "default",
      "description": "默认 SFTP运行配置",
      "connection": {
        "host": "your-server.com",
        "port": 22,
        "username": "your-username",
        "password": "your-password",
        "readyTimeout": 20000
      },
      "run": {
        "localPath": "./dist",
        "remotePath": "/var/www/html",
        "exclude": [
          "node_modules",
          ".git",
          ".DS_Store",
          "*.log"
        ],
        "cleanRemote": false,
        "preserveStructure": true
      }
    }
  }
}

配置选项详细说明

connection（连接配置）

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | host | string | ✅ | - | 服务器地址或IP | | port | number | ❌ | 22 | SSH端口号 | | username | string | ✅ | - | SSH用户名 | | password | string | ❌ | - | SSH密码（与privateKey二选一） | | privateKey | string | ❌ | - | 私钥文件路径（与password二选一） | | passphrase | string | ❌ | - | 私钥密码（私钥加密时需要） | | readyTimeout | number | ❌ | 20000 | 连接超时时间（毫秒） |

run（运行配置）

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | localPath | string | ✅ | - | 本地源目录路径 | | remotePath | string | ✅ | - | 远程目标目录路径 | | exclude | string[] | ❌ | [] | 排除的文件/目录模式数组 | | cleanRemote | boolean | ❌ | false | 运行前是否清空远程目录 | | preserveStructure | boolean | ❌ | true | 是否保持目录结构 | | transferMode | string | ❌ | 'auto' | 传输模式：'single'/'archive'/'auto' | | archiveThreshold | number | ❌ | 10 | 自动模式下切换到压缩传输的文件数量阈值 | | archiveFormat | string | ❌ | 'tar.gz' | 压缩格式：'tar.gz'/'zip' | | extractCommand | string | ❌ | 见下方 | 服务器解压命令模板 |

配置文件结构

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | version | string | ✅ | 配置文件版本 | | default | string | ❌ | 默认使用的配置名称 | | configs | object | ✅ | 配置字典，key为配置名称 |

单个配置结构

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | name | string | ✅ | 配置名称 | | description | string | ❌ | 配置描述 | | connection | object | ✅ | 连接配置 | | run | object | ✅ | 运行配置 |

传输模式详解

传输模式选项

| 模式 | 说明 | 适用场景 | 优缺点 | |------|------|---------|--------| | single | 单文件传输 | 文件少、需要精确控制 | ✅ 精确控制 ❌ 效率低 | | archive | 压缩包传输 | 文件多、追求效率 | ✅ 高效率 ❌ 需要服务器支持解压 | | auto | 自动选择（推荐） | 大多数场景 | ✅ 智能优化 ✅ 适应性强 |

默认解压命令

# tar.gz 格式（默认）
cd {remotePath} && tar -xzf {archiveName} && rm {archiveName}

# zip 格式
cd {remotePath} && unzip -o {archiveName} && rm {archiveName}

变量说明：

• {remotePath}: 远程目录路径
• {archiveName}: 压缩包文件名

性能对比

| 文件数量 | 单文件传输 | 压缩传输 | 性能提升 | |---------|-----------|---------|---------| | 5个文件 | 10秒 | 8秒 | +25% | | 50个文件 | 60秒 | 15秒 | +300% | | 500个文件 | 600秒 | 30秒 | +2000% |

注意：实际性能取决于网络环境、文件大小和服务器性能。

🔐 认证方式

密码认证

{
  "connection": {
    "host": "example.com",
    "port": 22,
    "username": "user",
    "password": "your-password",
    "readyTimeout": 20000
  }
}

私钥认证

{
  "connection": {
    "host": "example.com", 
    "port": 22,
    "username": "user",
    "privateKey": "~/.ssh/id_rsa",
    "passphrase": "key-password",
    "readyTimeout": 30000
  }
}

自定义端口配置

{
  "connection": {
    "host": "example.com",
    "port": 2222,
    "username": "user",
    "privateKey": "~/.ssh/id_ed25519"
  }
}

完整配置示例

{
  "version": "1.0.0",
  "default": "production",
  "configs": {
    "development": {
      "name": "development",
      "description": "开发环境配置",
      "connection": {
        "host": "dev.example.com",
        "port": 22,
        "username": "dev-user",
        "password": "dev-password",
        "readyTimeout": 15000
      },
      "run": {
        "localPath": "./dist",
        "remotePath": "/var/www/dev",
        "exclude": ["*.map", "*.test.js", "node_modules"],
        "cleanRemote": true,
        "preserveStructure": true,
        "transferMode": "single",
        "archiveThreshold": 5,
        "archiveFormat": "tar.gz",
        "extractCommand": "cd {remotePath} && tar -xzf {archiveName} && rm {archiveName}"
      }
    },
    "production": {
      "name": "production", 
      "description": "生产环境配置",
      "connection": {
        "host": "prod.example.com",
        "port": 2222,
        "username": "prod-user",
        "privateKey": "~/.ssh/prod_key",
        "passphrase": "prod-key-password",
        "readyTimeout": 30000
      },
      "run": {
        "localPath": "./build",
        "remotePath": "/var/www/html",
        "exclude": ["*.log", "*.tmp", ".DS_Store"],
        "cleanRemote": false,
        "preserveStructure": true,
        "transferMode": "auto",
        "archiveThreshold": 20,
        "archiveFormat": "tar.gz",
        "extractCommand": "cd {remotePath} && tar -xzf {archiveName} && rm {archiveName}"
      }
    }
  }
}

📋 命令详解

init - 初始化配置

itriton-sftp init [options]

Options:
  -n, --name <name>     配置名称 (default: "default")
  -f, --force          强制覆盖现有配置文件
  --no-interactive     使用默认模板，不进行交互式配置

run - 执行上传

itriton-sftp run [options]

Options:
  -c, --config <name>  指定配置名称
  -v, --verbose        显示详细日志
  -d, --dry-run        试运行，不实际上传文件
  -f, --force          强制覆盖远程文件

list - 列出配置

itriton-sftp list
# 或
itriton-sftp ls

config - 显示配置详情

itriton-sftp config [name]

📁 排除文件

支持多种排除模式：

{
  "exclude": [
    "node_modules",      // 排除目录
    ".git",              // 排除隐藏目录
    "*.log",             // 通配符匹配
    "temp/*",            // 目录下所有文件
    ".DS_Store"          // 特定文件
  ]
}

🎯 使用示例

基本用法

# 1. 初始化配置
itriton-sftp init

# 2. 编辑配置文件 .sftp.json

# 3. 运行部署
itriton-sftp run

多环境配置

# 创建开发环境配置
itriton-sftp init --name dev

# 创建生产环境配置  
itriton-sftp init --name prod

# 部署到开发环境
itriton-sftp run --config dev

# 部署到生产环境
itriton-sftp run --config prod

安全部署

# 先试运行，检查将要上传的文件
itriton-sftp run --dry-run

# 确认无误后正式运行
itriton-sftp run --verbose

🔧 在项目中使用

本地安装使用方式（推荐）

如果不想全局安装，可以在项目中本地安装：

# 安装为开发依赖（注意使用包名）
npm install @itriton/sftp --save-dev
# 或
pnpm add -D @itriton/sftp

💡 为什么推荐本地安装？

• ✅ 项目依赖明确，便于团队协作
• ✅ 不同项目可以使用不同版本
• ✅ 避免全局环境污染

然后在 package.json 中配置脚本（两种方式）：

方式一：直接使用命令名（推荐）

{
  "scripts": {
    "sftp:init": "itriton-sftp init",
    "sftp:init:prod": "itriton-sftp init --name production",
    "deploy:dev": "itriton-sftp run --config dev",
    "deploy:prod": "itriton-sftp run --config prod", 
    "deploy:check": "itriton-sftp run --dry-run",
    "deploy:verbose": "itriton-sftp run --verbose"
  }
}

方式二：使用 npx + 命令名

{
  "scripts": {
    "sftp:init": "npx itriton-sftp init",
    "sftp:init:prod": "npx itriton-sftp init --name production",
    "deploy:dev": "npx itriton-sftp run --config dev",
    "deploy:prod": "npx itriton-sftp run --config prod", 
    "deploy:check": "npx itriton-sftp run --dry-run",
    "deploy:verbose": "npx itriton-sftp run --verbose"
  }
}

方式三：使用 npx + 包名

{
  "scripts": {
    "sftp:init": "npx @itriton/sftp init",
    "sftp:init:prod": "npx @itriton/sftp init --name production",
    "deploy:dev": "npx @itriton/sftp run --config dev",
    "deploy:prod": "npx @itriton/sftp run --config prod", 
    "deploy:check": "npx @itriton/sftp run --dry-run",
    "deploy:verbose": "npx @itriton/sftp run --verbose"
  }
}

说明：当你本地安装包后，npm/pnpm 会在 node_modules/.bin 中创建可执行文件链接，所以在 package.json 的 scripts 中可以使用：

• 方式一：直接使用命令名（最简洁）
• 方式二：npx + 命令名（更明确）
• 方式三：npx + 包名（最明确）

三种方式都可以正常工作，选择你喜欢的即可！

使用方式：

# 初始化配置
npm run sftp:init

# 部署到开发环境
npm run deploy:dev

# 部署到生产环境
npm run deploy:prod

# 试运行检查
npm run deploy:check

使用 npx（无需安装）

如果你不想安装包，可以直接使用 npx 运行：

# 直接使用，无需安装
npx @itriton/sftp init
npx @itriton/sftp run --config production
npx @itriton/sftp list
npx @itriton/sftp config

# 也可以在终端直接运行
npx @itriton/sftp run --dry-run --verbose

注意：使用 npx 时需要使用完整包名 @itriton/sftp，而不是命令名 itriton-sftp。

包名 vs 命令名说明：

• 包名：@itriton/sftp （用于 npm install 和 npx）
• 命令名：itriton-sftp （用于全局安装后的命令行和 package.json scripts）

全局安装使用方式

# 全局安装
npm install -g @itriton/sftp

# 直接使用命令
itriton-sftp init
itriton-sftp run --config production

编程方式使用

import { initConfig, getConfig, run } from '@itriton/sftp';

// 初始化配置
await initConfig({
  name: 'my-config',
  interactive: false
});

// 获取配置
const config = getConfig('my-config');

// 执行部署
const result = await run(config, {
  verbose: true,
  dryRun: false
});

console.log(`上传了 ${result.uploadedFiles} 个文件`);

🛡️ 安全建议

1. 不要在代码中硬编码密码，建议使用环境变量或私钥认证
2. 将配置文件添加到 .gitignore，避免敏感信息泄露
3. 使用试运行模式预览上传内容，确保安全
4. 定期更换服务器密码和私钥
5. 使用最小权限原则，只给必要的目录访问权限

📝 更新日志

v0.0.1

• 🎉 首次发布
• ✨ 支持密码和私钥认证
• ✨ 支持多配置管理
• ✨ 支持文件排除规则
• ✨ 支持试运行模式
• ✨ 完整的CLI命令支持
• 🗜️ 支持压缩包传输模式
• 🚀 智能传输模式自动选择
• 📊 大幅提升大量文件传输性能

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

ISC