# itriton-sftp

**Repository Path**: ibaleine-open-source/itriton-sftp

## Basic Information

- **Project Name**: itriton-sftp
- **Description**: @itriton/sftp 基于 ssh2-sftp-client 的项目部署工具，支持密钥证书登录和配置文件管理。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-18
- **Last Updated**: 2025-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @itriton/sftp

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

## ✨ 特性

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

## 📦 安装

```bash
npm install -g @itriton/sftp
```

或者在项目中使用：

```bash
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. 初始化配置

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

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

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

### 2. 运行部署

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

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

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

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

### 3. 管理配置

```bash
# 列出所有配置
itriton-sftp list

# 查看配置详情
itriton-sftp config

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

## ⚙️ 配置文件

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

```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` | 自动选择（推荐） | 大多数场景 | ✅ 智能优化 ✅ 适应性强 |

#### 默认解压命令

```bash
# 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% |

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

## 🔐 认证方式

### 密码认证

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

### 私钥认证

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

### 自定义端口配置

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

### 完整配置示例

```json
{
  "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 - 初始化配置

```bash
itriton-sftp init [options]

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

### run - 执行上传

```bash
itriton-sftp run [options]

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

### list - 列出配置

```bash
itriton-sftp list
# 或
itriton-sftp ls
```

### config - 显示配置详情

```bash
itriton-sftp config [name]
```

## 📁 排除文件

支持多种排除模式：

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

## 🎯 使用示例

### 基本用法

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

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

# 3. 运行部署
itriton-sftp run
```

### 多环境配置

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

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

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

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

### 安全部署

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

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

## 🔧 在项目中使用

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

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

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

> **💡 为什么推荐本地安装？**
> - ✅ 项目依赖明确，便于团队协作
> - ✅ 不同项目可以使用不同版本
> - ✅ 避免全局环境污染

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

**方式一：直接使用命令名（推荐）**
```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 + 命令名**
```json
{
  "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 + 包名**
```json
{
  "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 + 包名（最明确）
> 
> 三种方式都可以正常工作，选择你喜欢的即可！

使用方式：

```bash
# 初始化配置
npm run sftp:init

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

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

# 试运行检查
npm run deploy:check
```

### 使用 npx（无需安装）

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

```bash
# 直接使用，无需安装
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）

### 全局安装使用方式

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

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

### 编程方式使用

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

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

ISC