企业官网建设流程全解析

简介：《GitLab用户手册v2.pdf》是一份面向Git初学者和团队协作开发者的技术资料，重点解决从Git客户端安装到GitLab平台日常使用中的常见配置与操作问题。手册先后梳理了环境搭建、全局用户名与邮箱设置、SSH密钥生成及导入、项目创建与克隆、版本历史查看等基础环节，也介绍了CI/CD流水线、代码评审、权限管理等高级功能，兼具入门指导与速查价值。整个资源以单个PDF文件构成，压缩包体积约1.04MB，适合下载后离线浏览或打印对照。目前已有538人浏览学习，适合正在搭建GitLab环境、需要配置SSH认证，或想系统了解GitLab基础与进阶操作的开发与运维人员使用。手册中结合实际命令与界面路径，细致展示了GIT Bash下常用命令的用法、SSH密钥生成和导入的具体步骤，以及登录GitLab后完成个人配置的跳转流程，能有效减少初次使用者常见的环境与认证踩坑，是一份实用的GitLab入门参考。

1. GitLab 用户手册 v2：把内网 Git 环境从能装到能用的一本薄手册

我拆这份 GitLab 用户手册 v2.pdf 的时候，最大的感受是：它做的事非常朴素，就是把「装 Git → 配全局用户名 → 生成 SSH key → 把公钥放进 GitLab → 能克隆能推送」这条链路按顺序写清楚了。很多团队刚搭好 GitLab（比如手册里这个 http://10.10.169.27/ 的内网服务器），卡人的往往不是 Git 命令本身，而是 SSH 密钥这一环：生成了不知道怎么导入，导入了不知道成没成功。这份手册正好把这些步骤理顺了，适合刚接触 GitLab 的开发者、需要给团队做环境准备的负责人，以及经常换电脑、每次都要重配一遍 SSH 的重装党。下面我按自己的使用习惯把每一步重新走一遍，顺带补上手册里没写透的坑。

2. 环境准备：从 Git 安装到 user.name 与 user.email 的全局配置

2.1 下载与安装 Git：三个值得手动改的默认选项

手册指定的下载地址是 https://git-for-windows.github.io，也就是 Git for Windows 的官方入口。下载完安装包双击运行，一路 Next 确实能装完，但我不建议完全用默认值。安装过程中有几步会影响后面 Git Bash 的使用体验，尤其是 Adjusting your PATH environment 这一步，它决定你能否在系统命令行（cmd、PowerShell、IDE 内嵌终端）里直接调用 git。

这一步通常给三个选项：Git from the command line and also from 3rd-party software、Git from the command line only、以及只从 Git Bash 里使用。我一般选第一个，理由很实际：很多 Java 项目或 IDE（手册里提到 MyEclipse）在构建或做版本操作时，是从系统路径直接调 git 的，如果只选了 Git Bash 内使用，IDE 里执行 git 命令就会提示找不到命令。选完 PATH 后还有一步比较关键的是换行符处理，Windows 默认选项是 Checkout Windows-style, commit Unix-style line endings，意思是检出时自动转成 CRLF、提交时转回 LF。这个设置在纯 Windows 团队里没问题，但团队只要有一个 Linux 部署脚本或 .sh 文件，就容易出现「明明没改文件，git status 却显示一堆 modified」的翻车现场。所以我习惯选 Checkout as-is, commit as-is，把换行符的决定权交给项目自己的 .gitattributes。

第三个值得动一下的是终端模拟器选择。MinTTY 和 Windows 默认终端对 Git 命令本身没有影响，但 Windows 默认终端在打开多个窗口、复制超长命令时更稳，我习惯选 Windows 默认。装完以后打开 Git Bash，先跑一次版本确认：

git --version

预期输出类似 git version 2.x.x。这一步同时确认两件事：Git 装好了，Git Bash 能正常执行外部命令。如果这里报错，大概率是 PATH 选项没选对，重装一次即可，不用做其他排查。装完 Git 后，桌面上出现 Git Bash 的图标，右键菜单里也会多出 Open Git Bash here 和 Open Git GUI here 两个入口，前者是我们日常主要的命令行入口，后者是图形化界面，适合不习惯命令行的人，但功能覆盖不如命令完整，建议还是以 Bash 为主。

