簡介面向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)模式、傳輸類型與編碼三件事拆開配一段可以直接跑的探測(cè)代碼先把鏈路摸清楚再談上傳下載。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ì)先用一段最小的探測(cè)代碼把歡迎語、當(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è)小文件的測(cè)試目錄完整跑一遍包括上傳、下載、校驗(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)擊獲取