萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

Python FTP 目錄遞歸上傳下載:支援斷點續傳的完整實現

需求分析

標準 ftplib 僅提供單文件操作,實際項目常需遞歸同步整個目錄樹,且需處理斷點續傳、權限錯誤、編碼、符號鏈接等工程化問題。

核心類設計


import ftplib
import os
import sys
from typing import Optional, Callable

class FTPDirectorySync:
    def __init__(self, host: str, port: int = 21, user: str = '', passwd: str = '', 
                 passive: bool = True, encoding: str = 'utf-8', timeout: int = 30):
        self.ftp = ftplib.FTP()
        self.ftp.connect(host, port, timeout=timeout)
        self.ftp.login(user, passwd)
        self.ftp.set_pasv(passive)
        self.ftp.encoding = encoding
        self._progress_callback: Optional[Callable] = None
    
    def set_progress_callback(self, callback: Callable[[str, int, int], None]):
        """進度回調: callback(filename, transferred, total)"""
        self._progress_callback = callback
    
    def close(self):
        try:
            self.ftp.quit()
        except:
            self.ftp.close()
    
    def __enter__(self):
        return self
    
    def __exit__(self, *args):
        self.close()

目錄判斷與列表獲取


    def _is_remote_dir(self, path: str) -> bool:
        """判斷遠程路徑是否為目錄 (兼容無 MLSD 服務器)"""
        try:
            # 優先使用 MLSD (機器可解析)
            self.ftp.sendcmd('OPTS MLST type;perm;size;modify')
            facts = dict(self.ftp.mlsd(path))
            return facts.get('type') == 'dir'
        except ftplib.error_perm:
            # 回退:嘗試 CWD
            try:
                cwd = self.ftp.pwd()
                self.ftp.cwd(path)
                self.ftp.cwd(cwd)
                return True
            except ftplib.error_perm:
                return False
    
    def _list_remote_dir(self, path: str) -> list:
        """獲取目錄條目列表 [(name, facts), ...]"""
        self.ftp.cwd(path)
        try:
            return list(self.ftp.mlsd())
        except ftplib.error_perm:
            # 回退 NLST (僅名稱)
            names = self.ftp.nlst()
            return [(n, {'type': 'file'}) for n in names]

斷點續傳核心邏輯


    def _download_with_resume(self, remote_path: str, local_path: str, blocksize: int = 8192):
        local_size = os.path.getsize(local_path) if os.path.exists(local_path) else 0
        
        try:
            remote_size = self.ftp.size(remote_path)
        except ftplib.error_perm:
            raise FileNotFoundError(f"Remote file not found: {remote_path}")
        
        if local_size >= remote_size:
            return
        
        # 設置斷點
        self.ftp.voidcmd(f'REST {local_size}')
        
        mode = 'ab' if local_size > 0 else 'wb'
        with open(local_path, mode) as f:
            def callback(data):
                f.write(data)
                if self._progress_callback:
                    local_size += len(data)
                    self._progress_callback(remote_path, local_size, remote_size)
            
            self.ftp.retrbinary(f'RETR {remote_path}', callback, blocksize=blocksize, rest=local_size)
    
    def _upload_with_resume(self, local_path: str, remote_path: str, blocksize: int = 8192):
        local_size = os.path.getsize(local_path)
        
        try:
            remote_size = self.ftp.size(remote_path)
        except ftplib.error_perm:
            remote_size = 0
        
        if remote_size >= local_size:
            return
        
        with open(local_path, 'rb') as f:
            f.seek(remote_size)
            self.ftp.voidcmd(f'REST {remote_size}')
            
            def callback(data):
                if self._progress_callback:
                    remote_size += len(data)
                    self._progress_callback(remote_path, remote_size, local_size)
            
            self.ftp.storbinary(f'APPE {remote_path}', f, blocksize=blocksize, callback=callback)

遞歸下載目錄


    def download_dir(self, remote_dir: str, local_dir: str = '.'):
        remote_dir = remote_dir.rstrip('/')
        os.makedirs(local_dir, exist_ok=True)
        
        self.ftp.cwd(remote_dir)
        entries = self._list_remote_dir('.')
        
        for name, facts in entries:
            if name in ('.', '..'):
                continue
                
            remote_path = f"{remote_dir}/{name}"
            local_path = os.path.join(local_dir, name)
            
            if facts.get('type') == 'dir':
                self.download_dir(remote_path, local_path)
            else:
                self._download_with_resume(remote_path, local_path)
        
        self.ftp.cwd('..')

遞歸上傳目錄


    def upload_dir(self, local_dir: str, remote_dir: str = '.'):
        remote_dir = remote_dir.rstrip('/')
        
        # 確保遠程目錄存在
        try:
            self.ftp.mkd(remote_dir)
        except ftplib.error_perm as e:
            if not e.args[0].startswith('550'):
                raise
        
        self.ftp.cwd(remote_dir)
        
        for name in os.listdir(local_dir):
            local_path = os.path.join(local_dir, name)
            remote_path = name
            
            if os.path.isdir(local_path):
                self.upload_dir(local_path, remote_path)
            else:
                self._upload_with_resume(local_path, remote_path)
        
        self.ftp.cwd('..')

進度回調示例


def progress_bar(filename: str, transferred: int, total: int):
    percent = transferred / total * 100 if total > 0 else 0
    bar_len = 30
    filled = int(bar_len * transferred / total) if total > 0 else 0
    bar = '█' * filled + '░' * (bar_len - filled)
    print(f"\r{filename[:30]:30s} [{bar}] {percent:5.1f}% ({transferred}/{total})", end='')
    if transferred >= total:
        print()

# 使用
with FTPDirectorySync('ftp.example.com', user='u', passwd='p') as ftp:
    ftp.set_progress_callback(progress_bar)
    ftp.upload_dir('./project', '/backup/project')
    ftp.download_dir('/backup/project', './restore')

錯誤處理與重試增強


import time
from functools import wraps

def ftp_retry(max_retries=3, base_delay=1.0):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except (ftplib.error_temp, ftplib.error_proto, ConnectionError, TimeoutError) as e:
                    if attempt == max_retries - 1:
                        raise
                    delay = base_delay * (2 ** attempt)
                    print(f"Retry {attempt+1}/{max_retries} after {delay}s: {e}")
                    time.sleep(delay)
            return func(*args, **kwargs)
        return wrapper
    return decorator

# 應用於關鍵方法
@ftp_retry()
def _download_with_resume(self, ...): ...

生產環境檢查清單

  • ✅ 被動模式 + 端口範圍配置 (防火牆)
  • ✅ UTF-8 編碼支援中文路徑
  • ✅ 斷點續傳 (REST/APPE)
  • ✅ 遞歸目錄同步
  • ✅ 進度回調 / 日誌記錄
  • ✅ 指數退避重試
  • ✅ 上下文管理器自動清理連接
  • ⚠️ TLS/SSL 加密 (需 ftplib.FTP_TLS)
  • ⚠️ 大文件分片並行傳輸 (需多連接)

此實現提供了生產可用的 FTP 目錄同步基礎,可直接集成至備份系統、部署流水線、數據遷移工具中。

copyright © 萬盛學電腦網 all rights reserved