GitHub 私有仓库的 SSH 访问配置这事说大不大说小不小。很多开发者平时 clone 公开仓库习惯了直接复制 HTTPS 链接回车就拉代码完全没意识到认证方式后面会变成拦路虎。可一旦项目切到私有仓库麻烦就来了——命令行开始要求输入账号密码开了两步验证之后密码根本不够用得去生成 Personal Access Token参数一长串权限要逐一勾选过期时间还得记着续。这种体验谁弄谁知道。这篇 SOP 就是把完整流程写清楚Mac 和 Windows 各来一套覆盖从生成密钥、配置 ssh-agent、把公钥放进 GitHub 账号到最后成功 clone 私有仓库的完整闭环。中间穿插大量实际踩过的坑比如权限报错、多账号密钥串场、粘贴公钥时多出来的换行符。很适合经常在终端里操作、手头有多台设备、或者需要写脚本自动拉私有仓库的开发者参考。照着做一遍后面就再也不碰密码和 token 了。1. 为什么私有仓库一定要配 SSH先把账算清楚1.1 HTTPS 和 SSH 的认证差异很多团队的代码仓库分布在不同的托管平台GitHub 是最常用的一种。平时 clone 公开仓库HTTPS 链接直接能用因为公开仓库不需要任何认证服务器允许匿名读取。私有仓库就不一样了它要验证“你是谁”还得确认“你被允许看这个仓库”。HTTPS 方式下认证过程通常是账号密码。但 GitHub 在几年前就强制要求开启两步验证的账号不能直接用密码来拉代码必须用 Personal Access Token 代替密码。这个 token 本质上是一串随机字符串在命令行输入时不能复制粘贴错一个字符过期了还得重新生成。要是你管理多个仓库、多台机器token 的创建和分发就成了纯粹的体力活。SSH 方式则是另一种逻辑本地生成一对密钥公钥放在 GitHub 账号里私钥留在本地。每次连接时服务器用公钥验证你的身份过程是全自动的不需要输密码也不需要 token。只要你把私钥交给本地的 ssh-agent 管着后面所有 Git 命令都是静默认证。1.2 私有仓库场景下 SSH 的优势私有仓库的价值在于“只有授权的人能看”。这个场景下SSH 的优势非常明显第一免密。配置一次长期使用。无论 clone、pull 还是 push都不需要输入任何认证信息。第二安全。SSH 传输过程中的数据加密强度高于 HTTPS 的常规认证方式私钥本身可以额外设置 passphrase 进行二次保护。第三可编程。脚本、CI 流程、定时任务里写 Git 命令时不用在代码里嵌入密码或 token直接调用 SSH 即可。对个人开发者来说平时可能感受不深但真到需要自动化部署、服务器拉代码、多台电脑同步项目的时候SSH 几乎是唯一体面的方案。1.3 这篇 SOP 覆盖的范围和适用人群这份配置文档覆盖 Mac 和 Windows 两套系统。Mac 走终端命令行Windows 走 PowerShell底层原理一致命令略有差异。适用的人群很广刚接触私有仓库的新手、经常在多台设备间切换的开发者、需要为团队整理环境配置文档的运维同学。你不需要很懂密码学只需要照着命令敲理解每一步在干什么就行。2. 弄清楚 SSH 的工作链路配置才不会翻车2.1 公钥和私钥到底谁是锁谁是钥匙很多人第一次接触 SSH 密钥时会被“公钥”“私钥”这两个名字绕晕。用开锁来类比就特别简单私钥是钥匙公钥是锁。你把锁公钥交给 GitHub钥匙私钥自己留着。别人连接 GitHub 时服务器拿出锁来只有你手里的钥匙能对上身份就通过了。GitHub 保存的是公钥放在你账号的 SSH and GPG keys 设置页里。私钥永远不离开本地任何平台、任何客服都不应该要求你提供私钥内容。一旦私钥泄露等于把钥匙丢了别人就能拿它访问所有配置了对应公钥的仓库。本地生成的密钥文件一般有两个id_ed25519是私钥id_ed25519.pub是公钥。上传到 GitHub 的永远是.pub结尾的那份。2.2 一次 SSH 连接过程中的身份验证逻辑完整过程可以简化成三步第一步本地 Git 发起连接SSH 客户端会读取~/.ssh/目录下的密钥文件尝试用私钥回应服务器的挑战。第二步服务器根据配置判断这个公钥是否存在于某个 GitHub 账号下如果存在则验证通过。第三步验证成功后GitHub 会放行并且标记出是哪个账号连接进来的。这个过程中有个细节值得注意SSH 默认尝试的密钥文件是id_rsa或id_ed25519如果你的密钥用了其他文件名git 不会自动识别必须在~/.ssh/config里显式指定。很多“为什么我明明传了公钥还是连不上”的问题根源就出在这。2.3 ssh-agent 是干什么的ssh-agent 是一个后台服务负责在内存里缓存已经解锁的私钥。它的价值体现在一个很实际的场景你给私钥设置了 passphrase建议设那么每次 SSH 连接时客户端都会要求输入这个口令。有了 ssh-agent你只需要在开机后或会话开始时解锁一次之后所有 Git 操作都不再询问。Mac 和 Windows 都自带 ssh-agent只是默认状态和行为不同。Mac 需要手动启动Windows 则默认停用服务需要在服务管理器或 PowerShell 里开启。2.4 先认识配置文件SSH 的配置文件在 Mac 和 Linux 下是~/.ssh/configWindows 下是C:\Users\用户名\.ssh\config。这个文件不存在也没关系需要时自己创建。它存在的意义是让你对 SSH 连接做更精细的控制指定密钥文件、区分多账号、修改端口、配置连接超时等。后面会专门讲这个文件的具体写法这里先建立一个概念没有 config 的时候SSH 走默认行为有了 config一切按你写的规则来。3. Mac 端配置从生成密钥到克隆第一份私有仓库3.1 生成密钥对优先 ed25519打开终端先看一下~/.ssh目录是否存在避免一会儿生成密钥时被提示覆盖已有文件。ls -la ~/.ssh如果目录不存在就用mkdir -p ~/.ssh创建。然后生成密钥ssh-keygen -t ed25519 -C 你的邮箱或备注信息 -f ~/.ssh/id_ed25519这里的-t ed25519指定密钥类型-C是注释方便你在 GitHub 上识别哪台机器生成的密钥-f指定保存路径和文件名。为什么推荐 ed25519 而不是传统的 RSA两点原因一是签名速度更快密钥更短二是在目前的安全标准下ed25519 的安全性更高GitHub 官方也推荐使用。老机器或老系统如果遇到兼容性问题再退回 RSAssh-keygen -t rsa -b 4096 -C 你的邮箱或备注信息 -f ~/.ssh/id_rsa生成过程中会提示设置 passphrase也就是使用私钥时额外要求输入的口令。建议设置尤其笔记本容易丢失的场景下这相当于给钥匙再加一道锁。3.2 把私钥交给 ssh-agent生成完成后启动 ssh-agent 并把私钥加进去eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519如果私钥设置了 passphrase执行ssh-add后会要求输入一次。输入正确后私钥就被缓存在内存里后续连接不再询问。有个常见问题Mac 重启之后 ssh-agent 会清空下次 Git 操作又要求输入 passphrase。解决方法是把启动和添加命令写进 shell 配置比如在~/.zshrc末尾追加eval $(ssh-agent -s) /dev/null ssh-add ~/.ssh/id_ed25519 /dev/null 21这样每次打开新的终端窗口私钥自动加载。3.3 把公钥上传到 GitHub复制公钥内容最简单的方式是用pbcopy它会直接把内容送入剪贴板pbcopy ~/.ssh/id_ed25519.pub复制完公钥后打开 GitHub 网页进入右上角头像菜单的 Settings找到 SSH and GPG keys点击 New SSH key。Title 随便填比如“MacBook Pro 2024”Key 类型保持默认的 Authentication Key然后粘贴公钥内容点 Add SSH key。这一步最容易犯的错就是把id_ed25519私钥内容贴上去。记住带.pub后缀的才是公钥。3.4 测试连接并确认指纹密钥上传完成后先做一次连通性测试ssh -T gitgithub.com第一次连接时SSH 会提示无法确认主机真实性询问是否继续连接列出指纹。这是正常现象输入yes回车即可。如果一切正常终端会出现类似这样的提示Hi 用户名! Youve successfully authenticated, but GitHub does not provide shell access.看到这行字说明公钥已经和账号绑定成功。那个用户名的位置会显示你的 GitHub 账号名可以用来确认当前生效的是哪个账号。3.5 实际 clone 私有仓库认证通了clone 操作就很简单。在 GitHub 仓库页面选择 SSH 形式的地址形如gitgithub.com:用户名/仓库名.git然后执行git clone gitgithub.com:用户名/私有仓库名.git如果是已经用 HTTPS 方式 clone 过的本地仓库想切换成 SSH不需要重新 clone直接改 remote 地址git remote set-url origin gitgithub.com:用户名/仓库名.git之后所有 pull 和 push 都走 SSH 通道免密执行。4. Windows 端配置PowerShell 与系统自带的 OpenSSH4.1 确认 OpenSSH 客户端是否安装Windows 10 和 Windows 11 都自带 OpenSSH 客户端但也有个别精简版系统没有启用。在 PowerShell 里先确认Get-Command ssh如果能返回一条命令路径说明已经安装。如果没有可以打开“设置 - 应用 - 可选功能”勾选 OpenSSH 客户端后安装。装完重新打开 PowerShell 再确认一次。4.2 在 PowerShell 中生成密钥生成密钥的命令和 Mac 上基本一致只是默认路径不同ssh-keygen -t ed25519 -C 你的邮箱或备注信息Windows 下默认保存路径是C:\Users\你的用户名\.ssh\id_ed25519。按回车确认默认路径即可或者手动指定路径也行。生成过程同样会提示设置 passphrase建议设置。这一步完成后检查一下公钥文件Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub输出的内容就是需要传到 GitHub 的公钥。4.3 启动 ssh-agent 并加载私钥Windows 的 ssh-agent 默认是停用状态。如果不开启每次 Git 操作都要手动输入私钥的 passphrase非常影响体验。管理员身份打开 PowerShell依次执行Get-Service ssh-agent Set-Service -Name ssh-agent -StartupType Automatic Start-Service ssh-agent第一条用来查看当前状态第二条设置开机自启第三条立即启动服务。启动完成后加载私钥ssh-add $env:USERPROFILE\.ssh\id_ed25519同样如果设置了 passphrase这一步会要求输入一次之后就不再询问。4.4 公钥上传与连接验证在 PowerShell 里复制公钥内容一条命令搞定Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard然后去 GitHub 网页按 Mac 篇里说的流程Settings - SSH and GPG keys - New SSH key粘贴并保存。测试连接ssh -T gitgithub.com第一次连接需要确认指纹输入yes。看到Hi 用户名!就说明通了。4.5 遇到 22 端口不通时的备用方案SSH 默认走 22 端口。有些办公网络、公共 WiFi 或部分校园网环境会限制这个端口连接会一直卡住超时。GitHub 官方提供了备用方案改用 443 端口连接。做法是在~/.ssh/config文件里写入以下内容Host github.com HostName ssh.github.com Port 443 User git其实这段配置在 Mac 上也适用哪边遇到端口受限都可以采用。配置完成后直接按之前的命令 clone 或测试正常走 443 通道。5. ~/.ssh/config 配置详解解决多账号、多仓库、端口问题5.1 为什么需要 config 文件如果没有 config 文件SSH 会按默认方式寻找密钥。当你只有一个账号、一把密钥时完全够用。但现实中很容易出现这些情况同时使用个人账号和公司账号希望不同仓库走不同密钥给 Git 仓库设定了非默认端口的代理服务需要给某些慢网络环境设置连接超时。这些场景都是默认行为覆盖不了的这就需要 config 文件来兜底。config 文件不是 Git 的文件而是 SSH 客户端的配置文件~/.ssh/config或者 Windows 的C:\Users\用户名\.ssh\config。不存在就手动创建文件名可以没有后缀但内容格式必须正确。5.2 最小可用配置长什么样一个最简单的 config 可以这样写Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yes逐行解释一下Host连接别名写 github.com 时表示这个配置块专门作用于目标地址为 github.com 的连接。HostName实际连接的服务器域名一般和 Host 一样。User连接用户名GitHub 固定填 git。IdentityFile指定使用哪个私钥文件。IdentitiesOnly yes强制只使用这里指定的密钥不尝试其他密钥避免多密钥时搞混。有了这个配置即使你的私钥文件名不叫id_ed25519Git 也能正确识别。5.3 多个 GitHub 账号的隔离配置假设你有个人账号 A 对应的密钥是id_ed25519_personal公司账号 B 对应的密钥是id_ed25519_work。两个密钥都要存到~/.ssh/下然后在 config 里定义两个别名Host github.com-personal HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal IdentitiesOnly yes Host github.com-work HostName github.com User git IdentityFile ~/.ssh/id_ed25519_work IdentitiesOnly yes注意这里Host是自定义别名不是真的域名。clone 个人仓库时要把仓库地址改写成gitgithub.com-personal:用户名/仓库名.gitclone 公司仓库时则用gitgithub.com-work:用户名/仓库名.git关键在于SSH 客户端看到别名github.com-personal会去 config 里找这个 Host然后按照HostName github.com真正连到 GitHub再使用指定的私钥文件。这样两套账号互不干扰。已经 clone 过的仓库用git remote set-url origin gitgithub.com-personal:用户名/仓库名.git改一下地址就能切换。5.4 config 文件里的权限和放置位置Mac 和 Linux 对~/.ssh目录及文件权限很敏感。如果目录或文件的权限太开放SSH 会直接拒绝使用该密钥并提示Bad owner or permissions。正确权限是目录~/.ssh设为700私钥文件设为600chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519Windows 上通常不需要手动改权限但要注意 config 文件必须放在当前用户的.ssh目录下而不是系统级目录。6. 实操中踩过的坑权限、多密钥、换行符6.1 Permission denied (publickey) 的标准排查顺序这是最经典的报错公钥配好了连接时却报Permission denied (publickey)。遇到这个问题我建议按顺序排查第一步确认当前用的是 SSH 地址而不是 HTTPS 地址git remote -v看一眼。第二步确认密钥已经加入 ssh-agent执行ssh-add -l能看到指纹列表说明已加载。第三步用调试模式连接一次ssh -vT gitgithub.com输出里会显示尝试了哪些密钥文件。重点看最后一两行如果提示Offering public key后面跟着的不是你上传到 GitHub 的那个公钥文件名说明密钥选错了检查 config 文件的 IdentityFile 配置。第四步确认 GitHub 账号里确实添加了对应的公钥去网页端检查有的团队会用多个账号注意别加到另一个账号下。6.2 Bad owner or permissions 的修复Mac 上隔一段时间就会出现一次原因通常是密钥文件是从压缩包或移动硬盘解压出来的权限位被打乱了。SSH 为了保证安全遇到私钥文件权限过大会直接拒绝使用。修复方法就两条命令chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519如果密钥文件名不是默认的记得把id_ed25519换成你的实际文件名。Windows 上极少出现这类报错但如果你手动把密钥文件复制过来也可能遇到直接重新设置文件权限或重新生成密钥即可。6.3 公钥粘贴时的小坑换行和多余字符有一次某同事说密钥已经上传了但就是连不上。我远程看了半小时最后发现公钥粘贴到 GitHub 时末尾多了一个换行符GitHub 的输入框没做严格的去空格处理导致密钥内容不匹配。解决办法是上传公钥前先确认复制的内容只有一行。Mac 上用cat ~/.ssh/id_ed25519.pub看一下有没有多出来的空行。Windows 上用Get-Content输出检查。粘贴完成后再回到终端测试一次基本能定位问题。另外要注意公钥内容是一段 base64 编码的字符串中间是连续字符不要从网页上手动框选复制。因为网页端的换行渲染有时会打乱内容最好始终用命令读取、用剪贴板复制。6.4 常见问题速查表现象可能原因解决方案Permission denied (publickey)密钥未上传 / 密钥选错 / remote 用了 HTTPS检查 GitHub 公钥用 ssh -T 测试切换为 SSH 地址Bad owner or permissions密钥权限过宽chmod 700 ~/.ssh chmod 600 私钥连接超时22 端口被网络限制config 里改 HostName ssh.github.com Port 443每次操作都要输入 passphrasessh-agent 未启动或未加载eval $(ssh-agent -s) ssh-add多账号 clone 到错误仓库密钥串用config 里显式指定 IdentityFile加 IdentitiesOnly yes上传公钥后仍验证失败公钥粘贴出现换行/多余字符用命令复制检查内容是否为一整行6.5 一个容易忽略的细节git 的 core.sshCommand极少数情况下Git 未必会使用系统默认的 SSH 命令尤其是 Windows 环境和一些特殊的 Git 安装方式。如果上述排查都无效可以尝试显式指定 SSH 显卡git config --global core.sshCommand ssh正常情况下不会用到但列在这里算是一个兜底方案。7. 日常维护与安全管理的几条心得7.1 私钥保护是底线私钥文件等同于你访问私有仓库的通行证。不该把它发送到聊天工具、不该放到云盘的明文备份里、更不该提交到 Git 仓库。如果确有备份需求应该使用加密压缩或密码管理器存储。另外当发现私钥可能泄露时及时去 GitHub 删除对应公钥并重新生成一对新的密钥这是成本最低的止损方式。7.2 passphrase 的取舍建议前面提到建议设置 passphrase。很多人嫌麻烦但换个场景想笔记本丢失了没有 passphrase 的私钥相当于不设防的钥匙捡到电脑的人直接就能 clone 你的私有仓库。设置了 passphrase即使文件也被拷贝走对方猜不出口令就无法使用。日常使用中有了 ssh-agentpassphrase 只需要在开机后输入一次代价很小。唯一要注意的是 Mac 重启后 ssh-agent 会清空前面说过把这步写进 shell 配置里重新打开终端自动解锁一次体验就顺畅多了。7.3 密钥轮换的时机不需要像改密码那样频繁轮换但有些节点建议换离职或团队权限变化时笔记本报废回收时怀疑私钥泄露时超过一年半载没什么实际动作且面临风险窗口时。轮换的流程很简单生成新密钥更新 GitHub 公钥本地切换配置然后从 ssh-agent 里删掉旧密钥。7.4 多设备之间的密钥管理常见误区是把同一把私钥复制到所有设备。这样做的问题是某台设备丢失或被人接触你需要同时更新所有设备的公钥而且被克隆出去的风险更高。更推荐的做法是每台设备生成独立的密钥对分别登记到 GitHub。这样你在 GitHub 后台可以看到每个设备的公钥列表哪台设备不需要访问了单独删掉它对应的公钥即可不影响其他设备。我把这套方案已经用了很久最大的感受是私有仓库的 SSH 配置麻烦只在前十分钟。跑通一次之后后面所有 Git 操作都安静得让人忘记认证这回事。换新电脑、重装系统、加新仓库照着这篇 SOP 走一遍基本没有意外。最后分享一个小技巧生成密钥后把公钥文件的内容贴在密码管理器或团队内部的知识库里各存一份。公钥本身不是敏感信息丢失也无妨但这样你在补充新设备配置时不需要重新生成密钥直接把旧公钥复制到 GitHub 新账号就行效率会高不少。