企业官网建设流程全解析

开头得先交代一下场景：同一台电脑上，SSH 要同时管 GitHub、Gitee，还可能要管工作用的 Git 服务器，甚至 GitHub 上还有个人号和公司号两个账号。这类需求很常见，但很多人一开始只生成一把默认密钥，结果平台上密钥加了好几次，最后发现权限全乱了。我折腾过几轮之后，把~/.ssh/config的用法彻底摸透了，配置好之后基本一劳永逸。这篇文章就把完整思路、密钥生成、config 写法、账号隔离和排错方法全部过一遍，适合刚接触 SSH 的新手，也适合已经在用多账号但总出问题的朋友。

1. 为什么一把默认密钥搞不定多个平台

1.1 单密钥方案的局限

大多数人第一次配置 Git 平台时，都是直接执行ssh-keygen -t ed25519，一路回车，生成一把id_ed25519私钥和对应的id_ed25519.pub公钥，然后把公钥复制到 GitHub、Gitee 或者其他平台。这套做法在“一台电脑只连一个平台、只有一个账号”的前提下没问题，可一旦平台变多，问题就来了。

原因很简单：SSH 的认证本质上是“私钥 + 公钥”的配对。你在某个平台上传了哪把公钥，这个平台就会认为“持有对应私钥的人”是某个账号。如果你把所有平台都上传同一把公钥，所有平台都会把你识别成同一个身份。GitHub 和 Gitee 是两个独立平台，身份混在一起问题还不算致命，但如果你在 GitHub 上有两个账号，比如一个个人号、一个公司号，那就彻底没办法区分了。平台返回的权限永远是“这个公钥最初绑定的那个账号”，你无法通过换一个远程仓库地址就让平台认为你是另一个账号。

另外还有一个特别容易踩的坑：如果之前已经用默认名称生成过密钥，后面又直接执行同样的命令，SSH 会提示id_ed25519已存在并询问是否覆盖。有些朋友在这里直接输入y，结果旧密钥被覆盖，原来能访问的服务器全部失效。这是很多“莫名其妙突然连不上”事故的根源。

1.2 解决问题的主角：SSH config

多平台、多账号并存的正确做法，是让 SSH 客户端根据不同的目标地址，自动选择不同的私钥。这个能力由 SSH 的配置文件~/.ssh/config提供。

它的工作原理不算复杂：当你执行类似ssh -T git@github.com这样的命令时，SSH 客户端会读取~/.ssh/config，把命令行里的“主机名”和配置文件里的Host字段做匹配。一旦命中，就使用该条目里指定的IdentityFile、User、Port等参数建立连接。所以核心思路可以概括成一句话：给每个平台、每个账号安排一个独立的“入口”，每个入口绑定一把私钥。

生活里类比一下更好理解：你住的小区有好几个门，每个门都能进小区，但门禁卡不同。一把默认密钥相当于只有一张门禁卡，走哪个门都是同一张卡；而~/.ssh/config就是在每个门旁边放了一张不同的卡，刷哪个门就用哪张卡，互不干扰。Git 平台其实并不关心你叫什么名字、来自哪台电脑，它只看你出示的公钥是否在自己系统里，以及这个公钥属于哪个账号。

2. 生成与管理多把 SSH 密钥

2.1 密钥生成命令与命名规范

既然要区分平台和账号，第一步就是为每一个目标生成一把独立的密钥。推荐使用 ed25519 算法，它的密钥长度短、安全性高，GitHub、Gitee 这类主流的 Git 平台都支持得很好。生成命令可以写成下面这样：

ssh-keygen -t ed25519 -C "github-personal" -f ~/.ssh/id_ed25519_github_personal

-C是注释，相当于给这把密钥贴一个标签，方便以后识别，写用途就行，不一定要写邮箱。-f是保存路径，这个参数非常关键，它决定了密钥不会覆盖默认的id_ed25519。

我习惯的文件命名规则是这样：

这个命名方式的好处是，以后看到.ssh目录里的文件名，立刻就知道它对应哪个平台哪个账号。如果配置的平台多，建议认真维护命名规则，否则一两年后你自己都会分不清哪把钥匙是哪把。

生成过程中会提示设置 passphrase，也就是私钥密码。如果设置了，每次使用这把私钥连接服务器时，SSH 都会要求输入这个密码；如果不设置，私钥文件就是明文保存。从安全角度讲，建议设置一个 passphrase，再配合 SSH agent 来避免反复输入，这个后面会说。

2.2 密钥加载与权限管理

私钥生成之后，最好把它加入 SSH agent 管理。SSH agent 可以理解成一个专门保管私钥的“钥匙扣”，你向它添加一次私钥，它就在内存里记住这个私钥，后续连接时自动提供给 SSH 客户端，不用每次输 passphrase。

