Bitbucket新旧版添加SSH Key全指南：入口变化与避坑实操

做了一阵子Git托管，发现很多人还卡在Bitbucket新旧界面切换的坎上。尤其是2021年7月那次改版之后，原来在个人设置里直接填SSH Key的地方挪了窝，不少同事第一反应是“入口怎么没了”。这篇文章就专门对比一下旧版和新版Bitbucket添加SSH Key的完整流程，把入口差异、填表字段、保存逻辑和验证方式都理清楚，顺便把我自己踩过的坑也一并交代了。

1. 为什么添加SSH Key的入口会发生这么大变化

1.1 账户体系的调整是根源

旧版Bitbucket的SSH Key管理是挂在Bitbucket账号下的，登录后进Personal settings就能看到SSH keys选项，逻辑非常简单：这个密钥属于当前登录的Bitbucket用户。新版则把SSH Key的管理收拢到了Atlassian账户层面，因为Bitbucket已经全面切换到Atlassian账号体系。也就是说，你添加的SSH Key不再只服务于某一个Bitbucket工作区，而是绑定在整个Atlassian账户名下，所有关联的Bitbucket工作区、Jira站点、其他Atlassian产品都能共用这套密钥。

这个改动从产品层面看是合理的，统一密钥管理确实比各产品各管一套方便。但对老用户来说，最直观的感受就是入口变了，甚至跳转路径会先经过Atlassian账户管理页面。如果不了解这层背景，就会一直在旧版记忆里的Personal settings里找那个熟悉的SSH keys按钮，结果发现位置完全不一样。

1.2 改版后Bitbucket的Workspace概念

改版后Bitbucket引入了Workspace的概念，替代了原来的Team和User主页。原来的个人仓库地址从bitbucket.org/username/repo变成了bitbucket.org/workspace/repo，虽然很多老仓库做了自动跳转，但权限模型已经重构了。SSH Key和Workspace的关系也值得说明：新版里密钥挂在Atlassian账户下，但实际访问仓库时，是账户映射到Workspace成员身份，再由Workspace的权限配置决定你能读写哪些仓库。

这就会引出一些奇怪的现象：假设你在公司A的Workspace下用账户A添加了SSH Key，换到公司B的Workspace时，如果两个Workspace都绑定了你的Atlassian账户，那么同一把密钥可以访问两个Workspace下你有权限的仓库。这种跨工作区共用密钥的机制，是旧版没有的，也是很多人在新版配置时感到困惑的点。

2. 旧版流程回顾：一张表单走天下

2.1 旧版入口定位

旧版Bitbucket的界面以蓝色和灰色为主，左侧菜单结构比较清晰。登录后点击右上角头像，下拉菜单里直接有Personal settings，进去之后左侧列表有一项是SSH keys，点击就能进入管理页。整体路径就是：头像 → Personal settings → SSH keys。

那个时代还有个习惯性操作：进入SSH keys页面后，列表会展示你已经添加过的密钥，包括Label、指纹（Fingerprint）、添加时间等。页面顶部有一个Add key按钮，点击后弹出表单，需要填写两个字段：

• Label：给密钥起个名字，比如“MacBook Pro 2023”或“company-workstation”
• Key：粘贴公钥内容，也就是id_rsa.pub或id_ed25519.pub文件里的完整文本

表单很简洁，没有额外的密钥类型或过期时间选项，保存后直接在列表里能看到新密钥。整个过程30秒内能完成，不需要任何额外的账户验证或跳转。

2.2 旧版密钥生成的配套命令

旧版时代，大家生成密钥的方式也比较统一。我一般推荐用Ed25519算法，因为密钥短、安全性高、兼容性也够好。生成命令如下：

bash复制ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/bitbucket_ed25519

-t指定算法，-C是注释，通常会填邮箱便于识别，-f指定生成的文件路径。如果直接用默认路径，按回车用默认的id_ed25519也行。生成后，把公钥内容复制出来：

bash复制cat ~/.ssh/bitbucket_ed25519.pub

复制以ssh-ed25519开头的一整行内容，粘贴到Bitbucket的Key输入框里，Label随便填一个方便识别的名字，提交保存。为了测试是否生效，执行：

bash复制ssh -T git@bitbucket.org

