ginkgo-tools-batchssh 0.1.0__py3-none-any.whl

ginkgo_tools_batchssh/__init__.py

@@ -0,0 +1,53 @@
+"""
+GINKGO-TOOLS-BATCHSSH
+=====================
+
+一个用于批量SSH操作和文件传输的Python工具包。
+
+主要功能：
+- SSH连接管理
+- 远程命令执行（支持超时控制）
+- SFTP文件上传下载（支持通配符）
+- 批量主机管理
+- 日志记录系统
+
+模块说明：
+- SSHWrapper: 核心SSH连接和操作类
+- module_logger: 日志配置和管理模块  
+- moduel_convenient_tools: 便捷工具函数集合
+
+作者: 霍城
+邮箱: 495466557@qq.com
+"""
+
+__version__ = "0.1.0"
+__author__ = "霍城"
+__email__ = "495466557@qq.com"
+__description__ = "批量SSH操作和文件传输工具包"
+
+# 核心类导入
+
+from .module_SSHwrapper import SSHWrapper
+from .moduel_convenient_tools import read_hosts_file, parse_and_filter_hosts
+from .module_logger import setup_logging, get_logger
+
+
+# 定义公共API
+__all__ = [
+    # 核心类
+    'SSHWrapper',
+    
+    # 便捷工具函数
+    'read_hosts_file',
+    'parse_and_filter_hosts',
+    
+    # 日志相关
+    'setup_logging',
+    'get_logger',
+    
+    # 版本信息
+    '__version__',
+    '__author__',
+    '__email__',
+    '__description__'
+]

ginkgo_tools_batchssh/moduel_convenient_tools.py

@@ -0,0 +1,51 @@
+import os
+
+"""读取hosts文件，优先以当前目录下的Hosts为准，如果不存在，则读取/etc/hosts"""
+def read_hosts_file(local_host_dir: str = None) -> str:
+    """读取hosts文件内容"""
+    local_host = os.path.join(local_host_dir, "hosts")
+    try:
+        with open(local_host, "r", encoding="utf-8") as f:
+            return f.read()
+    except:
+        with open("/etc/hosts", "r", encoding="utf-8") as f:
+            return f.read()
+
+
+
+
+"""过滤操作对象的主机地址列表，并执行去重和反向主机名匹配"""
+
+
+def parse_and_filter_hosts(hosts_content: str, filter_list: list) -> dict:
+    """解析并过滤hosts文件内容"""
+    """输入的content可以是read_hosts_file()的值，也可以是手动生成的字符串，保证是ip host1 host2的行格式即可"""
+    target_hosts = {}
+
+    for line_num, line in enumerate(hosts_content.splitlines(), 1):
+        # 跳过注释行和空行
+        line = line.strip()
+        if not line or line.startswith("#"): continue
+
+        # 解析行内容
+        parts = line.split()
+        if len(parts) < 2: continue
+
+        ip_address, *hostnames = parts
+
+        # 跳过本地回环地址
+        if ip_address in ("127.0.0.1", "::1"): continue
+        # 应用过滤条件
+        if filter_list and not all(filter_word in line for filter_word in filter_list): continue
+        # 合并主机名（去重）
+        if ip_address in target_hosts:
+            target_hosts[ip_address].extend(hostnames)
+        else:
+            target_hosts[ip_address] = hostnames.copy()
+    return target_hosts
+
+
+
+
+
+

ginkgo_tools_batchssh/module_SSHwrapper.py