不同系统的操作略有差异。Linux 下一般先启动 agent，再添加密钥：

eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519_github_personal

macOS 上如果想让私钥在系统重启后仍然保留在钥匙串里，可以这样：

ssh-add --apple-use-keychain ~/.ssh/id_ed25519_github_personal

Windows 10 和 11 自带的 OpenSSH 客户端也支持ssh-add，只要 OpenSSH 服务处于运行状态，在 PowerShell 或命令提示符里执行同样的命令即可。需要注意的是，在 Windows 上使用 Git Bash 时，HOME 目录可能和你预期的不一样，密钥和 config 文件的位置务必确认清楚，后面排错部分还会提到。

还有一个很容易被忽视的问题：文件权限。在 Linux 和 macOS 下，.ssh目录的权限不能太开放，私钥文件通常要设置为只有本人可读写。SSH 客户端如果发现私钥权限过宽，会直接拒绝使用它，并提示权限错误。推荐执行：

chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519_*

Windows 上一般不受 POSIX 文件权限模型的限制，这个问题相对少见，但如果你在 Git Bash 或 WSL 环境下操作，同样要注意。

2.3 把公钥上传到平台

生成密钥后，需要把公钥内容添加到目标平台。公钥文件是带.pub后缀的那个，比如~/.ssh/id_ed25519_github_personal.pub。查看内容可以用：

cat ~/.ssh/id_ed25519_github_personal.pub

然后把显示的整行内容复制到平台的 SSH keys 设置页面。GitHub 在个人设置里的SSH and GPG keys，Gitee 在个人设置里的SSH 公钥，其他平台也都有类似入口。

上传的时候有几个细节要提醒一下。第一，平台上的“标题”只是用来给你自己看的备注，不影响校验逻辑，但是有些平台要求同一账号下的标题不能重复。第二，同一个公钥不建议绑定到多个平台账号上。虽然某些平台允许这么做，但由于公钥本身就能直接定位到账号，混用公钥等于又把多账号区分的问题绕回来了，完全没有必要。第三，复制公钥内容时注意不要多复制换行或者空格，否则平台保存后校验不过。

3. 整理 ~/.ssh/config 实现多平台映射

3.1 先看一个可以直接用的配置模板

密钥准备好之后，核心操作就是编辑~/.ssh/config。如果这个文件不存在，直接创建就好。

这里给一份可直接对照修改的模板，覆盖了 GitHub 个人号、GitHub 公司号、Gitee 三个入口：

# GitHub 个人号 Host github-personal HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github_personal IdentitiesOnly yes # GitHub 公司号 Host github-work HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github_work IdentitiesOnly yes # Gitee Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee IdentitiesOnly yes

注意一个容易混淆的地方：Host后面的名字不一定非得是真实的域名。比如github-personal和github-work都是本地自定义的别名，真正连接的目标由HostName字段指定。至于 Gitee 那条，我直接用gitee.com作为别名，这样既可以省去HostName这一行，也符合大多数人的使用习惯，完全没问题。

配置保存之后，先别急着改仓库地址，可以先用下面的命令测试一下：

ssh -T git@github-personal ssh -T git@github-work ssh -T git@gitee.com

如果密钥和平台账户都配置正确，各平台会返回一串欢迎信息，告诉你认证已经成功，并显示对应的用户名。看到这些输出，就说明 SSH 层面的映射已经通了。

3.2 逐项拆解关键配置字段

很多朋友照着模板配完之后，偶尔还是会报错，原因往往是不理解每个字段的意义，不知道如何调整。这里把几个关键字段逐个解释清楚。

Host是匹配的关键字，SSH 命令行或远程仓库地址里的主机名会和它做匹配。它可以是真实域名，也可以是本地别名。需要强调的是，匹配是“前缀匹配”还是“精确匹配”？实际上 SSH 的规则比较复杂，但在普通配置里你可以把它理解为对等匹配。同一个文件里可以有多个Host块，从上到下逐条匹配，使用第一条命中的配置。

HostName是真正要连接的目标主机，也就是服务器地址。当你把Host写成自定义别名时，必须写HostName。比如Host github-personal，HostName github.com，最终 TCP 连接还是去github.com，只是本地命令和仓库地址里用的名字换成了github-personal。

User是登录用户名。对 GitHub、Gitee 这类 Git 托管平台来说，SSH 连接的用户名固定是git，不管你的账号叫什么，这里都写git。自己搭建的 Git 服务器如果用了不同的系统用户，那就按实际情况改。

IdentityFile用于指定私钥路径，也就是该Host使用的钥匙。多账号的核心就在这里：不同的Host指向不同的私钥，平台就能认出不同的身份。

