基於 JSch 實現 SFTP 伺服器檔案上傳、下載與遠端操作完整指南

專案需要實現資源管理功能，除 FastDFS 存儲單檔外，特定資源仍需暫存於應用伺服器。考慮到 FTP 權限管理繁雜（尤其 Linux 環境刪除文件權限問題），團隊決定採用 SFTP 協議。本文基於 JSch（純 Java 實現 SSH2）封裝完整工具類，支援檔案上傳下載、目錄操作、遠端命令執行、壓縮解壓、磁碟/CPU 監控等實用功能。

核心依賴

<dependency>
    <groupId>com.jcraft</groupId>
    <artifactId>jsch</artifactId>
    <version>0.1.55</version>
</dependency>

官網範例：Shell.java

關鍵實作要點

1. 認證資訊封裝

實作 UserInfo 與 UIKeyboardInteractive 介面，處理密碼、密鑰、Yes/No 確認等交互邏輯。

2. 連線管理

單例模式管理 Session 與 ChannelSftp，提供 connect()/disconnect() 統一入口，支援連線超時設定。

3. 檔案傳輸核心 API

• 上傳：sftp.put(local, remote, monitor, ChannelSftp.OVERWRITE) 支援進度監聽與覆蓋模式
• 下載：sftp.get(remote, local, monitor, ChannelSftp.OVERWRITE)
• 刪除檔案/目錄：sftp.rm() / execCommand("rm -rf " + dir)
• 目錄列表：sftp.ls(path) 過濾 . .. 返回檔名列表
• 建立目錄：sftp.mkdir(path)

4. 遠端命令執行與系統監控

// 執行任意 Shell 命令
public String execCommand(String command, boolean waitForResult) {
    ChannelExec channel = (ChannelExec) session.openChannel("exec");
    channel.setCommand("export TERM=ansi && " + command);
    // ... 讀取輸入流 ...
}

// 獲取 CPU 資訊
public String[] getCpuInfo() { /* top -bn 1 解析 */ }

// 獲取磁碟資訊
public String getHardDiskInfo() { /* df -lh 解析 */ }

// 獲取剩餘空間（位元組）
public double getFreeDisk() { /* 單位換算 KB/MB/GB/TB/PB */ }

5. 壓縮解壓支援

// 遠端壓縮目錄
public void compressDir(String directory, String zipName) {
    execCommand("cd " + directory + " && zip -r " + zipName + " .");
}

// 解壓（中文檔名編碼注意）
// unzip -O cp936 test.zip -d /target/path

完整工具類結構

public class Ssh {
    private String host, user, password;
    private int port = 22;
    private Session session;
    private ChannelSftp sftp;
    
    // 連線/斷線
    public void connect() throws JSchException { ... }
    public void disconnect() { ... }
    
    // 檔案操作
    public boolean upload(String local, String remote) { ... }
    public boolean download(String local, String remote) { ... }
    public boolean deleteFile(String dir, String file) { ... }
    public String deleteDir(String dir, boolean sure) { ... }
    public List<String> listFiles(String directory) { ... }
    public boolean mkdir(String path) { ... }
    
    // 遠端命令與監控
    public String execCommand(String cmd, boolean wait) { ... }
    public String[] getCpuInfo() { ... }
    public String getHardDiskInfo() { ... }
    public double getFreeDisk() { ... }
    public void compressDir(String dir, String zipName) { ... }
}

測試驗證

public static void main(String[] args) throws Exception {
    Ssh ssh = new Ssh("10.10.10.83", 22, "test", "test");
    ssh.connect();
    
    // 上傳測試
    ssh.upload("d:/test.zip", "webapp/test.zip");
    
    // 列出目錄
    ssh.listFiles("webapp").forEach(System.out::println);
    
    // 系統監控
    System.out.println("CPU: " + Arrays.toString(ssh.getCpuInfo()));
    System.out.println("Disk: " + ssh.getHardDiskInfo());
    System.out.println("Free: " + ssh.getFreeDisk() + " bytes");
    
    ssh.disconnect();
}

常見坑點提醒

• 中文檔名亂碼：解壓時加參數 unzip -O cp936 指定編碼
• 權限不足：確保 SSH 使用者對目標目錄有讀寫執行權限
• 連線洩漏：finally 區塊務必關閉 Channel 與 Session
• 大檔傳輸：建議調整緩衝區大小、啟用壓縮 session.setConfig("compression.s2c", "zlib@openssh.com")

JSch 作為成熟的 Java SSH2 實現，配合 SFTP 協議，能優雅解決跨平台檔案傳輸與遠端運維需求，是替代傳統 FTP 的不二之選。