自托管GitLab部署与DevOps实践：从安装到CI/CD全流程指南

GitLab自托管DevOps

于 2026-08-05 06:56:48 修改

·本内容遵循CC 4.0 BY-SA版权协议

1. 从零到一：为什么你的团队需要一个自托管的GitLab

如果你是一名开发者，或者正在管理一个技术团队，那么“代码放哪儿”这个问题，可能比“今天吃什么”更让你头疼。用网盘？版本混乱，无法协作。用公共的Git托管服务（如GitHub、Gitee）？对于商业项目，代码安全、访问速度、定制化流程又成了新的顾虑。这正是GitLab这类自托管Git平台的价值所在——它让你完全掌控自己的代码仓库、CI/CD流水线乃至整个开发生命周期。

简单来说，GitLab是一个开源的、一体化的DevOps平台。它远不止是一个Git服务器。你可以把它理解为你团队私有的、功能超级增强版的“GitHub”。从代码托管、版本管理、代码审查、问题跟踪，到自动化构建、测试、部署，甚至安全扫描和容器镜像仓库，它试图在一个产品里解决软件开发中的所有协作问题。对于初创团队、企业内部项目或对数据主权有严格要求的组织，自建GitLab意味着数据留在自己的服务器上，网络访问内网直达，所有流程规则都可以根据团队习惯深度定制。

我经历过从SVN迁移到Git，再从使用第三方服务到自建GitLab的全过程。最初觉得维护一套系统很麻烦，但实际用下来发现，这种“麻烦”带来的自主性和效率提升是巨大的。特别是当你的构建流程需要对接内部系统，或者你的代码仓库体积增长到几个GB时，内网部署的优势就非常明显了。接下来，我将以一个“过来人”的身份，带你从最基础的部署、配置，到日常高频操作和进阶玩法，手把手搭建并玩转属于你自己的GitLab。

2. 部署基石：选择最适合你的GitLab安装方式

部署是使用GitLab的第一步，也是决定后续维护复杂度的关键。网上教程很多，但如果不加选择地照搬，很容易掉进坑里。主流部署方式有三种：官方Omnibus包、Docker容器化和从源码编译。对于绝大多数团队，我强烈推荐前两种。

2.1 Omnibus包：省心省力的“全能套餐”

Omnibus是GitLab官方打包的一体化安装包，它把GitLab运行所需的所有服务（Ruby on Rails应用、PostgreSQL数据库、Redis、Nginx等）都打包在一起，并用一套统一的配置工具进行管理。这就像你去餐厅点了一个套餐，主食、配菜、汤都给你搭配好了。

为什么选择它？ 对于刚接触GitLab或者希望快速搭建生产环境的团队，这是最稳妥的选择。它的安装和升级都是一条命令的事，配置文件集中在一个地方（/etc/gitlab/gitlab.rb），日志也统一管理。你不需要关心各个组件之间的依赖和版本匹配问题。

实操步骤与核心配置： 假设你在一台全新的Ubuntu 22.04 LTS服务器上操作。

安装依赖并配置仓库：

BASH

sudo apt update

sudo apt install -y curl openssh-server ca-certificates tzdata perl

# 添加GitLab官方仓库

curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash

这里安装tzdata和perl是为了避免后续安装过程中因缺少基础依赖而报错，这是很多精简版系统镜像容易忽略的点。
执行安装：

BASH

# 将`https://gitlab.example.com`替换为你自己的域名或IP

sudo EXTERNAL_URL="https://gitlab.yourcompany.com" apt install gitlab-ee

这条命令非常关键。EXTERNAL_URL环境变量告诉安装程序你最终访问GitLab的地址。安装程序会根据这个地址自动配置Nginx等组件。如果这里填错了，后续修改会比较麻烦，可能需要手动调整多个配置。
初始配置与启动：安装完成后，需要进行初始配置并启动服务。

BASH

# 重新配置GitLab（这步会基于gitlab.rb生成所有组件的实际配置）

sudo gitlab-ctl reconfigure

# 启动所有GitLab服务

sudo gitlab-ctl start

# 检查服务状态

sudo gitlab-ctl status

reconfigure命令是Omnibus包管理的核心。任何时候修改了/etc/gitlab/gitlab.rb文件，都需要运行它来使配置生效。

必须修改的配置项： 安装后，立刻编辑/etc/gitlab/gitlab.rb，有几个关乎性能和安全的配置必须看：

RUBY

# 修改外部访问URL，必须与安装时一致

external_url 'https://gitlab.yourcompany.com'