@@ -0,0 +1,832 @@
+"""
+作者：霍城 495466557@qq.com
+
+SSH 连接封装模块
+提供 SSH 连接功能，支持首次连接确认流程
+"""
+import paramiko
+import uuid
+from typing import Optional
+from . import module_logger
+import os
+import stat
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+
+
+
+logger = module_logger.get_logger(__name__)
+
+
+class SSHWrapper:
+    def __init__(self, host_ip="127.0.0.1", port=22, username="test_user", password="password", host_name="", timeout=10):
+        self._ssh_client = None
+        self._sftp_client = None
+        self.ssh_connected = False
+        self.sftp_connected = False
+
+        self.host_ip = host_ip
+        self.host_name = host_name
+        self.port = port
+        self.password = password
+        self.username = username
+        self.timeout = timeout
+        self.uuid_mark = str(uuid.uuid4()) # 标记主机+本次操作，方便日志追踪
+
+    @property
+    def ssh_client(self) -> Optional[paramiko.SSHClient]:
+        """SSH客户端实例"""
+        if self._ssh_client:
+            return self._ssh_client
+        else:
+            return self.ssh_connect()
+
+    @property
+    def sftp_client(self) -> Optional[paramiko.SFTPClient]:
+        """SFTP客户端实例"""
+        if self._sftp_client:
+            return self._sftp_client
+        else:
+            return self.sftp_connect()
+
+    def _ensure_remote_directory(self, remote_dir: str):
+        """确保远程目录存在，如果不存在则递归创建"""
+        # 标准化路径并分割
+        path_parts = remote_dir.strip('/').split('/')
+        current_path = ""
+
+        for part in path_parts:
+            if not part:  # 跳过空部分
+                continue
+            current_path = f"{current_path}/{part}" if current_path else f"/{part}"
+
+            try:
+                # 尝试创建当前层级目录
+                self.sftp_client.mkdir(current_path)
+                logger.debug(f"创建远程目录: {current_path}")
+            except OSError:
+                # 目录可能已存在，验证是否存在且为目录
+                try:
+                    stat_info = self.sftp_client.stat(current_path)
+                    # 使用Python标准库的stat模块进行目录类型检查
+
+                    if stat.S_ISDIR(stat_info.st_mode):
+                        logger.debug(f"确认远程目录已存在: {current_path}")
+                    else:
+                        logger.warning(f"路径存在但不是目录: {current_path}")
+                        return False
+                except FileNotFoundError:
+                    logger.warning(f"无法创建或确认远程目录: {current_path}")
+                    return False
+
+        return True
+
+    def _pattern_remote_files(self, path_pattern: str) -> list:
+        """
+        扫描远程目录，返回符合通配符模式的所有文件路径
+
+        Args:
+            path_pattern (str): 包含通配符的路径模式
+
+        Returns:
+            list: 符合条件的文件路径列表
+        """
+        import re
+
+        # 判断是否为绝对路径
+        is_absolute = path_pattern.startswith('/')
+        
+        # 标准化路径（保留开头的/）
+        if is_absolute:
+            normalized_path = path_pattern.lstrip('/')
+            base_path = '/'
+        else:
+            normalized_path = path_pattern.lstrip('/')
+            base_path = '..'
+            
+        if not normalized_path:
+            return []
+
+        def match_pattern(text: str, pattern: str) -> bool:
+            """通配符匹配"""
+            regex_pattern = pattern.replace('*', '.*').replace('?', '.')
+            regex_pattern = f"^{regex_pattern}$"
+            try:
+                return bool(re.match(regex_pattern, text))
+            except:
+                return False
+
+        def expand_paths_recursive(segments: list, current_path: str) -> list:
+            """递归展开路径段"""
+            if not segments:
+                return []
+
+            segment = segments[0]
+            remaining_segments = segments[1:]
+            results = []
+
+            if '*' in segment or '?' in segment:
+                # 通配符段：列出当前目录并匹配
+                try:
+                    items = self.sftp_client.listdir(current_path)
+
+                    for item in items:
+                        if match_pattern(item, segment):
+                            # 构造完整路径
+                            if current_path == '/' or current_path == '.':
+                                full_path = f"{current_path}{item}" if current_path == '/' else item
+                            else:
+                                full_path = f"{current_path}/{item}"
+                            
+                            try:
+                                stat_info = self.sftp_client.stat(full_path)
+                                if stat.S_ISDIR(stat_info.st_mode):
+                                    # 是目录，继续递归
+                                    if remaining_segments:
+                                        results.extend(expand_paths_recursive(remaining_segments, full_path))
+                                    else:
+                                        # 没有更多段了，列出目录中的文件
+                                        dir_files = self.sftp_client.listdir(full_path)
+                                        for filename in dir_files:
+                                            if full_path == '/':
+                                                file_full_path = f"/{filename}"
+                                            else:
+                                                file_full_path = f"{full_path}/{filename}"
+                                            try:
+                                                file_stat = self.sftp_client.stat(file_full_path)
+                                                if stat.S_ISREG(file_stat.st_mode):
+                                                    results.append(file_full_path)
+                                            except:
+                                                continue
+                                elif stat.S_ISREG(stat_info.st_mode) and not remaining_segments:
+                                    # 是文件且是最后一段，直接添加
+                                    results.append(full_path)
+                            except:
+                                continue
+                except Exception as e:
+                    logger.warning(f"处理通配符段 {segment} 在路径 {current_path} 下失败: {e}")
+            else:
+                # 固定路径段
+                if current_path == '/' or current_path == '.':
+                    next_path = f"{current_path}{segment}" if current_path == '/' else segment
+                else:
+                    next_path = f"{current_path}/{segment}"
+                
+                if remaining_segments:
+                    results.extend(expand_paths_recursive(remaining_segments, next_path))
+                else:
+                    # 最后一段，如果是目录则列出其中文件，如果是文件则直接返回
+                    try:
+                        stat_info = self.sftp_client.stat(next_path)
+                        if stat.S_ISDIR(stat_info.st_mode):
+                            # 列出目录中的文件
+                            dir_files = self.sftp_client.listdir(next_path)
+                            for filename in dir_files:
+                                if next_path == '/':
+                                    file_full_path = f"/{filename}"
+                                else:
+                                    file_full_path = f"{next_path}/{filename}"
+                                try:
+                                    file_stat = self.sftp_client.stat(file_full_path)
+                                    if stat.S_ISREG(file_stat.st_mode):
+                                        results.append(file_full_path)
+                                except:
+                                    continue
+                        elif stat.S_ISREG(stat_info.st_mode):
+                            results.append(next_path)
+                    except:
+                        pass
+
+            return results
+
+        # 处理完整路径
+        path_segments = normalized_path.split('/')
+        return expand_paths_recursive(path_segments, base_path)
+
+
+    def ssh_connect(self):
+        """
+        连接到远程主机SSH
+        
+        Returns:
+            paramiko.SSHClient: SSH客户端实例
+        """
+        try:
+            self._ssh_client = paramiko.SSHClient()
+            # 处理首次SSH连接确认流程
+            self._ssh_client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+            
+            self._ssh_client.connect(
+                hostname=self.host_ip,
+                port=self.port,
+                username=self.username,
+                password=self.password,
+                timeout=self.timeout
+            )
+            self.ssh_connected = True
+            logger.info(f"SSH连接成功：{self.host_ip} - {self.host_name}")
+            return self._ssh_client
+        except Exception as e:
+            logger.error(f"SSH连接失败: ：{self.host_ip} - {self.host_name}：{e}")
+            raise None
+
+    def sftp_connect(self):
+        """
+        连接到远程主机SFTP
+        
+        Returns:
+            paramiko.SFTPClient: SFTP客户端实例
+        """
+        try:
+            if not self._ssh_client:
+                self.ssh_connect()
+                
+            self._sftp_client = self._ssh_client.open_sftp()
+            self.sftp_connected = True
+            logger.info(f"SFTP连接成功：{self.host_ip} - {self.host_name}")
+            return self._sftp_client
+        except Exception as e:
+            logger.error(f"SFTP连接失败: {self.host_ip} - {self.host_name}：{e}")
+            raise None
+
+    def _execute_timeout_manage(self, stdin, stdout, stderr, timeout: int) -> dict:
+        """
+        管理命令执行的超时和输出读取（类函数）
+        
+        Args:
+            stdin: 标准输入通道
+            stdout: 标准输出通道  
+            stderr: 错误输出通道
+            timeout (int): 超时时间（秒）
+            
+        Returns:
+            dict: 包含执行结果的字典，结构如下：
+                {
+                    "stdout": "标准输出内容",          # 命令的标准输出
+                    "stderr": "错误输出内容",          # 命令的错误输出
+                    "exit_status": None,              # 退出状态码(int)，超时为None
+                    "timeout": 30,                    # 超时时间设置(秒)
+                    "do_break": False,                # 是否主动断开(bool)
+                    "error": "错误信息",              # 异常时的错误描述
+                    "result": False,                  # 执行结果(bool)
+                    "channels_closed": True           # 通道是否已关闭(bool，异常时存在)
+                }
+        """
+        import time
+        
+        response_dict = {
+            "stdout": "",
+            "stderr": "",
+            "exit_status": None,
+            "timeout": timeout,
+            "do_break":False,# 主动断开
+            "error":"",
+            "result":False
+        }
+        
+        start_time = time.time()
+        
+        try:
+            while time.time() - start_time < timeout:
+                # 检查命令是否完成
+                if stdout.channel.exit_status_ready():
+                    response_dict["exit_status"] = stdout.channel.recv_exit_status()
+                    response_dict["stdout"] = stdout.read().decode('utf-8')
+                    response_dict["stderr"] = stderr.read().decode('utf-8')
+                    if response_dict["exit_status"] == 0:
+                        response_dict["result"] = True
+                    else:response_dict["result"] = False
+                    break
+
+                # 非阻塞读取标准输出，超时时有用
+                if stdout.channel.recv_ready():
+                    chunk = stdout.channel.recv(1024).decode('utf-8')
+                    if chunk:
+                        response_dict["stdout"] += chunk
+                    else:
+                        break
+                # 非阻塞读取错误输出，超时时有用
+                if stderr.channel.recv_stderr_ready():
+                    chunk = stderr.channel.recv_stderr(1024).decode('utf-8')
+                    if chunk:
+                        response_dict["stderr"] += chunk
+                    
+                time.sleep(0.1)
+                
+            # 超时处理
+            if time.time() - start_time >= timeout:
+
+                response_dict["error"] = f"命令执行超过设置时间： ({timeout}秒)"
+                response_dict["result"] = False
+                response_dict["do_break"] = True # 主动中断操作链接
+                
+            # 关闭通道
+            self._close_channels_safely(stdout, stderr, stdin)
+            response_dict["channels_closed"] = True
+            
+        except Exception as e:
+            response_dict["stderr"] = f"超时管理代码异常: {str(e)}"
+            logger.error(f"超时管理代码异常: {str(e)}")
+            self._close_channels_safely(stdout, stderr, stdin)
+            response_dict["channels_closed"] = True
+            
+        return response_dict
+    
+    def _close_channels_safely(self, stdout, stderr, stdin):
+        """安全关闭SSH通道"""
+        channels = [stdout, stderr, stdin]
+        for channel_obj in channels:
+            try:
+                if hasattr(channel_obj, 'channel') and channel_obj.channel:
+                    channel_obj.channel.close()
+            except:
+                pass
+
+
+    def execute_command(self, command: str, timeout: int = 30) -> dict:
+        """
+        在远程主机上执行单个命令，支持超时控制
+        
+        Args:
+            command (str): 要执行的命令
+            timeout (int): 超时时间（秒），默认30秒
+            
+        Returns:
+            dict: 包含执行结果的字典，结构如下：
+                {
+                    "command": "执行的命令",           # 执行的完整命令
+                    "stdout": "标准输出内容",          # 命令的标准输出
+                    "stderr": "错误输出内容",          # 命令的错误输出
+                    "exit_status": 0,                 # 退出状态码(int)，超时为None
+                    "result": True,                   # 执行结果(bool)
+                    "timeout": 30,                    # 超时时间设置(秒)
+                    "do_break": False,                # 是否主动断开(bool)
+                    "error": "错误信息",              # 异常时的错误描述
+                    "channels_closed": True           # 通道是否已关闭(bool)
+                }
+        """
+        response_dict = dict()
+        response_dict["command"] = command
+
+
+        if not self.ssh_client:raise ConnectionError("SSH未连接")
+
+        stdin, stdout, stderr = self.ssh_client.exec_command(command)
+
+        # 管理命令执行的超时和输出读取
+        etm_response_dict = self._execute_timeout_manage(stdin, stdout, stderr, timeout)
+        # 合并字典
+        response_dict.update(etm_response_dict)
+
+        return response_dict
+
+
+    def execute_multiple_commands(self, command_list: list,combine_str = "&&", timeout: int = 30) -> dict:
+        """
+        在远程主机上执行多个命令，使用&&连接
+        
+        Args:
+            command_list (list): 要执行的命令列表
+            cwd (str, optional): 工作目录，如果不为None，则在此目录下执行命令
+            
+        Returns:
+            dict: 包含执行结果的字典，结构如下：
+                {
+                    "stdin": "",                    # 标准输入
+                    "stdout": "",                   # 标准输出
+                    "stderr": "",                   # 错误输出
+                    "exit_status": 0,                # 退出状态码(int)或None(异常时)
+                    "command": "cmd1 && cmd2",       # 执行的命令
+                    "command_count": 2,              # 命令数量
+                    "command_list": ["cmd1", "cmd2"], # 命令列表
+                    "result": True                   # 执行结果(bool)
+                }
+        """
+        response_dict = dict()
+        response_dict["command_count"] = len(command_list)
+        response_dict["command"] = f" {combine_str}".join(command_list)
+        
+        if not self.ssh_client:raise ConnectionError("SSH未连接")
+
+
+        stdin, stdout, stderr = self.ssh_client.exec_command(response_dict["command"])
+        # 管理命令执行的超时和输出读取
+        etm_response_dict = self._execute_timeout_manage(stdin, stdout, stderr, timeout)
+        # 合并字典
+        response_dict.update(etm_response_dict)
+
+        return response_dict
+
+    def execute_shell_commands(self, commands: list, timeout: int = 30) -> dict:
+        """
+        在同一个会话中执行多个命令，打包为shell脚本执行
+        
+        Args:
+            commands (list): 要执行的命令列表
+            cwd (str, optional): 工作目录，如果不为None，则在此目录下执行命令
+            
+        Returns:
+            dict: 包含执行结果的字典，结构如下：
+                {
+                    "stdin": "",                    # 标准输入
+                    "stdout": "",                   # 标准输出
+                    "stderr": "",                   # 错误输出
+                    "exit_status": 0,                # 退出状态码(int)
+                    "command": "bash script",        # 执行的完整脚本命令
+                    "command_list": ["cmd1", "cmd2"], # 原始命令列表
+                    "result": True                   # 执行结果(bool)
+                }
+        """
+        if not self.ssh_client: raise ConnectionError("SSH未连接")
+
+        response_dict = dict()
+        # 将命令转换为脚本内容
+        script_lines = ["#!/bin/bash"]
+        script_lines.extend(commands)
+        script_content = "\n".join(script_lines)
+        # 使用heredoc方式执行脚本内容
+        combined_command = f'bash -s << "EOF"\n{script_content}\nEOF'
+        response_dict["command"] = combined_command
+        response_dict["command_list"] =  commands
+
+        stdin, stdout, stderr = self.ssh_client.exec_command(combined_command)
+        # 管理命令执行的超时和输出读取
+        etm_response_dict = self._execute_timeout_manage(stdin, stdout, stderr, timeout)
+        # 合并字典
+        response_dict.update(etm_response_dict)
+
+        return response_dict
+
+
+    def commands_to_shell_trans(self, command_list: list = None, command_str: str = None,delete_local_shell: bool = True) -> dict:
+        """
+        将命令生成为shell文件并传输到远程主机，但不执行
+        
+        Args:
+            command_list (list, optional): 命令列表
+            command_str (str, optional): 命令字符串
+            
+        Returns:
+            dict: 包含传输结果的字典，结构如下：
+                {
+                    "file_name": "operation_xxx.sh",     # 生成的shell文件名
+                    "uuid": "uuid-string",               # 操作唯一标识
+                    "remote_path": "/home/user/file.sh", # 远程文件路径
+                    "result": True,                      # 传输结果(bool)
+                    "upload_response": {...}             # 上传响应详情
+                }
+        """
+        response_dict = dict()
+        response_dict["result"] = False
+        operation_uuid = str(uuid.uuid4())
+        file_name = "operation_" + operation_uuid + ".sh"
+        file_ready = False
+        # 分两种情况写shell文件
+        if command_list:
+            with open(file_name, "w") as f:
+                for command in command_list:
+                    f.write(command + "\n")
+            file_ready = True
+        elif command_str:
+            command_str = command_str.replace("\r", "\n")# 处理可能存在的win换行符问题
+            with open(file_name, "w",newline="\n") as f:
+                f.write(command_str)
+            file_ready = True
+
+        if file_ready:
+            logger.debug(f"命令封装执行前流程，shell操作文件封装完毕：{file_name}")
+            remote_path = f"/home/{self.username}/{file_name}"
+            response_dict["file_name"] = file_name
+            response_dict["uuid"] = operation_uuid
+            response_dict["remote_path"] = remote_path
+            response_dict["result"] = True
+
+            # 上传后操作状态更新为上传操作
+            logger.debug(f"命令封装执行前流程，开始上传shell操作文件{file_name}到远程主机{self.host_name}，目标远端目录：{remote_path}")
+            upload_response = self.sftp_upload_file(file_name, remote_path)
+            response_dict["upload_response"] = upload_response
+            response_dict["result"] = response_dict["result"] and upload_response["result"]
+            if delete_local_shell:os.remove(file_name)
+            if response_dict["result"]:
+                logger.debug(f"命令封装执行前流程，上传shell操作文件{file_name}到远程主机{self.host_name}成功")
+            else:
+                logger.warning(f"命令封装执行前流程，上传shell操作文件{file_name}到远程主机{self.host_name}失败，请检查反馈异常为：{upload_response['error']}")
+        else:
+            logger.warning(f"命令封装执行前流程，shell操作文件封装失败，未提供命令列表或命令字符串")
+        return response_dict
+
+    def commands_to_shell_run(self, trans_result: dict, sudo_to_user = False, timeout: int = 30) -> dict:
+        """
+        运行已传输的shell文件
+        
+        Args:
+            trans_result (dict): commands_to_shell_trans函数的返回结果
+            sudo_to_user (str, optional): 切换到指定用户执行，默认为False(不切换)
+            
+        Returns:
+            dict: 包含执行结果的字典，结构与execute_command一致，额外包含：
+                {
+                    "remote_path": "/path/to/script.sh", # 执行的脚本路径
+                    "file_name": "script.sh"             # 脚本文件名
+                }
+        """
+        shell_path = trans_result["remote_path"]
+        file_name = trans_result["file_name"]
+        if sudo_to_user:
+            logger.debug(f"命令封装执行前流程，触发sudo切换执行操作")
+            # 执行转移和变更操作
+            sudoers_shell_path = f"/home/{sudo_to_user}/{file_name}"
+            logger.info(f"命令封装执行后流程，开始将shell文件{shell_path}转移至用户{sudo_to_user}，目标路径为：{sudoers_shell_path}")
+            mv_result = self.execute_command(f'sudo su - root -c "chown {sudo_to_user} {shell_path};mv {shell_path} {sudoers_shell_path}"')
+            if not mv_result["result"]:
+                logger.warning(f"命令封装执行后流程，将shell文件{shell_path}转移至用户{sudo_to_user}失败，请检查反馈异常为：{mv_result['stderr']}")
+                return mv_result
+            logger.debug(f"命令封装执行后流程，将shell文件{shell_path}转移至用户{sudo_to_user}成功")
+
+            response_dict = self.execute_command(f'sudo su - {sudo_to_user} -c "sh {sudoers_shell_path}"', timeout= timeout)
+            response_dict["remote_path"] = sudoers_shell_path
+            response_dict["file_name"] = file_name
+            logger.debug(f"命令封装执行后流程，sudo执行shell文件{sudoers_shell_path}")
+
+            self.execute_command(f'sudo su - root -c "rm -f {sudoers_shell_path}"')
+            logger.debug(f"命令封装执行后流程，sudo删除shell文件{sudoers_shell_path}")
+        else:
+            logger.debug(f"命令封装执行后流程，常规运行流程")
+            response_dict = self.execute_command(f"sh {shell_path}", timeout= timeout)
+            response_dict["remote_path"] = shell_path
+            response_dict["file_name"] = file_name
+            logger.debug(f"命令封装执行后流程，执行shell文件{shell_path}")
+
+            self.execute_command(f"rm -f {shell_path}")
+            logger.debug(f"命令封装执行后流程，删除shell文件{shell_path}")
+        return response_dict
+
+    def sftp_upload_file(self, local_path: str, remote_path: str = "") -> dict:
+        """
+        上传单个文件到远程主机（不支持通配符）
+
+        Args:
+            local_path (str): 本地文件路径
+            remote_path (str, optional): 远程文件路径，为空时使用本地文件名
+
+        Returns:
+            dict: 包含上传结果的字典，结构如下：
+                {
+                    "local_path": "/local/file.txt",     # 本地文件路径
+                    "remote_path": "/remote/file.txt",   # 远程文件路径
+                    "result": True,                      # 上传结果(bool)
+                    "file_size": 1024,                   # 文件大小(bytes)
+                    "error": ""                          # 错误信息(失败时存在)
+                }
+        """
+        response_dict = {
+            "local_path": local_path,
+            "remote_path": remote_path,
+            "result": False
+        }
+
+        # 本地文件验证
+        if not os.path.exists(local_path):
+            response_dict["error"] = f"本地文件不存在: {local_path}"
+            logger.warning(response_dict["error"])
+            return response_dict
+        
+        if not os.path.isfile(local_path):
+            response_dict["error"] = f"指定路径不是文件: {local_path}"
+            logger.warning(response_dict["error"])
+            return response_dict
+
+        try:
+            sftp = self.sftp_client
+            # 执行上传
+            sftp.put(local_path, remote_path)
+            response_dict["result"] = True
+            response_dict["file_size"] = os.path.getsize(local_path)
+            
+            logger.info(f"文件上传成功: {local_path} -> {remote_path}")
+            
+        except Exception as e:
+            response_dict["result"] = False
+            response_dict["error"] = str(e)
+            logger.error(f"文件上传失败: {local_path} -> {remote_path}, 错误: {e}")
+            
+        return response_dict
+
+    def sftp_upload_to(self, local_path: str, remote_dir: str = "") -> dict:
+        """
+        支持通配符的批量SFTP上传方法
+
+        Args:
+            local_path (str): 本地路径，支持通配符模式(*, ?, **) 
+            remote_dir (str, optional): 远程目录路径，为空时使用本地文件名
+
+        Returns:
+            dict: 包含上传结果的字典，结构如下：
+                {
+                    "local_pattern": "*.txt",            # 本地匹配模式
+                    "remote_base": "/remote/dir/",      # 远程基础路径
+                    "uploaded_files": [                  # 成功上传的文件列表
+                        {
+                            "local_path": "/local/file.txt",
+                            "remote_path": "/remote/file.txt",
+                            "result": True
+                        }
+                    ],
+                    "failed_files": [                     # 上传失败的文件列表
+                        {
+                            "local_path": "/local/failed.txt",
+                            "remote_path": "/remote/failed.txt",
+                            "error": "error message",
+                            "result": False
+                        }
+                    ],
+                    "result": True                       # 总体结果(bool)
+                }
+        """
+        import glob
+        import os
+
+        # 解析通配符，获取所有匹配的本地文件
+        matched_files = glob.glob(local_path, recursive=True)
+
+        response_dict = {
+            "local_pattern": local_path,
+            "remote_base": remote_dir,
+            "uploaded_files": [],
+            "failed_files": [],
+            "result": True
+        }
+
+        # 遍历所有匹配的文件进行上传
+        for local_file in matched_files:
+            # 检查是否为文件（而不是目录）
+            if os.path.isfile(local_file):
+                # 计算目标远程路径
+                if remote_dir:
+                    # 如果指定了远程路径
+                    remote_path = os.path.join(remote_dir, os.path.basename(local_file)).replace("\\", "/")
+                else:
+                    # 如果未指定远程路径，则使用本地文件名
+                    remote_path = os.path.basename(local_file)
+
+                # 确保远程目录存在
+                if remote_dir:
+                    if not self._ensure_remote_directory(remote_dir):
+                        response_dict["failed_files"].append({
+                            "local_path": local_file,
+                            "remote_path": remote_path,
+                            "error": "无法创建远程目录，请检查是否是账户权限和目标路径不匹配",
+                            "result": False
+                        })
+                        response_dict["result"] = False
+                        logger.warning(f"无法创建远程目录: {remote_dir}，请检查是否是账户权限和目标路径不匹配")
+                        continue
+
+                # 执行上传
+                try:
+                    sftp = self.sftp_client
+                    sftp.put(local_file, remote_path)
+                    response_dict["uploaded_files"].append({
+                        "local_path": local_file,
+                        "remote_path": remote_path,
+                        "result": True
+                    })
+                except Exception as e:
+                    response_dict["failed_files"].append({
+                        "local_path": local_file,
+                        "remote_path": remote_path,
+                        "error": str(e),
+                        "result": False
+                    })
+                    response_dict["result"] = False
+
+        return response_dict
+
+    def sftp_download_file(self, remote_path: str, local_path: str) -> dict:
+        """
+        从远程主机下载文件
+
+        Args:
+            remote_path (str): 远程文件路径
+            local_path (str): 本地文件路径
+
+        Returns:
+            dict: 包含下载结果的字典，结构如下：
+                {
+                    "remote_path": "/remote/file.txt",   # 远程文件路径
+                    "local_path": "/local/file.txt",     # 本地文件路径
+                    "result": True,                      # 下载结果(bool)
+                    "error": ""                          # 错误信息(失败时存在)
+                }
+        """
+        response_dict = dict()
+        response_dict["remote_path"] = remote_path
+        response_dict["local_path"] = local_path
+
+        try:
+            sftp = self.sftp_client
+            sftp.get(remote_path, local_path)
+            response_dict["result"] = True
+        except Exception as e:
+            response_dict["result"] = False
+            response_dict["error"] = str(e)
+        return response_dict
+
+
+
+    def sftp_download_to(self, remote_path: str, local_dir: str = "") -> dict:
+        """
+        支持多级通配符的批量SFTP下载方法
+
+        Args:
+            remote_path (str): 远程路径，支持多级通配符模式(*, ?, **) 
+            local_dir (str, optional): 本地目录路径，为空时使用远程文件名
+
+        Returns:
+            dict: 包含下载结果的字典，结构如下：
+                {
+                    "remote_pattern": "*.txt",           # 远程匹配模式
+                    "local_base": "/local/dir/",        # 本地基础路径
+                    "downloaded_files": [                # 成功下载的文件列表
+                        {
+                            "remote_path": "/remote/file.txt",
+                            "local_path": "/local/file.txt",
+                            "result": True
+                        }
+                    ],
+                    "failed_files": [                     # 下载失败的文件列表
+                        {
+                            "remote_path": "/remote/failed.txt",
+                            "local_path": "/local/failed.txt",
+                            "error": "error message",
+                            "result": False
+                        }
+                    ],
+                    "result": True                       # 总体结果(bool)
+                }
+        """
+        import os
+
+        response_dict = {
+            "remote_pattern": remote_path,
+            "local_base": local_dir,
+            "downloaded_files": [],
+            "failed_files": [],
+            "result": True
+        }
+
+        try:
+            sftp = self.sftp_client
+            
+            # 获取所有匹配的远程文件路径
+            matched_files = self._pattern_remote_files(remote_path)
+            
+            # 遍历所有匹配的文件进行下载
+            for remote_file_path in matched_files:
+                try:
+                    # 计算目标本地路径
+                    if local_dir:
+                        local_file_path = os.path.join(local_dir, os.path.basename(remote_file_path))
+                    else:
+                        local_file_path = os.path.basename(remote_file_path)
+
+                    # 确保本地目录存在
+                    if local_dir and not os.path.exists(local_dir):
+                        os.makedirs(local_dir, exist_ok=True)
+
+                    # 执行下载
+                    sftp.get(remote_file_path, local_file_path)
+                    response_dict["downloaded_files"].append({
+                        "remote_path": remote_file_path,
+                        "local_path": local_file_path,
+                        "result": True
+                    })
+                    logger.info(f"文件下载成功: {remote_file_path} -> {local_file_path}")
+                    
+                except Exception as e:
+                    response_dict["failed_files"].append({
+                        "remote_path": remote_file_path,
+                        "local_path": local_file_path if 'local_file_path' in locals() else "",
+                        "error": str(e),
+                        "result": False
+                    })
+                    response_dict["result"] = False
+                    logger.error(f"文件下载失败: {remote_file_path}, 错误: {e}")
+
+        except Exception as e:
+            response_dict["result"] = False
+            response_dict["error"] = str(e)
+            logger.error(f"批量下载初始化失败: {e}")
+
+        return response_dict
+
+
+    def close(self):
+        """关闭SSH和SFTP连接"""
+        if self._sftp_client:
+            self._sftp_client.close()
+            self.sftp_connected = False
+
+
+
+