旧版返回信息里面会直接显示你的用户名，类似“authenticated via ssh key as username”，看到这个就说明密钥添加成功，可以正常拉取和推送仓库了。

2.3 旧版容易忽略的两个细节

旧版虽然流程简单，但有两个细节需要留意。第一个是如果你本地有多个SSH Key，需要检查~/.ssh/config里是否配置了Host别名。否则ssh会默认尝试使用id_rsa或id_ed25519，不会自动匹配你的bitbucket专用密钥文件。我当时就遇到过这种情况，明明公钥已经粘贴到Bitbucket里了，但ssh -T就是报Permission denied，排查了半天发现是ssh在尝试用默认密钥连接，而默认密钥根本没有添加到Bitbucket里。

第二个细节是，旧版复制公钥时很容易把换行符也带进去，或者选多了末尾的空格。在网页表单里，粘贴时哪怕多了一个空格，保存后测试也会报错。所以建议复制公钥后，用文本编辑器打开确认首尾没有多余空格或空行，再粘贴到表单里。这个习惯直到今天依然适用，新版也一样。

3. 新版流程详解：入口变了，但核心逻辑更清晰

3.1 新版入口的真实路径

新版Bitbucket的界面是黑白风格，整体更清爽，但改动也更大。添加SSH Key的入口有几个方式可以到达，我说一下自己常走的一条：

登录bitbucket.org后，点击左下角的头像，弹出菜单选择Personal settings，进入后左侧菜单列表里有SSH keys，点击会出现一个重定向提示，跳转到Atlassian账户管理页面。跳转后的地址一般是https://id.atlassian.com/manage-profile/security/ssh-keys，也就是Atlassian账户的安全设置页。

如果说得再直白一点：新版Bitbucket实际上没有自己独立的SSH Key管理页面了，它把这个功能委托给了Atlassian账户中心。你在Bitbucket界面点击SSH keys，最终会被带到Atlassian账户的设置中心去操作。这个跳转是自动的，不需要额外选择什么，但初次操作的人很容易觉得“怎么跑到另一个网站去了”，误以为操作出错了。

另一种更快的方式是直接访问https://bitbucket.org/account/settings/ssh-keys/，然后让浏览器自动跳转到Atlassian页面。如果你已经是登录状态，跳转后直接就进入SSH keys列表页，中间不需要输入密码。如果之前没有登录，Atlassian会先要求你输入账户密码，甚至要完成两步验证，然后才能进入密钥管理页面。

3.2 新版页面的字段变化

新版SSH Key添加页面比旧版多了几个字段，这里逐个说一下：

• Name：必填项，相当于旧版的Label，给密钥起名用，便于识别
• SSH key type：这个字段是旧版没有的。通常情况下选择Authentication key，用于Git操作的认证。还有一个选项是Signing key，用于Git提交签名。如果只是普通拉取推送代码，选Authentication key就够了；如果你还需要用SSH密钥对提交进行签名，那需要单独再添一把Signing key
• Public key：粘贴公钥内容，和旧版一样
• Expiration date：新增的可选字段，可以设置密钥的过期时间。如果设置了过期时间，到期后密钥会失效，需要重新添加。这个功能对企业安全策略比较友好，个人使用通常不填，保持无过期状态

保存按钮在填写完所有字段后才会变得明显。注意，新版在保存时如果检测到公钥格式有问题，会直接在公钥输入框下方提示错误，比如“Key is invalid. It must be a valid SSH public key”。这个校验比旧版严格，但我认为是一件好事，能提前发现复制错误的问题。

3.3 新版保存后的验证机制

新版保存密钥后，返回列表页就能看到新添加的密钥，但列表里显示的字段比旧版多，包括名称、类型、指纹、过期时间。指纹通常显示为SHA256格式，如下：

text复制SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

这个时候执行ssh -T git@bitbucket.org验证，返回信息和旧版略有不同。我实测的新版返回是：

text复制authenticated via ssh key.

You can use git to connect to Bitbucket. Shell access is disabled.

这个返回信息不再直接显示你的用户名，因为Atlassian账户和Bitbucket用户名之间的映射关系可能不是一一对应。如果关联了多个Workspace，返回的信息也不会告诉你具体经过的是哪个Workspace，只确认密钥有效。这一点和旧版体验有明显差别，如果脚本里依赖旧版返回的用户名做判断，需要调整。