2.2 git config：名字和邮箱不是随便填的

Git 的提交记录里有两个字段：user.name 和 user.email。手册给的命令是：

git config --global user.name "yourname" git config --global user.email "email@example.com"

第一条配置全局用户名，会显示在提交记录的作者位置；第二条配置全局邮箱，这个邮箱必须和你登录 GitLab 的账号邮箱完全一致。不一致的后果很隐蔽：代码能正常 push，但 GitLab 的提交历史里，author 不会关联到你的账号，贡献统计、代码评审的指派全都会对不上。而且提交记录一旦生成，事后改邮箱只能改历史，在团队仓库里做这种事情非常麻烦。

--global 参数的含义是写到当前系统用户目录下的 ~/.gitconfig 文件，对所有仓库生效。如果一台电脑同时参与公司和个人的项目，可以在某个仓库目录内执行不带 --global 的 config 命令，用 --local 级别覆盖全局配置。我一般这样用：全局写公司邮箱，个人项目目录里单独设置，避免把公司身份带进开源项目。配置完成后可以用下面这条命令检查所有生效项：

git config --list

输出里能看到 user.name、user.email、core.autocrlf 等条目。注意，如果同一配置项在多个级别都存在，后输出的是优先级更高的值，级别优先级从低到高是 system < global < local。如果发现配置不对，重新执行 config 命令就能覆盖；如果只想看单个配置项，用 git config user.name 这种写法即可。

还有一个新手容易忽略的点：Git Bash 打开后的当前目录默认是用户主目录，执行 git config --global 不依赖当前路径；但 --local 必须先进入某个已经初始化的仓库目录，否则会报错。另外，user.name 可以填中文，Git 本身支持，但 GitLab 在部分版本里对中文 user.name 的兼容一般，建议用英文或拼音，避免在代码评审界面出现乱码头像。

3. 生成 SSH 密钥：ssh-keygen 参数与密钥文件落点

3.1 为什么 GitLab 场景首选 SSH 免密

GitLab 支持 HTTP 和 SSH 两种协议访问仓库。HTTP 克隆简单，但每次 push 都要输入账号密码，或者依赖本机的凭据管理器记住密码；SSH 在第一次配置好密钥后，后续所有操作全程免密。对于手册里这类内网 GitLab，我默认走 SSH，还有一个实际原因：内网 GitLab 常用自签证书，HTTP 克隆经常撞上 SSL 证书校验失败的问题，而 SSH 通道不涉及证书体系，直接绕开了证书信任这层麻烦。

这里有个反直觉的点：SSH key 是「一人多机」绑定的。同一个开发者在办公电脑、笔记本、家里电脑上可以分别生成不同的密钥，然后在自己的 GitLab 账号下全部添加，服务器通过公钥识别是哪台机器在连接。每台机器独立的 key 也方便某台电脑丢失时单独吊销，不影响其他设备。这套机制本质上是用非对称加密：客户端持有私钥，服务器持有公钥，连接时用私钥签名、公钥验签，全程不传输密码，也不怕被嗅探。这也是为什么 GitLab 使用教程里几乎都会先讲配置 SSH 密钥——它是整个免密链路的起点。

3.2 ssh-keygen 生成命令：每个参数都有用途

手册里给的命令是：

ssh-keygen -t rsa -C "lijianyu_alice@163.com"

我自己的习惯是在中间加一个 -b 参数：

ssh-keygen -t rsa -b 4096 -C "lijianyu_alice@163.com"

执行后按三次回车即可：第一次回车是确认保存路径，默认是 ~/.ssh/id_rsa；后两次是设置 passphrase（口令），可以留空，也可以设置。逐项说明参数的含义：-t rsa 指定密钥算法为 RSA；-b 4096 指定密钥长度为 4096 位，手册里没有写 -b，默认是 2048，对绝大多数场景够用，但 4096 更稳妥；-C 是注释，习惯写自己的邮箱，这样在 GitLab 的 SSH Keys 列表里能一眼看出这把 key 对应哪个人的哪台机器。