# 配置邮箱服务，否则用户注册、密码重置等功能无法工作

gitlab_rails['smtp_enable'] = true

gitlab_rails['smtp_address'] = "smtp.your-email-provider.com"

gitlab_rails['smtp_port'] = 587

gitlab_rails['smtp_user_name'] = "gitlab@yourcompany.com"

gitlab_rails['smtp_password'] = "your-password"

gitlab_rails['smtp_domain'] = "yourcompany.com"

gitlab_rails['smtp_authentication'] = "login"

gitlab_rails['smtp_enable_starttls_auto'] = true

gitlab_rails['gitlab_email_from'] = 'gitlab@yourcompany.com'

# 限制Sidekiq作业队列的内存使用，避免OOM

sidekiq['max_concurrency'] = 10

sidekiq['min_concurrency'] = 2

# 调整Puma（Web服务器）的工作进程数，根据CPU核心数设置

puma['worker_processes'] = 2

修改后，再次运行sudo gitlab-ctl reconfigure。

注意：首次通过浏览器访问你设置的EXTERNAL_URL时，系统会强制你为默认的root用户设置一个新密码。请务必使用强密码并妥善保存，这是你系统的超级管理员账户。

2.2 Docker部署：灵活与隔离的现代选择

如果你熟悉Docker，或者希望在一台机器上运行多个服务且互不干扰，Docker部署是更佳选择。GitLab官方提供了全功能的Docker镜像。

为什么选择它？ 隔离性好，升级和回滚极其方便（换个镜像标签即可），资源占用相对清晰，也更容易实现高可用部署。缺点是需要你具备一定的Docker和容器网络知识。

使用Docker Compose一键部署： 创建一个docker-compose.yml文件是管理复杂容器应用的最佳实践。

YAML

version: '3.7'

services:

gitlab:

image: 'gitlab/gitlab-ee:latest' # 社区版使用 gitlab/gitlab-ce

container_name: gitlab

restart: always

hostname: 'gitlab.yourcompany.com' # 重要：必须与访问域名一致

environment:

GITLAB_OMNIBUS_CONFIG: |

external_url 'https://gitlab.yourcompany.com'

# 以下配置可覆盖镜像内的默认设置

gitlab_rails['gitlab_shell_ssh_port'] = 2222 # 映射宿主机的2222端口到容器的22端口

gitlab_rails['smtp_enable'] = true

gitlab_rails['smtp_address'] = "smtp.gmail.com"

gitlab_rails['smtp_port'] = 587

gitlab_rails['smtp_user_name'] = "your-email@gmail.com"

gitlab_rails['smtp_password'] = "your-app-password" # 注意使用应用专用密码

gitlab_rails['smtp_domain'] = "gmail.com"

gitlab_rails['smtp_authentication'] = "login"

gitlab_rails['smtp_enable_starttls_auto'] = true

gitlab_rails['gitlab_email_from'] = 'your-email@gmail.com'

ports:

- '80:80'

- '443:443'

- '2222:22' # 将宿主机的2222端口映射到容器的22端口，用于SSH克隆

volumes:

- './config:/etc/gitlab' # 配置文件持久化

- './logs:/var/log/gitlab' # 日志持久化

- './data:/var/opt/gitlab' # 应用数据持久化（仓库、数据库等）

shm_size: '256m' # 避免内存不足问题

关键点解析：

hostname和external_url必须严格一致，否则GitLab生成的仓库克隆地址会是错的。
我们将容器的SSH端口（22）映射到了宿主机的2222端口。这意味着你克隆仓库时需要使用ssh://git@gitlab.yourcompany.com:2222/group/project.git这样的地址。这是为了避免与宿主机本身的SSH服务（端口22）冲突。
三个volumes映射至关重要，它们将配置、日志和数据持久化到宿主机，这样即使容器被删除，你的所有数据（包括代码仓库）都还在。
shm_size是为了解决GitLab（特别是其中的Puma和Sidekiq组件）在默认的64M共享内存下可能崩溃的问题。

启动与初始化：

BASH

# 在docker-compose.yml所在目录执行

docker-compose up -d

首次启动需要较长时间（可能超过5分钟）来初始化数据库和启动所有服务。你可以通过docker-compose logs -f gitlab来跟踪日志，直到看到gitlab Reconfigured!这样的信息。

