batchrun-usage

# batchRun 工具使用手册 ## 一、项目简介 batchRun 是一款 HPC 系统批量操作、资产管理和信息采集工具，支持命令行和 GUI 两种模式。核心能力： - **批量执行**：通过 SSH 在大量远程主机上并行执行命令 - **资产管理**：管理主机清单、分组、硬件信息 - **数据采集**：定期采集主机状态、网络拓扑、队列信息 - **安全分析**：集群安全审计和风险评估 --- ## 二、CLI 批量执行（batch_run） ### 2.1 命令格式 ```bash 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 主机指定方式 ```bash # 直接指定 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` 将每台主机的输出分别保存到文件： ```bash # 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 常用场景 ```bash # 检查所有主机负载 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]` 定义分组，每行一个主机： ```ini [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 启动 ```bash 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 网段，发现活跃主机： ```bash # 扫描所有配置的网段 network_scan --alive # 结果保存到 db/network_scan/network_scan.json ``` ### 5.2 主机信息采集（sample_host_info） 采集 OS、CPU、内存等静态信息： ```bash sample_host_info --groups ALL # 结果保存到 db/host_info/host_info.json ``` ### 5.3 主机状态采集（sample_host_stat） 采集运行时状态（负载、CPU利用率、内存、swap、tmp）： ```bash sample_host_stat --groups ALL # 结果保存到 db/host_stat/YYYYMMDD/HHMMSS/host_stat.json ``` ### 5.4 队列信息采集（sample_host_queue） 采集 LSF/openlava 调度器队列映射： ```bash sample_host_queue --groups ALL # 结果保存到 db/host_queue/host_queue.json ``` --- ## 六、密码管理 ### 6.1 保存密码 ```bash 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（自动读取加密密码）。也可以临时通过环境变量提供密码（优先级高于加密存储）： ```bash BATCH_RUN_PASSWORD='***' batch_run -G ALL -c 'uptime' ``` ### 6.2 切换用户 ```bash batch_run -u other_user -c 'whoami' ``` --- ## 七、安装与配置 ### 7.1 安装 ```bash python3 install.py ``` 安装脚本会： 1. 检查 Python 版本（要求 3.12+） 2. 生成 shell 包装脚本（bin/batch_run, bin/batch_run_gui, tools/*） 3. 生成默认配置文件 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 重要规则 1. **batch_run 的完整路径**：`$BATCH_RUN_INSTALL_PATH/bin/batch_run` 2. **并行执行**：对多台主机操作务必加 `-P 128`（或更大），否则串行执行非常慢 3. **超时设置**：远程命令执行时间长时需加 `-t 30` 或更大值 4. **输出级别**：如果只需要结果数据，使用 `-l 1`（仅命令输出）便于解析 5. **输出到文件**：大量主机时用 `-o /tmp/result/HOST` 收集结果，再逐一读取分析 ### 8.2 典型调用模式 ```bash # 查看所有主机负载（实时） $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` 过滤