企业官网建设流程全解析

简介：GitLab 用户手册 v2.pdf 是一份面向开发团队、运维人员及测试人员的 GitLab 实操入门指南，系统梳理了从环境搭建到高级功能应用的完整链路。手册以 Git 客户端安装为起点，逐步讲解全局用户名与邮箱配置、通过 GIT BASH 执行 ssh-keygen 生成 SSH 密钥、将公钥导入 GitLab 服务器（含修改初始密码、Profile Setting、SSH Keys 页面操作）等关键环节；后半部分则进一步覆盖项目创建与克隆、版本历史与提交记录查看，以及 CI/CD 管道、代码评审、权限管理等进阶能力，全程配合图文步骤说明，适合初涉 GitLab 的开发者按步骤快速上手。PDF 文件共 1 个，压缩包仅 1.04MB，体积轻量便于随时查阅。文档配有具体命令与界面操作说明，可帮助读者理解 Git 与 GitLab 的协作机制，掌握项目版本管理、提交记录查看及团队协作的核心技能。已有 538 人学习下载，是入门 GitLab 的实用参考资料。

1. 为什么 GitLab 手册能写两百页，核心却只有这几件事

拿到《gitlab用户手册v2.pdf》这份文档的人，多半不是想通读，而是带着具体问题来的：新同事要配 SSH 密钥、团队要导入一批代码仓库、服务器重启后 GitLab 起不来了、仓库越来越大磁盘快满了。这三类问题，基本覆盖了 GitLab 从部署到日常使用的全部场景。

这本手册如果把每个功能都展开写，篇幅会非常吓人。但对一线工程师来说，真正值得花时间掌握的只有一条主线：账号与认证怎么配、项目怎么建怎么导、权限怎么卡、备份怎么做、出了故障怎么排查。其余功能都是在主线上长出来的枝叶。本文不打算复述整本 PDF，而是把手册里最容易被跳过、却最能救命的章节挑出来，配上一线踩坑记录，让你看完能直接回到工位上动手。目录、权限、CI、运维，各取所需。如果你刚接手团队 GitLab，看完至少能回答两个问题：这系统现在健不健康，以及我能不能在不动全局的情况下把日常管理撑起来。

2. 账号与认证：SSH 密钥、HTTP 凭据与 login failed 的真相

2.1 SSH 密钥配置：从生成到测试的完整链路

GitLab 的开发者日常交互，九成走 SSH 协议。这里说的配置，不是简单把公钥贴到网页里就完事，而是整条链路都要通。首先生成密钥，我一般建议用 ed25519，兼容性和安全性都优于老旧的 RSA 2048：

ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/gitlab_ed25519

生成后把公钥内容复制出来，登录 GitLab 网页端，在「用户设置 → SSH 密钥」页面粘贴并保存。密钥类型会自动识别为 Ed25519，有效期字段可以留空，默认表示永不过期。然后配置~/.ssh/config，让 Git 知道连 GitLab 时该用哪个私钥，这对一台机器配多个 Git 服务的情况尤其重要：

Host gitlab.example.com HostName gitlab.example.com User git IdentityFile ~/.ssh/gitlab_ed25519 IdentitiesOnly yes

IdentitiesOnly yes这个参数容易被忽略，它的作用是禁止 SSH 尝试所有已加载的私钥，强制只使用指定文件。如果不加，当本机有其他密钥时，认证过程会逐个尝试，GitLab 服务端看到太多无效签名，偶尔会直接拒绝连接。配置完成后用ssh -T git@gitlab.example.com验证，看到 "Welcome to GitLab" 字样就说明链路通了。

2.2 HTTP 方式与凭据管理器：什么时候不推荐 SSH

并非所有场景都能走 SSH。有些公司的网络策略只放行 443 端口，GitLab 的 SSH 端口被防火墙挡死，这时候只能退到 HTTP 协议。HTTP 方式的关键在于凭据保存，否则每次 push 都要输一次用户名和密码。Linux 下我一般启用 Git 自带的凭证存储：

git config --global credential.helper store

这个命令把凭据明文存在~/.git-credentials里，安全级别不高，适合内网环境。如果对安全有要求，换成cache模式，只缓存内存里一段时间。Windows 环境下通常用 Git Credential Manager，首次输入密码后由 Windows 凭据管理器代为保存，会自动弹出登录窗口，体验比 Linux 下完整不少。