踩坑记录：我曾因为没设置shm_size，在团队开始频繁使用GitLab后，Sidekiq作业经常莫名崩溃，日志里报Cannot allocate memory错误。调整到256m或512m后问题消失。另一个坑是邮件配置，Gmail等邮箱需要开启“应用专用密码”而不是直接使用登录密码，否则SMTP认证会失败。

3. 安全与协作基础：用户、SSH密钥与项目权限

部署完成只是第一步，让团队安全、高效地使用起来才是核心。这涉及到用户管理、认证方式和项目权限模型。

3.1 用户管理：从邀请到权限分配

GitLab的用户可以通过多种方式注册：管理员创建、邮件邀请、LDAP/AD集成、OAuth2（如GitHub、Google登录）等。对于内部团队，我推荐使用“邮件邀请”或“LDAP集成”。

管理员手动创建用户： 以管理员身份登录后，进入 管理区域（Admin Area） -> 用户（Users），点击“新建用户”。填写基本信息后，系统会向该邮箱发送一封设置密码的邮件。这里有个细节：你可以选择“跳过确认”，这样用户会立即收到激活邮件，而不是等待管理员确认。

更高效的方式：群组邀请 在实际协作中，我们通常按部门或项目划分群组（Group）。在群组页面，点击“邀请成员”，输入邮箱或用户名，并直接为其分配在该群组内的角色（如：报告者、开发者、维护者、所有者）。被邀请的用户会收到邮件通知。这种方式将用户创建和权限分配一步完成，效率更高。

用户权限模型解读： GitLab的权限是层级化的，从高到低为：所有者（Owner）-> 维护者（Maintainer）-> 开发者（Developer）-> 报告者（Reporter）-> 访客（Guest）。理解每个角色的能力边界对安全管理至关重要：

访客：只能看，不能动。适合外部顾问或审计人员。
报告者：可以看代码、提Issue、写Wiki，但不能推送代码。适合测试或产品人员。
开发者：核心开发角色。可以克隆、推送代码到非受保护分支、创建合并请求、管理自己创建的Issue。但不能直接推送到main、master等受保护分支，也不能操作生产环境相关的CI/CD变量。
维护者：项目技术负责人。可以推送至受保护分支、管理合并请求、运行CI/CD流水线、管理项目设置（除删除项目和解散群组）。
所有者：拥有项目的最高权限，可以删除项目、转移项目、管理群组成员。

一个常见的权限设计误区是给所有开发者“维护者”权限。正确的做法应该是：默认给开发者角色，仅对技术负责人或核心成员授予维护者权限。 通过“受保护分支”规则来强制代码必须通过合并请求（Merge Request）才能进入主分支，这是保证代码质量的关键防线。

3.2 SSH密钥配置：告别每次输入密码

使用HTTPS克隆代码每次都需要输入用户名密码，非常繁琐。配置SSH密钥后，可以实现免密认证，安全又方便。

本地生成SSH密钥对： 打开终端（Linux/Mac）或Git Bash（Windows），执行：

BASH

ssh-keygen -t ed25519 -C "your_email@example.com"

# 或者使用更兼容的RSA算法

# ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

按提示选择密钥保存路径（默认即可）和设置密码（可为空）。完成后，在~/.ssh/目录下会生成两个文件：id_ed25519（私钥，绝不可泄露）和id_ed25519.pub（公钥）。

将公钥添加到GitLab：

复制公钥内容：cat ~/.ssh/id_ed25519.pub，全选复制。
登录GitLab，点击右上角头像 -> 偏好设置（Preferences） -> SSH密钥（SSH Keys）。
将复制的公钥内容粘贴到“密钥”文本框中，“标题”会自动生成，也可以手动修改一个易识别的名字（如“My Laptop - Ed25519”）。
点击“添加密钥”。

验证连接：

BASH

ssh -T git@gitlab.yourcompany.com

如果配置了非标准SSH端口（如Docker部署时的2222），需要修改~/.ssh/config文件：

BASH

Host gitlab.yourcompany.com

HostName gitlab.yourcompany.com

User git

Port 2222

IdentityFile ~/.ssh/id_ed25519

然后再执行ssh -T git@gitlab.yourcompany.com，看到Welcome to GitLab, @your_username!就成功了。

实操心得：团队新成员入职时，我会要求他们第一件事就是配置SSH密钥并验证通过。很多“克隆失败”的问题都源于SSH配置错误。一个快速排查命令是ssh -vT git@gitlab.yourcompany.com，通过-v参数输出详细日志，可以清晰地看到认证过程在哪一步失败了。

3.3 项目创建与初始推送：迈出第一步

有了用户和密钥，就可以开始创建项目并推送代码了。