ginkgo_tools_batchssh/module_logger.py

@@ -0,0 +1,57 @@
+import uuid
+import datetime
+import os
+import logging
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+
+
+def setup_logging(console_level="INFO", file_level="DEBUG", log_dir="batch_record"):
+
+    """配置整个应用的日志系统"""
+    # 获取根记录器
+    root_logger = logging.getLogger()
+
+    # 避免重复添加处理器
+    # 也保证了在一次链式调用中，只会产生一个日志文件
+    if root_logger.handlers:
+        return
+
+    timestr = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
+    os.makedirs(log_dir, exist_ok=True)
+    log_path = os.path.join(log_dir, f'batch-{timestr}.log')
+
+    # 设置根记录器的级别为最低，确保消息能传递到处理器
+    level_dict = {
+        "INFO":logging.INFO,
+        "DEBUG":logging.DEBUG,
+        "WARNING":logging.WARNING,
+        "ERROR":logging.ERROR,
+        "CRITICAL":logging.CRITICAL
+    }
+    root_logger.setLevel(min(level_dict.get(console_level), level_dict.get(file_level)))
+
+    # 控制台输出日志，简化版本
+    console_formatter = logging.Formatter("%(levelname)s - %(name)s - %(message)s")
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(level_dict.get(console_level))
+    console_handler.setFormatter(console_formatter)
+    # 记录到文件的使用详细格式化的日志版本
+    file_formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(name)s - %(message)s")
+    file_handler = logging.FileHandler(log_path, mode='a', encoding='utf-8')
+    file_handler.setLevel(level_dict.get(file_level))
+    file_handler.setFormatter(file_formatter)
+
+    root_logger.addHandler(console_handler)
+    root_logger.addHandler(file_handler)
+
+    # 顺手关掉第三方库的日志
+    logging.getLogger("paramiko").setLevel(logging.CRITICAL)
+
+
+
+def get_logger(name):
+    """获取预配置的日志记录器"""
+    logger_instance = logging.getLogger(name)
+    # 根记录器已经配置，不需要额外配置
+    return logger_instance

