Skip to content

batch operation

Jump to bottom
ZHAO Xudong edited this page Apr 16, 2026 · 7 revisions

Batch Operation Widget

Language / 语言: English | 中文

English

Overview

The Batch Operation widget allows you to define and execute multi-step SSH/SFTP workflows with progress tracking. It runs entirely in the frontend without requiring server-side components.

Click the Batch Operation button on the left sidebar to open the widget panel, then define your workflow as a JSON array and execute it.

Features

  • JSON-based workflow definition - Define steps in a simple JSON array
  • Progress tracking - Visual feedback for each step's execution status (✓ success, ✗ error, → running)
  • Multiple action types - Connect SSH, run commands, upload/download files via SFTP
  • Full SSH auth support - Password, private key, passphrase, certificate, profiles, tunnels, connection hopping
  • Template support - Load example workflows directly in the editor
  • CLI support - Run workflows from command line with electerm -bo "/path/to/workflow.json"

Step Structure

Every step shares the following top-level fields:

Field Type Required Description
name string Yes Human-readable step label shown in the log
action string Yes Action type (see below)
prevDelay number No Milliseconds to wait before this step runs
afterDelay number No Milliseconds to wait after this step completes

For connect action, parameters are placed inside the params object. For all other actions, parameters are at the top level (flat format):

{
  "name": "Connect to Server",
  "action": "connect",
  "params": {
    "host": "192.168.1.100",
    "port": 22,
    "username": "root",
    "password": "your_password"
  }
}
{
  "name": "Run Command",
  "action": "command",
  "afterDelay": 500,
  "command": "ls -la /tmp"
}

Action Types

connect — Connect SSH

Connect to a remote SSH server and open a terminal tab.

{
  "name": "Connect to Server",
  "action": "connect",
  "params": {
    "host": "192.168.1.100",
    "port": 22,
    "username": "root",
    "authType": "password",
    "password": "your_password",
    "enableSftp": true
  }
}
Field Type Required Description
host string Yes SSH server address
port number No SSH port (default: 22)
username string No SSH username
authType string No password, privateKey, or profiles (default: password)
password string No Password for authentication
privateKey string No Private key content or path
passphrase string No Passphrase for private key/certificate
certificate string No Certificate content
profile string No Profile ID to reuse saved auth
enableSftp boolean No Enable SFTP (default: true)
enableSsh boolean No Enable SSH (default: true)
useSshAgent boolean No Use SSH agent (default: true)
sshAgent string No SSH agent path
term string No Terminal type (default: xterm-256color)
encode string No Charset (default: utf8)
envLang string No ENV LANG (default: en_US.UTF-8)
setEnv string No Environment variables: KEY1=VALUE1 KEY2=VALUE2
startDirectoryRemote string No Remote starting directory
startDirectoryLocal string No Local starting directory
proxy string No Proxy address (socks5://...)
x11 boolean No Enable X11 forwarding (default: false)
displayRaw boolean No Display raw output (default: false)
sshTunnels array No SSH tunnel definitions
connectionHoppings array No Connection hopping definitions

command — Run Terminal Command

Execute a command in the current terminal tab.

{
  "name": "List Files",
  "action": "command",
  "afterDelay": 500,
  "command": "ls -la /tmp"
}
Field Type Required Description
command string Yes Command to execute
tabId string No Specific tab ID (uses active tab if omitted)

sftp_upload — Upload via SFTP

Upload a local file or folder to the remote server via SFTP.

{
  "name": "Upload Config File",
  "action": "sftp_upload",
  "afterDelay": 200,
  "localPath": "/local/config/app.json",
  "remotePath": "/etc/app/config.json"
}
Field Type Required Description
localPath string Yes Local file/folder path to upload
remotePath string Yes Remote destination path
tabId string No Specific tab ID

sftp_download — Download via SFTP

Download a remote file or folder from the server via SFTP.

{
  "name": "Download Log File",
  "action": "sftp_download",
  "afterDelay": 200,
  "remotePath": "/var/log/app.log",
  "localPath": "/local/logs/app.log"
}
Field Type Required Description
remotePath string Yes Remote file/folder path to download
localPath string Yes Local destination path
tabId string No Specific tab ID

Complete Workflow Example

[
  {
    "name": "Connect SSH",
    "action": "connect",
    "params": {
      "host": "192.168.1.100",
      "port": 22,
      "username": "root",
      "authType": "password",
      "password": "your_password",
      "enableSftp": true
    }
  },
  {
    "name": "Create test file",
    "action": "command",
    "afterDelay": 500,
    "command": "echo 'hello batch-op' > /tmp/batch_test.txt && echo '[LOG] File created'"
  },
  {
    "name": "Log file content",
    "action": "command",
    "command": "cat /tmp/batch_test.txt"
  },
  {
    "name": "Download test file",
    "action": "sftp_download",
    "afterDelay": 200,
    "remotePath": "/tmp/batch_test.txt",
    "localPath": "/tmp/batch_test_local.txt"
  },
  {
    "name": "Delete remote source file",
    "action": "command",
    "afterDelay": 200,
    "command": "rm -f /tmp/batch_test.txt && echo '[LOG] Remote source deleted'"
  },
  {
    "name": "Upload file back",
    "action": "sftp_upload",
    "afterDelay": 200,
    "localPath": "/tmp/batch_test_local.txt",
    "remotePath": "/tmp/batch_test_uploaded.txt"
  },
  {
    "name": "Verify and clean up",
    "action": "command",
    "command": "ls -la /tmp/batch_test_uploaded.txt && rm -f /tmp/batch_test*.txt && echo '[LOG] All done'"
  }
]

{ "name": "Verify and clean up", "action": "command", "params": { "command": "ls -la /tmp/batch_test_uploaded.txt && rm -f /tmp/batch_test*.txt && echo '[LOG] All done'" } } ]