在GitLab上创建新项目： 点击导航栏的“+”号 -> “新建项目”。你可以选择：

空白项目：最常用，创建一个空的Git仓库。
从模板创建：使用内置的.gitlab-ci.yml模板快速创建CI/CD流水线。
导入项目：从GitHub、Bitbucket等平台导入。

创建时，注意填写项目路径（URL的一部分）、项目名称，以及选择可见性级别：

私有：只有被明确授予权限的用户和组成员可见。
内部：所有登录用户可见（适合公司内部开源）。
公开：互联网上所有人可见（无需登录）。

将本地代码推送到新仓库： 假设你本地已有一个项目目录my-project。

BASH

cd my-project

# 初始化本地仓库（如果尚未初始化）

git init

# 添加所有文件到暂存区

git add .

# 提交到本地仓库

git commit -m "Initial commit"

# 添加远程仓库地址（从GitLab项目页面复制SSH或HTTPS地址）

git remote add origin git@gitlab.yourcompany.com:your-group/my-project.git

# 推送代码到远程的main分支，并设置上游追踪

git push -u origin main

# 如果你的默认分支是master，则用

# git push -u origin master

-u参数设置了上游分支关联，以后在这个分支上直接执行git push或git pull即可，无需再指定远程和分支名。

常见问题：“login failed. check api token or gitlab version.” 这个错误通常出现在通过API或某些客户端（如Jenkins、IDE插件）认证时。原因和解决方案：

令牌问题：使用的个人访问令牌（Personal Access Token）或项目访问令牌（Project Access Token）已过期、被撤销，或者权限范围（scopes）不足。去 偏好设置 -> 访问令牌 检查令牌的有效期和勾选的权限（如api， read_repository， write_repository等）。
GitLab版本不兼容：某些较老的客户端或脚本可能不支持新版本GitLab的API。尝试升级客户端，或者检查GitLab的API版本。如果是通过Git命令行操作，确保你的Git版本不是太老。
URL或认证方式错误：确认你使用的API地址（如https://gitlab.yourcompany.com/api/v4）是否正确，以及是在请求头中正确传递了令牌（PRIVATE-TOKEN: <your_token>）。

4. 日常开发流：分支策略、合并请求与代码审查

GitLab的核心价值在于赋能团队协作。一个清晰的Git工作流是高效协作的基础。我将介绍一种基于功能分支的Git Flow简化版，这也是目前最流行的实践之一。

4.1 功能分支工作流：从开发到合并

我们假设主分支是main，所有开发都在特性分支上进行。

从主分支创建特性分支：

BASH

# 首先，确保本地主分支是最新的

git checkout main

git pull origin main

# 创建并切换到新分支，分支名最好有描述性，如 feature/user-authentication

git checkout -b feature/add-search-function
在特性分支上开发并提交：进行你的代码修改，然后频繁提交。

BASH

git add .

git commit -m "feat: implement basic search API endpoint"

# ... 继续开发 ...

git add .

git commit -m "test: add unit tests for search service"
推送分支到远程：

BASH

git push origin feature/add-search-function

首次推送时，Git会提示你使用--set-upstream，直接按提示操作即可。
在GitLab上创建合并请求（Merge Request, MR）：推送后，GitLab页面通常会有一个醒目的按钮提示你“创建合并请求”。点击它。
- 源分支：选择你刚推送的feature/add-search-function。
- 目标分支：选择main。
- 标题：清晰描述这个MR的目的，如“添加用户搜索功能”。
- 描述：详细说明修改内容、为什么修改、测试情况等。可以使用模板（GitLab支持自定义MR描述模板）。
- 分配评审者：选择相关的同事进行代码审查。
- 设置：勾选“删除源分支”（合并后自动删除特性分支，保持仓库整洁），根据情况选择“压缩提交”（将多个提交合并为一个）。
代码审查与讨论：评审者会在MR的“变更”页面上查看代码差异，并可以针对某一行代码发表评论。开发者可以根据评论在线修改代码并再次推送，MR会自动更新。所有讨论都记录在MR中，形成知识沉淀。
CI/CD流水线通过后合并：如果项目配置了CI/CD（见下一章），MR会触发一条流水线。必须在流水线成功（绿色）后，才能合并。维护者点击“合并”按钮，代码就并入了主分支。

4.2 高效代码审查：GitLab AI Code Review 与人工结合