生成过程中如果之前已经生成过密钥，会出现 Overwrite (y/N)? 提示。输入 y 会直接覆盖旧私钥和公钥，等于废掉旧密钥。如果旧公钥已经贴到 GitLab 或其他服务器上，覆盖后需要去对应页面删掉旧公钥并导入新的，否则那边会留一把永久失效的 key。如果旧密钥还在别的服务器上用，覆盖前要慎重，建议确定旧 key 没有作用了再执行。

生成完成后，密钥对落在 ~/.ssh 目录。要查看公钥内容，用：

cat ~/.ssh/id_rsa.pub

输出是一长行以 ssh-rsa 开头、末尾带邮箱注释的文本。公钥可以公开，可以发给管理员，也可以贴到任意需要免密的服务器上；私钥 id_rsa 绝对不能给任何人。这里有个常见错误是把公钥和私钥搞反，导入时贴的是私钥内容，服务器直接拒绝。想确认文件是否正常，可以列出 ~/.ssh 目录看看：

ls -la ~/.ssh

正常情况下能看到 id_rsa 和 id_rsa.pub 两个文件，id_rsa 的权限在 Linux 下要求是 600，Windows 下虽然没有强制要求，但也不要让多用户共享这份私钥。

提示：任何情况下都不要把私钥内容贴到网页表单里。GitLab 的 SSH Keys 页面只接受公钥，也就是 .pub 文件里的内容。

3.3 passphrase 的取舍：免密也不等于裸奔

ssh-keygen 过程中出现的 Enter passphrase 提示，处理方式会影响日复一日的手感。不设置口令，直接回车，私钥文件是明文存储的，谁拿到这份文件谁就能使用这把 key 连接所有配置过公钥的服务器；设置一个口令，私钥文件会被加密，每次使用需要输口令，但可以通过 ssh-agent 让它只输一次。

我的内网团队建议是：设置一个不太长的口令，然后配合 ssh-agent 缓存。具体做法在第 5 章的对应坑位里展开。如果不设置口令，至少要保证系统用户密码够强、硬盘启用 BitLocker 之类的全盘加密，否则私钥文件泄露的后果和账号密码泄露差不多。对于 GitLab 这种承载代码资产的系统，安全底线不能太低。

4. 导入 SSH Key 到 GitLab：登录、改密与 Profile Setting 实测路径

4.1 首次登录：初始密码是第一道必须过的关

GitLab 管理员创建账号后会把初始密码给到个人，浏览器打开手册里的服务器地址 http://10.10.169.27/，用账号和初始密码登录，系统会跳转到修改密码页面。这一步没有捷径：初始密码不换，账号就处于「知道密码的人都能登录」的状态。GitLab 在用户侧看，改完密码才算真正激活账号，也才能进入后面的 SSH Keys 页面。

这里要插一句手册的真实情况：手册里「导入 sshkey」这一大段被连续粘贴了很多次，看起来像是从现场操作截图里直接拼出来的，实际步骤并不多，核心就是登录、改密码、进 Profile Setting、加公钥四步。被复制多遍的内容不用逐条看，按下面的路径走就能完成。

4.2 Profile Setting 与 Add SSH Key：把公钥交给服务器

登录进 GitLab 后，界面右上角是头像下拉框，点击后选择 Profile Setting——新版界面里可能显示为 Preferences，入口位置一样。进入后左侧菜单找到 SSH Keys，点击 Add SSH Key 按钮，会出现两个输入区域：Title 和 Key。

Title 是给这把 key 起一个可识别的名字，建议按「使用者-设备」的格式，例如 alice-office-pc 或 alice-macbook，避免出现一堆同名 key 分不清哪个是哪个。Key 区域粘贴公钥内容，也就是第 3 章里 cat ~/.ssh/id_rsa.pub 输出的那一整行。GitLab 支持同一账号下添加多把公钥，所以多台电脑分别生成的公钥都可以贴进来，互不影响。粘贴完成后点 Add key 保存，页面会出现一条带 Key fingerprint 的记录。