很多人不知道的是，HTTP 方式的账号密码并非登录密码，而是需要单独生成访问令牌。在 GitLab 网页端「用户设置 → 访问令牌」里，勾选write_repository和read_repository权限生成一串令牌，push 时用户名填任意非空值、密码填令牌即可。热词里提到的login failed. check api token or gitlab version. log in via git if the versi这类报错，九成出现在 IDE 的 GitLab 集成插件里，原因就是填了登录密码而不是访问令牌，或者令牌权限没勾仓库读写。

2.3 登录失败排查：令牌、版本与缓存的三方博弈

这类login failed报错，通常发生在 IDEA、VS Code 的 GitLab 插件或第三方桌面客户端里，现象是插件提示无法连接，但命令行 Git 一切正常。先确认版本匹配：GitLab 15.0 之后，旧版的插件 API 调用可能失效；GitLab 16 又改了部分接口的返回格式。插件若长期不更新，就会出现「命令行能用、插件永远登录失败」的怪象。

提示：登录失败时，先打开浏览器访问 GitLab 首页确认服务正常，再在命令行执行git ls-remote http://gitlab.example.com/group/repo.git验证令牌是否有效。两步都通过，问题就锁定在插件缓存上，清掉 IDE 的 GitLab 插件缓存重试即可。

还有一个低频但隐蔽的坑：某些版本里令牌有api和read_api的单独开关，插件要求令牌具备api权限，而用户在创建令牌时只勾了read_repository，结果读仓库正常、写操作和元数据拉取全部失败。做法是重新生成令牌，直接勾选api权限，一劳永逸。

3. 项目导入与仓库管理：从新增项目到 pack 文件瘦身

3.1 新增项目流程：四种来源与权限的默认选择

GitLab 里新增项目是高频操作，但团队里最常犯的错误是把「新建空项目」和「导入现有项目」混为一谈。网页端「新建项目」按钮下有四个分支：空白项目、导入项目、从 CI/CD 模板创建、从运维模板创建。导入项目又分 GitLab 实例间迁移、GitHub 导入、Bitbucket 导入、以及任意 URL 导入。选择任意 URL 导入时，源仓库地址支持 HTTP 和 SSH 两种格式，HTTP 方式需要提供源仓库的凭据，GitLab 后台会异步执行导入，大仓库可能需要几分钟。

创建项目时命名规范建议直接定死，我经手的团队一般统一小写字母加连字符，比如backend-user-service，禁止驼峰和下划线。可见性级别选「私有」，默认不要开「内部」或「公开」，避免代码意外泄露。初始化仓库时建议同时勾选「使用默认 README 初始化」，这样项目自带一个默认分支，后续推送代码不会出现「空白仓库 push 被拒」的困惑。

3.2 本地项目上传到 GitLab：两种命令路径与分支错位

很多开发者的本地项目已有 Git 历史，这时不需要重新 init，直接添加远程地址推送即可：

git remote add origin git@gitlab.example.com:group/backend-user-service.git git branch -M main git push -u origin main

branch -M main这步是强制把本地分支改名，避免本地叫master而 GitLab 默认分支叫main，导致推送后两边分支不一致、网页端看到两条默认分支的混乱局面。如果是全新目录，则先git init再走同样流程。要注意推送前先确认git status里没有敏感文件，.env、密钥、打包产物等必须写进.gitignore。另一个常见问题是提交时未配置 user.name 和 user.email，推送会被 GitLab 拒绝或提交显示为未知用户，排查时先执行：

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

邮箱建议用 GitLab 账号绑定的邮箱，否则提交记录不会关联到你的用户头像，代码量统计也会漏人。

3.3 pack 文件过大：仓库膨胀的元凶与清理手段

热词里有一条非常具体：gitlab pack-fb5fe7dfac8e953d5cc65d26074f72d5fa961d98.pack文件很大。这是管理员视角的问题，出现在服务端仓库存储目录里。GitLab 的仓库存储本质上就是裸 Git 仓库，所有历史对象都被打包成.pack文件。团队频繁推送大文件、误提交二进制又没有后续清理，pack 文件会在几次 GC 后快速膨胀。先定位哪些仓库占空间：

