开发指南

基于 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	是否保持目录结构

配置文件结构

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

单个配置结构

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

🔐 认证方式

密码认证

{
  "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
      }
    },
    "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
      }
    }
  }
}

📋 命令详解

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. 使用最小权限原则，只给必要的目录访问权限