建议把 GitLab 页面上的 fingerprint 和本机公钥生成的指纹做一次对照，命令是：

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

输出的指纹串如果和页面上显示的一致，说明本机这把公钥确实成功导入了，这个动作虽然多花几秒，但能彻底排除「贴错 key」的可能。

4.3 用 ssh -T 验证密钥：别等 push 才发现问题

公钥导入 GitLab 后，最直接的验证方式是让 SSH 客户端与 GitLab 建立一次连接：

ssh -T git@10.10.169.27

首次连接会出现一个确认提示，询问是否信任该主机的指纹，输入 yes 回车。如果一切正常，服务端会返回 Welcome to GitLab, @yourname!，看到这一句就说明密钥链路已经打通。如果输出 Permission denied (publickey)，说明密钥没被服务器接受，优先按第 5 章的对应条目排查，而不是反复重新粘贴公钥。

这一步建议固定到每次新电脑配置的流程里。密钥验证通过后再 git clone，可以把后续一连串问题挡在前面。不同 GitLab 版本的欢迎语措辞略有差异，有的版本还提示 You're about to create a project，只要没有出现 denied 或 failed 字样，就说明 SSH 握手成功了。验证命令不带 -T 的话会进入登录交互界面，所以 -T 这个参数不能省，它表示禁止分配终端。

5. 避坑清单：GitLab 接入中最容易翻车的五个场景

5.1 Permission denied (publickey)：密钥没被服务器接受

现象：执行 ssh -T git@10.10.169.27，返回 Permission denied (publickey)，GitLab 页面却显示 key 已经添加成功。

原因：大概率是三类问题之一：贴进 GitLab 的是私钥内容而不是公钥；公钥粘贴时漏了开头或多了换行；本机 SSH 连接时用的不是这把私钥，比如 ssh-keygen 时改过默认文件名，或系统里同时存在多把 key 导致 SSH 选择了错误的私钥。

解决：先在 GitLab 的 SSH Keys 页面删掉疑似有问题的 key，重新复制 id_rsa.pub 的完整内容再添加，注意必须是 .pub 结尾的文件。如果生成时用了自定义文件名，连接时需要显式指定私钥：

ssh -i ~/.ssh/mykey -T git@10.10.169.27

多数情况下删掉重新贴一次就能解决。如果仍不行，可以加 -v 参数跑一次详细日志，看 SSH 实际尝试了哪些 key：

ssh -vT git@10.10.169.27

日志里会输出 Authenticated to ... 或 Permission denied 的关键行，能看到具体是哪把 key 被拒绝了，排查范围能一下子缩小。

5.2 提交记录关联不上账号：email 和 GitLab 不一致

现象：代码正常 push 到 GitLab，仓库里也能看到提交，但提交记录的作者区域显示 Unknown 或一串数字 id，点进去关联不到任何账号。

原因：commit 的作者信息由本机 git config 提供，提交时用的是 user.email 字段。如果这个邮箱和 GitLab 账号的邮箱不一致，GitLab 无法把提交归到你的名下。这个错误没有任何报错、没有警告，是最隐蔽的坑。

解决：先执行 git config --list 看当前配置，把 user.email 改成 GitLab 账号对应的邮箱，改完再提交新代码即可。已经产生的错误提交，最近一次的可以用 git commit --amend --reset-author 修改；如果已经推送且历史提交很多，就需要 rebase 或由仓库管理员协助处理。从那以后我都把「先配 user.email 再生成密钥」当成强制顺序。

5.3 每次 push 都要输 passphrase：ssh-agent 没接管

现象：明明设置的 passphrase 不想每次输入，但每次 push、pull 都在问 Enter passphrase for key。

原因：设置口令后 SSH 每次使用私钥都需要口令，只有把私钥交给 ssh-agent 缓存，才能做到整个会话内免输。Git Bash 每次重启后，ssh-agent 默认是空的。

解决：手动加载一次：

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

