標準 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, ...): ...
ftplib.FTP_TLS)此實現提供了生產可用的 FTP 目錄同步基礎,可直接集成至備份系統、部署流水線、數據遷移工具中。