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

示例 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

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

设置工作目录为 Nginx 的默认静态文件目录

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

将我们自定义的 Nginx 配置文件复制到容器中

替换掉默认的 default.conf，让 Nginx 按我们的配置运行

将打包后的前端 dist 目录复制到 Nginx 静态目录

暴露容器的 80 端口（HTTP）

启动 Nginx 前台运行（daemon off 表示不以守护进程模式运行）

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

五,nginx配置

六、执行流程

七、常用排查命令

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

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