简介

TaskSSH 是一个单文件、无外部依赖的 SSH 批量运维工具。 写一个 inventory.yaml,定义服务器组与任务步骤, 一条命令对多台服务器执行命令、上传下载文件。

安装

下载二进制

从 Releases 页面下载对应平台压缩包,解压即用。

Linux / macOS 下添加执行权限:

chmod +x taskssh

从源码构建

需 Go 1.26 及以上版本:

git clone https://github.com/melvek/TaskSSH.git
cd TaskSSH
go build -o taskssh main.go

快速开始

常规命令

不写任何配置文件,用位置参数指定主机,直接执行:

# 执行远程命令
taskssh command "192.168.1.1, 192.168.1.2" -u web -p "123456" -e "uptime"
taskssh command "192.168.1.1, 192.168.1.2" -u deploy -e "date"

# 上传文件或目录
taskssh push app_domain1 -u deploy -f app.jar -d /opt/app/

# 下载文件或目录,不指定 `-d` 时,下载到当前目录
taskssh fetch web1 -u deploy -f /var/log/app.log -d ./logs/

# 上传脚本并执行, `-r` 会在执行完成后删除脚本文件
taskssh script web1 -u deploy -f ./deploy.sh -d /tmp -r

也可以同时指定多台主机,或使用组名、glob、排除等 pattern:

# 多台主机
taskssh command "10.0.0.1,10.0.0.2" -u deploy -e "df -h"

# 直接指定 IP
taskssh command "192.168.1.10" -u deploy -e "uptime"

完整的主机 pattern 语法见 主机 pattern; 各 action 的参数见对应章节。

使用清单文件

当主机较多、需要分组、或需要复用认证与变量时,可以使用 inventory.yaml清单文件,把配置固化为可复用、可提交、可审查的文件。

1. 生成 Vault 密钥

用于加密清单中的密码。只需执行一次:

taskssh keygen

2. 加密密码

taskssh encrypt
# 按提示输入密码,输出密文:xxxxx

3. 编写 inventory.yaml

defaults:
  username: deploy
  password: "xxxxx"          # 上一步的密文

servers:
  prod:
    vars:
      service_path: /opt/myapp/
    hosts:
      web1: 192.168.1.10
      web2: 192.168.1.11

tasks:
  release:
    steps:
      - name: "上传新版本"
        action: push
        with:
          file: "./dist/app.jar"
          dest: "{{service_path}}"
          force: true

      - name: "重启服务"
        action: command
        with:
          command: "systemctl restart myapp"

4. 执行任务

taskssh release prod

执行前可用 --dry-run 预览每台主机每步将执行的内容。

inventory

inventory.yaml 是 TaskSSH 的配置文件,结构如下:

include:    # 引用其它清单文件(可选)
defaults:   # 文件级默认值
servers:    # 服务器组与主机
tasks:      # 任务定义

除 include 外,其余段都可省略。 不写 servers 时,用位置参数直接指定主机; 不写 tasks 时,用内置 action 执行单步操作。

变量合并优先级

每台主机最终的变量池按以下顺序合并(低 → 高):

层级 来源 作用范围
1 defaults 所有主机
2 servers.<组>.vars 组内主机
3 主机字段与 Extra 单台主机
4 CLI -D 所有主机
5 date / exec_id 运行时注入

defaults

文件级默认值。所有主机继承,可被组 vars 或主机字段覆盖。 字段结构和主机定义一致(见 host), 非专有字段进入变量池。

defaults:
  username: deploy
  password: "encrypted-password"
  app_name: myapp
  version: 1.0.0

username / password 为连接凭据; app_name / version 为自定义变量, 任务中通过 {{app_name}} 引用。

servers

定义服务器组。每个组有 vars(组内共享)和 hosts(组内主机列表)。

servers:
  prod:
    vars:
      service_path: /opt/myapp/
    hosts:
      web1: 192.168.1.10              # 简写,其余字段继承
      web2:
        host: 192.168.1.11            # 完整写法
        port: 2222
        username: root

  uat:
    vars:
      service_path: /opt/myapp-uat/
    hosts:
      uat1: 10.1.0.1

