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