Maven settings.xml servers server privateKey SSH私钥路径

settings.xml中privatekey必须为绝对路径，不支持相对路径或环境变量；私钥需为openssh v1 pem格式或v2格式（maven 3.8+支持），且须与配套配置，的id须与pom.xml中repository的id完全匹配。

settings.xml 里 privateKey 必须是绝对路径

SSH 私钥文件路径在 Maven settings.xml 的 <server></server> 配置中不支持相对路径或环境变量展开。Maven 启动时直接将该字符串传给 JSch（默认 SSH 实现），而 JSch 不解析 ~、$HOME 或 ./ 这类符号。

常见错误现象：Auth fail 或 Failed to read private key，但私钥权限、格式都正确——问题往往就出在路径没解析成功。

• privateKey 值必须写成类似 /home/user/.ssh/id_rsa 或 C:Usersuser.sshid_rsa
• windows 下反斜杠要双写或用正斜杠（推荐 C:/Users/user/.ssh/id_rsa）
• 路径中不能含空格，否则 JSch 会截断；若实在无法避免，暂无可靠绕过方式，建议软链接到无空格路径

私钥格式必须是 OpenSSH v1（PEM）或新式 OpenSSH v2（OpenSSH private key format）

Maven 3.8+ 默认使用 JSch 0.1.55+，它支持新式 OpenSSH 私钥（以 -----BEGIN OPENSSH PRIVATE KEY----- 开头），但老版本 JSch（如 Maven 3.6 内置的）只认传统 PEM 格式（-----BEGIN RSA PRIVATE KEY-----）。

使用场景：你用 ssh-keygen -t rsa -b 4096 生成的密钥，默认就是新格式；但 Maven 旧版本读不了，直接报 invalid privatekey。

• 检查私钥开头：head -n1 ~/.ssh/id_rsa，如果是 -----BEGIN OPENSSH PRIVATE KEY-----，需转换
• 转成兼容格式：ssh-keygen -p -m PEM -f ~/.ssh/id_rsa（输入原密码，不设新密码）
• 不要用 PuTTY 的 .ppk，JSch 不支持

settings.xml 中 <server></server> 的 username 和 privateKey 必须配套生效

仅配 privateKey 不够——Maven 不会自动从私钥推导用户名，也不读取 ~/.ssh/config。你必须显式指定 <username></username>，且该用户需对目标服务器有对应私钥的访问权限。

常见错误现象：提示 Permission denied (publickey)，但本地 ssh user@host 能通——说明 Maven 没用对用户，或服务端 authorized_keys 里绑定的是另一个用户。

• <username></username> 值必须和你手动 SSH 登录时用的用户名完全一致（区分大小写）
• 若私钥设置了密码（passphrase），Maven 无法交互输入，必须留空或用 <passphrase></passphrase> 配置项（但明文存密码不推荐）
• <server></server> 的 id 必须和 pom.xml 中 <distributionmanagement></distributionmanagement> 的 <repository></repository> / <snapshotrepository></snapshotrepository> 的 id 完全匹配

调试 privateKey 加载失败的真实原因

Maven 默认隐藏 JSch 的底层异常，只报泛泛的认证失败。想看到真实错误，得开 DEBUG 日志并确认 JSch 是否真加载了私钥文件。

执行命令：mvn deploy -X 2>&1 | grep -A5 -B5 "privateKey"，重点看是否出现 JSch: Connecting to ... 后的 authentications: publickey，以及是否有 readPrivateKeys: 行。

• 没看到 readPrivateKeys: → 路径错或文件不可读（检查 ls -l 权限，确保 Maven 进程能读）
• 看到 readPrivateKeys: invalid privatekey → 格式不兼容（见上一条）
• 看到 Auth fail 且已确认路径/格式/用户名正确 → 检查服务端 sshd_config 是否允许公钥认证、authorized_keys 权限是否为 600、是否禁用了 passwordAuthentication 却未启用 PubkeyAuthentication

实际用起来，最常卡住的不是配置写法，而是私钥路径写成了相对路径、或者新生成的密钥格式不向下兼容——这两点几乎占了八成以上的问题。