4. 新旧版核心差异对照与应用建议

4.1 新旧版流程差异对照表

我整理了一张表格，把新旧版的关键差异放在一起，方便快速对比：

这个表基本覆盖了我在实操中遇到的差异。如果你正在从旧版迁移到新版，最需要适应的就是入口跳转和字段变化。前者属于操作路径变化，后者属于配置自由度提升，整体逻辑不难。

4.2 从旧版迁移到新版时的密钥处理策略

如果你之前已经在旧版添加过SSH Key，改版后这个密钥不会自动迁移到新的Atlassian账户体系。因为存储位置发生了变化，Bitbucket和Atlassian账户中心在数据迁移时没有做SSH Key的同步迁移。我遇到过不止一个用户问“为什么之前能正常推送，改版后就突然报错”，原因就是这个：旧密钥没有迁移过来，需要在新版重新添加一遍。

我的建议是，不要直接把旧密钥的公钥重新粘贴一次这件事做太急，而是先检查本地密钥文件是否还在。因为很多人的公钥和私钥存放在~/.ssh目录下，重装系统或更换电脑后就遗失了。如果本地密钥还在，直接拿旧的公钥内容粘贴到新版即可；如果本地密钥丢了，需要重新生成一把新密钥，并把新公钥添加到Bitbucket，同时更新所有使用旧密钥的本地仓库连接。

重新生成密钥时，建议不要覆盖旧的密钥文件，尤其当你有其他平台（比如GitHub、GitLab）还在使用同一把密钥时。稳妥的做法是新建一个专用密钥文件，然后通过~/.ssh/config配置不同的Host来区分不同平台，避免相互干扰。具体配置方式我在后面一节会详细讲。

4.3 新版中管理多个Workspace时的密钥策略

新版因为密钥绑定在Atlassian账户上，所有Workspace共享同一把密钥。这个机制在个人使用场景下很舒服，不用每加一个Workspace就重新添一次密钥。但在企业场景下可能有隐患：如果你同时在A公司的Workspace和B公司的Workspace中都是成员，那么你本地这把密钥对两个公司的仓库都有访问权限（前提是你在对应Workspace里有相应项目权限）。

这种情况下，从安全角度考虑，可以给不同的Workspace配置不同的密钥。具体来说，为A公司生成一把密钥，为B公司生成另一把密钥，然后在~/.ssh/config里通过Host配置来区分不同的仓库域名。但Bitbucket的多Workspace共享同一个域名bitbucket.org，要基于不同Workspace使用不同密钥，需要借助URL重写或别名配置，稍微有点绕。

我自己的做法是：个人用途统一用一把密钥，工作用途单独一把密钥，两把都添加到同一个Atlassian账户下。这样无论访问哪个Workspace的仓库，都能通过账户关联到正确的密钥。虽然Atlassian账户允许添加多个密钥，但Git连接时具体使用哪一个，取决于本地的SSH配置，而不是Bitbucket端。所以本地ssh-agent和config管理是真正决定用哪把密钥的关键。

5. 本地SSH配置与连接验证的完整实操

5.1 生成公钥和私钥的推荐步骤

不管新旧版Bitbucket，操作的前提都是本地有一对SSH密钥。以我个人的习惯，我推荐用Ed25519算法，生成命令如下：

bash复制ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/bitbucket_ed25519

执行后会提示设置passphrase，也就是私钥密码。这里我建议设置一个，虽然每次SSH连接时会要求输入密码，但可以配合ssh-agent把私钥加载到内存里，只需在开机后输入一次即可。如果完全不想输密码，直接回车跳过，安全性会低一些，看个人取舍。

密钥生成完成后，当前目录下会多出两个文件：bitbucket_ed25519（私钥）和bitbucket_ed25519.pub（公钥）。注意私钥文件的权限最好设置为600，公钥设置为644，避免被其他用户读取。如果权限不对，SSH会拒绝使用该密钥，这也是一个高频问题。

5.2 配置~/.ssh/config提升连接效率

如果你本地只有一把密钥，那么不配置config也能正常连接。但如果像我一样，同时使用GitHub、GitLab、Bitbucket多个平台，就必须用config文件来管理。我的~/.ssh/config里Bitbucket相关配置如下：

