基于Paramiko的Python SFTP服务器连接超时问题求助

一、Subsystem Handler的正确用法 #

必须使用transport.set_subsystem_handler注册SFTP子系统，这是Paramiko实现SFTP服务的标准方式。SFTP属于SSH协议的子系统，只有通过该方法将自定义的SFTPServerInterface实现与sftp子系统绑定，客户端的SFTP请求才能被正确路由到你的处理逻辑。

如果注释的代码是尝试直接启动shell会话，会导致客户端的SFTP请求无法被识别，进而出现连接后无响应的情况。

二、卡顿超时的核心排查点 #

1. ServerInterface方法实现问题 #

ServerInterface的check_channel_request方法必须正确处理session类型请求，否则客户端无法建立有效会话：

class CustomServer(ServerInterface):
    def check_channel_request(self, kind, chanid):
        # 允许session类型请求，这是SFTP会话建立的前提
        if kind == "session":
            return OPEN_SUCCEEDED
        # 拒绝其他类型请求
        return OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED

若该方法返回错误值，客户端会卡在会话初始化阶段，最终超时。

2. SFTPServerInterface方法实现不全 #

客户端卡住通常是因为某个SFTP命令（如OPENDIR、LIST）未得到正确响应，需确保以下核心方法正确实现：

• listdir: 返回指定目录下的文件列表，需处理路径拼接和权限检查
• stat: 返回文件/目录的属性信息，需正确构造SFTPAttributes对象
• readdir: 配合listdir返回目录内容，不能抛出未捕获的异常
• realpath: 处理路径解析，确保返回基于ROOT_FOLDER的绝对路径，同时防范路径遍历攻击

示例实现片段：

class CustomSFTP(SFTPServerInterface):
    def __init__(self, server, root_folder):
        self.root_folder = os.path.abspath(root_folder)
        super().__init__(server)

    def realpath(self, path):
        resolved = os.path.abspath(os.path.join(self.root_folder, path.lstrip('/')))
        if not resolved.startswith(self.root_folder):
            raise SFTPError(EPERM, "Permission denied")
        return resolved

    def listdir(self, path):
        real_path = self.realpath(path)
        if not os.path.isdir(real_path):
            raise SFTPError(ENOENT, "No such directory")
        return os.listdir(real_path)

3. 权限与路径问题 #

• 确保ROOT_FOLDER是绝对路径，且运行服务器的进程对该目录有读写权限
• 检查路径处理逻辑，防止因相对路径错误导致文件/目录无法访问

4. 日志分析重点 #

从你提供的日志中需关注：

• Paramiko日志中是否有Exception或Error级别的信息，尤其是SFTP方法执行时的报错
• WinSCP/FileZilla日志中最后执行的SFTP命令（如LIST），对应排查该命令的处理方法是否存在问题

三、调试建议 #

• 在SFTPServerInterface的每个核心方法中添加日志输出，记录客户端请求的路径和方法执行结果，定位卡住的具体步骤
• 使用Paramiko自带的SFTP客户端测试连接，代码示例：

import paramiko

client = paramiko.SSHClient()
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
client.connect('localhost', port=2222, username='test', password='test')
sftp = client.open_sftp()
print(sftp.listdir('/'))
sftp.close()
client.close()

这种方式能获取更直接的报错信息，比GUI客户端更容易定位问题

内容的提问来源于stack exchange，提问作者MagoLione