GitLab CI + Docker 自动构建前端项目并部署 — 完整流程文档

一、环境准备

1. 服务器准备

一台Linux服务器（CentOS/Ubuntu皆可），推荐至少4核8GB内存
已安装 Docker（及 Docker 服务已启动）
已安装 GitLab Runner

2. 服务器上安装 Docker （如果没装）

# CentOS9以下举例
sudo yum install -y yum-utils device-mapper-persistent-data lvm2
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io -y
sudo systemctl start docker
sudo systemctl enable docker



# 适用于 CentOS 9 / CentOS Stream 9 安装 Docker CE

# 1. 卸载可能冲突的旧版本
sudo dnf remove -y docker \
                docker-client \
                docker-client-latest \
                docker-common \
                docker-latest \
                docker-latest-logrotate \
                docker-logrotate \
                docker-engine

# 2. 安装必要的依赖
sudo dnf -y install dnf-plugins-core

# 3. 添加 Docker 官方仓库
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 4. 安装 Docker CE（--nobest 解决可能的版本依赖冲突）
sudo dnf install -y --nobest docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 5. 启动 Docker
sudo systemctl start docker

# 6. 设置开机自启
sudo systemctl enable docker

# 7. 查看 Docker 版本
docker --version

# 8. 测试运行
sudo docker run hello-world

3. 安装 GitLab Runner

# 下载二进制文件
sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

# 赋予执行权限
sudo chmod +x /usr/local/bin/gitlab-runner

# 添加用户（可选）
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash || true

# 安装 Runner 服务
sudo /usr/local/bin/gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner

# 启动 Runner 服务
sudo /usr/local/bin/gitlab-runner start

4. 将 `gitlab-runner` 用户加入 Docker 用户组

sudo usermod -aG docker gitlab-runner
sudo systemctl restart docker

二、GitLab Runner 注册

1,登录你的 GitLab，进入项目设置 > CI/CD > Runners 页面

2,找到 registration token（注册令牌）

3,在服务器执行注册命令（替换 URL 和 token）：

sudo /usr/local/bin/gitlab-runner register \
  --non-interactive \
  --url "http://你的gitlab地址:端口/" \
  --registration-token "你的注册token" \
  --description "deploy-runner" \
  --executor "shell" \
  --tag-list "deploy" \
  --run-untagged="false" \
  --locked="false"

4,注册成功后，用命令检查 Runner 状态：

sudo /usr/local/bin/gitlab-runner status

三、准备项目代码和 Dockerfile

1

2. 示例 Dockerfile

# 使用官方 Nginx 作为基础镜像（默认自带 /usr/share/nginx/html 目录）
FROM nginx

# 设置工作目录为 Nginx 的默认静态文件目录
WORKDIR /usr/share/nginx/html/

# 切换到 root 用户（方便修改配置文件和目录）
USER root

# 将我们自定义的 Nginx 配置文件复制到容器中
# 替换掉默认的 default.conf，让 Nginx 按我们的配置运行
COPY ./docker/nginx.conf /etc/nginx/conf.d/default.conf

# 将打包后的前端 dist 目录复制到 Nginx 静态目录
COPY ./dist  /usr/share/nginx/html/

# 暴露容器的 80 端口（HTTP）
EXPOSE 80

# 启动 Nginx 前台运行（daemon off 表示不以守护进程模式运行）
CMD ["nginx", "-g", "daemon off;"]

四、编写 GitLab CI 配置 `.gitlab-ci.yml`

# ===============================
# 全局 before_script
# ===============================
before_script:
  # 切换 npm 源为淘宝镜像（国内安装依赖更快）
  - npm config set registry https://registry.npmmirror.com

# ===============================
# CI/CD 阶段定义
# ===============================
stages:
  - build   # 第一阶段：构建阶段（编译前端代码）
  - deploy  # 第二阶段：部署阶段（运行容器）

# ===============================
# 构建 Job
# ===============================
build-job:
  stage: build          # 该 Job 属于 build 阶段
  tags:
    - deploy            # Runner 标签（需和 GitLab Runner 配置一致）
  script:
    # 安装依赖（会使用 before_script 中设置的淘宝源）
    - npm install
    # 打包生产环境代码（Vue/React 等前端项目）
    - npm run build:prod
    # 使用 Docker 构建镜像，命名为 user-center-frontend:latest
    - docker build -t user-center-frontend:latest .

