GitLab CI/CD 自动化部署

---

以下是使用 GitLab CI/CD 自动化部署的完整配置方案，涵盖 代码构建、Docker 镜像推送、服务器部署 及 回滚机制。示例基于 FastAPI 应用部署到服务器，并集成 HTTPS 负载均衡环境。

---

一、架构流程

main 分支

v* 标签

GitLab 代码仓库

CI/CD 流水线

分支/标签判断

构建 Docker 镜像

生产环境部署

推送镜像到 Registry

SSH 连接服务器更新容器

重启服务

---

二、GitLab CI/CD 配置文件 (.gitlab-ci.yml)

variables:
  DOCKER_IMAGE: "registry.example.com/your-project/fastapi-app"
  SSH_USER: "deploy-user"
  SERVER_IP: "your-server-ip"
  APP_PORT: "8000"  # 应用默认端口

# 定义流水线阶段
stages:
  - build
  - deploy

# 缓存 Docker 层加速构建
cache:
  key: docker-layers
  paths:
    - .cache

# ---------------------- 阶段 1: 构建 Docker 镜像 ----------------------
build-image:
  stage: build
  image: docker:24.0
  services:
    - docker:24.0-dind
  rules:
    - if: $CI_COMMIT_BRANCH == "main"  # 仅 main 分支触发构建
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $DOCKER_IMAGE:$CI_COMMIT_SHORT_SHA .
    - docker push $DOCKER_IMAGE:$CI_COMMIT_SHORT_SHA

# ---------------------- 阶段 2: 部署到服务器 ----------------------
deploy-staging:
  stage: deploy
  image: alpine:3.18
  rules:
    - if: $CI_COMMIT_BRANCH == "main"  # main 分支部署到测试环境
  before_script:
    - apk add --no-cache openssh-client rsync    # 安装 SSH 客户端和文件同步工具
  	- eval $(ssh-agent -s)                      # 启动 SSH 代理
  	- echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -  # 加载 SSH 私钥（从 GitLab CI 变量）
  	- mkdir -p ~/.ssh                           # 创建 SSH 目录
  	- chmod 700 ~/.ssh                          # 设置目录权限
  	- ssh-keyscan $SERVER_IP >> ~/.ssh/known_hosts  # 自动信任服务器指纹
  script:
  	- ssh $SSH_USER@$SERVER_IP << EOF            # SSH 连接到目标服务器
      docker pull $DOCKER_IMAGE:$CI_COMMIT_SHORT_SHA   # 拉取最新镜像
      docker stop fastapi-staging || true        # 停止旧容器（忽略错误）
      docker rm fastapi-staging || true          # 删除旧容器（忽略错误）
      docker run -d --name fastapi-staging -p 8000:8000 $DOCKER_IMAGE:$CI_COMMIT_SHORT_SHA  # 启动新容器
      EOF

deploy-prod:
  stage: deploy
  image: alpine:3.18
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/  # 标签格式为 vX.Y.Z 时部署生产环境
  before_script:
    - apk add --no-cache openssh-client rsync
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - ssh-keyscan $SERVER_IP >> ~/.ssh/known_hosts
  script:
    - ssh $SSH_USER@$SERVER_IP << EOF
      docker pull $DOCKER_IMAGE:$CI_COMMIT_SHORT_SHA
      docker stop fastapi-prod || true
      docker rm fastapi-prod || true
      docker run -d --name fastapi-prod -p 8001:8000 $DOCKER_IMAGE:$CI_COMMIT_SHORT_SHA
      # 执行数据库迁移（若有）
      docker exec fastapi-prod alembic upgrade head
      # 重新加载 Nginx（若配置变更）
      docker exec nginx nginx -s reload
      EOF

---

三、关键配置说明

1. 环境变量设置

在 GitLab 仓库设置 CI/CD Variables（Settings → CI/CD → Variables）：

变量名	值示例	保护/掩码
CI_REGISTRY_USER	your-registry-username	✅
CI_REGISTRY_PASSWORD	your-registry-password	✅
SSH_PRIVATE_KEY	服务器部署用户的私钥	✅
SERVER_IP	203.0.113.1	✅

2. 服务器端准备

• Docker 环境：确保服务器已安装 Docker 并允许远程管理。
• 部署用户权限：创建专用用户 deploy-user，配置 SSH 密钥认证和 docker 组权限：

sudo useradd -m -s /bin/bash deploy-user
sudo usermod -aG docker deploy-user

3. Nginx 集成（补充配置）

在服务器上的 Nginx 配置中添加负载均衡规则：

upstream fastapi_servers {
    server 127.0.0.1:8000;  # 测试环境
    server 127.0.0.1:8001;  # 生产环境
}

server {
    listen 443 ssl;
    server_name example.com;
    # ... SSL 配置 ...
    location / {
        proxy_pass http://fastapi_servers;
    }
}

---

四、高级优化

1. 回滚机制

添加手动回滚任务到 .gitlab-ci.yml：

rollback-prod:
  stage: deploy
  image: alpine:3.18
  variables:
    ROLLBACK_TAG: "previous-commit-sha"  # 通过 CI/CD 界面动态指定
  script:
    - ssh $SSH_USER@$SERVER_IP << EOF
      docker stop fastapi-prod
      docker rm fastapi-prod
      docker run -d --name fastapi-prod -p 8001:8000 $DOCKER_IMAGE:$ROLLBACK_TAG
      EOF
  when: manual  # 手动触发

2. 多服务器部署

使用 parallel 关键字同时部署到多台服务器：

deploy-prod:
  parallel:
    matrix:
      - SERVER_IP: "203.0.113.1"
      - SERVER_IP: "203.0.113.2"
  # 其他配置同上

3. 通知集成

在流水线结束时发送 Slack 通知：

notify-slack:
  stage: .post
  script:
    - curl -X POST -H 'Content-type: application/json' --data "{\"text\":\"Pipeline $CI_PIPELINE_ID 状态: $CI_JOB_STATUS\"}" $SLACK_WEBHOOK_URL
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"

---

五、完整流程测试

1. 提交代码到 main 分支：触发镜像构建并部署到测试环境（端口 8000）。
2. 创建 Git 标签 v1.0.0：触发生产环境部署（端口 8001）。
3. 访问 https://example.com：Nginx 自动将请求负载均衡到两个容器。

---