代码审查是保证质量的关键环节。GitLab自身提供了强大的评论、批注、草稿模式（Draft MR）等功能。此外，从16.2版本开始，GitLab引入了基于AI的代码审查建议（GitLab Duo Code Suggestions），这是一个值得尝试的提效工具。

AI Code Review 如何工作？ 当你在MR中查看代码差异时，GitLab Duo可以自动分析变更，并提供改进建议。例如，它可能提示：“这里可以考虑添加错误处理”，或者“这个函数复杂度较高，建议重构”。它基于大量的开源代码模式进行学习，能发现一些常见的代码异味、潜在bug和安全漏洞。

但请记住，AI是辅助，不是替代：

不要盲目接受：AI的建议可能不总是正确或符合你项目的特定编码规范。审查者需要判断建议的合理性。
结合人工审查重点：人工审查应聚焦于AI不擅长的领域：业务逻辑的正确性、架构设计的合理性、非功能性需求（如性能、可扩展性）以及团队约定的特定模式。
作为学习工具：对于团队新人，AI给出的建议可以作为一个很好的学习参考，了解常见的代码最佳实践。

我的审查清单：在审查一个MR时，我通常会按以下顺序进行：

整体把握：先看MR描述和关联的Issue，理解变更背景和目的。
浏览变更范围：快速浏览所有改动的文件，评估影响面。
逐文件审查：
- 逻辑正确性：算法、边界条件处理是否正确？
- 代码风格：是否符合项目ESLint/Prettier/SonarQube规则？
- 测试覆盖：新增代码是否有对应的单元测试或集成测试？
- 文档更新：公共API的修改是否同步更新了文档？
- 安全与性能：有无SQL注入、XSS风险？有无N+1查询、内存泄漏隐患？
运行与测试：在本地拉取该分支，运行测试套件，必要时手动测试核心功能。

4.3 同步Fork的仓库：参与开源或内部复用

“Fork”是参与开源项目或内部跨团队协作的常用模式。你Fork了上游（主）仓库后，在自己的副本上开发。如何让你的Fork与上游仓库保持同步，是一个高频问题。

为上游仓库添加远程地址： 假设你Fork的仓库地址是git@gitlab.com:your-name/original-project.git，上游仓库地址是git@gitlab.com:upstream-group/original-project.git。

BASH

# 克隆你自己的Fork到本地

git clone git@gitlab.com:your-name/original-project.git

cd original-project

# 添加上游仓库作为一个新的远程，通常命名为 upstream

git remote add upstream git@gitlab.com:upstream-group/original-project.git

# 查看所有远程仓库

git remote -v

# 应该显示 origin（你的Fork）和 upstream（原始仓库）

获取上游更新并合并到你的分支： 当上游仓库有新的提交时，你需要将它们同步到你的本地仓库，并解决可能的冲突。

BASH

# 1. 确保你在你想更新的本地分支上（比如 main）

git checkout main

# 2. 从上游仓库获取所有分支的最新提交

git fetch upstream

# 3. 将上游的main分支合并到你本地的main分支

git merge upstream/main

# 如果出现冲突，需要手动解决冲突文件，然后 git add . 和 git commit

# 4. 将更新后的本地main分支推送到你自己的Fork（origin）

git push origin main

将更新同步到你的特性分支： 如果你的特性分支是从旧的main分支创建的，那么在向主仓库提交MR前，最好先同步一下上游的改动，减少冲突。

BASH

# 在特性分支上

git checkout feature/my-feature

# 将上游main分支的更新合并进来

git merge upstream/main

# 或者使用变基，使提交历史更清晰（但变基会重写历史，协作分支需谨慎）

# git rebase upstream/main

处理完冲突后，推送到你的Fork，你的MR会自动更新。

注意：如果你在GitLab网页端对Fork的仓库发起了合并请求（MR）到上游，那么上游的维护者合并后，你的Fork仓库不会自动更新。你仍然需要按照上述步骤，手动将上游的变更拉取到你的Fork中。一些第三方工具或GitLab的“同步Fork”按钮（如果上游仓库允许）可以简化这个过程，但原理相同。

5. 自动化引擎：GitLab CI/CD 从入门到实践

CI/CD（持续集成/持续部署）是现代软件工程的基石。GitLab CI/CD是其最强大的功能之一，它通过项目根目录下的一个名为.gitlab-ci.yml的配置文件来定义整个自动化流程。

5.1 .gitlab-ci.yml 文件结构与核心概念

这个文件采用YAML格式。我们从一个最简单的例子开始，构建一个Node.js应用。

YAML

# .gitlab-ci.yml

stages:

- test

- build

- deploy

