5分钟上手sshtunnel：Python实现SSH端口转发的简单方法

史霁蔷Primrose

679人浏览 · 2026-03-05 02:01:47

史霁蔷Primrose · 2026-03-05 02:01:47 发布

5分钟上手sshtunnel：Python实现SSH端口转发的简单方法

【免费下载链接】sshtunnel SSH tunnels to remote server. 项目地址: https://gitcode.com/gh_mirrors/ss/sshtunnel

sshtunnel是一个轻量级Python库，让开发者和系统管理员能够轻松创建安全的SSH端口转发隧道。无论是本地开发调试远程服务，还是安全访问内网资源，这个工具都能帮你快速建立加密连接，无需复杂的命令行配置。

🚀 为什么选择sshtunnel？

在现代开发和运维工作中，我们经常需要访问位于防火墙后的服务器资源。传统SSH命令虽然功能强大，但复杂的端口转发语法常常让新手望而却步。sshtunnel通过Python API封装了这些复杂操作，让你用几行代码就能实现安全的端口转发。

核心优势：

简单易用：Python接口直观，无需记忆复杂的SSH命令参数
跨平台兼容：完美支持Linux、Windows和macOS系统
安全可靠：基于OpenSSH协议，确保数据传输加密
灵活配置：支持本地端口转发、远程端口转发和动态端口转发

📦 快速安装指南

安装sshtunnel只需一个简单的pip命令：

pip install sshtunnel

如果你需要从源码安装最新开发版本，可以克隆仓库后手动安装：

git clone https://gitcode.com/gh_mirrors/ss/sshtunnel
cd sshtunnel
python setup.py install

项目的安装配置文件位于setup.py，依赖管理通过pyproject.toml和setup.cfg实现，确保了安装过程的稳定性和兼容性。

🔧 基础使用示例

本地端口转发

最常见的使用场景是将本地端口转发到远程服务器，以下是一个简单示例：

from sshtunnel import SSHTunnelForwarder

with SSHTunnelForwarder(
    ('remote.server.com', 22),
    ssh_username='your_username',
    ssh_password='your_password',
    remote_bind_address=('127.0.0.1', 3306),
    local_bind_address=('127.0.0.1', 3307)
) as tunnel:
    print(f"隧道已建立，本地端口: {tunnel.local_bind_port}")
    # 现在可以通过 localhost:3307 访问远程服务器的3306端口了
    input("按Enter键关闭隧道...")

这段代码创建了一个安全隧道，将本地3307端口转发到远程服务器的3306端口（通常是MySQL数据库服务）。

使用SSH密钥认证

为了提高安全性，建议使用SSH密钥认证而非密码：

with SSHTunnelForwarder(
    ('remote.server.com', 22),
    ssh_username='your_username',
    ssh_pkey='/path/to/private/key',
    ssh_private_key_password='key_password',  # 如果密钥有密码
    remote_bind_address=('127.0.0.1', 5432),
    local_bind_address=('0.0.0.0', 5432)  # 允许外部访问
) as tunnel:
    print(f"PostgreSQL隧道已建立在端口 {tunnel.local_bind_port}")
    # 连接到 localhost:5432 即可访问远程PostgreSQL数据库

⚙️ 高级配置选项

sshtunnel提供了丰富的配置选项，满足各种复杂场景需求：

远程端口转发

将远程服务器端口转发到本地网络：

with SSHTunnelForwarder(
    ('remote.server.com', 22),
    ssh_username='your_username',
    ssh_pkey='/path/to/key',
    remote_bind_address=('local.service.com', 8080),
    local_bind_address=('0.0.0.0', 8080),
    reverse=True  # 启用远程端口转发
) as tunnel:
    print(f"远程端口转发已启用: {tunnel.local_bind_port}")

多端口转发

同时转发多个端口：

with SSHTunnelForwarder(
    ('remote.server.com', 22),
    ssh_username='your_username',
    ssh_pkey='/path/to/key',
    remote_bind_addresses=[
        ('127.0.0.1', 3306),  # MySQL
        ('127.0.0.1', 6379),  # Redis
        ('127.0.0.1', 5432)   # PostgreSQL
    ],
    local_bind_addresses=[
        ('127.0.0.1', 3307),
        ('127.0.0.1', 6380),
        ('127.0.0.1', 5433)
    ]
) as tunnel:
    print("多端口隧道已建立")
    for local_port in tunnel.local_bind_ports:
        print(f"本地端口: {local_port}")

🧪 测试与验证

项目提供了完整的测试套件，位于tests/目录下。你可以通过运行测试来验证sshtunnel的功能：

pytest tests/

对于更复杂的场景测试，可以参考e2e_tests/目录下的端到端测试脚本，如run_docker_e2e_db_tests.py和run_docker_e2e_hangs_tests.py。

📚 学习资源与文档

完整官方文档：项目的docs/目录包含详细的使用说明和API文档
配置示例：通过查看test_forwarder.py了解更多使用场景
故障排除：遇到问题时，可以参考Troubleshoot.rst文档

💡 使用技巧与最佳实践

连接池管理：对于频繁创建隧道的场景，考虑复用SSH连接以提高性能
日志配置：通过设置logger参数启用详细日志，便于调试
超时设置：合理设置ssh_timeout和request_timeout参数，避免连接挂起
异常处理：使用try-except块捕获可能的连接错误，确保程序健壮性

try:
    with SSHTunnelForwarder(
        ('remote.server.com', 22),
        ssh_username='your_username',
        ssh_pkey='/path/to/key',
        remote_bind_address=('127.0.0.1', 3306),
        local_bind_address=('127.0.0.1', 3307),
        ssh_timeout=10.0,
        request_timeout=10.0
    ) as tunnel:
        print("隧道连接成功")
except Exception as e:
    print(f"隧道连接失败: {str(e)}")