IdentitiesOnly yes建议一定要加。它的作用是告诉 SSH 客户端“只使用IdentityFile指定的密钥，不要用 agent 里其他乱七八糟的密钥”。如果不加这一项，SSH 会把 agent 里所有可用的密钥都依次发给服务器尝试。很多平台对单次连接的密钥尝试次数有限制，一旦次数超限，直接断连，报Too many authentication failures。加了IdentitiesOnly yes就相当于告诉客户端：别自作聪明，就用这一把。

3.3 让现有仓库走新的 SSH 配置

配置好~/.ssh/config之后，本地仓库还需要使用 SSH 方式连接，并且远程地址里的主机名要换成你在Host里定义的别名。

如果是新建仓库克隆，命令是：

git clone git@github-personal:username/repo.git

注意这里的github-personal已经不是真实域名了，SSH 会从 config 里找到对应的HostName，再用IdentityFile指定的私钥去连接。

如果是已经存在的仓库，之前用的是 HTTPS 地址，需要改一下 remote。用下面的命令：

git remote set-url origin git@github-personal:username/repo.git

改完之后用git remote -v检查一下：

git remote -v

正常情况下输出里应该只显示 SSH 格式的地址，不再是https://github.com/...这种带 HTTPS 前缀的地址。

这里多说一句，为什么远程地址可以把主机名写成别名？因为在 Git 使用的 scp-like SSH 语法里，git@github-personal:username/repo.git会被拆成用户名git、主机名github-personal、仓库路径username/repo.git。SSH 客户端在真正建立连接前会先查 config，找到Host github-personal对应的HostName和IdentityFile，然后用它们完成连接。所以别名只是本地映射，不会影响真正的服务器地址，平台侧完全感知不到。

4. 提交身份别搞混：user.name 与 user.email 的局部配置

4.1 全局身份配置为什么会“串号”

SSH 只解决“连得上、以哪个账号连”的问题，但 Git 提交记录里的作者身份，是由user.name和user.email决定的。这两项配置如果没有按仓库区分，很容易出现一个非常尴尬的情况：你用公司账号在 GitHub 上操作，提交人却显示个人昵称和个人邮箱。

原因在于很多人在电脑上配 Git 时，顺手就执行了类似这样的命令：

git config --global user.name "个人昵称" git config --global user.email "personal@example.com"

这个--global配置会被这台电脑上的所有 Git 仓库继承。如果你之后又在同一台电脑上用 SSH 连接公司账号操作仓库，提交记录里的user.name和user.email依然来自全局配置。平台在网页端展示提交记录时，会直接读取提交者邮箱对应的账号头像和名称，于是你的公司仓库里就出现了个人账号的信息。

GitHub 和 Gitee 这类平台校验提交身份的方式不完全一样，但它们都会尽量把提交邮箱关联到平台账号。邮箱对不上，提交记录要么显示成灰色“无法验证”的状态，要么就关联到了错误的账号。这个问题不是 SSH 配置能解决的，必须单独处理。

4.2 按仓库指定身份与 includeIf 的进阶用法

最稳妥的做法是：全局配置只设置一个兜底身份，每个仓库进入后单独设置身份。按仓库设置用下面两条命令：

git config user.name "工作昵称" git config user.email "work@example.com"

注意不要加--global，这样配置只写入当前仓库的.git/config，不会影响其他仓库。

如果电脑上仓库数量很多，每次新建仓库都要手动执行两条命令，确实容易忘。进阶做法是利用 Git 2.13 开始支持的includeIf条件引用，按照目录自动加载不同的配置文件。比如你打算把工作相关的仓库都放在~/work/目录下，个人仓库放在~/personal/目录下，可以在全局~/.gitconfig里写：

[includeIf "gitdir:~/work/"] path = ~/.gitconfig-work [includeIf "gitdir:~/personal/"] path = ~/.gitconfig-personal

然后在~/.gitconfig-work里写：

[user] name = 工作昵称 email = work@example.com

在~/.gitconfig-personal里写个人身份。之后只要仓库位于对应目录下，Git 就会自动应用对应身份，不用每个仓库单独设置，也不容易串号。唯一要注意的是gitdir:后面的路径最好带上结尾斜杠，表示匹配该目录下的所有子目录。

还有一个小细节：如果某个仓库内的身份配置与条件引用冲突，仓库目录里的本地配置优先级更高。也就是说，即使设置了includeIf，你仍然可以在某个仓库内单独执行不带--global的git config user.name覆盖它，这给了你足够灵活的调整空间。

5. SSH 多账号配置常见问题与排查实录

5.1 快速对照表：报错信息与解决办法

实际配置过程中，报错信息五花八门，这里整理一张常见错误对照表，方便直接对照排查。

5.2 完整排查流程：从 ssh -T 到 git 仓库

报错之后不要瞎试，按固定流程排查效率最高。

