This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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