variables:

# 定义全局变量

NODE_VERSION: "18"

# 定义作业（Jobs）

unit-test:

stage: test

image: node:$NODE_VERSION

script:

- npm ci # 使用ci命令安装依赖，比install更快更严格

- npm run test

artifacts:

when: always

paths:

- coverage/

reports:

junit:

- junit.xml

only:

- merge_requests # 仅在合并请求时运行

build-image:

stage: build

image: docker:latest

services:

- docker:dind # 使用Docker in Docker服务

variables:

DOCKER_HOST: tcp://docker:2375

DOCKER_TLS_CERTDIR: ""

script:

- docker build -t my-app:$CI_COMMIT_SHORT_SHA .

- docker tag my-app:$CI_COMMIT_SHORT_SHA my-registry.com/my-group/my-app:$CI_COMMIT_SHORT_SHA

- docker push my-registry.com/my-group/my-app:$CI_COMMIT_SHORT_SHA

only:

- main # 仅当代码推送到main分支时运行

deploy-to-staging:

stage: deploy

image: alpine:latest

script:

- apk add --no-cache curl

- |

# 假设你有一个部署脚本的API

curl -X POST https://deploy.internal.com/staging \

-H "Authorization: Bearer $DEPLOY_TOKEN" \

-d "image=my-registry.com/my-group/my-app:$CI_COMMIT_SHORT_SHA"

environment:

name: staging

url: https://staging.myapp.com

only:

- main

dependencies:

- build-image # 声明依赖，确保本作业能获取到上游作业的上下文（如变量）

核心概念解析：

stages：定义流水线的阶段顺序。作业（job）通过stage属性归属于某个阶段。同一阶段的作业并行执行，不同阶段按顺序执行。
job：一个具体的自动化任务，如unit-test。每个job必须包含script，即要执行的shell命令。
image：指定运行该job的Docker镜像。这保证了环境的一致性。
services：提供额外的Docker服务，如docker:dind让我们可以在job内运行Docker命令。
artifacts：指定job生成的产物（如编译后的jar包、测试报告、日志）并传递给后续阶段的job。这里我们把测试报告和覆盖率数据保存下来。
environment：为部署job定义环境（如staging, production），GitLab会跟踪每次部署到该环境的情况。
only/except：控制job在什么条件下触发。这里我们让测试在MR时运行，构建和部署只在main分支推送时运行。
variables：定义变量。可以在全局、job级别覆盖。CI_COMMIT_SHORT_SHA是GitLab预定义的变量，代表本次提交的短哈希值，常用于镜像标签。
dependencies：显式声明job依赖，用于获取上游job的artifacts。

5.2 配置Runner：流水线的执行者

定义了流水线，还需要有“工人”来执行它，这就是GitLab Runner。Runner是一个轻量级进程，它从GitLab拉取job并在指定环境中运行。

安装与注册Runner：

安装：根据你的服务器系统，参考官方文档安装Runner。例如在Ubuntu上：

BASH

# 添加官方仓库

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

sudo apt-get install gitlab-runner
注册：Runner需要向GitLab实例注册才能接收任务。

BASH

sudo gitlab-runner register

注册时会要求输入：
- GitLab实例URL：你的GitLab地址，如https://gitlab.yourcompany.com。
- 注册令牌：进入GitLab管理区域 -> 概览 -> Runners，找到“注册令牌”。对于共享Runner（所有项目可用）用这里的令牌；对于项目特定Runner，去项目设置 -> CI/CD -> Runners 获取令牌。
- 描述和标签：给Runner一个描述，并打上标签（如docker, linux）。标签用于在.gitlab-ci.yml中通过tags选择特定的Runner。
- 执行器：Runner运行job的方式。最常见的是docker，它为每个job启动一个干净的容器。也可以选shell（直接在Runner主机上运行）、kubernetes等。

配置优化与踩坑：

并发数与资源：在Runner的配置文件（/etc/gitlab-runner/config.toml）中，可以设置concurrent限制同时运行的job数，避免耗尽主机资源。
Docker执行器的缓存：为了加速依赖安装，可以配置Docker卷缓存。例如，缓存Node.js的node_modules：

TOML

[[runners]]

executor = "docker"

[runners.docker]

volumes = ["/cache", "/home/user/.npm:/root/.npm:rw"] # 将宿主机的npm缓存目录挂载到容器内
私有镜像拉取：如果job中需要从私有Docker仓库拉取镜像，需要在Runner配置或job中配置认证。一种方式是在config.toml中配置[runners.docker]的pull_policy和auth，更安全的方式是在job里使用DOCKER_AUTH_CONFIG变量。

