Paramiko 是一个强大的、纯 Python 实现的 SSHv2 协议库，它让你能够用 Python 代码来执行远程服务器的命令、传输文件（SFTP）等，而无需在本地系统上安装 SSH 客户端。
安装 Paramiko
安装 paramiko 非常简单，主要使用 Python 的包管理工具 pip。
环境准备
请确保你的系统已经安装了 Python，你可以在终端或命令提示符中运行以下命令来检查：
python --version # 或者 python3 --version
如果已经安装,它会显示你的 Python 版本，确保 pip 也已安装：
pip --version # 或者 pip3 --version
pip 没有安装，通常在安装 Python 时会一并安装，如果没有，可以参考 pip 官方安装指南 进行安装。
使用 pip 安装
打开你的终端（在 Windows 上是 Command Prompt 或 PowerShell，在 macOS/Linux 上是 Terminal），然后运行以下命令：
pip install paramiko
如果你使用的是 Python 3，并且你的系统同时有 Python 2 和 Python 3，建议使用 pip3 来确保安装到正确的 Python 环境中：
pip3 install paramiko
安装完成后,你会看到类似 "Successfully installed paramiko-xxx" 的提示信息，这表示安装成功。
验证安装
为了验证 paramiko 是否已正确安装，你可以在 Python 解释器中尝试导入它：
python >>> import paramiko >>> print(paramiko.__version__) # 如果没有报错，并输出版本号，说明安装成功。
或者在终端中直接运行：
python -c "import paramiko; print(paramiko.__version__)"
基本使用示例
安装完成后,我们来看几个 paramiko 最常用的基本示例。
示例 1：执行远程命令
这是最常见的用法,连接到远程服务器并执行一条命令，然后获取输出。
import paramiko
import sys
# --- 1. 创建 SSHClient 实例 ---
ssh = paramiko.SSHClient()
# --- 2. 自动添加主机密钥（不推荐在生产环境中使用） ---
# 第一次连接时，目标主机的密钥不在本地的 known_hosts 文件中，
# 连接会失败，这个调用会自动添加，但存在安全风险。
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. 执行命令 ---
command = "ls -l" # 示例：列出当前目录的文件
print(f"正在执行命令: {command}")
# stdin, stdout, stderr 分别是标准输入、标准输出和标准错误流
stdin, stdout, stderr = ssh.exec_command(command)
# 获取命令的输出
output = stdout.read().decode('utf-8')
error = stderr.read().decode('utf-8')
if error:
print(f"命令执行出错:\n{error}")
else:
print("命令执行成功，输出如下:")
print(output)
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("连接已关闭。")
示例 2：使用 SSH 密钥进行认证（更安全）
在生产环境中,强烈推荐使用 SSH 密钥而不是密码进行认证。
import paramiko
# --- 1. 创建 SSHClient 实例 ---
ssh = paramiko.SSHClient()
ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
# --- 2. 准备密钥 ---
# 假设你的私钥文件在 ~/.ssh/id_rsa
private_key_path = os.path.expanduser('~/.ssh/id_rsa') # 需要导入 os 模块
# --- 3. 连接服务器 ---
hostname = "your_server_ip_or_domain"
username = "your_username"
try:
# 使用密钥文件连接
ssh.connect(hostname, username=username, key_filename=private_key_path)
print("使用密钥连接成功！")
# --- 4. 执行命令 ---
stdin, stdout, stderr = ssh.exec_command("uname -a")
output = stdout.read().decode('utf-8')
print("系统信息:")
print(output)
except paramiko.AuthenticationException:
print("密钥认证失败，请检查密钥文件或是否将公钥添加到服务器。")
except Exception as e:
print(f"发生错误: {e}")
finally:
if ssh:
ssh.close()
print("连接已关闭。")
示例 3：使用 SFTP 传输文件
paramiko 也内置了 SFTP 客户端功能，可以方便地在本地和远程服务器之间传输文件。
import paramiko
import os
# --- 1. 连接服务器 (与之前相同) ---
hostname = "your_server_ip_or_domain"
username = "your_username"
password = "your_password" # 或使用密钥
try:
transport = paramiko.Transport((hostname, 22))
transport.connect(username=username, password=password)
# 创建 SFTP 客户端
sftp = paramiko.SFTPClient.from_transport(transport)
print("SFTP 连接成功！")
# --- 2. 上传文件 ---
local_path = "local_file.txt" # 本地文件路径
remote_path = "/home/username/remote_file.txt" # 远程路径
print(f"正在上传 {local_path} 到 {remote_path}...")
sftp.put(local_path, remote_path)
print("文件上传成功！")
# --- 3. 下载文件 ---
# remote_download_path = "/home/username/remote_file.txt"
# local_download_path = "downloaded_file.txt"
# print(f"正在从 {remote_download_path} 下载到 {local_download_path}...")
# sftp.get(remote_download_path, local_download_path)
# print("文件下载成功！")
except Exception as e:
print(f"SFTP 操作出错: {e}")
finally:
# --- 4. 关闭连接 ---
if sftp:
sftp.close()
if transport:
transport.close()
print("SFTP 连接已关闭。")
常见问题与解决方法
Q1: pip install paramiko 失败，提示 error: Microsoft Visual C++ 14.0 or greater is required。
原因：这通常发生在 Windows 系统上。paramiko 的一些依赖（如 cryptography）需要编译 C/C++ 扩展，而你的系统上没有安装相应的 C++ 编译器（如 Microsoft Visual C++ Build Tools）。
解决方法：
-
安装编译工具：
- 最简单的方法是安装 Microsoft C++ Build Tools。
- 在安装程序中,选择 "Desktop development with C++" 工作负载，然后安装。
- 安装完成后,再次运行
pip install paramiko。
-
使用预编译的二进制包（推荐）：
- 很多时候,
pip会自动从 PyPI 下载预编译好的.whl文件，避免本地编译，如果失败，可以尝试指定一个兼容的版本。 - 如果你使用 Python 3.8，可以尝试：
pip install paramiko --only-binary :all:
- 或者直接下载对应平台的
.whl文件（从 PyPI），然后使用pip install安装它。
- 很多时候,
Q2: 连接服务器时提示 paramiko.ssh_exception.SSHException: No existing session
原因：这通常发生在使用 Transport 对象时，在调用 connect() 之前就尝试执行了其他操作（如 exec_command）。
解决方法：确保在使用 exec_command 或创建 SFTPClient 之前，已经成功调用了 transport.connect()。
Q3: 连接时提示 paramiko.ssh_exception.AuthenticationException: Authentication failed.
原因：
- 用户名或密码错误。
- 如果使用密钥认证,可能是私钥文件路径错误、私钥密码错误（如果设置了），或者服务器的
~/.ssh/authorized_keys文件中没有添加你的公钥。
解决方法：
- 仔细核对用户名和密码。
- 确认私钥文件路径是否正确,并且有读取权限。
- 登录到服务器,检查
authorized_keys文件的内容是否与你的公钥匹配。
希望这份详细的指南能帮助你顺利安装和使用 paramiko！
