什么是 Paramiko？

Paramiko 是一个纯 Python（版本 2.7, 3.4+）实现的 SSHv2 协议库，它允许你用 Python 代码来连接和操作远程服务器，就像在终端里使用 ssh, scp, sftp 一样,它的主要功能包括：

• 执行远程命令：在远程服务器上运行命令并获取输出。
• 文件传输：通过 SFTP 协议上传或下载文件。
• SSH 代理转发：处理复杂的认证场景。
• 端口转发：建立 SSH 隧道。

环境准备

在安装 paramiko 之前,请确保你的系统已经准备好：

• Python 环境：你的系统需要安装 Python，你可以通过在终端或命令提示符中运行 python --version 或 python3 --version 来检查。
• 包管理器：pip 是 Python 的标准包安装工具，通常与 Python 一起安装，你可以通过 pip --version 或 pip3 --version 来检查。

安装 Paramiko

安装 paramiko 非常简单，使用 pip 即可，打开你的终端（macOS/Linux）或命令提示符/PowerShell（Windows）,执行以下命令。

推荐方式（使用 pip3）

为了确保你安装的是为 Python 3 版本准备的包，建议始终使用 pip3。

pip3 install paramiko

通用方式（使用 pip）

如果你确定你的环境默认使用 Python 3，或者你只需要为 Python 2 安装，可以使用 pip。

pip install paramiko

使用国内镜像（加速下载）

如果你的网络访问 PyPI（Python Package Index）较慢，可以使用国内的镜像源（如阿里云、豆瓣等）来加速下载。

# 使用阿里云镜像
pip3 install paramiko -i https://mirrors.aliyun.com/pypi/simple/
# 使用豆瓣镜像
pip3 install paramiko -i https://pypi.douban.com/simple/

验证安装

安装完成后，你可以通过在 Python 解释器中导入 paramiko 来验证是否安装成功。

python3
>>> import paramiko
>>> print(paramiko.__version__)
# 如果没有报错，并输出版本号，说明安装成功。

按 Ctrl+D 或输入 exit() 退出 Python 解释器。

Paramiko 的基本使用

安装完成后，我们来看一个简单的例子,连接到一台远程服务器并执行一个命令。

import paramiko
# --- 1. 创建 SSHClient 对象 ---
ssh = paramiko.SSHClient()
# --- 2. 自动添加主机密钥（不推荐用于生产环境） ---
# 当连接到一台新的服务器时，它的主机密钥是未知的。
# 为了避免交互式提示，可以自动添加，这会带来安全风险（中间人攻击）。
ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
# --- 3. 连接服务器 ---
# 请替换为你的服务器信息
hostname = "your_server_ip_or_domain"
port = 22
username = "your_username"
password = "your_password" # 或者使用密钥认证
try:
    print(f"正在连接到 {hostname}...")
    ssh.connect(hostname, port=port, username=username, password=password)
    print("连接成功！")
    # --- 4. 执行远程命令 ---
    # 使用一个 with 语句可以确保命令执行后通道会自动关闭
    with ssh.open_sftp() as sftp:
        # 示例1：执行命令
        print("\n--- 执行命令 'ls -l' ---")
        stdin, stdout, stderr = ssh.exec_command('ls -l')
        # stdout 是标准输出，stderr 是标准错误
        # 读取输出
        print("标准输出:")
        print(stdout.read().decode('utf-8'))
        print("标准错误:")
        print(stderr.read().decode('utf-8'))
        # 示例2：通过 SFTP 上传文件
        print("\n--- 上传文件 'local.txt' 到远程服务器的 '/home/user/' ---")
        local_path = 'local.txt'
        remote_path = '/home/user/remote.txt'
        sftp.put(local_path, remote_path)
        print(f"文件 {local_path} 已成功上传到 {remote_path}")
        # 示例3：通过 SFTP 下载文件
        print("\n--- 下载远程文件 '/home/user/remote.txt' 到本地 ---")
        sftp.get(remote_path, 'downloaded_remote.txt')
        print(f"文件 {remote_path} 已成功下载到 downloaded_remote.txt")
except paramiko.AuthenticationException:
    print("认证失败，请检查用户名和密码。")