第一步，先用 SSH 命令单独测试连接，不掺入 Git 逻辑：

ssh -T git@github-personal

不管结果是成功还是失败，先确认 SSH 层面有没有通。第二步，如果失败，加上-v参数看详细日志：

ssh -vT git@github-personal

重点看日志里Offering public key这一行，它后面跟的密钥指纹，就是你实际向服务器提供的公钥指纹。把它和平台后台保存的公钥做对比，能直接判断私钥有没有选对。

第三步，确认 agent 里加载了哪些密钥：

ssh-add -l

如果列表里没有你想要的私钥，或者私钥过多导致混乱，可以清空后重新添加：

ssh-add -D ssh-add ~/.ssh/id_ed25519_github_personal

第四步，检查本地仓库配置。在出问题的仓库目录下执行：

git remote -v git config --list --show-origin

git remote -v能看出仓库到底走的是 SSH 还是 HTTPS；git config --list --show-origin不仅能显示当前生效的配置内容，还能标注每一项配置来自哪个文件，方便你定位是全局配置还是仓库本地配置造成的身份混乱。

第五步，确认公钥指纹是否和平台一致。本地执行：

ssh-keygen -lf ~/.ssh/id_ed25519_github_personal.pub

再去平台 SSH keys 页面找到对应钥匙的指纹，两者一致才说明上传的确实是这把公钥。

5.3 几个容易踩的坑

排错表列完之后，再补几个亲身踩过的坑，都属于那种“看文档看不出来、一踩一个准”的细节。

第一个坑是IdentitiesOnly yes加晚了。我刚开始配多账号时没有这个概念，agent 里同时挂着四五把私钥，结果 GitHub 偶尔报Too many authentication failures，Gitee 也会时不时抽风。后来逐一对每个Host加上IdentitiesOnly yes，问题立刻消失。如果你已经按前面的模板配置，别跳过这一行。

第二个坑是远程仓库地址里的“伪主机名”没写对。你 config 里写的Host是github-personal，那远程地址就必须是git@github-personal:...，不能是git@github.com:...。如果仍写真实域名，SSH 会尝试匹配Host github.com，大多数人并没有配置这个条目，于是又回退到默认密钥，自然无法通过认证。

第三个坑是 HTTPS 和 SSH 地址混用。很多人明明已经配置好了 SSH，却发现操作仓库还是要输入密码，原因是仓库当初是用 HTTPS 方式克隆的。Git 的 remote 地址不会因为你配置了 SSH 就自动切换，必须手动执行git remote set-url。还有个更隐蔽的情况：~/.gitconfig里配置了 URL 重写规则，比如把https://github.com/替换为某个 SSH 地址，但只对部分域名生效，导致有些仓库走了重写规则、有些没走，行为很怪异。建议一开始就不要依赖重写规则，把 remote 地址写清楚。

第四个坑和平台限制有关。有些平台不允许同一把公钥同时绑定多个账号。比如你在 GitHub 个人号上传了公钥 A，再用公钥 A 去绑 GitHub 公司号，平台可能会提示“公钥已被使用”，强行绑定也会导致认证时永远命中个人号。所以每新增一个账号，都重新生成一把新密钥，这是最省心的方案。

第五个坑是 Windows 环境下的 HOME 路径。Windows 自带的 OpenSSH 默认读取C:\Users\用户名\.ssh\config，但在 Git Bash 里，HOME 可能被设置成其他路径。如果你在 Git Bash 里编辑了~/.ssh/config，在 PowerShell 里却用的是另一套配置，两边行为就会不一致。建议固定在一个终端环境下配置和测试，避免跨环境操作。

第六个坑是和已知主机记录相关。如果你之前从来没有连接过某个平台，首次连接时会看到Are you sure you want to continue connecting (yes/no)?，输入yes即可，这是正常提示。但如果以前连接过，之后平台换了服务器密钥，或者你重装过系统，known_hosts 里可能留下旧记录，结果第一条提示变成Host key verification failed。这时候要先确认目标服务器没有问题，再用ssh-keygen -R github.com清理对应记录，重新连接。

还有一个小建议：把每一次新配置的平台或账号都整理进~/.ssh/config，不要图省事在某个仓库的.git/config里硬写密钥路径。前者是全局管理，后者换个目录就失效，长期维护下来前者轻松得多。

多账号并存这件事，核心原则其实就一条：把“平台连接”和“仓库身份”拆开来看。平台连接靠 SSH 密钥和 config 映射解决，仓库身份靠 Git 的 user.name、user.email 解决。这两条线分别管理好，再多的账号也不会打架。我自己现在每次配完新环境，都会先跑一遍ssh -T确认用户名，再用git config --list看一眼提交身份，确认无误后才开始克隆代码。这套习惯帮我省下了大量排错时间，建议你也试试。