📘 GitLab 配置 SSH Key 新手教程（免密版）
✅ 适合刚接触 Git 和 GitLab 的开发者
✅ 图文结合，操作步骤详细
✅ 支持 Windows、Mac、Linux 系统
✅ 全程免密使用 SSH 地址，无需输入用户名和密码
🧩 一、什么是 SSH？为什么要配置 SSH Key？
🔐 什么是 SSH？
SSH 是一种安全协议，可以让你在本地电脑和远程服务器之间建立安全连接。GitLab 就是一个远程 Git 仓库服务。
📌 为什么要配置 SSH Key？
- ❌ 不用每次拉取或推送代码都输入用户名和密码
- ✅ 更安全：避免密码泄露
- ✅ 更方便：配置一次，终身免密
🛠️ 二、生成你的 SSH 密钥对（免密）
我们先来生成一对 SSH 密钥：一个“私钥”（你留着），一个“公钥”（上传到 GitLab）。
步骤 1：打开终端（命令行工具）
| 系统 | 工具 |
|---|---|
| Windows | 推荐使用 Git Bash（安装 Git for Windows 后自带） |
| macOS | 终端（Terminal） |
| Linux | 终端 |
步骤 2：运行命令生成密钥
ssh-keygen -t ed25519 -C "your_email@example.com"ed25519是一种更现代、更安全的加密方式-C后面是你自己的邮箱，用于标识这个密钥是谁的
步骤 3：一路回车跳过所有提示
你会看到类似以下提示：
Enter file in which to save the key (/c/Users/xxx/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:直接按回车即可，不要设置密码（这就是“免密”的关键！）
🌐 三、将公钥添加到 GitLab（重要！）
你现在有了一个 SSH 密钥对，接下来要把“公钥”上传到 GitLab，让它知道你是谁。
步骤 1：查看你的公钥内容
cat ~/.ssh/id_ed25519.pub你会看到一行很长的内容，像这样：
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX your_email@example.com⚠️ 注意：
- 这是一整行，不能换行
- 必须包含开头的
ssh-ed25519和结尾的邮箱
步骤 2：登录 GitLab → 添加 SSH 公钥
- 打开浏览器访问你的 GitLab 地址
- 登录后点击右上角头像 →
Preferences或Settings - 在左侧菜单中选择
SSH Keys - 把刚才复制的那行公钥粘贴进去
- 点击
Add key
✅ 成功上传！
🔁 四、配置 SSH 别名（可选但推荐）
如果你是通过容器部署 GitLab，并且映射了非标准端口（如 2222），建议你配置一个别名，让使用更简单。
步骤 1：编辑 SSH 配置文件
nano ~/.ssh/config或者用记事本打开：
notepad ~/.ssh/config步骤 2：添加如下内容（根据你的实际情况修改）
可以支持多个项的配置
# 别名配置
Host gitlab-local
HostName 192.168.1.27
Port 2222
User git
IdentityFile ~/.ssh/id_ed25519
# 直接 IP 地址配置
Host 192.168.1.27
Port 2222
User git
IdentityFile ~/.ssh/id_ed25519解释一下字段含义：
| 字段 | 含义 |
|---|---|
Host | 你自己定义的别名，比如 gitlab-local |
HostName | GitLab 的 IP 地址 |
Port | GitLab 映射的 SSH 端口（不是默认的 22） |
User | 默认是 git |
IdentityFile | 指定你要使用的私钥路径 |
保存退出后，你可以使用这个别名来克隆项目：
git clone git@gitlab-local:family/test.git🚦 五、测试 SSH 是否配置成功
运行以下命令测试连接：
ssh -T git@gitlab-local如果输出：
Welcome to GitLab, @your_username!说明 SSH 配置已经成功！
📦 六、使用 SSH 地址克隆项目（免密）
你现在可以直接使用 SSH 地址克隆仓库：
git clone git@gitlab-local:family/test.git或者原始地址（已自动识别端口）：
git clone git@192.168.1.27:family/test.git都不需要输入任何密码 ✅
⚠️ 七、注意事项（非常重要）
| 事项 | 说明 |
|---|---|
| 不要泄露私钥文件 | 如 ~/.ssh/id_ed25519，一旦泄露后果严重 |
| 不要手动修改公钥内容 | 必须完整复制，否则 GitLab 无法识别 |
| 不要重复添加多个相同公钥 | GitLab 不会报错，但容易混淆 |
| 不要使用 root 用户生成密钥 | 建议使用普通开发账号生成和使用 |
| 定期备份 .ssh 目录 | 重装系统或换电脑时非常有用 |
| 免密私钥仅限个人开发环境使用 | 不建议用于生产服务器或共享设备 |
🧠 八、你不需要做什么（免密用户的特别提醒）
既然你选择了免密使用 SSH Key，那么你 不需要做以下事情：
| 操作 | 是否需要 | 原因 |
|---|---|---|
| 设置 Passphrase（私钥密码） | ❌ 不需要 | 你希望全程免密使用 SSH |
编写或运行 load_ssh_keys.sh 脚本 | ❌ 不需要 | 因为没有 Passphrase，不需要缓存密码 |
手动运行 ssh-agent 和 ssh-add | ❌ 不需要 | 免密私钥默认会被自动加载 |
| 每次操作都输入密码 | ❌ 不需要 | 这正是免密的目的 |
🧾 九、一句话总结
只要你正确生成并上传了 SSH 公钥，并配置了 .ssh/config（如有必要），就可以 全程免密使用 GitLab 的 SSH 地址进行代码拉取、推送等操作。📎 十、常用命令一览表
| 功能 | 命令 |
|---|---|
| 查看当前 SSH 密钥 | ls -al ~/.ssh/ |
| 生成新密钥 | ssh-keygen -t ed25519 -C "your_email@example.com" |
| 查看公钥内容 | cat ~/.ssh/id_ed25519.pub |
| 测试 SSH 连接 | ssh -T git@gitlab-local |
| 克隆仓库（推荐方式） | git clone git@gitlab-local:family/test.git |
| 删除旧主机指纹（修复连接失败） | ssh-keygen -R "[192.168.1.27]:2222" |