5.3 进阶实践：Webhook触发Jenkins与Docker Compose部署

虽然GitLab CI/CD功能强大，但有些团队已有成熟的Jenkins流水线。这时可以将GitLab作为源代码管理和触发源，通过Webhook集成Jenkins。

在GitLab中配置Webhook： 进入项目设置 -> Webhooks。

URL：填写你的Jenkins项目的GitLab Webhook触发地址，通常是https://jenkins.yourcompany.com/project/your-project或https://jenkins.yourcompany.com/gitlab/build_now（取决于Jenkins插件）。
触发事件：至少勾选“推送事件”和“合并请求事件”。这样代码推送或MR更新都会触发Jenkins构建。
Secret令牌：生成一个令牌，并在Jenkins的GitLab插件配置中填入相同的令牌，用于验证请求来源，防止恶意触发。

在Jenkins中配置GitLab插件：

安装插件：GitLab Plugin和GitLab API Plugin。
在Jenkins任务配置中：
- 源码管理选择Git，填入GitLab仓库地址，并配置认证（SSH密钥或用户名密码/令牌）。
- 在“构建触发器”中勾选“Build when a change is pushed to GitLab”，并填入从GitLab Webhook配置页面复制的Secret令牌。
- 在“高级”设置中，可以指定哪些分支的推送或MR事件会触发构建。

使用Docker Compose部署： 在CI/CD的deploy阶段，一个常见的模式是使用Docker Compose在服务器上更新服务。

YAML

deploy-to-server:

stage: deploy

image: alpine:latest

before_script:

- apk add --no-cache openssh-client docker-compose

- eval $(ssh-agent -s)

- echo "$SSH_PRIVATE_KEY" | ssh-add -

- mkdir -p ~/.ssh

- chmod 700 ~/.ssh

script:

- ssh -o StrictHostKeyChecking=no user@deploy-server "

cd /opt/my-app &&

docker-compose pull &&

docker-compose up -d

only:

- main

variables:

# 这些变量需要在GitLab项目设置 -> CI/CD -> Variables中定义

# SSH_PRIVATE_KEY: 部署服务器的SSH私钥

# SSH_KNOWN_HOSTS: 部署服务器的主机密钥

这个job做了几件事：

安装必要的工具（ssh, docker-compose）。
加载存储在GitLab CI/CD变量中的SSH私钥（切勿将私钥硬编码在yml文件中！）。
通过SSH连接到部署服务器，进入项目目录，拉取最新的Docker镜像，然后重启服务。

安全警告：将SSH私钥放在CI/CD变量中是常见的做法，但务必确保该密钥是专为部署生成的，权限最小化（只能执行必要的命令），并定期轮换。另一种更安全的方式是使用类似Vault的密钥管理工具动态获取凭证。

6. 运维与安全：漏洞修复、备份与日常管理

将GitLab用于生产，就必须关注其安全性和稳定性。这包括及时修复漏洞、定期备份以及掌握日常管理技巧。

6.1 高危漏洞修复：以CVE-2023-XXXX为例

当GitLab发布安全公告时，特别是“高危”或“严重”级别，需要立即行动。修复流程通常是升级到已修复的版本。

升级步骤（以Omnibus包为例）：

查看当前版本与公告：在GitLab管理区域 -> 概览查看当前版本。关注GitLab官方发布的安全公告，确认影响版本和修复版本。
备份：升级前务必进行完整备份！ 执行sudo gitlab-rake gitlab:backup:create。备份文件默认在/var/opt/gitlab/backups/目录下。
执行升级：

BASH

# 对于Omnibus包，升级命令与安装类似

# 指定要升级到的版本号，例如16.8.1

sudo apt update

sudo apt install gitlab-ee=16.8.1-ee.0

也可以使用sudo apt upgrade gitlab-ee升级到仓库中的最新版本。
重新配置与重启：

BASH

sudo gitlab-ctl reconfigure

sudo gitlab-ctl restart
验证：升级完成后，访问GitLab页面，检查各功能是否正常，并在管理区域确认版本号已更新。

Docker部署的升级： 对于Docker部署，升级更为简单和安全。

备份数据卷（config, logs, data）。
修改docker-compose.yml中的镜像标签到新版本，例如image: 'gitlab/gitlab-ee:16.8.1-ee.0'。
执行docker-compose pull拉取新镜像。
执行docker-compose up -d重启容器。GitLab容器在启动时会自动运行数据库迁移等升级步骤。