text复制Host bitbucket.org
  HostName bitbucket.org
  User git
  IdentityFile ~/.ssh/bitbucket_ed25519
  IdentitiesOnly yes

这里的User固定填git，因为Bitbucket的SSH连接用户就是git，不要改成你的Bitbucket用户名。IdentityFile指定私钥路径，IdentitiesOnly yes表示只使用这里指定的密钥，不尝试其他可用密钥。这个配置能避免SSH客户端优先尝试默认密钥而导致的认证失败问题。

需要注意，如果你有多个Bitbucket相关配置，Host不能重复。一个Host块对应一个主机别名，如果Bitbucket的多个Workspace想用不同密钥，可以把Host写成别名，比如：

text复制Host bitbucket-work
  HostName bitbucket.org
  User git
  IdentityFile ~/.ssh/bitbucket_work

然后在clone仓库时，把git@bitbucket.org:workspace/repo.git替换成git@bitbucket-work:workspace/repo.git。这样就能实现不同密钥访问不同仓库。操作上多一步，但权限隔离更清晰。

5.3 测试连接与常见报错解读

配置完成后，执行测试命令：

bash复制ssh -T git@bitbucket.org

成功时新版返回的是“authenticated via ssh key”，旧版返回的则是“authenticated via ssh key as 用户名”。这两者的区别前面已经说过，不再赘述。如果返回的是：

text复制Permission denied (publickey)

说明SSH没有成功通过密钥认证。排查思路按顺序来：

• 检查公钥是否完整粘贴到了Bitbucket或Atlassian账户中心
• 检查本地私钥路径是否和~/.ssh/config里配置的一致
• 检查私钥文件权限是否为600
• 检查ssh-agent是否加载了正确的密钥，用ssh-add -l查看已加载的密钥列表
• 如果启用了IdentitiesOnly，确认指定的IdentityFile路径没有拼写错误

还有一个比较隐蔽的问题是，如果你之前用旧版界面添加过密钥，而改版后密钥没有迁移，那么即使本地配置全部正确，也会报Permission denied。这时需要登录Atlassian账户中心，确认是否有当前密钥对应的公钥记录。

5.4 多平台共存时的ssh-agent管理技巧

当本地存在多个平台的密钥时，ssh-agent的管理容易出问题，尤其是MacOS和Linux上。默认情况下，SSH会尝试加载所有默认位置的密钥，比如~/.ssh/id_rsa、~/.ssh/id_ed25519等。如果你把Bitbucket的密钥保存为id_ed25519，同时又需要GitHub使用另一把密钥，可能会出现密钥串用的情况。

解决方案有两类。一是采用非默认文件名，比如bitbucket_ed25519、github_ed25519，配合config文件里的IdentityFile指定路径。二是保持默认文件名，但只在ssh-agent里加载当前需要使用的密钥。我个人更推荐第一种，因为config文件能明确控制每个Host使用什么密钥，避免ssh-agent里多把密钥都能匹配时产生混乱。

如果使用非默认文件名，记得在config里加IdentitiesOnly yes，这个选项能避免SSH在服务器允许任意密钥时先尝试其他已加载密钥。实测下来，这个配置能减少很多莫名其妙的认证失败情况。

5.5 在Windows上使用新版Bitbucket的密钥配置

Windows用户的配置路径和Mac/Linux稍有不同。Windows 10及以上版本自带OpenSSH客户端，密钥默认存放在C:\Users\你的用户名.ssh目录下。生成密钥用同样的命令，只是路径换成Windows格式。比如：

powershell复制ssh-keygen -t ed25519 -C "your_email@example.com" -f $env:USERPROFILE\.ssh\bitbucket_ed25519

config文件路径是C:\Users\你的用户名.ssh\config，内容和Mac/Linux一致。Windows下需要特别注意权限设置，密钥文件的权限不能像Linux那样直接chmod 600，需要通过文件属性里的安全选项卡修改权限，或者用icacls命令：

powershell复制icacls $env:USERPROFILE\.ssh\bitbucket_ed25519 /inheritance:r /grant:r "$env:USERNAME:F"

如果这一步没做，OpenSSH会拒绝加载私钥，报错类似“UNPROTECTED PRIVATE KEY FILE”。网上很多教程忽略了Windows的权限问题，我第一次在Windows上配置时就卡在这里，花了不少时间排查。