ginkgo_tools_batchssh-0.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: ginkgo-tools-batchssh
+Version: 0.1.0
+Summary: 批量SSH操作和文件传输工具包
+Author-email: 霍城 <495466557@qq.com>
+Maintainer-email: 霍城 <495466557@qq.com>
+License: MIT
+Keywords: ssh,sftp,batch,automation,remote
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: paramiko>=2.7.0
+
+# GINKGO-TOOLS-BATCHSSH
+
+一个用于批量SSH操作和文件传输的Python工具包。
+
+## 功能特性
+
+- 🔧 **SSH连接管理** - 简化SSH连接建立和管理
+- ⚡ **远程命令执行** - 支持超时控制的远程命令执行
+- 📁 **SFTP文件传输** - 支持通配符的批量文件上传下载
+- 🎯 **批量主机操作** - 支持多主机并行操作
+- 📝 **智能日志系统** - 自动记录操作日志便于追踪
+- 🛠️ **便捷工具函数** - 提供常用的主机管理和过滤工具
+
+## 安装
+
+```bash
+pip install ginkgo_tools_batchssh
+```
+
+## 快速开始
+
+### 基本SSH连接和命令执行
+
+```python
+from ginkgo_tools_batchssh import SSHWrapper
+
+# 创建SSH连接
+ssh = SSHWrapper(
+    host_ip="192.168.1.100",
+    username="your_username",
+    password="your_password"
+)
+
+# 执行单个命令
+result = ssh.execute_command("ls -la")
+print(f"执行结果: {result['result']}")
+print(f"输出内容: {result['stdout']}")
+
+# 执行多个命令
+commands = ["cd /tmp", "pwd", "ls"]
+result = ssh.execute_shell_commands(commands)
+print(result['stdout'])
+```
+
+### 文件传输操作
+
+```python
+# 上传单个文件
+upload_result = ssh.sftp_upload_file("local_file.txt", "/remote/path/file.txt")
+
+# 批量上传文件（支持通配符）
+upload_result = ssh.sftp_upload_to("*.log", "/remote/logs/")
+
+# 下载文件
+download_result = ssh.sftp_download_file("/remote/file.txt", "local_file.txt")
+
+# 批量下载文件（支持通配符）
+download_result = ssh.sftp_download_to("/remote/logs/*.log", "./local_logs/")
+```
+
+### 主机管理工具
+
+```python
+from ginkgo_tools_batchssh import read_hosts_file, parse_and_filter_hosts
+
+# 读取hosts文件
+hosts_content = read_hosts_file()
+
+# 过滤和解析主机
+filter_list = ["web", "server"]  # 只选择包含这些关键词的主机
+target_hosts = parse_and_filter_hosts(hosts_content, filter_list)
+
+# target_hosts 格式: {"ip_address": ["hostname1", "hostname2"]}
+for ip, hostnames in target_hosts.items():
+    print(f"{ip}: {', '.join(hostnames)}")
+```
+
+## 核心组件
+
+### SSHWrapper 类
+
+主要的SSH操作类，提供以下核心功能：
+
+- `ssh_connect()` - 建立SSH连接
+- `execute_command()` - 执行单个命令
+- `execute_shell_commands()` - 执行多个命令
+- `sftp_upload_*()` - 文件上传相关方法
+- `sftp_download_*()` - 文件下载相关方法
+- `commands_to_shell_*()` - Shell脚本执行相关方法
+
+### 便捷工具函数
+
+- `read_hosts_file()` - 读取hosts文件内容
+- `parse_and_filter_hosts()` - 解析和过滤主机列表
+
+### 日志系统
+
+- `setup_logging()` - 配置日志系统
+- `get_logger()` - 获取日志记录器
+
+## 高级用法
+
+### 超时控制
+
+```python
+# 设置命令执行超时时间（秒）
+result = ssh.execute_command("sleep 60", timeout=30)
+if result['do_break']:
+    print("命令执行超时")
+```
+
+### Shell脚本执行
+
+```python
+# 将命令封装为shell脚本并执行
+commands = [
+    "echo '开始执行任务'",
+    "date",
+    "ls -la"
+]
+
+# 传输脚本文件
+trans_result = ssh.commands_to_shell_trans(command_list=commands)
+
+# 执行脚本（可选sudo切换用户）
+exec_result = ssh.commands_to_shell_run(trans_result, sudo_to_user="root")
+```
+
+### 批量主机操作示例
+
+```python
+from ginkgo_tools_batchssh import SSHWrapper, read_hosts_file, parse_and_filter_hosts
+
+# 获取目标主机列表
+hosts_content = read_hosts_file()
+target_hosts = parse_and_filter_hosts(hosts_content, ["production"])
+
+# 批量执行操作
+results = {}
+for ip, hostnames in target_hosts.items():
+    try:
+        ssh = SSHWrapper(
+            host_ip=ip,
+            username="admin",
+            password="password",
+            host_name=hostnames[0]
+        )
+        
+        result = ssh.execute_command("uptime")
+        results[ip] = result
+        
+        ssh.close()
+    except Exception as e:
+        results[ip] = {"result": False, "error": str(e)}
+
+# 查看结果
+for ip, result in results.items():
+    if result['result']:
+        print(f"{ip}: {result['stdout'].strip()}")
+    else:
+        print(f"{ip}: 执行失败 - {result.get('error', '未知错误')}")
+```
+
+## 返回值格式
+
+大多数方法返回统一的字典格式：
+
+```python
+{
+    "result": True/False,           # 操作是否成功
+    "stdout": "输出内容",            # 标准输出
+    "stderr": "错误内容",            # 错误输出
+    "exit_status": 0,               # 退出状态码
+    "error": "错误信息",             # 错误描述（失败时）
+    # 其他特定字段...
+}
+```
+
+## 依赖要求
+
+- Python >= 3.8
+- paramiko >= 2.7.0
+
+## 许可证
+
+MIT License
+
+## 作者
+
+霍城 <495466557@qq.com>
+
+---
+*注意：请根据实际使用场景调整连接参数和安全设置*

