簡介面向Java開發(fā)者的FTP文件傳輸學(xué)習(xí)包圍繞從服務(wù)器上傳與下載文件的常見需求梳理連接建立、登錄驗(yàn)證、主動(dòng)/被動(dòng)模式切換、目錄操作、二進(jìn)制傳輸、文件收發(fā)及斷開清理等核心環(huán)節(jié)。壓縮包共2個(gè)文件以1個(gè)Java源碼和1個(gè)jar依賴庫為主整體約106KB源碼可用于對(duì)照理解FTPClient調(diào)用流程jar依賴便于直接補(bǔ)齊運(yùn)行環(huán)境適合在本地搭建小型FTP客戶端示例并調(diào)試。已有251人學(xué)習(xí)下載說明該主題在Java網(wǎng)絡(luò)編程入門與日常運(yùn)維腳本場景中具有一定參考需求。讀者可從中獲得一套可運(yùn)行的FTP操作代碼骨架結(jié)合異常捕獲、傳輸模式設(shè)置與資源釋放等細(xì)節(jié)快速定位上傳下載失敗、目錄切換異?；蜻B接未關(guān)閉等問題并在此基礎(chǔ)上擴(kuò)展超時(shí)控制、重試機(jī)制與安全傳輸配置形成適合自身業(yè)務(wù)的文件傳輸工具。1. FTP 上傳下載文件這件事老協(xié)議為什么還壓在生產(chǎn)線上「FTP 上傳下載文件」聽著像是上個(gè)時(shí)代的活但真正在機(jī)房待過的人都知道它離消失還早得很。我最近一次和它打交道是個(gè)凌晨跑完不對(duì)賬的定時(shí)任務(wù)控制連接一切正常登錄成功、命令一條條返回 226可目標(biāo)目錄里就是少了一個(gè)包。后來定位到是數(shù)據(jù)連接被中間的防火墻掐了日志干凈得像沒事發(fā)生——這種「看起來很成功」的失敗是 FTP 最典型的一面。這份資源要解決的就是繞不開 FTP 的那幾類活老設(shè)備只肯吐 FTP、外部對(duì)接方只給一個(gè)賬號(hào)密碼、內(nèi)網(wǎng)機(jī)器之間搬運(yùn)日志和備份包、需要按天做增量同步。新手可以照著腳本跑通第一次上傳和下載熟手更該盯住它的邊界——兩條獨(dú)立連接、被動(dòng)模式的端口區(qū)間、文件名編碼、斷點(diǎn)續(xù)傳的偏移量每一項(xiàng)都能讓你在半夜被叫起來。下面按「先看懂模型、再動(dòng)手寫腳本、最后把坑挖出來」的順序往下走。2. 兩條連接與兩種模式通信模型里最容易配錯(cuò)的三處FTP 和 HTTP 最大的差別在于它一次會(huì)話要開兩條 TCP 連接而且這兩條連接的建立方向可以反過來。很多人腳本寫得沒問題、賬號(hào)密碼也沒錯(cuò)最后卡在 425 或者「列表能拿到但文件傳不動(dòng)」根子都在這一層。這一章把連接結(jié)構(gòu)、主動(dòng)被動(dòng)模式、傳輸類型與編碼三件事拆開配一段可以直接跑的探測代碼先把鏈路摸清楚再談上傳下載。2.1 控制連接與數(shù)據(jù)連接是兩套東西控制連接固定連服務(wù)器的 21 端口明文 FTP 的默認(rèn)端口實(shí)際部署也可能改成別的整個(gè)會(huì)話期間一直保持所有命令和響應(yīng)都以文本行的形式在這條通道上走USER、PASS 完成認(rèn)證CWD 切目錄PWD 看當(dāng)前位置TYPE 設(shè)傳輸類型PASV 協(xié)商數(shù)據(jù)通道。你看到的220、230、250、226這些三位數(shù)字碼全是控制連接在說話。數(shù)據(jù)連接是臨時(shí)的只在實(shí)際傳文件或者列目錄的那一小段時(shí)間里存在。LIST、NLST、MLSD、RETR、STOR這些命令才會(huì)觸發(fā)數(shù)據(jù)連接傳完立刻關(guān)閉。問題在于這條數(shù)據(jù)連接由誰來發(fā)起、連到哪個(gè)端口是可以變的——這就是主動(dòng)模式和被動(dòng)模式的差別。理解這一點(diǎn)的實(shí)際價(jià)值在于控制連接通、數(shù)據(jù)連接不通是完全可能的。防火墻、NAT 網(wǎng)關(guān)、容器網(wǎng)絡(luò)策略任何一個(gè)環(huán)節(jié)都可能只管住數(shù)據(jù)連接那一側(cè)。我一般會(huì)先用一段最小的探測代碼把歡迎語、當(dāng)前目錄、文件列表和傳輸類型都打出來判斷到底是哪條腿瘸了。from ftplib import FTP, error_perm ftp FTP() # 編碼必須先設(shè)很多老服務(wù)器回包是 GBK不設(shè)會(huì)直接拋 UnicodeDecodeError ftp.encoding utf-8 ftp.set_debuglevel(2) # 2 會(huì)把收發(fā)的每條命令打印出來排錯(cuò)時(shí)非常有用 ftp.connect(ftp.example.com, 21, timeout15) ftp.login(demo_user, demo_pass) print(歡迎語:, ftp.getwelcome()) print(當(dāng)前目錄:, ftp.pwd()) # TYPE I 表示二進(jìn)制傳輸避免服務(wù)器做換行符轉(zhuǎn)換 print(TYPE 響應(yīng):, ftp.sendcmd(TYPE I)) print(目錄列表:, ftp.nlst(.)[:10]) # 只取前 10 條防止目錄太大刷屏 ftp.quit()這段代碼的價(jià)值不在功能而在診斷。set_debuglevel(2)會(huì)把-- PASV和-- 227 Entering Passive Mode (...)這類交互原樣打出來你能直接看到服務(wù)器返回的被動(dòng)端口是不是落在了防火墻放行的區(qū)間里。nlst是一次典型的數(shù)據(jù)連接操作如果它拋TimeoutError或者ConnectionRefusedError而前面pwd明明返回正常那基本可以確診為數(shù)據(jù)通道被攔。參數(shù)上要留意三處encoding建議先按服務(wù)器實(shí)際情況選utf-8或gbk拿不準(zhǔn)就兩種都試timeout不要設(shè)成默認(rèn)的None卡死的連接會(huì)讓整個(gè)腳本掛在那里不動(dòng)15 到 30 秒是個(gè)合理區(qū)間set_debuglevel只在排錯(cuò)時(shí)開生產(chǎn)腳本里關(guān)掉否則日志會(huì)被撐爆。2.2 主動(dòng)模式與被動(dòng)模式425 多半出在這里主動(dòng)模式PORT的流程是反的客戶端用 PORT 命令告訴服務(wù)器「你來連我的這個(gè) IP 和端口」然后服務(wù)器從自己的 20 端口主動(dòng)向客戶端發(fā)起數(shù)據(jù)連接。這在沒有 NAT 的年代很高效但在今天幾乎必然出事——客戶端躲在 NAT 后面時(shí)報(bào)給服務(wù)器的私網(wǎng) IP 服務(wù)器根本連不上或者客戶端本機(jī)的防火墻根本不接受外部主動(dòng)連入。被動(dòng)模式PASV把方向掰了回來客戶端發(fā) PASV服務(wù)器回一個(gè)227 Entering Passive Mode (h1,h2,h3,h4,p1,p2)里面是服務(wù)器開放的臨時(shí)端口客戶端主動(dòng)去連。Python 的 ftplib 默認(rèn)就是被動(dòng)模式set_pasv(True)這也是絕大多數(shù)場景該用的模式。但被動(dòng)模式有自己的坑服務(wù)器開放的是一段隨機(jī)端口區(qū)間常見做法是在服務(wù)端配置里把區(qū)間固定下來比如 50000 到 50100然后在防火墻和云安全組里把這段放行。區(qū)間不固定的話你永遠(yuǎn)不知道下一次連接會(huì)撞到哪個(gè)被攔的端口。判斷方法很直接如果控制連接正常、PWD正常但一執(zhí)行LIST或RETR就報(bào) 425「Cant open data connection」先懷疑被動(dòng)端口區(qū)間沒放行如果腳本在本地開發(fā)機(jī)跑得好好的一上生產(chǎn)服務(wù)器就掛八成是生產(chǎn)機(jī)的出網(wǎng)策略只放了 21 端口。from ftplib import FTP ftp FTP() ftp.encoding utf-8 ftp.connect(ftp.example.com, 21, timeout20) ftp.login(demo_user, demo_pass) # 顯式聲明使用被動(dòng)模式等價(jià)于發(fā)送 PASV 命令 ftp.set_pasv(True) # 手動(dòng)發(fā)一次 PASV看看服務(wù)器到底回了哪個(gè) IP 和端口 resp ftp.sendcmd(PASV) print(PASV 響應(yīng):, resp) # 227 Entering Passive Mode (10,0,0,5,195,80) ftp.quit()把195,80這兩個(gè)數(shù)換算一下195 * 256 80 50000這就是服務(wù)器讓你去連的端口。這段換算值得記住因?yàn)榕耪蠒r(shí)運(yùn)維只問你「卡在哪個(gè)端口」你答得出來就能省半小時(shí)。如果這個(gè)端口落在安全組放行范圍之外解決辦法有兩個(gè)讓服務(wù)端把pasv_min_port/pasv_max_port固定成一段連續(xù)區(qū)間并放行或者臨時(shí)切到主動(dòng)模式驗(yàn)證——但主動(dòng)模式只能作為定位手段不能作為長期方案尤其是在容器和云主機(jī)上。2.3 傳輸類型與文件名編碼看不見的破壞力TYPE命令決定數(shù)據(jù)連接上怎么解釋字節(jié)。TYPE AASCII會(huì)讓服務(wù)器在傳輸過程中做換行符轉(zhuǎn)換TYPE IIMAGE/Binary則原樣搬運(yùn)。這兩個(gè)選錯(cuò)了后果是靜默的傳一個(gè)壓縮包用 ASCII 模式大小可能差幾十個(gè)字節(jié)解壓直接報(bào)損壞傳一個(gè) shell 腳本用二進(jìn)制模式到了對(duì)端可能因?yàn)閾Q行符不對(duì)而執(zhí)行失敗。我的習(xí)慣是無腦TYPE I然后在需要的地方自己處理換行。ftplib 的storbinary和retrbinary默認(rèn)就走二進(jìn)制這一點(diǎn)比裸寫 socket 省心但如果你的腳本混用了storlines那就要清楚它是按行讀寫的適合純文本且你確認(rèn)對(duì)端接受當(dāng)前換行風(fēng)格。編碼是第二個(gè)隱形殺手。FTP 協(xié)議早期是純 ASCII 的中文文件名怎么表示完全看服務(wù)器實(shí)現(xiàn)。常見的兩種做法是在登錄后發(fā)OPTS UTF8 ON聲明使用 UTF-8或者干脆用服務(wù)器本地的 GBK。ftplib 的encoding屬性必須和服務(wù)器一致否則你上傳時(shí)文件名是對(duì)的nlst列出來卻是一串亂碼后面按名字下載全部失敗。from ftplib import FTP, error_perm ftp FTP() ftp.encoding utf-8 ftp.connect(ftp.example.com, 21, timeout20) ftp.login(demo_user, demo_pass) # 嘗試開啟 UTF-8 模式服務(wù)器不支持會(huì)拋 500/502忽略即可 try: print(ftp.sendcmd(OPTS UTF8 ON)) except error_perm as e: print(服務(wù)器不支持 UTF8 選項(xiàng):, e) ftp.set_pasv(True) ftp.sendcmd(TYPE I) # 二進(jìn)制傳輸壓縮包、圖片、數(shù)據(jù)庫備份都必須用這個(gè) # 用 MLSD 拿結(jié)構(gòu)化列表能同時(shí)得到文件名、大小和修改時(shí)間 for name, facts in ftp.mlsd(/, facts[type, size, modify]): print(name, facts) ftp.quit()MLSD比LIST和NLST都好用因?yàn)樗祷氐氖菣C(jī)器可解析的鍵值對(duì)size和modify直接能拿來做增量判斷不用再去正則匹配ls -l格式的字符串?？上Р皇撬欣戏?wù)器都支持遇到500 Unknown command就退回NLST加SIZE命令組合。如果mlsd拋出的文件名是亂碼把encoding換成gbk再試一遍這是我遇到中文名問題時(shí)固定的第一步。3. ftplib 落地上傳、下載、遞歸拉目錄的四段可抄代碼模型清楚之后剩下的就是把動(dòng)作固化成函數(shù)。這一章的四段代碼對(duì)應(yīng)四種最常見的活穩(wěn)定連接、上傳帶進(jìn)度、下載并保留目錄結(jié)構(gòu)、傳完做校驗(yàn)。每一段都可以單獨(dú)摳出來用也可以拼成一個(gè)腳本。我一般會(huì)把連接參數(shù)抽到配置里認(rèn)證信息走環(huán)境變量避免密碼硬編碼在倉庫里——這條不是潔癖是審計(jì)要求。3.1 連接骨架超時(shí)、重連與環(huán)境變量生產(chǎn)腳本和演示腳本最大的差別是容錯(cuò)。FTP 服務(wù)器的空閑超時(shí)往往設(shè)在 300 秒左右一個(gè)跑批腳本如果中間有長時(shí)間的本地處理再回來發(fā)命令就可能收到421 Timeout然后控制連接被服務(wù)端關(guān)掉。這時(shí)候繼續(xù)用同一個(gè)連接對(duì)象發(fā)命令必然報(bào)error_temp或者直接EOFError。解決辦法是把「拿連接」封裝成函數(shù)每次用之前判斷連接是否還活著不活就重連。ftp.voidcmd(NOOP)是最輕量的探活方式服務(wù)器回200就說明通道還在。import os from ftplib import FTP, all_errors def get_ftp(host, timeout20): ftp FTP() ftp.encoding utf-8 ftp.connect(host, 21, timeouttimeout) # 認(rèn)證信息從環(huán)境變量讀不要寫死在代碼里 ftp.login(os.environ[FTP_USER], os.environ[FTP_PASS]) ftp.set_pasv(True) ftp.sendcmd(TYPE I) return ftp def ensure_alive(ftp, host): try: ftp.voidcmd(NOOP) # 探活成功返回 200 return ftp except all_errors: try: ftp.close() except Exception: pass return get_ftp(host)all_errors是 ftplib 提供的異常元組把error_reply、error_temp、error_perm、error_proto和OSError都包了進(jìn)去捕它比逐個(gè)列異常省事。ensure_alive的寫法看起來有點(diǎn)粗暴——連接斷了就整個(gè)重建——但在批量任務(wù)里這是最省心的策略因?yàn)?FTP 的連接狀態(tài)很難恢復(fù)到「干凈」的狀態(tài)重建比修復(fù)便宜。要提醒一點(diǎn)connect的timeout和login之后的數(shù)據(jù)傳輸超時(shí)是兩個(gè)概念。socket層面的超時(shí)由connect傳入的timeout控制會(huì)作用到之后所有的 socket 操作上。如果你的網(wǎng)絡(luò)抖動(dòng)厲害把它設(shè)到 20 到 30 秒如果鏈路很穩(wěn)但要傳大文件設(shè)太小會(huì)在傳輸中途觸發(fā)超時(shí)那時(shí)候就只能靠斷點(diǎn)續(xù)傳來救代價(jià)更大。3.2 上傳storbinary 的回調(diào)與進(jìn)度統(tǒng)計(jì)上傳的核心是storbinary(cmd, fp, blocksize8192, callbackNone, restNone)。第一個(gè)參數(shù)是命令字符串通常是STOR 遠(yuǎn)程文件名第二個(gè)是打開的文件對(duì)象必須是二進(jìn)制模式blocksize決定每次從本地讀多少字節(jié)往 socket 里寫默認(rèn) 8192內(nèi)網(wǎng)可以調(diào)到 65536 提速跨公網(wǎng)保持在 8192 到 32768 更穩(wěn)。callback每次發(fā)送一個(gè)塊就被調(diào)用一次入?yún)⑹沁@一塊的字節(jié)數(shù)。用它做進(jìn)度條或者日志最好用但注意不要在回調(diào)里做耗時(shí)操作否則會(huì)拖慢整體傳輸。import os from ftplib import FTP def upload_file(ftp, local_path, remote_dir, remote_nameNone): remote_name remote_name or os.path.basename(local_path) total os.path.getsize(local_path) sent 0 def _on_block(block): nonlocal sent sent len(block) percent sent * 100 // total if total else 100 print(f\r上傳 {remote_name}: {sent}/{total} 字節(jié) ({percent}%), end) # 確保遠(yuǎn)程目錄存在不存在則逐級(jí)創(chuàng)建 try: ftp.cwd(remote_dir) except error_perm: for part in remote_dir.strip(/).split(/): try: ftp.mkd(part) except error_perm: pass ftp.cwd(part) with open(local_path, rb) as fp: ftp.storbinary(fSTOR {remote_name}, fp, blocksize32768, callback_on_block) print()這里有個(gè)細(xì)節(jié)值得說mkd在目錄已存在時(shí)會(huì)拋error_perm通常是 550直接吞掉繼續(xù)cwd就行這是 FTP 建目錄的常規(guī)寫法沒有冪等的mkdir -p。另外注意cwd的語義——FTP 的當(dāng)前目錄是服務(wù)端會(huì)話狀態(tài)你的函數(shù)改完之后要記得它對(duì)后續(xù)操作有影響最穩(wěn)妥的做法是每次操作前顯式cwd到目標(biāo)目錄不要依賴上一次殘留的位置。進(jìn)度統(tǒng)計(jì)用nonlocal累加會(huì)出現(xiàn)一個(gè)偏差callback收到的塊大小是寫入 socket 的量正常情況下和文件大小一致但如果中途失敗sent會(huì)停在半路。所以這個(gè)進(jìn)度只能用于人看不能當(dāng)成成功的判據(jù)——真正的成功判據(jù)是storbinary正常返回且遠(yuǎn)程SIZE對(duì)得上。3.3 下載retrbinary 與遞歸拉取整個(gè)目錄下載用retrbinary(RETR 文件名, callback, blocksize, restNone)回調(diào)收到的是數(shù)據(jù)塊需要自己往本地文件里寫。這一點(diǎn)和上傳不同上傳是 ftplib 幫你讀本地文件下載是 ftplib 把數(shù)據(jù)交給你怎么存由你決定。遞歸拉目錄的難點(diǎn)在于 FTP 沒有現(xiàn)成的遞歸命令只能自己維護(hù)一個(gè)棧。服務(wù)端的目錄遍歷有兩條路nlst只能列出名字MLSD能帶出type字段區(qū)分目錄和文件。優(yōu)先用MLSD不支持的話就用cwd試著切進(jìn)去切成功就是目錄——這個(gè)技巧雖然土但兼容性最好。import os from ftplib import FTP, error_perm def download_tree(ftp, remote_dir, local_dir): os.makedirs(local_dir, exist_okTrue) try: entries list(ftp.mlsd(remote_dir, facts[type, size])) structured True except error_perm: entries [(n, {}) for n in ftp.nlst(remote_dir)] structured False for name, facts in entries: if name in (., ..): continue remote_path f{remote_dir.rstrip(/)}/{name} local_path os.path.join(local_dir, name) is_dir facts.get(type) dir if structured else False if not structured: # 沒有 MLSD 時(shí)用 cwd 試探是否為目錄 try: ftp.cwd(remote_path) ftp.cwd(remote_dir) is_dir True except error_perm: is_dir False if is_dir: download_tree(ftp, remote_path, local_path) else: with open(local_path, wb) as fp: ftp.retrbinary(fRETR {remote_path}, fp.write, blocksize32768) print(已下載, remote_path)遞歸函數(shù)里對(duì)目錄的判斷邏輯有個(gè)隱患cwd試探會(huì)改變當(dāng)前目錄所以切進(jìn)去之后必須立刻切回來代碼里ftp.cwd(remote_dir)那一行就是干這個(gè)的。如果服務(wù)端對(duì)CWD的響應(yīng)慢這個(gè)方案會(huì)明顯拖慢遍歷速度那時(shí)候就只能退而求其次約定好目錄結(jié)構(gòu)只同步固定層級(jí)。另外注意local_path里的文件名直接來自服務(wù)器中文名場景下如果encoding設(shè)錯(cuò)這里會(huì)在本地創(chuàng)建出一堆亂碼文件名。跑之前先用一個(gè)小目錄試一遍確認(rèn)文件名字節(jié)正確再放開全量。這個(gè)驗(yàn)證動(dòng)作我每次都做因?yàn)樗鼘儆凇赋鲥e(cuò)之后清理成本極高」的那類問題。3.4 校驗(yàn)用 SIZE 和 MD5 把傳輸閉環(huán)傳輸成功不等于文件正確。FTP 在二進(jìn)制模式下不做完整性校驗(yàn)網(wǎng)絡(luò)中斷、磁盤寫滿、服務(wù)端中途返回 426都可能留下一個(gè)大小不對(duì)的文件。storbinary和retrbinary在不拋異常的情況下返回226 Transfer complete這只說明服務(wù)端認(rèn)為傳完了不代表字節(jié)一定對(duì)齊。第一層校驗(yàn)是SIZE命令單位是字節(jié)直接和本地os.path.getsize對(duì)比。這一層能擋住絕大多數(shù)截?cái)鄦栴}成本幾乎為零。import hashlib from ftplib import FTP, error_perm def remote_size(ftp, remote_path): try: return ftp.size(remote_path) # 返回 int單位字節(jié) except error_perm: return None # 服務(wù)器不支持 SIZE 命令時(shí)返回 None def remote_md5(ftp, remote_path): h hashlib.md5() ftp.retrbinary(fRETR {remote_path}, h.update, blocksize65536) return h.hexdigest() def local_md5(path): h hashlib.md5() with open(path, rb) as fp: for chunk in iter(lambda: fp.read(65536), b): h.update(chunk) return h.hexdigest()remote_md5的實(shí)現(xiàn)方式是把文件整個(gè)再拉一遍喂給哈希對(duì)象對(duì)于幾 GB 的備份包來說代價(jià)不小所以我的實(shí)際策略是分級(jí)的日常小文件用SIZE對(duì)比就夠了重要數(shù)據(jù)在傳完之后再跑一次MD5比對(duì)超大文件改成傳完立刻對(duì)端算哈希、通過別的通道回傳不在 FTP 里繞這一圈。還要注意ftp.size()在某些服務(wù)器上對(duì) ASCII 模式的文件返回的是轉(zhuǎn)換后的大小所以前面強(qiáng)調(diào)TYPE I不是可選項(xiàng)。如果你拿到的大小和本地差幾字節(jié)且文件是文本類第一反應(yīng)應(yīng)該是傳輸模式被改過而不是文件壞了。4. 命令行側(cè)的打法curl 與 lftp 在批量同步腳本里的分工不是所有活都值得寫 Python。臨時(shí)拉一個(gè)文件、CI 流水線里傳個(gè)制品、crontab 里跑個(gè)每日同步命令行工具更直接出問題也更容易在日志里看到原始錯(cuò)誤碼。這一章說清楚 curl 和 lftp 各自適合什么以及怎么把它們?nèi)M(jìn) shell 腳本而不留隱患。4.1 curl 的四種姿勢(shì)單文件上傳下載與建目錄curl 支持 FTP 協(xié)議語法統(tǒng)一返回值規(guī)范是腳本里的首選。四種最常見的用法下載單文件、上傳單文件、上傳時(shí)自動(dòng)建目錄、斷點(diǎn)續(xù)傳下載。# 1. 下載單個(gè)文件到當(dāng)前目錄保留遠(yuǎn)程文件名 curl -u $FTP_USER:$FTP_PASS \ --ftp-pasv \ --connect-timeout 15 \ -O ftp://ftp.example.com/data/report.csv # 2. 上傳單文件-T 指定本地文件 curl -u $FTP_USER:$FTP_PASS \ -T ./report.csv \ ftp://ftp.example.com/upload/report.csv # 3. 上傳時(shí)自動(dòng)創(chuàng)建缺失的遠(yuǎn)程目錄 curl -u $FTP_USER:$FTP_PASS \ --ftp-create-dirs \ -T ./report.csv \ ftp://ftp.example.com/upload/2024/06/report.csv # 4. 斷點(diǎn)續(xù)傳下載-C - 表示讓 curl 自動(dòng)計(jì)算偏移 curl -u $FTP_USER:$FTP_PASS -C - -O ftp://ftp.example.com/data/big.tar.gz--ftp-pasv在新版 curl 里已經(jīng)是默認(rèn)行為顯式寫上是為了讓腳本意圖清楚也防止某些環(huán)境變量把它改掉。--connect-timeout只控制建連階段傳輸階段的卡頓要靠--speed-time和--speed-limit來控制比如「連續(xù) 60 秒速度低于 1KB/s 就斷開」這在鏈路不穩(wěn)的場景下很實(shí)用能讓腳本快速失敗而不是掛一晚上。--ftp-create-dirs是最容易被忽略但最省事的一個(gè)參數(shù)。沒有它你把文件傳到不存在的目錄會(huì)直接得到550 No such directory而很多人會(huì)誤以為是權(quán)限問題去翻服務(wù)端配置翻半天。退出碼要檢查。curl 返回 0 才是成功$?非 0 時(shí)要按碼定位6 是域名解析失敗7 是連不上9 是 FTP 訪問被拒67 是登錄失敗78 是遠(yuǎn)程文件不存在。把這幾個(gè)碼寫進(jìn)腳本的錯(cuò)誤分支比事后翻日志快得多。if ! curl -sS -u $FTP_USER:$FTP_PASS --ftp-create-dirs \ -T ./report.csv ftp://ftp.example.com/upload/report.csv; then code$? case $code in 67) echo 認(rèn)證失敗檢查賬號(hào)密碼 2 ;; 78) echo 遠(yuǎn)程路徑不存在 2 ;; *) echo 上傳失敗curl 退出碼 $code 2 ;; esac exit 1 fi-sS的組合值得解釋-s靜默掉進(jìn)度條-S在出錯(cuò)時(shí)仍然把錯(cuò)誤信息打出來。只寫-s會(huì)讓腳本失敗得悄無聲息這是我在流水線里踩過的坑。4.2 lftp 的 mirror目錄級(jí)同步的正解單文件用 curl整目錄同步就該換 lftp。mirror子命令是 lftp 的核心競爭力它支持遞歸、支持?jǐn)帱c(diǎn)續(xù)傳、支持并行、支持排除規(guī)則寫起來還短。# 把遠(yuǎn)程 /data/2024 同步到本地 ./backup-c 表示續(xù)傳-n 只拉新文件 lftp -u $FTP_USER,$FTP_PASS ftp.example.com -e set ftp:passive-mode true; set net:timeout 20; set net:max-retries 3; mirror -c -n --parallel4 /data/2024 ./backup; bye # 反向把本地 ./dist 推送到遠(yuǎn)程 /public/release lftp -u $FTP_USER,$FTP_PASS ftp.example.com -e set ftp:passive-mode true; mirror -R -c --parallel4 --exclude-glob *.tmp ./dist /public/release; bye -c是續(xù)傳-n是只傳新文件基于大小和時(shí)間做判斷-R是反向鏡像本地到遠(yuǎn)程--parallel4開 4 個(gè)并發(fā)連接。并發(fā)數(shù)不是越大越好很多 FTP 服務(wù)器對(duì)單 IP 的連接數(shù)有限制超過會(huì)直接被拒或者限速4 到 8 是比較安全的區(qū)間。set net:max-retries 3配合net:timeout是穩(wěn)定性關(guān)鍵。FTP 在大批量小文件場景下很容易出現(xiàn)個(gè)別文件超時(shí)沒有重試的話整個(gè) mirror 會(huì)中斷。但重試也別設(shè)太大否則一個(gè)壞文件能把你卡到天亮。--exclude-glob用來排除臨時(shí)文件這個(gè)在鏡像構(gòu)建目錄時(shí)特別必要否則.tmp、.swp這些垃圾會(huì)反復(fù)被推送還會(huì)因?yàn)闀r(shí)間戳變化導(dǎo)致每次都被判定為「新文件」。4.3 定時(shí)同步腳本鎖、日志與失敗告警把上面的命令塞進(jìn) crontab 之前有三件事必須補(bǔ)上防并發(fā)、留日志、失敗可見。防并發(fā)用flock防止上一輪沒跑完下一輪又起來了兩個(gè)進(jìn)程同時(shí)往一個(gè)目錄寫結(jié)果一定是災(zāi)難。日志按天切分別讓它無限增長。失敗告警最簡單的做法是靠退出碼觸發(fā)lftp在-e里的命令失敗時(shí)退出碼非 0可以在外層判斷。#!/usr/bin/env bash set -euo pipefail LOG_DIR/var/log/ftp-sync mkdir -p $LOG_DIR LOG_FILE$LOG_DIR/sync-$(date %Y%m%d).log { echo 開始 $(date %F %T) if ! lftp -u ${FTP_USER},${FTP_PASS} ftp.example.com -e set ftp:passive-mode true; set net:timeout 20; set net:max-retries 3; mirror -c -n --parallel4 /data/2024 /data/backup/2024; bye ; then echo 同步失敗 $(date %F %T) 2 exit 1 fi echo 結(jié)束 $(date %F %T) } $LOG_FILE 21crontab 里的寫法是*/30 * * * * flock -n /tmp/ftp-sync.lock /opt/scripts/ftp-sync.sh。flock -n表示拿不到鎖就立刻退出不會(huì)堆積。這套結(jié)構(gòu)看著樸素但比很多花哨的同步框架可靠因?yàn)樗恳画h(huán)的失敗都能在日志里找到對(duì)應(yīng)的一行。5. 避坑與排查亂碼、425、超時(shí)、550 的五條血淚記錄前面幾章講的是「怎么讓它跑起來」這一章講的是「它跑起來之后為什么還會(huì)出事」。下面五條都是我在實(shí)際環(huán)境里遇到過的按「現(xiàn)象 → 原因 → 解決」記能對(duì)上一個(gè)就省一晚上的時(shí)間。5.1 中文文件名變成亂碼上傳后下載不回來現(xiàn)象本地文件名是日?qǐng)?bào)_20240601.csv上傳到服務(wù)器后用客戶端看是一串問號(hào)或者方塊用腳本nlst列出來是??_20240601.csv再按原名RETR直接報(bào) 550。原因控制連接上的文件名字節(jié)編碼和服務(wù)器解釋的編碼不一致。ftplib 的encoding默認(rèn)是 UTF-8很多國內(nèi)老服務(wù)器默認(rèn) GBK字節(jié)流過去之后被按另一套碼表解碼就成了亂碼。另外有些服務(wù)器即使支持 UTF-8也需要顯式發(fā)OPTS UTF8 ON才切換。解決先試ftp.sendcmd(OPTS UTF8 ON)成功說明服務(wù)器支持 UTF-8保持encodingutf-8如果返回500或502把encoding改成gbk再跑一遍。命令行側(cè) curl 沒有直接的編碼開關(guān)我一般改用 lftp 并設(shè)置set ftp:charset gbk或set ftp:charset utf-8。驗(yàn)證方法很簡單上傳一個(gè)中文名的小文件立刻nlst回來比對(duì)字節(jié)別等全量傳完再發(fā)現(xiàn)。5.2 425 打不開數(shù)據(jù)連接控制連接卻完全正?，F(xiàn)象登錄成功PWD正常返回一執(zhí)行LIST或RETR就報(bào)425 Cant open data connection重試幾次偶爾能成功。原因被動(dòng)模式下服務(wù)器返回的臨時(shí)端口沒有在防火墻或安全組放行。偶爾成功是因?yàn)閰^(qū)間里個(gè)別端口恰好被放通了或者會(huì)話復(fù)用了上一次的連接。另一種可能是服務(wù)器返回的 PASV IP 是內(nèi)網(wǎng)地址客戶端在公網(wǎng)側(cè)根本連不上。解決先開set_debuglevel(2)或者手動(dòng)發(fā)PASV把服務(wù)器返回的 IP 和端口算出來前面講過p1*256p2的換算。然后核對(duì)防火墻放行區(qū)間讓服務(wù)端把pasv_min_port和pasv_max_port固定成一段連續(xù)端口并整體放行。如果服務(wù)器返回的是內(nèi)網(wǎng) IP需要在服務(wù)端配置里指定對(duì)外通告的地址這一項(xiàng)各服務(wù)端軟件叫法不同得看具體實(shí)現(xiàn)。5.3 大文件傳到 90% 斷了重跑又從零開始現(xiàn)象幾 GB 的備份包傳了半小時(shí)在快結(jié)束時(shí)拋TimeoutError或ConnectionResetError腳本重跑一遍進(jìn)度從 0% 重新開始反復(fù)幾次永遠(yuǎn)傳不完。原因FTP 的空閑超時(shí)和數(shù)據(jù)傳輸超時(shí)都會(huì)在中途觸發(fā)尤其是鏈路質(zhì)量差的時(shí)候。更關(guān)鍵的是默認(rèn)的STOR命令會(huì)截?cái)嗤募匦聦懖痪邆淅m(xù)傳語義所以重跑必然是覆蓋。解決上傳用APPE命令追加或者用STOR配合rest參數(shù)指定偏移量下載用RETR配合rest。ftplib 的storbinary和retrbinary都有rest參數(shù)傳字節(jié)偏移即可。偏移量從遠(yuǎn)程SIZE拿本地文件也按同樣大小截?cái)鄬?duì)齊。更省事的做法是直接用 lftp 的mirror -c或者 curl 的-C -它們內(nèi)部處理了這套邏輯。5.4 550 權(quán)限錯(cuò)誤但賬號(hào)明明有寫權(quán)限現(xiàn)象上傳時(shí)報(bào)550 Permission denied或者550 No such file or directory運(yùn)維確認(rèn)賬號(hào)對(duì)目標(biāo)目錄有寫權(quán)限。原因三種可能。一是目標(biāo)目錄根本不存在FTP 不會(huì)自動(dòng)建目錄550 No such file or directory很多時(shí)候就是這個(gè)意思二是當(dāng)前工作目錄不在預(yù)期位置腳本上一步cwd到了別處三是服務(wù)端的chroot或家目錄限制讓絕對(duì)路徑不可達(dá)你用的/upload/xxx在服務(wù)端被解釋成了別的路徑。解決先用ftp.pwd()確認(rèn)當(dāng)前位置再用ftp.cwd(/)回到根看目錄結(jié)構(gòu)最后用相對(duì)路徑操作。目錄不存在就按前面mkd逐級(jí)創(chuàng)建的方式補(bǔ)上或者命令行加--ftp-create-dirs。如果cwd(/)之后看到的結(jié)構(gòu)和預(yù)期完全不同那就是被 chroot 了所有路徑都得按賬號(hào)家目錄的相對(duì)路徑來寫。5.5 腳本跑著跑著不報(bào)錯(cuò)也不動(dòng)了現(xiàn)象定時(shí)任務(wù)卡住沒有輸出進(jìn)程一直掛著ps能看到但 CPU 和網(wǎng)絡(luò)都是 0。原因connect時(shí)用了默認(rèn)的timeoutNonesocket 進(jìn)入阻塞狀態(tài)永不超時(shí)。服務(wù)端已經(jīng)悄悄斷了控制連接客戶端還在傻等一個(gè)永遠(yuǎn)不會(huì)來的響應(yīng)。解決所有connect調(diào)用強(qiáng)制傳timeout20 到 30 秒是常用值在長任務(wù)中間定期發(fā)NOOP探活失敗就重建連接。crontab 外面再套一層timeout 3600兜底讓卡死的進(jìn)程自己被殺掉比事后手工清理干凈得多。這套「超時(shí) 探活 外層兜底」三重保險(xiǎn)是我在吃過一次卡死一整晚的虧之后固定下來的寫法。6. 進(jìn)階收口斷點(diǎn)續(xù)傳、顯式 FTPS 與傳輸后校驗(yàn)把基礎(chǔ)的傳通之后剩下的價(jià)值都在「出事時(shí)能恢復(fù)」和「傳完之后能證明它是對(duì)的」這兩件事上。這一章說三個(gè)具體做法都是可以直接塞進(jìn)現(xiàn)有腳本的。6.1 用 REST 和 SIZE 做真正的斷點(diǎn)續(xù)傳斷點(diǎn)續(xù)傳的核心是一個(gè)字節(jié)偏移量。下載時(shí)先用SIZE拿到遠(yuǎn)程文件總大小再看本地已下載多少用rest參數(shù)告訴服務(wù)器從哪個(gè)字節(jié)開始發(fā)。上傳同理但方向反過來遠(yuǎn)程用SIZE拿已上傳的字節(jié)數(shù)本地文件用seek跳到對(duì)應(yīng)位置。import os from ftplib import FTP def resume_download(ftp, remote_path, local_path): remote_total ftp.size(remote_path) local_size os.path.getsize(local_path) if os.path.exists(local_path) else 0 if local_size remote_total: print(本地文件已完整跳過) return mode ab if local_size else wb with open(local_path, mode) as fp: # rest 參數(shù)即偏移量服務(wù)器從該字節(jié)位置開始發(fā)送 ftp.retrbinary(fRETR {remote_path}, fp.write, blocksize65536, restlocal_size) # 傳完必須校驗(yàn)不一致說明中途又?jǐn)嗔?if os.path.getsize(local_path) ! remote_total: raise RuntimeError(續(xù)傳后大小不一致需要整體重傳)這段邏輯里最容易錯(cuò)的是最后那個(gè)校驗(yàn)。rest參數(shù)在部分服務(wù)器上行為不規(guī)范可能忽略偏移量從頭開始發(fā)結(jié)果就是本地文件前面一段被重復(fù)追加大小直接超過遠(yuǎn)程。加一道大小比對(duì)能第一時(shí)間發(fā)現(xiàn)這種「假續(xù)傳」代價(jià)只是一次getsize。上傳側(cè)的寫法和這個(gè)鏡像對(duì)稱用storbinary的rest參數(shù)配合本地fp.seek(local_size)。要注意storbinary從文件對(duì)象的當(dāng)前位置開始讀所以seek必須在調(diào)用前完成。6.2 顯式 FTPS把明文通道關(guān)掉如果傳輸?shù)氖琴~號(hào)、日志、業(yè)務(wù)數(shù)據(jù)明文 FTP 意味著密碼和內(nèi)容都在網(wǎng)絡(luò)上裸奔。顯式 FTPSFTP over TLS在 21 端口上先明文建連再用AUTH TLS升級(jí)加密兼容性比隱式 FTPS 好大多數(shù)服務(wù)端都支持。import ssl from ftplib import FTP_TLS ftps FTP_TLS(contextssl.create_default_context()) ftps.encoding utf-8 ftps.connect(ftp.example.com, 21, timeout20) ftps.login(demo_user, demo_pass) ftps.prot_p() # 關(guān)鍵把數(shù)據(jù)連接也加密不加這行數(shù)據(jù)仍是明文 ftps.set_pasv(True) print(ftps.nlst(.)) ftps.quit()prot_p()這一行是分水嶺。很多腳本登錄之后忘了調(diào)用它控制連接加密了、數(shù)據(jù)連接還是明文等于白配。另外ssl.create_default_context()會(huì)啟用證書校驗(yàn)如果服務(wù)端用的是自簽證書會(huì)直接拋SSLCertVerificationError生產(chǎn)環(huán)境應(yīng)該把服務(wù)端證書的 CA 加進(jìn)信任鏈而不是圖省事用_create_unverified_context()關(guān)掉校驗(yàn)——關(guān)掉之后加密就只能防旁觀防不了中間人。6.3 傳輸后的校驗(yàn)清單最后說一個(gè)我固定執(zhí)行的動(dòng)作每次批量傳輸結(jié)束后跑一遍校驗(yàn)清單而不是相信「腳本沒報(bào)錯(cuò)就是成功」。檢查項(xiàng)手段判定標(biāo)準(zhǔn)文件數(shù)量本地ls計(jì)數(shù) vs 遠(yuǎn)程N(yùn)LST計(jì)數(shù)數(shù)量一致缺一個(gè)都要查單文件大小os.path.getsizevsftp.size()逐字節(jié)相等關(guān)鍵文件哈希本地 MD5 vs 遠(yuǎn)程RETR計(jì)算 MD5抽樣比對(duì)重要文件修改時(shí)間本地 mtime vsMDTM返回值增量同步時(shí)用于判斷新舊傳輸模式TYPE I是否生效文本文件大小不應(yīng)出現(xiàn)偏差這張表我一般做成一個(gè)獨(dú)立的小腳本傳完之后單獨(dú)跑輸出一份對(duì)賬結(jié)果。它的價(jià)值不在于發(fā)現(xiàn)大問題——大問題腳本早就拋異常了——而在于發(fā)現(xiàn)那些「差幾十字節(jié)」「少一個(gè)文件」的靜默失敗這類問題在第二天業(yè)務(wù)方找上門時(shí)才發(fā)現(xiàn)排查成本是當(dāng)場發(fā)現(xiàn)的十倍。還有一個(gè)習(xí)慣任何一次改動(dòng)過連接參數(shù)、編碼、路徑的腳本上線前先用一個(gè)只含兩三個(gè)小文件的測試目錄完整跑一遍包括上傳、下載、校驗(yàn)和故意中斷后的續(xù)傳。FTP 的問題大多不是邏輯錯(cuò)是環(huán)境差異本地跑通不代表生產(chǎn)跑通但本地跑不通一定別往生產(chǎn)推。那次凌晨少了一個(gè)包的教訓(xùn)之后我每次把同步腳本交給別人之前都會(huì)強(qiáng)制走一遍「小目錄全流程 斷網(wǎng)續(xù)傳 大小校驗(yàn)」這三步寧可多花二十分鐘也不想再對(duì)著干凈的日志找一晚上原因。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取