Java中JSch与jsch.addIdentity()完全详细解析_Java

前言

jsch（java secure channel）是 jcraft 提供的纯 java 实现的 ssh2 协议库，核心用于 java 程序实现 ssh 远程登录、远程命令执行、sftp 文件传输等操作。addidentity() 是 jsch 中配置 ssh 密钥认证的核心方法，用于替代传统的密码登录，提升认证安全性，以下是详细解析。

一、jsch 基础认知

1. 核心用途

ssh 远程执行命令（如 linux 服务器操作）；
sftp/scp 文件上传、下载；
端口转发（ssh 隧道）；
支持密码认证、公钥 / 私钥认证（核心场景）。

2. 依赖引入（maven/gradle）

使用 jsch 需先引入依赖（最新稳定版为 0.1.55）：

<!-- maven -->
<dependency>
    <groupid>com.jcraft</groupid>
    <artifactid>jsch</artifactid>
    <version>0.1.55</version>
</dependency>

<!-- gradle -->
implementation 'com.jcraft:jsch:0.1.55'

二、jsch.addidentity () 方法详解

1. 核心作用

addidentity() 用于向 jsch 实例添加ssh 私钥，实现公钥认证（无需输入密码即可登录 ssh 服务器），替代不安全的密码认证方式。ssh 公钥认证原理：本地生成公钥 / 私钥对，公钥上传至服务器~/.ssh/authorized_keys，本地用私钥签名，服务器用公钥验签完成认证。

2. 常用重载方法

jsch 提供多个重载的addidentity()，覆盖不同私钥存储形式（文件、字节数组），以下是最常用的 3 种：

方法签名	适用场景
`addidentity(string privatekeypath)`	私钥以文件形式存储（无密码加密）
`addidentity(string privatekeypath, string passphrase)`	私钥文件被密码加密（需传入解密密码）
`addidentity(string name, byte[] privatekey, byte[] publickey, byte[] passphrase)`	私钥以字节数组存储（如配置中心读取）

参数说明：

privatekeypath：私钥文件路径（如/home/user/.ssh/id_rsa）；
passphrase：私钥的加密密码（若私钥未加密，传null）；
name：身份标识（自定义，如 "ssh-key-1"）；
privatekey/publickey：私钥 / 公钥的字节数组；

3. 基础使用示例（私钥文件认证）

场景 1：未加密的私钥文件

import com.jcraft.jsch.*;
import java.util.properties;

public class jschdemo {
    public static void main(string[] args) {
        jsch jsch = new jsch();
        string host = "192.168.1.100"; // 远程服务器ip
        string user = "root"; // 登录用户名
        int port = 22; // ssh端口

        try {
            // 1. 添加私钥（无密码加密）
            jsch.addidentity("/home/user/.ssh/id_rsa"); // 本地私钥文件路径

            // 2. 创建ssh会话
            session session = jsch.getsession(user, host, port);
            // 跳过主机密钥验证（生产环境不建议，可配置known_hosts）
            properties config = new properties();
            config.put("stricthostkeychecking", "no");
            session.setconfig(config);

            // 3. 连接会话（无需密码，通过私钥认证）
            session.connect();
            system.out.println("ssh连接成功：" + session.isconnected());

            // 4. 后续操作（如执行命令、sftp传输）...

            // 5. 释放资源
            session.disconnect();
        } catch (jschexception e) {
            e.printstacktrace();
        }
    }
}

场景 2：加密的私钥文件

若私钥生成时设置了密码（如ssh-keygen -t rsa时输入了 passphrase），需传入解密密码：

// 替换addidentity行，传入私钥路径+解密密码
jsch.addidentity("/home/user/.ssh/id_rsa", "my-key-pass123");

4. 进阶示例（字节数组形式的私钥）

适用于私钥存储在配置中心（如 nacos、apollo），以字符串 / 字节数组获取的场景：

public static void connectwithkeybytes() throws jschexception {
    jsch jsch = new jsch();
    string host = "192.168.1.100";
    string user = "root";

    // 从配置中心读取的私钥字符串（需去除换行/空格，或保留原始格式）
    string privatekeystr = "-----begin rsa private key-----\n" +
            "miiepaibaakcaqeaxx...（省略私钥内容）...\n" +
            "-----end rsa private key-----";
    byte[] privatekey = privatekeystr.getbytes();
    string passphrase = "my-key-pass123"; // 私钥密码（无则传null）

    // 添加字节数组形式的私钥
    jsch.addidentity("ssh-key-1", privatekey, null, passphrase.getbytes());

    // 创建会话并连接（同基础示例）
    session session = jsch.getsession(user, host, 22);
    properties config = new properties();
    config.put("stricthostkeychecking", "no");
    session.setconfig(config);
    session.connect();

    system.out.println("字节数组私钥认证成功");
    session.disconnect();
}

三、关键注意事项

1. 私钥格式要求

jsch 支持openssh 格式的私钥（如id_rsa，pem 格式），不支持 pkcs#8 格式（需转换）；
转换命令（pkcs#8→openssh）：ssh-keygen -p -m pem -f id_rsa；

2. 服务器端配置

公钥需上传至服务器~/.ssh/authorized_keys（权限需为 600）；
服务器sshd_config需开启公钥认证：pubkeyauthentication yes；
服务器~/.ssh目录权限需为 700，否则会触发认证失败。

3. 生产环境最佳实践

禁止跳过主机密钥验证（stricthostkeychecking=no）：需将服务器公钥加入本地known_hosts文件；
私钥加密存储：避免明文写在代码中，通过配置中心 / 环境变量获取；
资源释放：session、channel（sftp/exec）使用后必须disconnect()/disconnect()，避免资源泄漏；
异常处理：捕获jschexception（如认证失败、连接超时、私钥错误），区分不同错误码（如auth_failed）。

4. 常见问题排查

异常现象	原因	解决方案
`auth fail`	私钥不匹配 / 权限错误 / 服务器公钥未配置	1. 核对私钥路径；2. 检查服务器 authorized_keys 权限；3. 验证私钥密码
`invalid privatekey`	私钥格式错误（如 pkcs#8）	转换为 openssh 格式（pem）
`connection refused`	端口错误 / ssh 服务未启动	核对端口（默认 22）；检查服务器 sshd 服务状态

四、扩展场景：结合 sftp 使用

添加身份认证后，可快速实现 sftp 文件传输：

// 连接成功后，创建sftp通道
channelsftp sftpchannel = (channelsftp) session.openchannel("sftp");
sftpchannel.connect();

// 上传文件
sftpchannel.put("/本地文件路径/test.txt", "/远程服务器路径/test.txt");

// 下载文件
sftpchannel.get("/远程服务器路径/test.txt", "/本地文件路径/test.txt");

// 关闭通道
sftpchannel.disconnect();