ginkgo_tools_batchssh-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ginkgo_tools_batchssh/__init__.py,sha256=S01AOuZJzGcIWh9XU_KL1xqHGh-xgmX44Rus8HwHGW4,1126
+ginkgo_tools_batchssh/moduel_convenient_tools.py,sha256=srhVAx43J8gl9RVK3ZYWolJ6HgPEi0claxgPZwRu-zU,1653
+ginkgo_tools_batchssh/module_SSHwrapper.py,sha256=-yJe7X7iKIyjsoAdowUoiGDNCtOn1z6ISXlrBgYb4ho,35597
+ginkgo_tools_batchssh/module_logger.py,sha256=SFnxCKgyFZmzUl3Tr7nMrNdEkiotjU2cN0oCTZEgWuo,2039
+ginkgo_tools_batchssh-0.1.0.dist-info/METADATA,sha256=MV52rpktac3X7vBpnZ35ex9lrIYOEaxe4ZpGdPEWO1Q,5938
+ginkgo_tools_batchssh-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ginkgo_tools_batchssh-0.1.0.dist-info/top_level.txt,sha256=LRf7tgGqGRB41Cit0RPETr5gjljt8IS2k5bl2SEPKxY,22
+ginkgo_tools_batchssh-0.1.0.dist-info/RECORD,,

ginkgo_tools_batchssh-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ginkgo_tools_batchssh-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ginkgo_tools_batchssh