6. 实际操作中最容易踩的坑与避坑方案

6.1 密钥迁移遗漏导致推送失败

我前面提到，新旧版切换时旧密钥不会自动迁移。实际案例是，有一个同事在公司电脑上一直正常使用Bitbucket，某天突然推送代码时被拒，报错内容是：

text复制Permission to workspace/repo.git denied to previous key

检查后发现，他本地使用的密钥是旧版添加的，改版后旧密钥被Bitbucket端标记为过期或已移除，而Atlassian账户中心里并没有对应的公钥。重新在新版添加同一把公钥后，推送立刻恢复正常。

所以，如果你在改版后还没重新配置过Bitbucket的SSH Key，建议抽空把本地公钥内容重新粘贴到Atlassian账户中心。即使之前的仓库还能正常访问，也建议提前操作，避免某天Bitbucket端彻底清理旧密钥数据时被动出问题。

6.2 公钥复制不完整导致格式校验失败

新版对公钥格式的校验严格很多，如果复制时遗漏了“ssh-ed25519”前缀，或者多复制了换行符，保存时就会报错。这类错误在旧版里有时不会立即暴露，因为旧版的校验逻辑比较宽松。我的建议是复制公钥后，先检查开头是否为ssh-rsa或ssh-ed25519，再看结尾是否有邮箱注释。

text复制ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK... your_email@example.com

格式基本保持这个结构。如果公钥内容里包含了多余的tab或空格，也会被视为非法。稳妥的做法是在终端里直接执行cat命令查看，然后用鼠标从开头拖到结尾，确保完整选中。

6.3 多密钥时确定生效密钥的排查工具

当你配置好了多把密钥，但不确定实际连接Bitbucket用的哪一把，可以用以下命令查看细节：

bash复制ssh -vT git@bitbucket.org

-v参数会输出详细的调试信息，包括尝试加载了哪些密钥文件、发送给服务器的公钥指纹等。找到类似“Offering public key”的行，就能看到实际尝试的密钥路径。如果输出里始终没有出现你预期的密钥，说明config配置有问题，或者IdentityFile路径写错了。

还有一个小技巧是使用ssh-add -l列出当前ssh-agent中的密钥，看看实际加载了哪些。如果密钥没有加载到agent里，而且在config里也没有正确指定IdentityFile，SSH可能根本不会尝试使用这把密钥。

6.4 新版本地仓库URL的调整要求

改版后，Bitbucket的仓库远程地址虽然大部分沿用旧格式，但如果你创建的是新版Workspace下的新仓库，远程URL里的路径格式可能会变化。比如：

text复制git@bitbucket.org:workspace/repo.git

如果你的本地仓库是从旧版clone下来的，远程URL可能还是旧版格式，比如带有用户名路径。当Bitbucket端做了账号迁移后，这个URL可能失效。检查方式很简单：

bash复制git remote -v

如果输出的远程地址格式和Bitbucket网页上显示的Clone地址不一致，用git remote set-url更新一下即可。这个操作和SSH Key本身无关，但很多人会在排查SSH问题时误以为是密钥的问题，结果折腾了半天其实是远程地址不对。

7. 个人体会与最终建议

说实话，Bitbucket这次改版从产品角度是合理的，统一到Atlassian账户体系之后，管理粒度更细，安全选项也更完整。但对老用户来说，入口变化和密钥迁移问题确实带来了一些学习成本。我在切换初期也踩了几个坑，特别是旧版密钥没有自动迁移那个问题，排查了一个下午才定位到原因。

如果你正在经历新旧版切换，我给几条实操建议。第一，尽快把本地所有仓库用到的公钥重新添加到Atlassian账户中心，不要等报错才行动。第二，本地SSH配置尽量用独立的密钥文件加config的方式管理，避免多平台密钥互相干扰。第三，遇到连接问题先跑一遍ssh -vT看日志，很多时候报错信息已经把答案写得很清楚了，只是我们没耐心去看。

配置SSH Key本身并不复杂，核心就是把公钥准确粘贴到正确的地方，然后把本地私钥路径配置对。新旧版差异虽然存在，但只要理解了账户体系的变化，就不会再被入口跳转吓到。希望这篇对比能帮你少走弯路，一次配好就稳定使用。