1. GitLab CI/CD 环境搭建实战指南
在当今的软件开发流程中,持续集成和持续交付(CI/CD)已经成为不可或缺的一环。作为一名长期从事DevOps实践的工程师,我想分享一套基于GitLab的CI/CD环境搭建方案,这套方案已经在多个生产环境中得到验证,能够有效提升团队的开发效率和部署质量。
本次搭建的环境将包含以下核心组件:
- GitLab CE 16.11.1:作为代码托管和CI/CD编排中心
- Harbor 2.10.0:作为私有镜像仓库
- GitLab Runner:负责执行CI/CD流水线任务
- 腾讯云CVM:作为基础设施平台
这套环境特别适合中小型团队使用,所有组件都部署在内网环境中,既保证了安全性又确保了构建速度。下面我将详细介绍从零开始搭建的全过程。
2. 环境准备与基础配置
2.1 服务器资源规划
我们需要准备三台腾讯云CVM服务器,具体配置如下:
| 服务器角色 | 配置 | 系统版本 | 内网IP示例 | 用途说明 |
|---|---|---|---|---|
| GitLab服务器 | 4C8G | Ubuntu 22.04 | 192.168.1.2 | 运行GitLab服务 |
| Harbor服务器 | 4C8G | Ubuntu 22.04 | 192.168.1.3 | 运行私有镜像仓库 |
| GitLab Runner | 2C4G | Ubuntu 22.04 | 192.168.1.4 | 执行CI/CD流水线任务 |
提示:虽然我们为每台机器分配了弹性公网IP,但实际生产环境中可以完全使用内网通信。公网IP仅用于方便安装时的软件下载。
2.2 基础软件安装
在所有三台服务器上执行以下操作:
- 更新系统并安装必要工具:
bash复制sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget vim net-tools
- 安装Docker和Docker Compose:
bash复制sudo apt install -y docker.io docker-compose
- 配置腾讯云镜像加速器:
bash复制sudo tee /etc/docker/daemon.json <<-'EOF'
{
"registry-mirrors": ["https://mirror.ccs.tencentyun.com"]
}
EOF
sudo systemctl restart docker
2.3 镜像与安装包准备
根据服务器角色准备相应的镜像文件:
GitLab服务器需要:
- gitlab-ce-16.11.1.tar(离线安装包)
Harbor服务器需要:
- harbor-online-installer-v2.10.0.tgz
Runner服务器需要:
- docker:24镜像
- gitlab/gitlab-runner:alpine镜像
- gitlab/gitlab-runner-helper:x86_64-v18.9.0镜像
注意事项:如果是在严格的内网环境中,需要先在一台能访问外网的机器下载这些文件,然后通过内网传输到各服务器。
3. GitLab服务部署
3.1 安装GitLab CE
在GitLab服务器(192.168.1.2)上执行以下步骤:
- 创建工作目录:
bash复制mkdir -p /srv/gitlab && cd /srv/gitlab
- 创建docker-compose.yml文件:
yaml复制version: "3.8"
services:
gitlab:
image: gitlab/gitlab-ce:16.11.1-ce.0
container_name: gitlab
restart: always
hostname: 192.168.1.2
environment:
GITLAB_OMNIBUS_CONFIG: |
external_url 'http://192.168.1.2'
ports:
- "80:80"
volumes:
- ./config:/etc/gitlab
- ./logs:/var/log/gitlab
- ./data:/var/opt/gitlab
- 启动GitLab服务:
bash复制docker-compose up -d
GitLab启动需要3-5分钟时间,可以通过以下命令检查状态:
bash复制docker logs -f gitlab
3.2 初始配置
- 获取初始root密码:
bash复制docker exec -it gitlab grep 'Password:' /etc/gitlab/initial_root_password
-
通过浏览器访问GitLab(使用公网IP),使用root账户和上面获取的密码登录。
-
登录后立即修改root密码。
-
创建两个项目仓库:
- demo-app:用于存放Java应用源代码和CI配置文件
- demo-gitops:用于存放部署配置(未来可用于CD流程)
4. Harbor私有镜像仓库部署
4.1 安装Harbor
在Harbor服务器(192.168.1.3)上执行:
- 下载并解压Harbor安装包:
bash复制wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-online-installer-v2.10.0.tgz
tar xvf harbor-online-installer-v2.10.0.tgz
cd harbor
- 准备配置文件:
bash复制cp harbor.yml.tmpl harbor.yml
vim harbor.yml
关键配置项:
yaml复制hostname: 192.168.1.3
http:
port: 80
harbor_admin_password: YourStrongPassword
- 执行安装:
bash复制./install.sh
4.2 Harbor用户与项目管理
-
访问Harbor UI(http://192.168.1.3),使用admin账户和设置的密码登录。
-
创建一个新项目"demo",访问级别设为"公开"。
-
创建一个普通用户(如ci-user),并赋予该项目"开发者"权限。
安全提示:生产环境中建议配置HTTPS并设置更严格的访问控制。
5. GitLab Runner部署与配置
5.1 Runner服务器准备
在Runner服务器(192.168.1.4)上执行:
- 配置Docker允许访问不安全的Harbor仓库:
bash复制sudo tee /etc/docker/daemon.json <<-'EOF'
{
"insecure-registries": ["192.168.1.3:80"],
"registry-mirrors": ["https://mirror.ccs.tencentyun.com"]
}
EOF
sudo systemctl restart docker
- 拉取Runner相关镜像:
bash复制docker pull gitlab/gitlab-runner:alpine
docker pull gitlab/gitlab-runner-helper:x86_64-v18.9.0
docker pull docker:24
5.2 启动Runner容器
- 创建Runner工作目录:
bash复制mkdir -p /srv/gitlab-runner/config
- 启动Runner容器:
bash复制docker run -d --name gitlab-runner --restart always \
-v /srv/gitlab-runner/config:/etc/gitlab-runner \
-v /var/run/docker.sock:/var/run/docker.sock \
gitlab/gitlab-runner:alpine
5.3 注册Runner到GitLab
-
在GitLab的demo-app项目中,进入Settings → CI/CD → Runners,复制注册token。
-
在Runner服务器上执行注册:
bash复制docker exec -it gitlab-runner gitlab-runner register
按照提示输入以下信息:
- GitLab URL: http://192.168.1.2
- 注册token: 从GitLab获取的token
- Runner描述: cvm-runner-1
- Tag列表: (直接回车留空)
- 执行器: docker
- 默认镜像: docker:24
- 关键配置修改:
编辑/srv/gitlab-runner/config/config.toml,确保有以下配置:
toml复制[[runners]]
[runners.docker]
privileged = true
volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
5.4 配置CI/CD变量
在GitLab的demo-app项目中,进入Settings → CI/CD → Variables,添加以下变量:
- HARBOR_USER: Harbor普通用户名(如ci-user)
- HARBOR_PASSWORD: 对应的密码
建议勾选"Mask variable"选项保护敏感信息。
6. Java应用CI流水线配置
6.1 项目结构准备
在demo-app项目中创建以下目录结构:
code复制demo-app/
├── .gitlab-ci.yml
├── Dockerfile
├── pom.xml
└── src/
├── main/
│ ├── java/
│ │ └── com/example/demo/
│ │ ├── DemoApplication.java
│ │ └── HelloController.java
│ └── resources/
│ └── application.properties
6.2 关键文件配置
- .gitlab-ci.yml内容:
yaml复制image: docker:24
variables:
DOCKER_TLS_CERTDIR: ""
HARBOR_HOST: "192.168.1.3:80"
HARBOR_PROJECT: "demo"
HARBOR_REPO: "spring-demo"
IMAGE: "$HARBOR_HOST/$HARBOR_PROJECT/$HARBOR_REPO"
stages:
- docker
build_and_push:
stage: docker
script:
- docker info | grep -A3 "Insecure Registries" || true
- docker login "$HARBOR_HOST" -u "$HARBOR_USER" -p "$HARBOR_PASSWORD"
- docker build -t "$IMAGE:$CI_COMMIT_SHA" .
- docker push "$IMAGE:$CI_COMMIT_SHA"
only:
- branches
- Dockerfile内容:
dockerfile复制FROM maven:3.9-eclipse-temurin-17 AS build
WORKDIR /app
COPY pom.xml .
COPY src ./src
RUN mvn -B -Dmaven.test.skip=true clean package
FROM eclipse-temurin:17-jre
WORKDIR /app
COPY --from=build /app/target/*.jar /app/app.jar
EXPOSE 8080
ENTRYPOINT ["java","-jar","/app/app.jar"]
6.3 触发流水线
-
将所有文件提交并推送到GitLab仓库。
-
在GitLab UI中,进入demo-app → CI/CD → Pipelines,点击"Run pipeline"。
-
观察流水线执行情况,正常情况下应该完成以下步骤:
- 拉取基础镜像
- Maven构建Java应用
- 构建Docker镜像
- 推送镜像到Harbor
7. 常见问题排查
7.1 Runner无法注册
症状:注册时连接GitLab失败
解决方案:
- 检查GitLab的external_url配置是否正确
- 确保Runner服务器能访问GitLab的内网IP
- 检查防火墙设置
7.2 Docker构建失败
症状:流水线中docker build命令失败
解决方案:
- 确认Runner的config.toml中privileged=true
- 检查/var/run/docker.sock的挂载是否正确
- 确保Harbor被正确添加到insecure-registries
7.3 镜像推送失败
症状:docker push命令失败
解决方案:
- 确认HARBOR_USER和HARBOR_PASSWORD变量已正确设置
- 检查Harbor中是否存在目标项目(demo)
- 确认ci-user有该项目的推送权限
8. 架构设计与工作原理
整个CI环境的架构如下图所示:
code复制+-------------------+ +-------------------+ +-------------------+
| GitLab Server | | Harbor Server | | Runner Server |
| (192.168.1.2:80) | | (192.168.1.3:80) | | (192.168.1.4) |
+-------------------+ +-------------------+ +-------------------+
| ^ |
| | |
v | |
+-------------------+ | |
| Developer Push | | |
| Code to Git | | |
+-------------------+ | |
| | |
| 1. Trigger Pipeline | |
|------------------------> |
| | |
| 2. Assign Job | |
|------------------------------------------> |
| | |
| 3. Build & Push Image | |
| | |
| | |
| | 4. Push Image |
| <--------------------------|
关键数据流说明:
- 开发者推送代码到GitLab仓库
- GitLab根据.gitlab-ci.yml触发流水线
- GitLab将任务分配给注册的Runner
- Runner执行构建任务,生成Docker镜像
- Runner将构建好的镜像推送到Harbor仓库
9. 生产环境优化建议
-
安全加固:
- 为Harbor配置HTTPS证书
- 移除insecure-registries配置
- 配置更精细的仓库访问权限
-
性能优化:
- 为Runner配置缓存卷,加速依赖下载
- 考虑使用Docker镜像分层构建策略
- 根据团队规模适当增加Runner数量
-
高可用考虑:
- GitLab和Harbor可以考虑集群部署
- 使用分布式Runner架构
- 配置定期备份策略
这套基于GitLab的CI环境搭建方案,经过多个项目的实际验证,能够稳定支持中小团队的持续集成需求。特别是在内网环境中,构建速度明显快于使用公共CI服务,同时也更加安全可控。