升级策略建议：

测试环境先行：如果条件允许，先在测试环境进行升级演练。
关注版本跳跃：大版本升级（如15.x -> 16.x）可能需要额外的升级步骤，请务必阅读官方升级指南。
订阅通知：订阅GitLab安全公告邮件，或使用漏洞扫描工具监控你的实例。

6.2 备份与恢复：数据安全的生命线

备份不仅仅是执行一条命令，更需要一个可靠的策略。

自动化备份配置： 编辑/etc/gitlab/gitlab.rb，可以配置备份策略：

RUBY

# 设置备份路径

gitlab_rails['backup_path'] = "/var/opt/gitlab/backups"

# 备份保留时间（秒），604800秒=7天

gitlab_rails['backup_keep_time'] = 604800

# 备份时包含仓库文件（默认包含）

gitlab_rails['backup_upload_connection'] = {

'provider' => 'AWS',

'region' => 'eu-west-1',

'aws_access_key_id' => 'AKIAKIAKI',

'aws_secret_access_key' => 'secret123'

}

gitlab_rails['backup_upload_remote_directory'] = 'my.gitlab.backups'

配置后运行sudo gitlab-ctl reconfigure。可以设置一个Cron任务定时执行备份：

BASH

# 编辑crontab -e，添加以下行，每天凌晨2点执行备份

0 2 * * * /opt/gitlab/bin/gitlab-rake gitlab:backup:create CRON=1

恢复演练（至关重要！）：备份文件不能恢复等于没有备份。定期在隔离环境进行恢复演练。

准备一台与生产环境版本一致的干净服务器。
停止相关服务：sudo gitlab-ctl stop unicorn sudo gitlab-ctl stop sidekiq。
恢复备份（假设备份文件名为1650012345_gitlab_backup.tar）：

BASH

# 将备份文件放到配置的备份路径下

sudo cp 1650012345_gitlab_backup.tar /var/opt/gitlab/backups/

cd /var/opt/gitlab/backups

# 恢复操作，BACKUP变量不需要带路径和`_gitlab_backup.tar`后缀

sudo gitlab-backup restore BACKUP=1650012345
重新配置并启动：sudo gitlab-ctl reconfigure sudo gitlab-ctl restart。
检查数据完整性。

6.3 日常管理技巧：令牌、成员与问题排查

个人访问令牌（Personal Access Token）在哪里生成？ 这是集成第三方工具（如Jenkins、IDEA、VS Code）的关键。进入 用户设置（Settings） -> 访问令牌（Access Tokens）。可以创建具有不同权限范围（Scopes）的令牌，如api（完全API访问）、read_repository（只读仓库）、write_repository（读写仓库）等。令牌只会显示一次，务必妥善保存。

GitLab管理员如何修改其他用户密码？ 管理员可以在 管理区域 -> 用户，找到相应用户，点击“编辑”。在编辑页面中，可以直接设置新密码。注意，这不会通知用户，通常用于用户忘记密码时的重置。

GitLab群组如何添加新成员？ 进入目标群组页面，点击左侧边栏的“成员”。点击“邀请成员”，输入用户名或邮箱，选择角色（Guest, Reporter, Developer, Maintainer, Owner），点击“邀请”即可。

常见问题排查思路：

页面访问502错误：通常是Puma（Unicorn）或Sidekiq服务异常。检查sudo gitlab-ctl status，查看相关服务日志sudo gitlab-ctl tail puma / sudo gitlab-ctl tail sidekiq。
仓库推送缓慢或失败：检查服务器磁盘空间（df -h）、内存使用（free -m）。GitLab的Gitaly组件（负责Git操作）对IO要求高，磁盘性能不足是常见瓶颈。
后台作业堆积：进入 管理区域 -> 监控 -> 后台作业，查看Sidekiq队列情况。如果队列持续增长，可能需要增加Sidekiq并发数或优化耗时作业。
磁盘空间清理：除了备份，可以定期清理无用数据：sudo gitlab-rake gitlab:cleanup:orphan_job_artifact_files清理过期的CI产物，sudo gitlab-rake gitlab:cleanup:orphan_lfs_file_references清理孤立的LFS文件引用。

从部署、配置到日常开发、自动化流水线，再到运维安全，GitLab提供了一个覆盖软件交付全生命周期的强大平台。掌握它，不仅仅是学会点击哪些按钮，更是理解其背后的设计理念和工作流，从而真正提升团队的研发效能与协作质量。