### How to Use

1. **Open the Widget**: Navigate to Widgets > Batch Operation in the left sidebar
2. **Edit Workflow**: Use the built-in JSON editor to define your workflow
3. **Load Template**: Click "Load Template" to insert a complete example workflow
4. **Show more**: Expand the info box to see all available params for each action
5. **Execute**: Click "Execute Workflow" to run the steps sequentially

During execution the log panel displays progress for each step:
- ✓ Success: Step completed successfully
- ✗ Error: Step failed (error message shown)
- → Running: Current step being executed

### Command Line Usage

```bash
electerm -bo "/path/to/workflow.json"

The workflow executes automatically on startup. Progress and results are logged to the console.

Timing: prevDelay / afterDelay

Use prevDelay and afterDelay on any step to insert pauses without a dedicated wait step:

{
  "name": "Run after short warm-up",
  "action": "command",
  "prevDelay": 1000,
  "afterDelay": 500,
  "command": "systemctl status nginx"
}

SSH Tunnels Format

"sshTunnels": [
  {
    "sshTunnel": "forwardRemoteToLocal",
    "sshTunnelLocalHost": "127.0.0.1",
    "sshTunnelLocalPort": 8080,
    "sshTunnelRemoteHost": "127.0.0.1",
    "sshTunnelRemotePort": 80,
    "name": "Web Forward"
  }
]

Tunnel types:

  • forwardRemoteToLocal — Forward remote port to local
  • forwardLocalToRemote — Forward local port to remote
  • dynamicForward — Dynamic SOCKS proxy

Connection Hopping Format

"connectionHoppings": [
  {
    "host": "jump-server.example.com",
    "port": 22,
    "username": "jumpuser",
    "authType": "password",
    "password": "jumppass",
    "privateKey": "",
    "passphrase": "",
    "certificate": "",
    "profile": ""
  }
]

Notes

  • Steps execute sequentially; if a step fails, execution stops and the error is shown
  • The tabId field is auto-populated from the most recent connect step
  • For SFTP transfers, ensure enableSftp: true in the connect step

中文

概述

批量操作小部件允许您定义和执行多步骤 SSH/SFTP 工作流，并提供进度跟踪功能。它完全在前端运行，无需服务器端组件。

在左侧侧边栏单击批量操作按钮，打开小部件面板，然后将工作流定义为 JSON 数组并执行。

功能

  • 基于 JSON 的工作流定义 — 在简单的 JSON 数组中定义步骤
  • 进度跟踪 — 每个步骤执行状态的可视化反馈（✓ 成功、✗ 错误、→ 运行中）
  • 多种操作类型 — 连接 SSH、运行命令、SFTP 上传/下载
  • 完整的 SSH 认证支持 — 密码、私钥、密码短语、证书、配置文件、隧道、跳板
  • 模板支持 — 在编辑器中直接加载示例工作流
  • 命令行支持 — 使用 electerm -bo "/path/to/workflow.json" 从命令行运行工作流

步骤结构

每个步骤共享以下顶层字段：

字段 类型 必填 描述
name string 是 步骤名称，显示在日志中
action string 是 操作类型（见下方）
prevDelay number 否 步骤执行前等待的毫秒数
afterDelay number 否 步骤执行后等待的毫秒数

对于 connect 操作，参数放在 params 对象中。其他操作使用扁平格式（参数在顶层）：

{
  "name": "连接服务器",
  "action": "connect",
  "params": {
    "host": "192.168.1.100",
    "port": 22,
    "username": "root",
    "password": "your_password"
  }
}
{
  "name": "运行命令",
  "action": "command",
  "afterDelay": 500,
  "command": "ls -la /tmp"
}

操作类型

connect — 连接 SSH

连接到远程 SSH 服务器并打开终端标签页。

{
  "name": "连接服务器",
  "action": "connect",
  "params": {
    "host": "192.168.1.100",
    "port": 22,
    "username": "root",
    "authType": "password",
    "password": "your_password",
    "enableSftp": true
  }
}
字段 类型 必填 描述
host string 是 SSH 服务器地址
port number 否 SSH 端口（默认：22）
username string 否 SSH 用户名
authType string 否 password、privateKey 或 profiles（默认：password）
password string 否 认证密码
privateKey string 否 私钥内容或路径
passphrase string 否 私钥/证书的密码短语
certificate string 否 证书内容
profile string 否 用于重用已保存认证的配置文件 ID
enableSftp boolean 否 启用 SFTP（默认：true）
enableSsh boolean 否 启用 SSH（默认：true）
useSshAgent boolean 否 使用 SSH 代理（默认：true）
sshAgent string 否 SSH 代理路径
term string 否 终端类型（默认：xterm-256color）
encode string 否 字符集（默认：utf8）
envLang string 否 环境变量 LANG（默认：en_US.UTF-8）
setEnv string 否 环境变量：KEY1=VALUE1 KEY2=VALUE2
startDirectoryRemote string 否 远程起始目录
startDirectoryLocal string 否 本地起始目录
proxy string 否 代理地址（socks5://...）
x11 boolean 否 启用 X11 转发（默认：false）
displayRaw boolean 否 显示原始输出（默认：false）
sshTunnels array 否 SSH 隧道定义
connectionHoppings array 否 连接跳板定义

command — 运行终端命令

在当前终端标签页中执行命令。

{
  "name": "列出文件",
  "action": "command",
  "afterDelay": 500,
  "command": "ls -la /tmp"
}
字段 类型 必填 描述
command string 是 要执行的命令
tabId string 否 指定标签页 ID（不指定则使用当前活动标签页）

sftp_upload — SFTP 上传

通过 SFTP 将本地文件或文件夹上传到远程服务器。

{
  "name": "上传配置文件",
  "action": "sftp_upload",
  "afterDelay": 200,
  "localPath": "/local/config/app.json",
  "remotePath": "/etc/app/config.json"
}
字段 类型 必填 描述
localPath string 是 要上传的本地文件/文件夹路径
remotePath string 是 远程目标路径
tabId string 否 指定标签页 ID

sftp_download — SFTP 下载

通过 SFTP 从远程服务器下载文件或文件夹。

{
  "name": "下载日志文件",
  "action": "sftp_download",
  "afterDelay": 200,
  "remotePath": "/var/log/app.log",
  "localPath": "/local/logs/app.log"
}
字段 类型 必填 描述
remotePath string 是 要下载的远程文件/文件夹路径
localPath string 是 本地目标路径
tabId string 否 指定标签页 ID

完整工作流示例

[
  {
    "name": "连接 SSH",
    "action": "connect",
    "params": {
      "host": "192.168.1.100",
      "port": 22,
      "username": "root",
      "authType": "password",
      "password": "your_password",
      "enableSftp": true
    }
  },
  {
    "name": "创建测试文件",
    "action": "command",
    "afterDelay": 500,
    "command": "echo 'hello batch-op' > /tmp/batch_test.txt && echo '[LOG] 文件已创建'"
  },
  {
    "name": "查看文件内容",
    "action": "command",
    "command": "cat /tmp/batch_test.txt"
  },
  {
    "name": "下载测试文件",
    "action": "sftp_download",
    "afterDelay": 200,
    "remotePath": "/tmp/batch_test.txt",
    "localPath": "/tmp/batch_test_local.txt"
  },
  {
    "name": "删除远程源文件",
    "action": "command",
    "afterDelay": 200,
    "command": "rm -f /tmp/batch_test.txt && echo '[LOG] 远程源文件已删除'"
  },
  {
    "name": "将文件上传回服务器",
    "action": "sftp_upload",
    "afterDelay": 200,
    "localPath": "/tmp/batch_test_local.txt",
    "remotePath": "/tmp/batch_test_uploaded.txt"
  },
  {
    "name": "验证并清理",
    "action": "command",
    "command": "ls -la /tmp/batch_test_uploaded.txt && rm -f /tmp/batch_test*.txt && echo '[LOG] 全部完成'"
  }
]

{ "name": "验证并清理", "action": "command", "params": { "command": "ls -la /tmp/batch_test_uploaded.txt && rm -f /tmp/batch_test*.txt && echo '[LOG] 全部完成'" } } ]


### 使用方法

1. **打开小部件**：导航到 小部件 > 批量操作
2. **编辑工作流**：使用内置 JSON 编辑器定义工作流
3. **加载模板**：点击"加载模板"插入完整示例工作流
4. **展开详情**：点击信息框中的"显示更多"查看各操作的可用参数
5. **执行**：点击"执行工作流"按顺序运行步骤

执行期间日志面板会显示每个步骤的进度：
- ✓ 成功：步骤已完成
- ✗ 错误：步骤失败（显示错误消息）
- → 运行中：当前正在执行的步骤

### 命令行用法

```bash
electerm -bo "/path/to/workflow.json"

