1. SSH 密钥格式的全景图谱手里攥着一把私钥却在新环境里连不上机器这种事我前前后后遇到过七八次。报错信息五花八门Load key id_rsa: invalid format、Permissions 0644 for key are too open、Java 那边干脆甩出一句invalid privatekey: [B3f5a1c2——看着像玄学其实根子就一个你手上的密钥和对方工具期望的格式不是同一个东西。SSH 密钥的格式转换看起来是个小知识点但它横跨了 OpenSSH、PuTTY、OpenSSL、Xshell、Bitvise、以及各种语言的 SSH 客户端库每一家都有自己的偏好。不把这层关系理顺你会在授权、迁移、自动化脚本三件事上反复卡壳。这篇内容我想做的是把常见的几种私钥、公钥格式摊开讲清楚告诉你每种格式长什么样、怎么一眼认出来、彼此之间用什么命令互转、转换过程中哪些参数不能省最后再把实际踩过的坑列成速查表。适合三类人看一是刚接触服务器运维、搞不清 PEM 和 PKCS#8 区别的新手二是要在 Windows 图形工具和 Linux 命令行之间来回搬密钥的开发者三是写 Java、Python 代码对接 SFTP 或者自动化部署、被密钥加载报错折磨过的工程师。全文的命令都可以直接复制执行参数我会解释为什么这么写。1.1 一串头信息就能定身份判断密钥格式最快的办法是看文件开头和结尾那行横线包裹的标识。私钥尤其明显文件开头标识格式名称典型来源-----BEGIN OPENSSH PRIVATE KEY-----OpenSSH 新格式openssh-key-v1OpenSSH 7.8 之后ssh-keygen默认输出-----BEGIN RSA PRIVATE KEY-----PKCS#1传统 PEM老版本 OpenSSH、部分 Java 库-----BEGIN DSA PRIVATE KEY-----DSA 专用 PEM早期环境基本淘汰-----BEGIN EC PRIVATE KEY-----SEC1 / SECG 椭圆曲线格式ECDSA 私钥常见-----BEGIN PRIVATE KEY-----PKCS#8 未加密OpenSSL 3.x 默认、多数语言库-----BEGIN ENCRYPTED PRIVATE KEY-----PKCS#8 加密带口令导出的 PKCS#8PuTTY-User-Key-File-2:PuTTY PPK v2PuTTYgen 0.68 之前PuTTY-User-Key-File-3:PuTTY PPK v3PuTTYgen 0.75 之后默认公钥这边区分度低一些但同样关键。OpenSSH 的单行格式长这样ssh-rsa AAAAB3NzaC1yc2EAAAADAQAB... userhost整行就是算法名 base64 数据 可选注释。另一种是 RFC4716 定义的 SSH2 公钥格式头尾是---- BEGIN SSH2 PUBLIC KEY ----和---- END SSH2 PUBLIC KEY ----注意这里是四个横杠而不是五个宽度通常在 70 字符左右换行。再就是 OpenSSL 体系的公钥-----BEGIN PUBLIC KEY-----PKCS#8/SPKI 公钥和-----BEGIN RSA PUBLIC KEY-----PKCS#1 公钥。提示openssl系列命令对文件内容很宽容但 SSH 相关工具往往只认准一种。转换前先head -1 your_key确认格式能省掉一半的排查时间。还有个更隐蔽的区分点OpenSSH 新格式的私钥base64 解码后开头是固定字符串openssh-key-v1后面跟加密算法、KDF 参数、公钥和私钥块。这意味着它不是 ASN.1 结构任何基于 OpenSSL 的解析器都读不懂它。反过来PKCS#8 的-----BEGIN PRIVATE KEY-----是标准 ASN.1 DER 再 base64OpenSSH 在 7.8 之前也不认。这就是两边互相说对方格式错误的根源。1.2 五种格式并存的历史原因为什么不能统一成一种因为这几套东西是不同时代、不同团队各自解决各自问题时长出来的。PKCS#1 是 RSA 实验室当年的标准只描述 RSA 密钥本身输出RSA PRIVATE KEY。它简单直接但没法泛化到 DSA、ECC。PKCS#8 是后来 IETF 接手的通用私钥封装外面套一层 AlgorithmIdentifier任何算法都能塞进去所以 Java 的KeyFactory、Python 的cryptography、Go 的x509全都优先吃 PKCS#8。OpenSSH 自己则在 7.8 版本搞了个openssh-key-v1动机很实在老的 PEM 格式没法在一个文件里同时放公钥、注释、以及支持多轮 KDF 加密而且加密方式固定在几个老算法上安全性跟不上。新格式一份文件既存私钥又存公钥加密支持 bcrypt KDF抗暴力破解能力强得多。PuTTY 的 PPK 则纯粹是 Windows 生态的历史包袱。PuTTY 一开始就没有走 OpenSSL 的 ASN.1 路线自己搞了一套二进制 文本混合的封装PuTTY-User-Key-File-N头部加 base64 的字段块。它在 Windows 上确实好用图形界面友好但拿到 Linux 上就得转。Bitvise SSH Server 这类 Windows 平台的服务端软件导入主机密钥时也是按 OpenSSH 格式来读的PPK 得先转过去。工具链的差异才是真正让格式转换变成日常需求的原因。同一个 RSA 密钥在 OpenSSH 里是新格式、在 Java 老版本 JSch 里必须是 PEM PKCS#1、在 PuTTY 里是 PPK、在 Ansible 的某些模块里可能是 PKCS#8。你不可能要求所有工具统一只能自己动手转。2. 动手前的准备工具、版本与安全底线转换命令本身都不长真正容易翻车的是版本差异。同一个openssl rsa命令在 OpenSSL 1.1.1 和 3.0 下输出完全不同这也是很多我照着教程做却报错的来源。所以先花点时间确认环境。2.1 工具链清单与版本检查基础三件套是ssh-keygen、openssl、puttygen。前两个 Linux 和 macOS 基本自带Windows 10 之后的系统内置了 OpenSSH 客户端但puttygen需要自己装。快速确认版本ssh -V # OpenSSH_8.9p1 Ubuntu-3ubuntu0.4, OpenSSL 3.0.2 ssh-keygen -h 21 | head -3 # usage: ssh-keygen [-q] [-b bits] ... openssl version # OpenSSL 3.0.2 15 Mar 2022 puttygen --version # puttygen: Release 0.78几个版本分界线必须记住OpenSSH 7.82018 年 8 月之后ssh-keygen生成私钥默认是OPENSSH PRIVATE KEY新格式之前是 PEM。OpenSSL 3.02021 年 9 月之后openssl rsa -in x -out y默认输出 PKCS#8想输出 PKCS#1 必须加-traditional1.1.1 默认输出 PKCS#1。PuTTYgen 0.75 之后默认保存 PPK v3旧版 PuTTY 客户端读不了 v3。跨设备用建议显式生成 v2或者用--ppk-param version2。Windows 用户如果只装了图形工具没装 OpenSSH可以在可选功能里添加 OpenSSH 客户端也可以直接用 Git for Windows 自带的 Git Bash里面ssh-keygen、openssl都有。图形化工具 Xshell、SecureCRT、MobaXterm 都带密钥导入导出功能但它们的导出选项命名常常含糊比如导出为 OpenSSH 格式到底对应新格式还是 PEM得靠导入后head -1验证。2.2 私钥处理的几条硬规矩做密钥转换时有几个原则我建议当成铁律。第一原文件永远不要就地覆盖。转换的常规姿势是读原文件、写新文件比如ssh-keygen -p -f old_key是就地重写而openssl pkcs8 -in old.pem -out new.pem是生成新文件。凡是就地重写的操作先cp old_key old_key.bak。我有一次批量处理二十多台机器的密钥脚本失误把未加密的私钥覆写成了加密版本结果自动化任务全线挂掉那次教训让我养成了备份习惯。第二权限必须收紧。私钥文件权限 600.ssh目录 700authorized_keys644。转换出来的新文件往往带着 umask 给的 644 权限OpenSSH 会直接拒绝加载并抛UNPROTECTED PRIVATE KEY FILE。顺手chmod 600 new_key是基本操作chmod 600 ~/.ssh/new_key chmod 700 ~/.ssh chmod 644 ~/.ssh/authorized_keys第三转换不等于重新生成密钥。格式转换只是把同一个数学密钥用不同容器包起来公钥指纹不变。你可以用ssh-keygen -lf new_key和ssh-keygen -lf old_key对比 SHA256 指纹一样就说明转换没丢信息。这个校验步骤强烈建议每次都做比事后连不上再排查省事得多。第四带口令的私钥在转换时会反复问密码。如果要做批量转换临时把口令去掉ssh-keygen -p -f key -N 、转完再加回来比在每个命令里手敲密码稳定。但要注意去口令期间私钥处于裸露状态操作完立刻恢复。第五别把私钥粘到任何在线转换工具里。网上有不少密钥格式在线转换页面把私钥贴上去等于把家门钥匙交给了陌生人。所有转换都在本地做这是底线。3. 私钥格式互转实操这一节是全文的核心。我把最常遇到的几条转换路径拆开讲每条都给出完整命令和验证方法。3.1 OpenSSH 新格式与经典 PEM 互转这是最高频的需求。场景通常是本机ssh-keygen生成的是新格式但目标系统上的老工具只认 PEM。从新格式转 PEM直接改容器格式# 备份 cp ~/.ssh/id_ed25519 ~/.ssh/id_ed25519.bak # 转换为 PEMRSA 会输出 PKCS#1其他算法输出对应 PEM ssh-keygen -p -m PEM -f ~/.ssh/id_rsa # 验证头部 head -1 ~/.ssh/id_rsa # -----BEGIN RSA PRIVATE KEY------p的意思是修改私钥的口令或格式-m PEM指定输出格式。这个命令是就地覆盖的所以备份不能省。如果原私钥带口令执行过程中会提示输入旧口令和新口令新口令可以直接回车留空。反方向从 PEM 转回 OpenSSH 新格式ssh-keygen -p -m OPENSSH -f ~/.ssh/id_rsa head -1 ~/.ssh/id_rsa # -----BEGIN OPENSSH PRIVATE KEY-----这里有个细节值得说清楚-m PEM对 RSA 输出的是 PKCS#1RSA PRIVATE KEY对 ECDSA 输出的是 SEC1EC PRIVATE KEY对 Ed25519 则输出 PKCS#8PRIVATE KEY。原因很简单Ed25519 在 PEM 语境下没有 PKCS#1 那种专属封装只能走 PKCS#8 通用容器。所以同一个-m PEM参数不同算法出来的头部不一样别以为是命令写错了。还有一个绕不开的点FIPS 模式或者某些企业环境的 OpenSSH 编译时禁用了老算法-m PEM可能报unsupported format。这时候改用-m PKCS8通常能过因为 PKCS#8 是更现代的标准。3.2 PKCS#1 与 PKCS#8 互换以及 OpenSSL 3.x 的坑Java、Python、Go 这些语言层面的库对 PKCS#8 的接受度最好。把 PKCS#1 转成 PKCS#8# PKCS#1 - 未加密 PKCS#8 openssl pkcs8 -topk8 -inform PEM -in id_rsa_pkcs1.pem \ -outform PEM -nocrypt -out id_rsa_pkcs8.pem head -1 id_rsa_pkcs8.pem # -----BEGIN PRIVATE KEY------topk8表示转为 PKCS#8-nocrypt表示不加密。如果要去掉-nocryptOpenSSL 会交互式询问加密口令输出ENCRYPTED PRIVATE KEY。Java 的 JSch 老版本能读未加密的 PKCS#8也能读加密的但要求口令以字节数组传入。反方向就不那么直观了。在 OpenSSL 1.1.1 上openssl rsa -in id_rsa_pkcs8.pem -out id_rsa_pkcs1.pem但在 OpenSSL 3.0 上同样的命令输出还是 PKCS#8因为 3.0 改了默认行为。必须加-traditionalopenssl rsa -in id_rsa_pkcs8.pem -traditional -out id_rsa_pkcs1.pem head -1 id_rsa_pkcs1.pem # -----BEGIN RSA PRIVATE KEY-----这个-traditional是很多人栽跟头的地方明明执行成功没有任何报错文件也确实生成了但头部还是BEGIN PRIVATE KEY喂给目标程序依旧报格式错。判断依据就是head -1别信命令的沉默。如果算法不是 RSAopenssl rsa用不了要换成通用的openssl pkey# 对 ECDSA / Ed25519 等用 pkey 子命令 openssl pkey -in key_pkcs8.pem -out key_pem.pemopenssl pkey是 OpenSSL 1.0.0 之后引入的通用私钥处理命令不绑定算法我现在的习惯是能用pkey就用pkey脚本里少一层判断。顺便补一个 DER 格式的转换。有些 Java 老库或者硬件设备要求二进制 DER# PEM - DER openssl pkey -in id_rsa.pem -outform DER -out id_rsa.der # DER - PEM openssl pkey -inform DER -in id_rsa.der -out id_rsa.pemDER 是纯二进制cat出来是乱码别用head -1去判断用file命令看类型file id_rsa.der # id_rsa.der: data3.3 PPK 与 OpenSSH 的双向转换Windows 用户手里一堆.ppk文件是常态。转换主力是puttygen命令行版本不用开图形界面。PPK 转 OpenSSH# PPK - OpenSSH 新格式私钥 puttygen id_rsa.ppk -O private-openssh-new -o id_rsa_openssh # PPK - 传统 PEM puttygen id_rsa.ppk -O private -o id_rsa_pem # 同时导出对应的公钥 puttygen id_rsa.ppk -L id_rsa.pub-O指定输出类型常用值有privatePEM PKCS#1、private-opensshOpenSSH 兼容格式、private-openssh-newOpenSSH 新格式。-L打印公钥到标准输出-l打印指纹。注意-L和-l大小写完全不同的语义我见过有人敲错之后对着空文件发懵。反方向OpenSSH 转 PPK# OpenSSH 私钥 - PPK v2兼容性最好 puttygen id_rsa -O private --ppk-param version2 -o id_rsa.ppk # 生成 PPK v3需要 PuTTY 0.75 puttygen id_rsa -O private --ppk-param version3 -o id_rsa_v3.ppkPPK 版本选哪个取决于你的 PuTTY 客户端版本。v3 支持 Argon2 加密抗暴力破解更好但 0.75 之前的客户端直接报unsupported PuTTY key file version。公司统一发的旧版 PuTTY 环境里老老实实生成 v2。判断现有 PPK 是哪个版本看文件第一行PuTTY-User-Key-File-2:或PuTTY-User-Key-File-3:。带口令的 PPK 转换时puttygen会提示输入 passphrase。如果要做无人值守的批量转换可以先用--old-passphrase和--new-passphrase参数把口令传进去也可以传空文件路径表示无口令puttygen id_rsa.ppk --old-passphrase old_pass.txt \ --new-passphrase /dev/null \ -O private-openssh-new -o id_rsa_openssh这种写法在 CI 环境里用来解密 PPK 很实用但口令文件用完要立刻删除别留在磁盘上。3.4 Ed25519 和 ECDSA 的转换边界Ed25519 现在是新项目的首选算法但它有几个转换限制必须提前知道。第一Ed25519 私钥没有 PKCS#1 格式。你能得到的是 OpenSSH 新格式、PKCS#8BEGIN PRIVATE KEY、以及 PPK。如果你试图ssh-keygen -p -m PEM转 Ed25519结果会是BEGIN PRIVATE KEY也就是说实质上转成了 PKCS#8不是很多人以为的传统 PEM。第二Ed25519 的 PKCS#8 支持要求 OpenSSL 1.1.1 及以上。CentOS 7 自带的 OpenSSL 1.0.2 处理不了会报unable to load key。这种情况要么升级 OpenSSL要么干脆重新生成一对 RSA 密钥给老系统用别硬转。第三把 Ed25519 转成 PPK 需要 PuTTY 0.68 以上。早期 PuTTYgen 只支持 RSA 和 DSA。ECDSA 的情况介于两者之间。它有 SEC1 的专属 PEM 格式BEGIN EC PRIVATE KEY也能塞进 PKCS#8。转向时按目标工具的要求选# ECDSAOpenSSH 新格式 - SEC1 PEM ssh-keygen -p -m PEM -f id_ecdsa head -1 id_ecdsa # -----BEGIN EC PRIVATE KEY----- # ECDSASEC1 PEM - PKCS#8 openssl pkcs8 -topk8 -nocrypt -in id_ecdsa_sec1.pem -out id_ecdsa_pkcs8.pem还有一条边界是加密算法的兼容性。OpenSSH 新格式的私钥如果用了 bcrypt KDF 加密puttygen在旧版本下可能读不了报Invalid key file。解决办法是先ssh-keygen -p -f key -N 去掉口令转完格式再加回来。这个顺序能避开绝大多数跨工具链的口令兼容问题。4. 公钥格式互转实操公钥看起来比私钥简单实际上坑一样多因为公钥有三种完全不同的表示方式而不同场景对号入座的要求很严格。4.1 单行授权格式与 RFC4716OpenSSH 的一行式公钥是绝大多数场景的通用货币authorized_keys、GitHub、GitLab 都吃这个格式ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGx... userexample.com从它转成 RFC4716 格式ssh-keygen -e -m RFC4716 -f id_ed25519.pub输出是---- BEGIN SSH2 PUBLIC KEY ---- Comment: 2048-bit RSA, converted by userhost from OpenSSH AAAAB3NzaC1yc2EAAAADAQAB... ---- END SSH2 PUBLIC KEY -----e是导出-m RFC4716指定目标格式。RFC4716 主要用于一些老式商业 SSH 客户端SecureCRT、部分网络设备和某些 Java 库。反方向用-i导入ssh-keygen -i -m RFC4716 -f key_rfc4716.pub id_rsa.pub注意 RFC4716 格式支持Comment:头而且 base64 内容会自动按 70 字符折行。手工编辑这个文件时折行不能乱删否则解析失败。另外它的头部是四个横杠我见过有人按五个横杠的 PEM 风格去改结果工具直接识别不了。有个细节值得留意ssh-keygen -e生成的 RFC4716 默认会带上Comment:行内容是自动生成的描述而不是原始注释。如果你依赖注释来区分密钥导出后需要手改。这在管理几十把密钥的环境里挺重要。4.2 PEM 和 DER 公钥的生成与还原有些场景需要 OpenSSL 体系的公钥。比如用openssl验证签名、生成证书、或者喂给某些策略引擎。从 OpenSSH 单行公钥转过来# 转 PKCS#8 公钥SPKI头部为 BEGIN PUBLIC KEY ssh-keygen -e -m PKCS8 -f id_rsa.pub id_rsa_pkcs8.pub head -1 id_rsa_pkcs8.pub # -----BEGIN PUBLIC KEY----- # 转 PKCS#1 公钥仅限 RSA ssh-keygen -e -m PEM -f id_rsa.pub id_rsa_pkcs1.pub head -1 id_rsa_pkcs1.pub # -----BEGIN RSA PUBLIC KEY-----反过来从 OpenSSL 公钥转回 OpenSSH 单行ssh-keygen -i -m PKCS8 -f id_rsa_pkcs8.pub id_rsa.pub这里-m PKCS8对公钥来说指的是 SPKI 结构。实测下来用-m PKCS8比-m PEM更稳因为-m PEM只对 RSA 有效碰上 ECDSA 或 Ed25519 会报错。DER 格式的公钥在嵌入式设备和一些老 Java 代码里能碰到# PEM 公钥 - DER openssl pkey -pubin -in id_rsa_pkcs8.pub -outform DER -out id_rsa.pub.der # DER - PEM openssl pkey -pubin -inform DER -in id_rsa.pub.der -out id_rsa_pkcs8.pub-pubin表示输入是公钥而不是私钥忘了加这个参数 OpenSSL 会把它当私钥解析然后报错。4.3 从私钥反推公钥和指纹校验密钥迁移过程中最有用的两个命令一个是反推公钥一个是算指纹。反推公钥ssh-keygen -y -f id_rsa id_rsa_pub_recovered.pub-y读取私钥输出对应的公钥。这个命令对 OpenSSH 新格式、PEM、PKCS#8 都有效只要 OpenSSH 版本支持该算法是恢复丢失公钥文件的标准手段。带口令的私钥会提示输入密码。算指纹# 默认 SHA256 ssh-keygen -lf id_rsa.pub # 4096 SHA256:AbCdEf1234567890... userhost (RSA) # 兼容老的 MD5 展示 ssh-keygen -lf id_rsa.pub -E md5 # 4096 MD5:ab:cd:ef:12:... (RSA) # 直接对私钥算指纹 ssh-keygen -lf id_rsa指纹是密钥转换正确性的最终裁判。流程转完之后对新旧文件各跑一次-lfSHA256 值一致就说明数学上是同一把密钥转换没有引入错误。我现在的习惯是把指纹记进变更单将来出问题回溯时一目了然。注意ssh-keygen -lf对私钥和公钥输出同一个指纹因为指纹算的是公钥部分。这条特性可以拿来验证一个私钥文件和一份公钥文件是不是配对的。5. 典型场景串联跨工具链迁移实录单条命令看懂了串起来用在真实场景里才见功力。下面三个场景都是我自己或者同事实际遇到过的按步骤走一遍。5.1 场景一从 Windows 图形工具迁移到命令行环境需求是这样的以前在 Windows 上用 PuTTY 连服务器.ppk文件攒了十几把现在团队要求统一用命令行和自动化脚本需要把它们都换成 OpenSSH 格式并存到~/.ssh/下。第一步把 PPK 全部转成 OpenSSH 新格式同时导出公钥和指纹mkdir -p ~/.ssh/migrated cd ~/ppk_files for f in *.ppk; do base${f%.ppk} puttygen $f -O private-openssh-new -o ~/.ssh/migrated/$base puttygen $f -L ~/.ssh/migrated/$base.pub chmod 600 ~/.ssh/migrated/$base echo -n $base: ssh-keygen -lf ~/.ssh/migrated/$base done第二步把公钥追加到服务器的authorized_keys。这一步要注意如果是新服务器直接用转出来的公钥就行如果是替换旧密钥先把新的追加进去、验证登录成功、再删除旧的避免把自己锁在外面。第三步写~/.ssh/config给每台机器配别名并指定私钥Host prod-web HostName 10.0.1.10 User deploy IdentityFile ~/.ssh/migrated/prod_web IdentitiesOnly yes Host prod-db HostName 10.0.1.20 User deploy IdentityFile ~/.ssh/migrated/prod_db IdentitiesOnly yesIdentitiesOnly yes这个选项很关键。不加它的话SSH 会先尝试 ssh-agent 里所有密钥服务器端的MaxAuthTries默认是 6密钥多了会在尝试到正确的之前就被踢掉报Too many authentication failures。我在一个 agent 里塞了二十多把密钥的环境里踩过这个坑加了IdentitiesOnly立刻正常。第四步验证ssh -vvv prod-web 21 | grep -iE offering|identity file|authenticated-vvv的输出里能看到实际尝试了哪个密钥文件、以及服务端最终接受了哪一个。排查密钥问题时这个命令比任何猜测都有效。5.2 场景二Java 程序对接 SFTP 的密钥格式选择Java 生态里 SSH 库主要有三种JSch、Apache MINA SSHD、sshj。它们对密钥格式的偏好差别很大这是很多代码里加载密钥报错的根源。JSch 的老版本0.1.54 及以前只认 PEM 格式的 RSA 私钥喂给它 OpenSSH 新格式会抛invalid privatekey: [B...。如果出于历史原因必须用老 JSch转换步骤是# 1. OpenSSH 新格式 - PKCS#8 ssh-keygen -p -m PKCS8 -f id_rsa # 2. PKCS#8 - PKCS#1OpenSSL 3.x 要加 -traditional openssl pkcs8 -in id_rsa -topk8 -nocrypt -out id_rsa_p8.pem openssl rsa -in id_rsa_p8.pem -traditional -out id_rsa_pkcs1.pem chmod 600 id_rsa_pkcs1.pemApache MINA SSHD 相对现代新版本能直接读 OpenSSH 新格式也支持 PKCS#8。sshj 则借助 BouncyCastle兼容性最好但要确保bcpkix-jdk15on依赖版本够新老版本 BouncyCastle 读不了 Ed25519。实际项目里我一般这么定新写的代码统一用 OpenSSH 新格式或者 PKCS#8 未加密私钥算法用 Ed25519 或 RSA 4096只在对接第三方固定环境时才退回到 PKCS#1。另外私钥不要打包进 jar通过配置中心、环境变量或者只读挂载注入构建产物里带私钥是很典型的安全事故来源。还有个容易被忽略的点JSch 读加密私钥时密码是byte[]如果从String转过来要注意字符集一致否则密码正确也报invalid privatekey。统一用 UTF-8 编码转换。5.3 场景三Git 与远程开发环境的密钥配置GitLab、GitHub 用公钥认证这个简单把 OpenSSH 单行公钥贴到网页上就行。真正麻烦的是自建 GitLab 用非标准端口或者有跳板机的情况。# 生成一把专用密钥注释写清楚用途 ssh-keygen -t ed25519 -C deployci-runner-2024 -f ~/.ssh/gitlab_ci # 贴到 GitLab 的 SSH Keys 页面 cat ~/.ssh/gitlab_ci.pub如果 GitLab 部署在内网、需要通过跳板机访问~/.ssh/config要这样写Host gitlab-internal HostName 10.20.30.40 User git IdentityFile ~/.ssh/gitlab_ci ProxyJump bastion Host bastion HostName 203.0.113.5 User ops IdentityFile ~/.ssh/bastion_keyProxyJump是 OpenSSH 7.3 之后引入的比老式的ProxyCommand nc ...写法简洁得多也不依赖 netcat。测试连通性用ssh -T gitgitlab-internalVSCode Remote-SSH 这类远程开发工具底层也是调 OpenSSH~/.ssh/config里的配置会被直接识别。密钥加载失败时VSCode 的 Remote-SSH 输出面板会打印完整命令拿那个命令在终端里手跑一遍再配合-vvv通常三五分钟就能定位。需要留意的是Windows 上 VSCode 用的是系统 OpenSSH 还是 Git 自带的 OpenSSH行为可能不同读的配置文件路径也不一样C:\Users\你\.ssh\config是两个都读的但密钥格式支持范围有差异。遇到终端能连、VSCode 连不上先确认remote.SSH.path指向的是哪个ssh.exe。6. 报错速查与排查路径密钥转换的报错信息大多不太友好同一个报错可能对应好几种原因。我把常遇到的整理成表配一套固定的排查顺序。6.1 常见报错对照表报错信息常见原因处理办法Load key x: invalid format密钥是 OpenSSH 新格式工具只认 PEM或反之head -1确认格式用ssh-keygen -p -m PEM/PKCS8/OPENSSH转换Permissions 0644 for x are too open私钥权限过宽chmod 600 x同时确认.ssh为 700UNPROTECTED PRIVATE KEY FILE同上或私钥放在被同步的目录下移出共享目录收紧权限invalid privatekey: [B...Java JSch 老版本遇到非 PEM 格式转 PKCS#1 PEM或升级 JSch/改用 BouncyCastleerror in libcrypto密钥内容被意外截断或补了多余换行用tail -1检查结尾行是否完整重新转换key_load_private_type: bad passphrase口令错误或新旧工具 KDF 不兼容先用-N 去口令再转格式转完加回unsupported PuTTY key file versionPPK v3 文件喂给老 PuTTY重新生成为--ppk-param version2Too many authentication failuresssh-agent 里密钥过多配置IdentitiesOnly yes并指定IdentityFileno matching host key type found客户端与服务端算法协商不一致检查双方支持的算法列表必要时放宽HostKeyAlgorithmsunable to load keyOpenSSL 版本过低读不了 Ed25519 PKCS#8升级 OpenSSL或改用 RSA 密钥这张表覆盖了我日常遇到的八成问题。剩下的疑难杂症基本都能靠-vvv定位。6.2 一套固定的排查顺序密钥连不上按下面这个顺序走比乱试快得多。第一确认格式。head -1和tail -1各看一眼确认头尾标识配对中间没有多出来的空行、没有因为复制粘贴被插入 Windows 换行符。Windows 换行符CRLF会让 OpenSSH 在某些版本下解析失败用file key看输出里有没有CRLF有的话用tr -d \r处理或者dos2unix。第二确认权限。ls -l看私钥是不是 600、目录是不是 700。这一步看着傻但排查记录里它出现的频率高得离谱。第三确认指纹。ssh-keygen -lf对比服务和客户端记录的公钥指纹确认用的确实是同一把密钥。指纹对不上说明文件搞错了后面怎么调都没用。第四确认协商过程。ssh -vvv userhost输出里搜几个关键词Offering public key看客户端提供了哪些公钥Server accepts key看服务端接受了哪个Authentications that can continue看剩下的可选方式。如果Offering里根本没出现你的密钥问题在客户端配置IdentityFile路径写错、IdentitiesOnly没开如果出现了但被拒绝问题在服务端authorized_keys或权限。第五看服务端日志。/var/log/auth.logDebian 系或/var/log/secureRHEL 系里会记录拒绝原因Authentication refused: bad ownership or modes for file这类信息比客户端报错精确得多。7. 几条只有踩过才知道的经验写了这么多命令最后补几条纯经验性质的东西都是文档里不会写、但实际干活时反复用到的。关于用ssh-keygen -p批量转格式这个命令是就地覆盖的脚本里批量跑之前一定先cp。另外它会保留原有口令但在无人值守场景下会卡在交互提示加-P 旧口令 -N 新口令两个参数可以完全免交互。关于转换后的公钥私钥格式变了公钥文件里的内容是不变的AAAAB3NzaC1...那串 base64 完全一样。所以如果你只是把私钥从新格式转成 PEM服务器端的authorized_keys不需要改。这个认知能避免很多无谓的重复配置。关于注释字段OpenSSH 单行公钥末尾的注释userhost只是给人看的不参与认证计算。修改注释不会导致认证失败但会让指纹对比的输出看起来不一样容易吓自己一跳。管理多把密钥时我建议把注释写成用途-环境-生成日期比如deploy-staging-20240315半年后回头看能立刻分清哪把是哪把。关于别急着删老密钥格式转换做完验证新密钥能登录之后再去服务器上清理旧的authorized_keys条目。顺序反过来万一转换有问题你就得走控制台救援流程了。关于主机密钥和用户密钥是两回事Bitvise SSH Server 这类 Windows 服务端软件配置时要填的是主机密钥host key它是给服务端证明自己身份用的用户认证用的密钥对是另一套。这两个概念混了会配得莫名其妙。主机密钥要求 OpenSSH 格式PPK 得先转。关于算法选择的现实考虑Ed25519 又快又短但生态兼容性是短板老设备、老 Java 库、老网络设备都可能不支持。RSA 4096 兼容性最好但密钥长、握手慢。我现在的默认策略是新环境用 Ed25519需要对接老旧系统的场景单独生成一把 RSA 4096两把密钥并存各自用在合适的场景里别指望一把走天下。关于口令和自动化的折中完全无口令的私钥方便自动化但有风险每次都要口令的安全但不适合脚本。常见的折中是私钥带口令 ssh-agent缓存交互式场景体验好CI 环境则用受限的部署密钥配合服务端的command和from限制把密钥的权限边界框死。最后一条也是我觉得最重要的任何格式转换都留一份原始文件。我自己的目录结构是~/.ssh/keys/原始格式/和~/.ssh/keys/转换后/分开存放文件名带上格式后缀比如id_rsa.openssh、id_rsa.pkcs1.pem、id_rsa.pkcs8.pem、id_rsa.ppk。看起来啰嗦但当你需要在三种工具之间来回折腾时这种一份源文件、多种派生格式的组织方式能省掉大量重复劳动也避免了一不小心把唯一一份原始密钥转坏却没备份的尴尬。