主机声明方式

字段含义见 host。 非专有字段进入 Extra,参与变量替换,见 扩展字段。

多环境

环境差异由组级变量承载。同一任务可分别对多个组执行:

taskssh release prod
taskssh release uat

host

defaults、组 vars、主机定义三层使用相同字段结构, 仅作用范围不同。

字段 类型 说明
host string 主机地址(IP / 域名)
port int SSH 端口,默认 22
username string 登录用户名
password string 登录密码,必须是 taskssh encrypt 的密文
identity_file string SSH 私钥路径,~ 展开为 home
passphrase string 私钥口令,必须是密文

其他任意字段进入 Extra,通过 {{字段名}} 引用。

servers:
  prod:
    hosts:
      web1:
        host: 192.168.1.10
        role: web              # 进入 Extra
        zone: cn-north-1

tasks

每个任务由唯一名称、可选描述、若干 steps 组成。 step 按声明顺序执行。

tasks:
  release:
    description: "发布新版本"          # 可选
    serial: 2                         # 可选,按组分批
    min_available: 1                  # 可选,组内保留台数
    steps:
      - name: "上传"
        action: push
        with:
          file: "./dist/app.jar"
          dest: "{{service_path}}"

任务级字段

字段 说明
description 任务描述
serial 每组每批 N 台,默认 0(不分批)
min_available 每组至少留 N 台在跑,默认 0
steps 步骤列表(必填)
ℹ️

command / push / fetch / script / encrypt / decrypt / keygen 为保留命令名。 tasks 段中定义同名任务不会生效,需改用其他名称。

step

每个 step 是一次 action 调用。

字段 必填 说明
name 否 步骤名,用于日志
action 是 command / push / fetch / script
with 是 action 参数,值支持 {{var}}
when 否 条件表达式,不满足则跳过
delay 否 成功后固定等待秒数,默认 0
ignore_errors 否 失败不中断后续,默认 false
interval 否 失败重试间隔秒数,0 = 不重试
timeout 否 重试总超时秒数,默认 30

when:条件执行

条件为 true 才执行,否则跳过。支持 == != > >= < <= in && ||。

- action: command
  when: "{{env}} == prod && {{role}} == db"
  with:
    command: "pg_dump mydb > /backup/mydb.sql"
⚠️

> < 等比较使用 float64。 版本号如 1.10 与 1.2 的结果可能反直觉, 建议用整数版本号。

delay:固定等待

成功后固定等待 N 秒。适用于等待无法用命令探测的状态 (如文件系统同步、内核参数生效)。

可探测的状态(端口监听、进程状态、健康检查接口)应使用 interval + timeout 轮询,而非猜一个固定时长。

interval / timeout:失败重试

- name: "等待端口就绪"
  action: command
  with:
    command: "nc -z localhost 8080"
  interval: 2
  timeout: 30
interval timeout 行为
0 任意 不重试
> 0 0 / 不写 重试,超时 30 秒
> 0 > 0 重试到 timeout 秒

连接类错误(网络中断、连接重置)立即失败,不重试。 命令非零退出码正常触发重试。

⚠️

重试会重复执行 action,要求 action 幂等。 echo ... >> file 这类追加写入会内容重复。

ignore_errors

失败时输出警告但不中断当前主机的后续步骤。 仍按 interval / timeout 重试,重试超时后仅告警。

- action: command
  with:
    command: "rm -f /tmp/deploy-*.tmp"
  ignore_errors: true

该字段仅作用于 step 执行失败。连接失败属于主机级问题, 不受此字段影响。

include

清单变大后,可拆成多个文件,主文件用 include 引入:

include:
  - servers/*.yaml
  - tasks/*.yaml

defaults:
  username: deploy
  password: "encrypted-password"

include 语法

形式 示例
精确路径 servers/prod.yaml
目录 servers/(等价 servers/*.yaml)
glob servers/*.yaml(按文件名排序)

路径相对主文件所在目录解析。

合并规则

段 规则
defaults 子文件的 defaults 只作用于该文件的 servers;主文件的 defaults 作为兜底
servers 同名组报错,指明冲突文件
tasks 同名任务报错

推荐结构

project/
├── inventory.yaml
├── servers/
│   ├── prod.yaml
│   └── uat.yaml
└── tasks/
    ├── release.yaml
    └── rollback.yaml

限制

主机 pattern

目标主机通过一个主机 pattern 位置参数指定。多个组或主机可用逗号或空格组合, 例如 taskssh command "prod_server,web_server" -e "date"; 主机 pattern 是唯一指定目标主机的方式。

操作符

前缀 操作
(无) 并集:加到当前结果
! 差集:从当前结果移除
& 交集:在当前结果中过滤

第一个子表达式以 & 或 ! 开头时, 从所有主机(g:*)开始。

子表达式形式

形式 示例 说明
组名 prod 组内所有主机
组名/主机名 prod/web1 精确一台
主机名 web1 跨所有组匹配同名主机
IP / 独立主机 192.168.1.10 不在清单中时按独立主机
组 glob g:web* glob 匹配组名
主机 glob h:web* glob 匹配所有组内主机名
默认匹配 web* 同时匹配组名和主机名

组名和主机名不能包含 /,因为该字符用于 组名/主机名 选择器。 空白或逗号分隔后没有选择项时会报错;选择全部主机请显式使用 g:*。

glob 语法

模式 含义
* 任意多个字符
? 任意单个字符
[abc] 字符集合
[a-z] 字符范围
[!abc] 否定集合

示例

# 单个组
taskssh command prod -e "uptime"

# 多个组
taskssh command "prod,uat" -e "uptime"

# glob
taskssh command "g:web*" -e "uptime"

# 排除
taskssh command 'g:*,!h:web3' -e "uptime"

# 交集过滤:所有主机中过滤出 web_01
taskssh command "&h:web_01" -e "uptime"

# 组合:prod_server 排除 web_01,加 web_server,最后过滤 web_02
taskssh command "prod_server, !h:web_01, web_server, &web_02" -e "uptime"

# 直接 IP
taskssh command "192.168.1.10" -e "uptime"
⚠️

Bash / Zsh 中 ! 是历史展开符,参数需用单引号包裹。 PowerShell 无此限制。

注意事项

Action:command

在远程主机执行命令。退出码非 0 视为失败。命令内容必须通过 -e / --execute 指定。

选项 说明
-e / --execute 待执行的命令
-L / --local 在本机执行,不通过 SSH
taskssh command web1 -e "ls -la /opt"

作为 step 使用:

- action: command
  with:
    command: "systemctl restart {{app_name}}"
ℹ️

TaskSSH 变量是 {{var}};命令里的 $VAR / ${VAR} 为 shell 变量,原样传给远程 shell。

Action:push

上传本地文件或目录至远程。必须通过 -f / --file 和 -d / --dest 指定源文件与目标路径。

选项 参数 说明
-f / --file file or dir 本地文件或目录
-d / --dest path 远程目标路径
-F / --force — 覆盖已存在的远程文件
-z / --zip — 目录打包后上传(依赖远程 unzip)
# 单文件
taskssh push app-server -f app.jar -d /opt/app/

# 目录,递归上传
taskssh push prod -f ./dist/assets/ -d /opt/app/

# 目录,打包上传
taskssh push prod -f ./dist/assets/ -d /opt/app/ -z

路径规则

  1. -d 以 / 结尾视为目录,最终路径 = 目录 + 本地文件名
  2. 目标已存在且为目录:文件放入目录内
  3. 目标已存在且为文件:默认报错,-F 覆盖
  4. 远程目录不存在时报错,需先创建

Action:fetch

从远程下载文件或目录至本地。必须通过 -f / --file 指定远程源路径;本地目标路径通过 -d / --dest 指定,默认当前目录。

选项 参数 说明
-f / --file path 远程文件或目录
-d / --dest path 本地目标路径,默认 ./
-z / --zip — 目录远程打包后下载(依赖远程 zip)
-T / --tmp-dir path 远程临时目录,默认 /tmp,仅 -z 生效
# 下载至目录
taskssh fetch prod -f /var/log/app.log -d ./logs/

# 下载至文件
taskssh fetch prod/web1 -f /var/log/app.log -d ./app.log

# 下载目录
taskssh fetch prod -f /var/log/app/ -d ./logs/ -z

路径规则

  1. -d 以 / 结尾视为目录,按 dest/<主机标识>/<文件名> 存放
  2. -d 为文件路径则直接下载到该文件
  3. 本地文件存在时默认覆盖;父目录不存在时自动创建
  4. 远程路径为目录时:不加 -z 递归下载;加 -z 打包下载后本地解压

Action:script

上传本地脚本至远程并执行。必须通过 -f / --file 指定脚本文件。

选项 参数 说明
-f / --file file 本地脚本文件
-d / --dest path 远程目录,默认 /tmp
-r / --remove — 执行后删除远程脚本
-F / --force — 覆盖已存在的远程脚本
taskssh script prod -f ./scripts/deploy.sh -r

执行规则

  1. 脚本上传到 -d 指定目录,默认 /tmp
  2. 上传后自动 chmod +x 再执行
  3. -r 执行后删除脚本(不论成败)

变量替换

在 inventory.yaml 和 with 中使用 {{变量名}} 引用变量。花括号内允许前后空格。

变量值支持字符串、数字和布尔标量;列表、映射及 null 值不能直接替换,会报错。

来源与优先级

层级 来源
1 defaults
2 servers.<组>.vars
3 主机字段与 Extra
4 CLI -D
5 date / exec_id(运行时)

递归展开

变量值可引用其他变量,最多进行 5 轮替换。

defaults:
  app_name: myapp
  version: 1.0.0
  package: "{{app_name}}-{{version}}.jar"

未解析变量

严格模式:变量未定义时立即报错,不会以空字符串继续执行。

⚠️

例如 rm -rf {{target_dir}},若 target_dir 未定义,命令不会执行。

shell 变量与 TaskSSH 变量

{{var}} 是 TaskSSH 变量,执行前替换。 $VAR / ${VAR} 是 shell 变量,原样传给远程。

# shell 变量,原样传给远程
taskssh command prod -e "echo $HOME"

# TaskSSH 变量,执行前替换
taskssh command prod -e "echo {{app_name}}"

内置变量

运行时自动注入,所有主机共享同一值,不可被清单或 -D 覆盖。

变量 说明 示例
{{date}} 当前日期,格式 YYYYMMDD 20260926
{{exec_id}} 本次执行的唯一标识,8 位 Base36 0K8X7A2B

date 是 TaskSSH 内置变量,会覆盖清单中的同名变量。 如需使用 shell 的 date,请写 $(date ...)。

exec_id 为纯随机 8 位 Base36,空间约 2.82 × 10^12, 不含时间戳、不具备字典序。

标准变量

每台主机执行时注入,值因主机而异,不可被清单或 -D 覆盖:

变量 值
{{host_name}} 主机标识(不含组前缀)
{{group_name}} 所属组名,独立主机为空
{{host_addr}} 连接地址
{{host_port}} 连接端口
{{host_user}} 登录用户名

典型用法:按主机区分版本目录。

- action: command
  with:
    command: "mkdir -p {{service_path}}/releases/{{date}}_{{exec_id}}_{{host_name}}"

回退示例

tasks:
  revert:
    steps:
      - name: "校验目标存在"
        action: command
        with:
          command: "test -d {{service_path}}/releases/{{revert_id}}"
      - name: "回退软链接"
        action: command
        with:
          command: "ln -sfn {{service_path}}/releases/{{revert_id}} {{service_path}}/current"
taskssh revert prod -D revert_id=20260926_0K8X7A2B

CLI 注入

通过 -D / --define 注入变量,优先级高于清单, 作用于所有目标主机。格式 key=value,可重复。

            taskssh deploy prod -D version=1.2.3
            taskssh deploy prod -D version=1.2.3 -D env=uat

规则

扩展字段

defaults / 组 vars / 主机定义中, 除专有字段(host / port / username / password / identity_file / passphrase)外的 任意字段进入 Extra,参与变量替换。

defaults:
  app_name: myapp

servers:
  prod:
    vars:
      env: prod
    hosts:
      web1:
        host: 192.168.1.10
        role: web              # 进入 Extra
        zone: cn-north-1
- action: command
  when: "{{env}} == prod && {{role}} == web"
  with:
    command: "systemctl restart {{app_name}}"
ℹ️

Extra 字段名不能与专有字段同名。例如自定义 port 不会进入变量池,而会作为连接端口。

认证方式

按以下顺序尝试,第一个成功即完成连接:

顺序 方式 配置
1 SSH Agent SSH_AUTH_SOCK 环境变量
2 公钥认证 identity_file
3 私钥口令 passphrase
4 keyboard-interactive password
5 password password
6 终端交互输入 未配置任何认证时
💡

只有 密码和私钥口令需要在清单中存储密文。 使用 SSH Agent 或公钥认证时,不需要配置加解密。

SSH Agent

自动检测 SSH_AUTH_SOCK。适用于本地已 ssh-add 加载私钥、或通过跳板机 ssh -A 转发 agent 的场景。

eval $(ssh-agent)
ssh-add ~/.ssh/id_rsa

taskssh release prod
ℹ️

Windows 的 OpenSSH Agent 使用命名管道,当前版本暂不支持。 如需 agent 转发,请在 WSL 或 Git Bash 环境使用。

公钥认证

1. 本地生成密钥对(已有可跳过)

# 推荐 ed25519
ssh-keygen -t ed25519 -C "deploy@taskssh"

2. 上传公钥到服务器

# Linux / macOS
ssh-copy-id -i ~/.ssh/id_ed25519.pub deploy@192.168.1.10

无 ssh-copy-id 时手动复制:

cat ~/.ssh/id_ed25519.pub
# 登录远程主机,把上一步的输出追加到 authorized_keys
ssh deploy@192.168.1.10
mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo "粘贴公钥内容" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
⚠️

authorized_keys 权限必须是 600, ~/.ssh 目录必须是 700。 权限过宽会导致 SSH 拒绝公钥认证。

3. 在清单中配置

defaults:
  username: deploy
  identity_file: ~/.ssh/id_ed25519

servers:
  prod:
    hosts:
      web1: 192.168.1.10

~ 自动展开为 home。也可按主机单独配置 identity_file。

如私钥有 passphrase,用 taskssh encrypt 加密后填入 passphrase 字段。更推荐用 ssh-agent 管理。

4. 命令行临时覆盖私钥

taskssh release prod -k ~/.ssh/id_deploy

-i 已被 --inventory 占用,短选项为 -k。

密码认证

清单中的 password 必须是 taskssh encrypt 生成的密文。

taskssh encrypt
# 输出密文:xxxxx
defaults:
  username: deploy
  password: "xxxxx"

CLI -p / --password 允许传明文,会给出安全警告, 仅推荐临时排查时使用。

加密与密钥

清单中的 password 和 passphrase 必须为密文。 算法为 AES-256-GCM,密钥由用户管理,不硬编码在二进制中。

加密 / 解密

taskssh encrypt       # 按提示输入,输出密文
taskssh decrypt       # 按提示输入密文,输出明文

生成密钥

taskssh keygen

生成 32 字节随机密钥,Base64 编码后写入 ~/.taskssh/vault-key,权限 600。

选项 说明
-V / --secret-key-file 指定输出路径
-F / --force 覆盖已存在的密钥文件
⚠️

覆盖已有密钥后,之前用旧密钥加密的所有密文将无法解密。

密钥来源

按以下优先级查找:

顺序 来源
1 --secret-key-file / -V 指定的文件
2 TASKSSH_SECRET_KEY_FILE 环境变量
3 默认路径 ~/.taskssh/vault-key
4 交互输入

手动生成(可选)

mkdir -p ~/.taskssh
openssl rand -base64 32 > ~/.taskssh/vault-key
chmod 600 ~/.taskssh/vault-key

备份

串行与并发

默认串行执行:一台主机完成后再下一台,主机内 step 依次执行。 日志实时输出,失败可即时定位。

通过 -c 指定并发数:

taskssh release prod -c 5

最多同时操作 5 台主机,一台完成后自动补充下一台。

并发数 适用场景
1(默认) 生产发布、顺序敏感操作
2–5 小规模集群滚动操作
10+ 只读命令、日志收集、批量诊断
ℹ️

并发时,每台主机的日志先写入独立缓冲,执行完毕统一输出, 避免多主机日志交错。

按组分批

通过任务级 serial / min_available, 将同组主机切分成多批,滚动执行。

tasks:
  deploy:
    serial: 2              # 每组每批 2 台
    min_available: 1       # 每组至少留 1 台在跑
    steps: [...]

调度规则:组间串行,批间串行,批内并发。 每批只包含同一组的主机。

每批大小:

batchSize = min(serial, len(group) - minAvailable)
组大小 serial min_available 结果
4 2 1 批 2 + 2
2 2 1 批 1 + 1
4 0 1 批 3 + 1
4 0 0 批 4(全动)

CLI 可临时覆盖:

taskssh deploy order,stock -S 3 --min-available 1

参数对照

位置 参数 说明
任务级 serial 每组内每批 N 台
任务级 min_available 每组至少留 N 台
CLI -S / --serial 覆盖任务级 serial
CLI --min-available 覆盖任务级 min_available
CLI --stop-on-failure 一批失败后停止后续,默认 true

边界

Dry-run

--dry-run 不连接远程主机,输出每台主机每个 step 将执行的内容。

taskssh release prod --dry-run

行为

日志级别

级别 选项 显示内容
Error 始终显示;-q / --quiet 错误及失败诊断
Warn 默认 警告及被忽略的步骤失败
Info(默认) 默认 步骤状态、主机进度、成功信息、执行摘要、远程命令 stdout / stderr
Debug -v / --verbose 增加调试信息、重试细节
Trace --trace 高频细节,例如逐文件传输信息
附加行为 — --dry-run 至少启用 Debug;--trace 优先级最高;同时指定 -v 与 -q 时 -v 优先。

远程命令的 stdout / stderr 默认实时显示;-q 下隐藏原始命令输出。 命令非零退出时,错误信息始终包含退出码及限长诊断(优先 stderr,stderr 为空时使用 stdout); 设置 ignore_errors 时作为警告输出。

CLI 选项

全部选项索引。详细说明见对应章节。

选项 长选项 说明 详见
-i --inventory 指定清单文件 清单
-l --list 仅列出目标主机 清单
-P --port 覆盖 SSH 端口 host
-u --user 覆盖登录用户名 host
-p --password 覆盖登录密码(明文,不推荐) 认证方式
-k --identity-file 覆盖私钥路径 认证方式
— --connect-timeout 连接超时秒数,默认 10 host
-D --define 注入变量 key=value CLI 注入
-V --secret-key-file 指定 Vault 密钥文件 加密与密钥
-c --concurrency 并发数,默认 1 串行与并发
-S --serial 每组每批 N 台 按组分批
— --min-available 每组至少留 N 台 按组分批
— --stop-on-failure 一批失败后停止后续批次 按组分批
— --dry-run 预演,不实际执行 Dry-run
— --confirm 列出目标主机并等待确认 Dry-run
-v --verbose 详细输出 日志级别
-q --quiet 仅输出错误 日志级别
— --trace 启用跟踪输出 日志级别
— --version 显示版本信息 —
-h --help 显示帮助信息 —

子命令

命令 说明
command 执行远程命令
push 上传文件或目录
fetch 下载文件或目录
script 上传脚本并执行
encrypt / decrypt 加解密字符串
keygen 生成 Vault 密钥文件
test 测试连接,并同步更新公钥信息到本地 known_hosts