工作流在启动时自动执行，进度和结果输出到控制台。

延迟控制：prevDelay / afterDelay

在任意步骤上使用 prevDelay 和 afterDelay 插入等待，无需单独的等待步骤：

{
  "name": "预热后运行",
  "action": "command",
  "prevDelay": 1000,
  "afterDelay": 500,
  "command": "systemctl status nginx"
}

SSH 隧道格式

"sshTunnels": [
  {
    "sshTunnel": "forwardRemoteToLocal",
    "sshTunnelLocalHost": "127.0.0.1",
    "sshTunnelLocalPort": 8080,
    "sshTunnelRemoteHost": "127.0.0.1",
    "sshTunnelRemotePort": 80,
    "name": "Web 转发"
  }
]

隧道类型：

  • forwardRemoteToLocal — 远程端口转发到本地
  • forwardLocalToRemote — 本地端口转发到远程
  • dynamicForward — 动态 SOCKS 代理

连接跳板格式

"connectionHoppings": [
  {
    "host": "jump-server.example.com",
    "port": 22,
    "username": "jumpuser",
    "authType": "password",
    "password": "jumppass",
    "privateKey": "",
    "passphrase": "",
    "certificate": "",
    "profile": ""
  }
]

注意事项

  • 步骤按顺序依次执行；如果某个步骤失败，执行将停止并显示错误
  • tabId 字段会自动从最近的连接步骤获取
  • 对于 SFTP 文件传输，请在连接步骤中设置 enableSftp: true

Clone this wiki locally