sudo gitlab-rake gitlab:git:gc:status sudo du -sh /var/opt/gitlab/git-data/repositories/*/*/*.git

第二行命令按实际仓库路径层级调整。找到大仓库后，要区分是历史里藏了大文件，还是当前工作区就很大。用git rev-list --objects --all加git cat-file组合排查最准：

git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | awk '/^blob/ {print $3, $4}' | sort -rn | head -20

这条命令列出仓库历史中体积最大的 20 个 blob 对象，文件名和大小一目了然。确认是历史遗留问题后，用git filter-repo做历史重写，把特定路径从全部历史中抹除。重写后所有克隆过该仓库的开发者都需要重新 clone，因为 commit hash 全部变了。历史清理完成后，在 GitLab 后台执行仓库 GC 或运行gitlab-rake gitlab:git:gc触发一次全量垃圾回收，pack 文件会重新打包。

提示：清理大文件属于高危操作，操作前必须做一次仓库级的备份。git filter-repo支持--dry-run模式，先跑一遍看影响范围再实际执行，能极大减少翻车概率。

4. 权限、代码量统计与日常协作：手册里最常被翻烂的部分

4.1 权限模型：Guest、Reporter、Developer、Maintainer、Owner

GitLab 的权限分级一共五档，从低到高是 Guest（访客）、Reporter（报告者）、Developer（开发者）、Maintainer（维护者）、Owner（所有者）。大部分人只用过 Guest 和 Developer 两档，但权限设计失当引发的安全事故，几乎都出现在中间档位。Reporter 能看代码、看 CI 日志，不能 push；Developer 能 push 到非保护分支、能创建分支和标签；Maintainer 能改保护分支规则、能合并代码、能调整项目设置；Owner 是项目最高权限，可以删除项目或转移项目。

实操中我一般这么分配：外包或实习生给 Reporter，正式开发给 Developer，技术组长或模块负责人给 Maintainer，Owner 只保留一两个人。保护分支默认保护main和master，规则是只有 Maintainer 能直接 push，其余人必须走合并请求。这个默认规则建议不要改松，否则代码评审形同虚设。热词里的「gitlab新增项目流程」其实也和权限相关——新建项目时默认的 Owner 是创建者本人，如果创建者离职，项目会进入无人管理的状态，需要管理员在后台转移项目所有者。

4.2 代码量与注释率统计：别被单点数据骗了

「gitlab仓库代码量和注释率统计」这个热词，背后是考核需求。GitLab 本身不提供「代码量排行榜」这种开箱即用的报表，但有两种可靠做法。第一是走 Git 底层，在服务器上对每个仓库跑：

git ls-files | xargs wc -l

这条命令统计当前分支所有跟踪文件的代码行数，按目录、文件类型都能拆分。注释率需要结合语言类型处理，Python 和 Shell 的注释语法不同，写脚本时按扩展名分支处理即可。第二种做法是在 GitLab 的 Insights 功能里配置自定义报表，能统计提交频率、活跃贡献者、代码变更量，但需要管理员开启功能并写 YAML 配置，在「项目 → 分析 → 洞察」里生效。

统计时有个必须注意的坑：git ls-files只统计当前 checkout 出来的文件，不包含历史版本；分支上的代码可能已经合并到 main，也可能躺在功能分支上没合入。做团队考核时，要统一基准分支和统计口径，否则同一个仓库不同人统计出来的行数差异巨大。更合理的指标是「新增行数减去删除行数」，可以用git log --since限定时间窗口后统计，这才是真实的产出量。注释率比较适合做代码健康度参考，不适合做硬性考核，因为不同团队的注释风格差异太大，容易诱导堆注释。

4.3 拉取代码与下载项目：协议与分支的四个注意点

「gitlab怎么下载项目」和「gitlab拉取代码到本地」这两个热词看来简单，但团队新人最常在这上面卡壳。先分清两种含义：一个是「把代码拉到本地仓库」，另一个是「从网页下载 ZIP 包」。网页端下载 ZIP 在项目主页的「代码 → 下载」，但这个包只包含当前分支的最新快照，没有 Git 历史，不能继续在本地做版本管理。真正的拉取代码是：

git clone git@gitlab.example.com:group/repo.git cd repo git checkout -b feature/your-work origin/main