except paramiko.SSHException as e:
    print(f"SSH连接或命令执行出错: {e}")
except Exception as e:
    print(f"发生未知错误: {e}")
finally:
    # --- 5. 关闭连接 ---
    if ssh:
        ssh.close()
        print("\nSSH 连接已关闭。")

运行这个脚本前，请确保：

1. 你有一台可以访问的远程服务器（IP地址、用户名、密码）。
2. 在脚本中正确替换了 hostname, username, password。
3. 如果你想测试文件传输，在你的脚本所在目录创建一个名为 local.txt 的文件。

常见问题与解决方案 (FAQ)

Q1: pip install paramiko 失败，提示 ERROR: Could not build wheels for paramiko

原因分析： 这通常发生在 Windows 系统上。paramiko 的某些依赖（如 cryptography）在编译时需要一个 C 编译器（如 Visual C++ Build Tools）。pip 无法找到它,因此编译失败。

解决方案：

1. 安装 Microsoft C++ Build Tools：

   • 访问 Visual Studio 下载页面。
   • 下载 "Build Tools for Visual Studio"。
   • 运行安装程序，在 "工作负载" 选项卡中，勾选 “使用 C++ 的桌面开发”。
   • 安装完成后，重启你的终端或 IDE，再尝试 pip install。

2. 使用预编译的二进制包： 更简单的方法是安装 wheel 包，pip 会优先下载预编译好的 .whl 文件,从而避免本地编译。

   pip3 install wheel
   pip3 install paramiko

Q2: 如何使用 SSH 密钥进行认证，而不是密码？

使用密钥认证更安全,也是自动化脚本的首选方式。

import paramiko
ssh = paramiko.SSHClient()
ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
# --- 准备密钥 ---
# 方式A：从文件加载私钥
private_key_path = '/path/to/your/private_key' # ~/.ssh/id_rsa
private_key = paramiko.RSAKey.from_private_key_file(private_key_path)
# 方式B：如果私钥有密码
# private_key = paramiko.RSAKey.from_private_key_file(private_key_path, password='your_key_password')
try:
    # --- 连接时传入密钥 ---
    ssh.connect(hostname="your_server_ip", 
                username="your_username", 
                pkey=private_key) # 注意这里是 pkey 参数
    # ... 执行命令 ...
    stdin, stdout, stderr = ssh.exec_command('echo "Hello from key auth!"')
    print(stdout.read().decode())
    ssh.close()
except Exception as e:
    print(f"Error: {e}")

Q3: ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy()) 有什么风险？

这个方法会自动接受并保存任何未知服务器的 SSH 主机密钥，这会使得你的脚本容易受到中间人攻击，攻击者可以伪装成你的目标服务器,而你的脚本会毫无防备地连接过去。

安全替代方案（推荐用于生产环境）：

在连接前，先从已知的服务器获取其主机密钥,并进行验证。

import paramiko
# 1. 首先通过非 SSH 方式（如 DNS 或可信来源）获取服务器的公钥指纹
#    或者，你可以在第一次连接时手动记录下它的公钥
#    ssh-keyscan your_server_ip >> ~/.ssh/known_hosts
# 2. 在脚本中加载 known_hosts 文件
known_hosts_file = os.path.expanduser('~/.ssh/known_hosts')
# 3. 创建一个策略，该策略会检查 known_hosts 文件
policy = paramiko.RejectPolicy() # 初始设置为拒绝所有
# 或者加载已有的 known_hosts
# host_keys = paramiko.HostKeys(filename=known_hosts_file)
ssh = paramiko.SSHClient()
# 使用一个更安全的策略
ssh.load_host_keys(filename=known_hosts_file) 
# 如果服务器不在 known_hosts 中，连接会失败，这是安全的
try:
    ssh.connect(hostname="your_server_ip", username="your_username", password="your_password")
    # ... 正常执行 ...
    print("连接成功！")
except paramiko.SSHException as e:
    print(f"连接失败: {e}")
    print("请确保服务器的主机密钥已添加到 known_hosts 文件中。")
finally:
    ssh.close()

希望这份详细的指南能帮助你顺利安装和使用 paramiko！