输入一次口令后，当前 shell 会话内连接 GitLab 不再追问。想长期免输，可以把这两行追加到 ~/.bashrc 里，Git Bash 每次启动自动执行。不推荐直接把 passphrase 留空来省事，安全性差距太大，agent 方案既保安全又保手感。

5.4 手册命令抄下来直接报 command not found

现象：照着 PDF 抄ssh-keygen-trsa -C "xxx@163.com"，执行后提示 command not found。

原因：PDF 排版或导出时把 -t rsa 粘连成一个词了。这个现象在这份手册里原样存在，值得记一笔：任何 PDF 里抄出来的命令，先自己拆开确认每个参数，再执行。

解决：正确写法是 ssh-keygen -t rsa -C "邮箱"，参数之间必须有空格。同理，git config --global 里的连字符也不要复制丢字，否则会提示 git config --global 非法。这类问题还有个附带教训：看用户手册时，遇到命令先自己在脑子里过一遍结构，见过太多人因为 PDF 里一个小粘连卡住了半小时。

5.5 网页能打开，克隆总超时：证书与代理环境

现象：浏览器访问 http://10.10.169.27 正常，但 git clone 走 HTTP 地址时卡住或报 SSL certificate problem。

原因：内网 GitLab 常用自签证书，git 的 http.sslVerify 默认开启，证书链不受本地信任时直接拒绝连接；部分公司网络还有代理层拦截。

解决：手册推荐的 SSH 通道可以完全绕开证书校验。如果仓库地址已经是 HTTP 形式，在内网可信环境下可以单独针对该服务器关闭校验：

git config --global http.sslVerify false

这条命令只建议在内网 GitLab 场景使用，公网仓库务必保持默认开启。更稳妥的做法是让管理员给 GitLab 配置内部 CA 证书并下发到各机器，一劳永逸，但需要管理员介入，普通开发者先用 SSH 通道最省事。

6. 密钥配好后：从克隆到推送的一轮完整 Git 工作流

密钥验证通过后，剩下的就是日常操作。在 GitLab 的项目页面复制 SSH 地址，格式是 git@10.10.169.27:group/project.git，然后执行：

git clone git@10.10.169.27:group/project.git cd project git checkout -b feature/login git add . git commit -m "add login page" git push -u origin feature/login

这是一条最常用的分支工作流。git checkout -b 创建并切换到新分支，git push -u origin feature/login 把本地分支和远端分支绑定，之后在同一分支上直接用 git push 即可。git add . 会把当前目录所有改动加入暂存区，提交前建议先 git status 确认没有把临时的编译产物或 IDE 配置带进去。

如果是把本地已有的项目上传到 GitLab，流程是先在 GitLab 上新建空仓库，复制它的 SSH 地址，再在本地项目目录里执行：

git init git remote add origin git@10.10.169.27:group/project.git git add . git commit -m "initial commit" git push -u origin main

本地项目上传到 GitLab 这个场景里，最常见的坑是分支名：GitLab 新建仓库时默认主分支可能是 main 或 master，推送前先确认远端仓库已初始化的默认分支名，避免产生两个毫无关联的主分支历史。

最后分享一个我长期在用的技巧：给内网服务器在 ~/.ssh/config 里配置别名。手写配置：

Host gitlab-internal HostName 10.10.169.27 User git IdentityFile ~/.ssh/id_rsa

配置后，克隆地址可以写成 git@gitlab-internal:group/project.git，以后服务器 IP 变了，只改 HostName 一处，本地的 remote url 不用动，本机所有依赖这个地址的脚本也都不受影响。日常拉代码时我还保留一个习惯：只走 git pull --rebase，避免产生无意义的 merge commit，让分支历史保持一条直线，后续回溯问题时清晰很多。

从那以后，我在任何新电脑上配 GitLab 环境，都会强制走一遍「生成 key → 导入 GitLab → ssh -T 看到 Welcome」再开始 clone，这套流程放在 GitHub 或 Gitee 上同样成立。希望帮到你。

本文还有配套的精品资源，点击获取