clone 默认拉取所有分支的引用和完整历史，但只 checkout 默认分支。切到功能分支开发，最后合并回 main，这是标准协作流。需要拉取指定历史阶段的代码时，用git checkout <commit-hash>进入 detached HEAD 状态，此时不能直接提交，需要先git switch -c new-branch-name建临时分支。拉取代码时还需要区分 HTTP 和 SSH，克隆地址在项目主页的「克隆」按钮里可以切换协议。内网环境如果配了 SSH 但 clone 用了 HTTP 地址，会提示输入密码，容易让新人误以为账号密码错了。排查这一步，最快的方法是直接看克隆地址第二段是git@还是http://。

5. 部署、备份与升级避坑：Ubuntu 24.04、Docker 与启动失败的排查路径

5.1 Ubuntu 24.04 与 GitLab 19：系统兼容性是个硬门槛

热词里「gitlab 19只支持ubuntu 24.04」这条信息，对准备新部署的团队非常重要。GitLab 的版本策略有一个明显趋势：新版本会提前放弃对旧系统的支持。如果服务器用的是 Ubuntu 22.04，而你想装最新的大版本，大概率会在 apt 安装阶段就报依赖错误。这属于上游决策，不会因为机器配置高就绕过去。

我一般建议：部署前先确认 GitLab 官方对当前 OS 的支持矩阵，重点看两件事——操作系统的 EOL 日期和 GitLab 版本要求的 GLIBC 版本。Ubuntu 24.04 的 GLIBC 版本较新，能支撑新版 GitLab，而 22.04 如果硬装新版，可能出现软件包依赖无法满足的报错。这不是 bug，而是系统底层库太旧。做法有两种：一是把系统升级到 24.04 再装 GitLab；二是安装 GitLab 对应该系统支持的最后一个大版本，然后固定在那个版本上，等系统迁移后再升级 GitLab。后一种做法更稳，适合生产环境。

5.2 Docker 部署 GitLab 社区版：最省心的方案也有三个参数要调

社区版用 Docker 部署是当前中小企业的主流选择，因为不用处理 Ruby 和 PostgreSQL 的环境依赖。最小启动命令如下：

sudo docker run --detach \ --hostname gitlab.example.com \ --publish 8443:443 --publish 8022:22 --publish 8080:80 \ --name gitlab \ --restart always \ --volume /srv/gitlab/config:/etc/gitlab \ --volume /srv/gitlab/logs:/var/log/gitlab \ --volume /srv/gitlab/data:/var/opt/gitlab \ gitlab/gitlab-ce:latest

端口映射里有讲究：8022:22是把宿主机的 8022 映射到容器的 SSH 端口，避免和宿主机自身的 22 端口冲突。8080:80是让 HTTP 访问走 8080。但注意，容器内部的 GitLab 配置必须同步修改，否则网页端显示的克隆地址还是默认端口，复制出来的地址无法直接使用。启动后进入容器修改配置：

sudo docker exec -it gitlab vim /etc/gitlab/gitlab.rb # 修改 external_url 'http://gitlab.example.com:8080' # 修改 gitlab_rails['gitlab_shell_ssh_port'] = 8022 sudo docker exec -it gitlab gitlab-ctl reconfigure

gitlab-ctl reconfigure是应用配置的关键步骤，忘记执行会导致端口修改不生效。容器方式跑 GitLab 的好处是备份方便——直接把三个 volume 目录打包即可，恢复时用相同参数重新启动容器，挂载回同样的数据目录。社区版没有高可用能力，但单机场景完全够用。

Docker 部署还有一个隐性注意点：latest标签会在docker pull时升级到新版本，这会导致容器重建后 GitLab 自动跨版本升级。跨大版本升级有一系列迁移操作，如果忘了执行，页面可能白屏或出现数据库错误。稳妥做法是固定版本号，例如gitlab/gitlab-ce:17.5.2-ce.0，每次升级都走手动流程。

5.3 备份与恢复：gitlab-backup的正确姿势与常见误解

热词「gitlab备份」对应的官方命令如下：

sudo gitlab-backup create

