bytedance batchRun 工具使用手册
一、项目简介
batchRun 是一款 HPC 系统批量操作、资产管理和信息采集工具，支持命令行和 GUI 两种模式。核心能力：
- 批量执行：通过 SSH 在大量远程主机上并行执行命令
- 资产管理：管理主机清单、分组、硬件信息
- 数据采集：定期采集主机状态、网络拓扑、队列信息
- 安全分析：集群安全审计和风险评估
二、CLI 批量执行（batch_run）
2.1 命令格式
batch_run [选项]
2.2 参数说明
| 参数 | 说明 | 示例 |
|---|---|---|
-H, --hosts |
指定目标主机（IP/主机名/文件） | -H 10.151.1.1 10.151.1.2 |
-G, --groups |
指定主机分组 | -G GPU_SERVER ALL |
-L, --list |
仅列出匹配的主机，不执行命令 | -G ALL -L |
-u, --user |
指定 SSH 登录用户（默认当前用户） | -u root |
-p, --password |
指定 SSH 密码（不推荐明文；写入历史时已脱敏为 ***，但执行期间仍可被 ps 看到，建议改用 BATCH_RUN_PASSWORD 环境变量或 save_password） |
|
-c, --command |
要执行的命令 | -c 'uptime' |
-P, --parallel |
并行度：1=串行，n=n路并行（≤ config.max_parallel，默认512；-P 0 不允许） |
-P 128 |
-t, --timeout |
SSH 超时秒数（串行默认10s，并行默认20s） | -t 30 |
-l, --output_message_level |
输出级别（0-4） | -l 1 |
-o, --output_file |
输出到文件（HOST会被替换为主机IP） | -o /tmp/out/HOST |
-g, --gui |
启动 GUI 模式 |
2.3 主机指定方式
# 直接指定 IP
batch_run -H 10.151.1.1 10.151.1.2 -c 'uptime'
# 指定 IP:端口
batch_run -H 10.151.1.1:2222 -c 'uptime'
# 排除某主机（波浪线前缀）
batch_run -H ALL ~10.151.1.1 -c 'uptime'
# 从文件读取主机列表
batch_run -H /path/to/host_file -c 'uptime'
# 指定分组
batch_run -G GPU_SERVER -c 'nvidia-smi'
# ALL 表示全部主机/分组
batch_run -H ALL -c 'hostname'
batch_run -G ALL -c 'hostname'
# 排除分组
batch_run -G ALL ~TEST_GROUP -c 'uptime'
2.4 输出级别
| 级别 | 含义 |
|---|---|
| 0 | 仅打印主机信息（IP） |
| 1 | 仅打印命令输出 |
| 2 | 打印主机信息 + 命令输出首行 |
| 3 | 打印主机信息 + 完整命令输出（默认） |
| 4 | 详细模式，含 SSH 命令本身 |
2.5 输出到文件
使用 -o 将每台主机的输出分别保存到文件：
# HOST 会被替换为实际的主机 IP
batch_run -G ALL -P 128 -c 'df -h' -o /tmp/disk_check/HOST
# 执行后每台主机有独立输出文件：
# /tmp/disk_check/10.151.1.1
# /tmp/disk_check/10.151.1.2
# ...
2.6 常用场景
# 检查所有主机负载
batch_run -G ALL -P 128 -c 'uptime'
# 检查磁盘使用
batch_run -G ALL -P 128 -c 'df -h /tmp'
# 查看内存状态
batch_run -G ALL -P 128 -c 'free -h'
# 检查指定进程
batch_run -G ALL -P 128 -c 'ps aux | grep java | grep -v grep'
# 查看系统版本
batch_run -G ALL -P 128 -c 'cat /etc/os-release'
# 批量重启服务（危险操作！）
batch_run -G WEB_SERVER -P 10 -c 'systemctl restart nginx'
# 批量分发文件（结合 scp）
batch_run -G ALL -P 128 -c 'scp user@mgmt:/path/file /local/path/'
# 列出某分组的所有主机
batch_run -G GPU_SERVER -L
三、主机列表（host.list）
3.1 格式
INI 风格，[group] 定义分组，每行一个主机：
[GPU_SERVER]
10.151.1.1 host_name=gpu01 ssh_port=22
10.151.1.2 host_name=gpu02
[WEB_SERVER]
10.151.2.1 host_name=web01
10.151.2.2 host_name=web02
[ALL]
# 支持引用其他分组
sub_groups = GPU_SERVER WEB_SERVER
3.2 特殊语法
host_name=xxx：指定主机名ssh_port=xxx：指定 SSH 端口（非22时必填）sub_groups = G1 G2：包含子分组exclude_hosts = ip1 ip2：排除主机exclude_groups = G1：排除子分组- 支持通配符
*匹配分组名
四、GUI 模式（batch_run_gui）
4.1 启动
batch_run_gui
# 或
batch_run -g
4.2 标签页
| 标签页 | 功能 |
|---|---|
| NETWORK | 网络拓扑：zone/network/IP 树 + 矢量拓扑图 |
| ASSET | 资产管理：设备信息表格 |
| HOST | 主机管理：分组树 + 多维筛选 + 详情表格 |
| STAT | 状态趋势：host_stat 历史曲线（负载/CPU/内存/swap/tmp） |
| RUN | 批量执行：选择主机 + 输入命令 + 实时输出 |
| LOG | 命令历史：查看历史执行记录 |
4.3 菜单功能
| 菜单 | 功能 |
|---|---|
| File | 导出表格、退出 |
| Setup | 选择数据源目录 |
| Tool | 更新 host.list、网络扫描、采集主机信息/状态/队列 |
| AI | AI 助手对话、集群分析报告、安全分析报告 |
五、数据采集工具
5.1 网络扫描（network_scan）
扫描 IP 网段，发现活跃主机：
# 扫描所有配置的网段
network_scan --alive
# 结果保存到 db/network_scan/network_scan.json
5.2 主机信息采集（sample_host_info）
采集 OS、CPU、内存等静态信息：
sample_host_info --groups ALL
# 结果保存到 db/host_info/host_info.json
5.3 主机状态采集（sample_host_stat）
采集运行时状态（负载、CPU利用率、内存、swap、tmp）：
sample_host_stat --groups ALL
# 结果保存到 db/host_stat/YYYYMMDD/HHMMSS/host_stat.json
5.4 队列信息采集（sample_host_queue）
采集 LSF/openlava 调度器队列映射：
sample_host_queue --groups ALL
# 结果保存到 db/host_queue/host_queue.json
六、密码管理
6.1 保存密码
save_password
# 交互式输入密码（不回显），加密保存到 db/password/<user>
密码解析优先级：-p/--password 参数 → BATCH_RUN_PASSWORD 环境变量 → 交互式输入。推荐用后两者，避免密码留在命令行历史/ps 中。
- 密码以 Fernet 加密（AES-128-CBC + HMAC-SHA256）保存，master key 独立存放于
db/password/.master_key。 - 密码文件与 master key 文件权限
0o600，密码目录权限0o700，仅属主可读写。 - 写入采用原子重命名；旧版本密码条目仍可读取（兼容迁移）。
密码保存后，batch_run 和 GUI 可免密执行 SSH（自动读取加密密码）。也可以临时通过环境变量提供密码（优先级高于加密存储）：
BATCH_RUN_PASSWORD='***' batch_run -G ALL -c 'uptime'
6.2 切换用户
batch_run -u other_user -c 'whoami'
七、安装与配置
7.1 安装
python3 install.py
安装脚本会：
- 检查 Python 版本（要求 3.12+）
- 生成 shell 包装脚本（bin/batch_run, bin/batch_run_gui, tools/*）
- 生成默认配置文件 config/config.py
7.2 配置文件（config/config.py）
| 变量 | 说明 |
|---|---|
host_list |
主机清单文件路径 |
db_path |
数据库根目录 |
default_ssh_command |
SSH 命令模板，默认 StrictHostKeyChecking=accept-new |
serial_timeout |
串行模式超时（秒） |
parallel_timeout |
并行模式超时（秒），默认 20 |
illegal_command_list |
禁止执行的命令列表（字面精确匹配，另内置破坏性命令模式拦截） |
log_retention_days |
日志保留天数 |
ai_api_base_url |
AI API 地址 |
ai_api_key |
AI API 密钥 |
ai_model_name |
AI 模型名称 |
ai_dangerous_commands |
AI 执行前需确认的危险命令列表（另会检测命令替换/编码垫片/解释器 -c 等绕过构造） |
八、AI 助手中使用 batch_run
在 AI 对话中，你可以通过 run_command 工具调用 batch_run 命令来批量操作远程主机。
8.1 重要规则
- batch_run 的完整路径：
$BATCH_RUN_INSTALL_PATH/bin/batch_run - 并行执行：对多台主机操作务必加
-P 128（或更大），否则串行执行非常慢 - 超时设置：远程命令执行时间长时需加
-t 30或更大值 - 输出级别：如果只需要结果数据，使用
-l 1（仅命令输出）便于解析 - 输出到文件：大量主机时用
-o /tmp/result/HOST收集结果，再逐一读取分析
8.2 典型调用模式
# 查看所有主机负载（实时）
$BATCH_RUN_INSTALL_PATH/bin/batch_run -G ALL -P 128 -t 20 -l 3 -c 'uptime'
# 检查磁盘空间不足的主机
$BATCH_RUN_INSTALL_PATH/bin/batch_run -G ALL -P 128 -t 20 -l 1 -c 'df -h / /tmp | tail -n +2'
# 查找特定进程
$BATCH_RUN_INSTALL_PATH/bin/batch_run -G ALL -P 128 -t 20 -l 3 -c 'ps aux | grep -v grep | grep java'
# 检查服务状态
$BATCH_RUN_INSTALL_PATH/bin/batch_run -G WEB_SERVER -P 128 -t 20 -l 3 -c 'systemctl is-active nginx'
# 输出到文件后分析
$BATCH_RUN_INSTALL_PATH/bin/batch_run -G ALL -P 128 -t 30 -l 1 -c 'cat /etc/os-release' -o /tmp/os_info/HOST
# 然后读取 /tmp/os_info/ 下各文件进行分析
# 列出指定分组的主机
$BATCH_RUN_INSTALL_PATH/bin/batch_run -G GPU_SERVER -L
8.3 注意事项
- 命令中包含单引号时需要转义或用双引号包裹
- 命令中包含管道符
|时需要用引号将整个命令括起来 batch_run会自动使用已保存的加密密码进行 SSH 认证- 如果某台主机 SSH 超时或失败，不影响其他主机的执行
- 使用
-o输出文件时，HOST 占位符会被替换为主机 IP
九、常见问题
Q: batch_run 连接超时？
- 检查目标主机是否可达（ping）
- 检查 SSH 端口是否正确（host.list 中 ssh_port 配置）
- 增大
-t超时值 - 确认密码已保存（
save_password）
Q: 如何查看有哪些分组？
- GUI 的 HOST 标签页左侧树形列表
- 或直接查看 host.list 文件中的
[group]段
Q: 如何添加新主机？
- 编辑 host.list 文件，在对应分组下添加行
- 或使用
switch_etc_hosts工具从 /etc/hosts 自动转换
Q: 并行数设多少合适？
- 一般 128 即可覆盖大部分场景
- 并行度上限为
config.max_parallel（默认 512），-P 0（无限并行）已被禁止 - 串行（默认 -P 1）适合需要逐一确认的场景
Q: 输出太多看不过来？
- 使用
-l 2只看每台主机的首行输出 - 使用
-o导出到文件后用 grep 筛选 - 在命令中加
| grep xxx过滤