# ===============================
# 部署 Job
# ===============================
deploy-job:
  stage: deploy         # 该 Job 属于 deploy 阶段
  tags:
    - deploy            # Runner 标签（需和 GitLab Runner 配置一致）
  script:
    # 如果已有旧容器，则停止运行（忽略错误）
    - docker stop user-center-frontend || true
    # 删除旧容器（忽略错误）
    - docker rm user-center-frontend || true
    # 启动新容器，映射宿主机 80 端口到容器 80 端口
    - docker run -d --name user-center-frontend -p 80:80 user-center-frontend:latest

五,nginx配置

server {
    listen 80;  # 监听 80 端口（HTTP 默认端口）

    # ===============================
    # gzip 压缩配置（开启传输压缩以减少流量）
    # ===============================
    gzip on;  # 开启 gzip 压缩
    gzip_min_length 1k;  # 文件大于 1KB 才会压缩
    gzip_comp_level 9;  # 压缩级别，范围 1-9，数字越大压缩率越高，但消耗更多 CPU
    gzip_types text/plain text/css text/javascript application/json application/javascript application/x-javascript application/xml;  
    # 指定需要压缩的文件类型
    gzip_vary on;  # 启用 Vary: Accept-Encoding 响应头，告诉缓存服务器区分压缩和未压缩的版本
    gzip_disable "MSIE [1-6]\.";  # 针对 IE6 以下浏览器禁用 gzip，避免兼容性问题

    # ===============================
    # 站点根目录
    # ===============================
    root /usr/share/nginx/html;  # 指定网站的根目录（静态文件所在位置）
    include /etc/nginx/mime.types;  # 引入 MIME 类型映射（让浏览器正确识别文件类型）

    location / {
        # 当请求的路径找不到对应文件时，返回 index.html
        # 适用于 SPA（单页应用）前端路由，防止刷新 404
        try_files $uri /index.html;
    }
}

六、执行流程

提交代码到 GitLab（包括 Dockerfile 和 .gitlab-ci.yml）
GitLab CI 自动触发流水线
Runner 会执行安装依赖、构建项目、构建 Docker 镜像
部署阶段会停止旧容器、删除容器并重新运行最新镜像
访问服务器 IP 或绑定域名的 80 端口即可访问最新前端页面

七、常用排查命令

查看镜像：

docker images

查看运行中的容器：

docker ps

查看容器日志：

docker logs user-center-frontend

八、注意事项

构建命令（如 npm run build:prod）需在 .gitlab-ci.yml 中正确填写，确保能生成 dist
确保服务器 Docker 服务正常，GitLab Runner 有权限操作 Docker
构建上下文路径和 Dockerfile 中的 COPY 路径必须匹配，否则复制文件失败
GitLab Runner 用户需加入 docker 组，避免权限问题

GitLab CI + Docker 自动构建前端项目并部署 — 完整流程文档

一、环境准备

1. 服务器准备

2. 服务器上安装 Docker （如果没装）

3. 安装 GitLab Runner

4. 将 `gitlab-runner` 用户加入 Docker 用户组

二、GitLab Runner 注册

三、准备项目代码和 Dockerfile

四、编写 GitLab CI 配置 `.gitlab-ci.yml`

五,nginx配置

六、执行流程

七、常用排查命令

网站公告

今日签到

热门文章

最新发布

GitLab CI + Docker 自动构建前端项目并部署 — 完整流程文档

一、环境准备

1. 服务器准备

2. 服务器上安装 Docker （如果没装）

3. 安装 GitLab Runner

4. 将 gitlab-runner 用户加入 Docker 用户组

二、GitLab Runner 注册

三、准备项目代码和 Dockerfile

四、编写 GitLab CI 配置 .gitlab-ci.yml

五,nginx配置

六、执行流程

七、常用排查命令

网站公告

今日签到

热门文章

最新发布

4. 将 `gitlab-runner` 用户加入 Docker 用户组

四、编写 GitLab CI 配置 `.gitlab-ci.yml`