这条命令默认备份数据库和 Git 仓库，备份文件生成在/var/opt/gitlab/backups目录。但很多人不知道，它默认不包含以下文件：gitlab.rb配置文件、/etc/gitlab/gitlab-secrets.json密钥文件、以及计划任务配置。这三个文件才是恢复的关键——如果没有gitlab-secrets.json，恢复后的实例无法解密已有的 Runner 注册令牌和 2FA 数据。所以完整备份实际是两个动作：

sudo gitlab-backup create sudo tar -czf /var/opt/gitlab/backups/etc-gitlab-backup.tar.gz /etc/gitlab

恢复操作同样要两步：先解压配置文件到/etc/gitlab，再执行gitlab-backup restore。恢复时要求 GitLab 版本与备份时的版本一致，跨版本恢复会直接报错。备份文件的保留策略默认只留 7 天，生产环境建议在gitlab.rb里调大backup_keep_time到 30 天，并把备份目录挂载到独立磁盘或对象存储，避免数据盘故障时备份也丢失。

5.4 启动不了与高危漏洞修复：三条快速定位路径

「gitlab启动不了」是运维热词，出现概率最高的三类根因：磁盘写满、PostgreSQL 数据损坏、权限被改动。先看目录占用：

df -h sudo gitlab-ctl status

gitlab-ctl status会列出所有服务组件的运行状态，哪个显示down就先处理哪个。如果是postgresql起不来，查看日志：

sudo gitlab-ctl tail postgresql

日志里频繁出现的could not open file或No space left on device，基本就是磁盘问题，清掉/var/log/gitlab下超过 30 天的旧日志，再留出 20% 余量即可。处理权限问题要小心，/var/opt/gitlab目录的属主必须是git:git，如果之前手动改过目录权限，恢复命令如下：

sudo chown -R git:git /var/opt/gitlab sudo chown -R git:git /var/log/gitlab

「gitlab高危漏洞修复方案」这个热词，对应的是 GitLab 定期发布的安全版本。修复动作没有惊喜，升级到修复后的版本即可。但升级前必须做全量备份，且注意大版本升级不能跳跃——比如从 16.x 直接升 18.x 很可能失败，需要先生到 17.x 再升 18.x。这个规则在官方升级路径文档里有明确说明，别试图跳级。

6. 最后一章：GitLab 日常巡检的五个命令与一个习惯

接手中途接手 GitLab 实例，先跑一遍巡检，比看任何手册都有用。下面这五条命令覆盖健康度、备份、脏数据、权限和磁盘五个维度，每季度跑一次能避免大多数突发故障。

# 1. 服务健康度 sudo gitlab-ctl status | grep -E "(run|down)" | wc -l # 2. 备份是否成功（看最后一行是否有备份文件） sudo find /var/opt/gitlab/backups -name "*.tar" -mtime -7 # 3. 有没有项目处于异常状态 sudo gitlab-rake gitlab:check # 4. 仓库里是否有超大的 pack 文件 sudo find /var/opt/gitlab/git-data/repositories -name "*.pack" -size +1G -exec ls -lh {} \; # 5. 磁盘余量 df -h /var/opt/gitlab | awk 'NR==2 {print "used:"$5}'

第一条里grep出来的数字正常应该和总服务数一致，数字不一致说明有组件挂了。第二条有输出代表最近一周有成功备份，没有输出就要立刻补一次手动备份。第三条的gitlab:check会输出一堆检测项，重点看Checking GitLab ... Finished和Checking Environment ... Finished之间有没有红色ERROR。第四条找出超过 1G 的 pack 文件，结合上一章的清理流程处理。第五条不用解释，磁盘满了一切服务都会停。

最后说一个我养成的习惯：每次做任何配置变更前，先把/etc/gitlab/gitlab.rb和/etc/gitlab/gitlab-secrets.json拷贝一份带日期的备份。这个文件只有几十 KB，但它是整个 GitLab 实例的「后悔药」。配置改坏了，把文件回滚再跑gitlab-ctl reconfigure就能救回来，比重新部署实例快得多。很多 GitLab 翻车现场，最终都是靠这两个文件 + 仓库备份救回来的。

希望这份基于手册的实战拆解能帮到你。下一份手册再更新时，拿着这五条命令和排查思路去对照，你会发现大部分内容都可以略读，真正要精读的始终只有认证、数据、备份和升级这四条主线。

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