Sci&Eng Blog
Go back

CI/CD的简化流水线

Updated:
Edit page

从最基础的Git自动部署，结合案例，完整梳理从轻量到稳定的自动化部署方案。

前言

现代微服务、工程工具开发时，我们最想要的效果很简单：即本地写完代码，推送上去，服务器自动更新上线。但个人维护生产系统也会遇到各种常见的问题。比如：长期积累会出现环境杂乱、软件版本冲突；使用Docker打包，镜像体积大、配置繁琐，转头就忘；而Kubernetes（K8s）作为企业级重型编排系统又过于复杂，在没有专业运维管理员时，其可扩展性反而会成为负担。

一、最基础方案：Git 钩子自动部署

我们本地写完代码，执行 git push 上传到服务器代码仓库后，仓库会自动触发一个提前写好的脚本（Git钩子），自动完成两大操作：拉取最新代码、重启线上服务。这种方式利用了Git本身的机制，全程只需推送代码，无需手动登录服务器操作，是最简单的自动化部署方式。

案例与工作流

比如我们写了一个LLM的网关服务，只包含一个 .py 文件，用于综合调度不同的本地模型和云端模型，代码经常需要调整。部署时，我们的期望工作流是：

本地电脑推送代码 → 服务器纯净代码仓库 → 触发Git钩子脚本 → 自动更新代码、重启服务

在这里，我们简化任务，完全绕开第三方的 GitHub/GitLab 等平台，直接将代码推送到生产主机上。利用 Git 服务的 hook 机制自动化运行脚本，代替我们手工完成代码更新、编译、配置和服务重启的操作。

1. 配置系统守护进程

针对这个 .py 脚本，我们首先需要为其配置独立的虚拟环境，并将其转换为系统守护进程。编写 llm-gateway.service 脚本，并将其拷贝到 Linux 的系统服务目录 /etc/systemd/system/ 下。

[Unit]
Description=LLM API Gateway Service
After=network.target  

[Service]
Type=simple
User=deploy   # 注意：指定运行该服务的系统用户
WorkingDirectory=/var/www/llm-gateway
ExecStart=/var/www/llm-gateway/.venv/bin/python main.py
Restart=always

[Install]
WantedBy=multi-user.target  # 开机启动，面向多用户

加载并启动服务：sudo systemctl enable —now llm-gateway。

2. 创建裸仓库与自动部署脚本

接下来，在服务器上，我们创建一个裸仓库接收代码，并配置 post-receive 钩子。

# 1. 创建纯净的裸仓库
git init --bare /home/deploy/gateway.git

# 2. 编辑钩子脚本
vim /home/deploy/gateway.git/hooks/post-receive
post-receive 脚本的思路是代替手工的运行流程，因此需要契合 Git 的运行机制。

Bash
#!/bin/bash

# Git post-receive hook - 自动部署脚本
# 并赋予可执行权限：chmod +x post-receive

# ============ 配置 ============
TARGET_DIR="/var/www/llm-gateway"
GIT_DIR="/home/deploy/gateway.git"
BRANCH="master" # 或设置为 main，视你的主分支名而定

# ============ 只在 push 指定分支时部署 ============
while read oldrev newrev refname; do
    if [[ $refname == "refs/heads/$BRANCH" ]]; then
        echo "================================="
        echo "开始部署 LLM Gateway..."
        echo "分支: $BRANCH"
        echo "版本: ${newrev:0:7}"

        # 1. 检出最新代码到目标工作目录
        echo "📂 检出代码到工作目录..."
        git --git-dir="$GIT_DIR" --work-tree="$TARGET_DIR" checkout -f "$BRANCH"

        # 2. 进入目录并安装依赖
        cd "$TARGET_DIR"

        # 如果使用虚拟环境，则激活
        if [ -d ".venv" ]; then
            source .venv/bin/activate
        fi

        # 静默安装 / 更新依赖
        echo "📚 更新依赖..."
        pip install -r requirements.txt -q

        # 3. 重启 Systemd 服务（系统级服务，需确保提权免密配置）
        echo "🔄 重启服务..."
        if sudo systemctl restart llm-gateway; then
            echo "✅ 部署完成！服务已重启。"
            # 显示服务状态前10行（status 为只读指令，通常不需要 sudo）
            systemctl status llm-gateway --no-pager -l | head -10
        else
            echo "❌ 服务重启失败！"
            exit 1
        fi

        echo "================================="
    fi
done

当我们执行 git push 时，Git 会通过标准输入（stdin）给服务器发送一段详细的数据。这一行数据的格式固定为三个字段：

oldrev：更新前的旧版本号

newrev：更新后的新版本号（即你刚推送的 commit ID）

refname：推送的分支或标签名（如 refs/heads/master）

脚本中的 while read 循环通过比对 $refname，确保只有推送指定的分支时，才会进入核心部署流程。

3. 常见权限与配置问题

在服务器环境设置中，权限是最容易产生阻塞的环节：

sudo后台输入密码的过程会卡死进程。钩子脚本通常由普通用户（如 deploy）触发，执行 sudo systemctl 时系统会要求交互式输入密码，导致自动部署中断。修复方法是修改 sudoers 文件（执行 sudo visudo），给该账号单独开通此命令的免密权限：

deploy ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart llm-gateway

此外，如果我们没有使用 git init —bare 创建裸仓库，而是往一个普通的（带有工作区的）代码库里 push，Git 默认会开启 receive.denyCurrentBranch 保护机制，禁止更新当前正在检出的分支。因此，严格使用 Bare 裸仓库作为远端中转，是自动化部署的标准工程规范。

二、 现代 CI/CD 平台与容器化演进

Git 钩子法虽然快，但很显然，钩子脚本本地运行，只能操作本地服务器。在实际生产系统中，代码通常托管在 GitHub、GitLab 等第三方平台上。

通常的做法是：本地推送到 GitHub 后，触发 Webhook向目标 发出 HTTP 通知。CI/CD 系统（如 GitHub Actions、GitLab CI 等）收到通知后，开辟一台隔离的 Runner 机器拉取代码、完成构建，最后通过 SSH 推送构建产物到生产服务器。这种相互之间的授权，是通过GitHub和Cloudflare之间实现的。

档我们在 Cloudflare Pages 或 Workers 中绑定 GitHub 仓库时，GitHub 就给 Cloudflare 发放了一张token。
Cloudflare 拿到token后，并不是去改代码，而是通过调用 GitHub 的 API，在你的仓库设置里注册了一个 Webhook 网址。
(我们可以去自己的 GitHub 仓库 -> Settings -> Webhooks 里面看，一定会发现有一个 Cloudflare 自动添加的网址链接)。
这个动作相当于 Cloudflare 在 GitHub 前台登记了一句嘱咐：“只要有人往 main 分支 Push 了代码，请立刻往我 Cloudflare 的服务器地址发一条 HTTP 请求告诉我。”

这解决了代码托管与运行环境分离的问题，但随着系统运行时间的增加，如果在物理机上直接部署，环境污染仍然不可避免。例如一台机器上混杂了不同版本的 Python、Node.js 环境，随运行时间的增加，肯定越来越乱。

1. Docker：隔离环境污染

为了彻底避免服务器环境日益混乱，引入 Docker 是业界主流方案。 通过采用多阶段构建（Multi-stage build），打包时只保留软件运行必需的产物，剔除庞大的编译工具链。无论代码依赖多复杂，对宿主机来说，它都只是一个高度隔离的容器。不仅解决了开发环境和生产环境不一致的“玄学问题”，还能通过共享公共基础镜像（Base Image）有效控制空间占用。

2. K3s：轻量级集群托管

即便使用了 Docker，开发者往往还需手动管理 docker run 参数、编写复杂的 docker-compose.yml，且缺乏崩溃自动恢复机制。

相比于企业级 Kubernetes的庞大复杂，对于个人项目或边缘节点，K3s（轻量级 Kubernetes 发行版）是常见的选择。服务器上甚至不需要安装任何 Python 环境，只需安装几十 MB 大小的 K3s 核心程序。

尤其是对于非专业运维人员，只需撰写声明式的 YAML 配置文件，K3s 就能自动完成服务发现、负载均衡、端口暴露，以及最麻烦的崩溃自动重启。

网关应用的 YAML 配置文件示例（llm-gateway.yaml）：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: llm-gateway
spec:
  replicas: 2  # 声明期望运行 2 个网关副本
  selector:
    matchLabels:
      app: llm-gateway
  template:
    metadata:
      labels:
        app: llm-gateway
    spec:
      containers:
      - name: gateway-container
        image: 127.0.0.1:5000/llm-gateway:v1  # 指定工作镜像
        ports:
        - containerPort: 8001
---
apiVersion: v1
kind: Service
metadata:
  name: gateway-service
spec:
  ports:

  - port: 80       # 宿主机对外暴露 80 端口
    targetPort: 8001 # 路由到容器内的 8001 端口
    selector:
    app: llm-gateway

运行时，执行 kubectl apply -f llm-gateway.yaml 即可。K3s 会在后台启动并维持 2 个网关副本。如果某个副本因内存溢出死机，K3s 的控制平面会立刻自动拉起一个新的副本填补空缺，确保服务高可用。

三、 集成构建

为了真正实现“代码 Push → 镜像构建 → K3s 自动发布”的闭环，同时又不引入复杂的外部构件链，我们将结合前面的 Git Hook 机制与 Docker 本地私有仓库。

首先，在服务器本地跑一个极轻量的私有镜像仓库，避免了往返公网传输镜像的漫长时间消耗：

Bash docker run -d -p 5000:5000 —restart=always —name local-registry registry:2 注意这里使用了 —restart=always 参数，Docker 守护进程会保证无论机器重启还是异常断电，该仓库服务都会被自动拉起，轻量且可靠。

接下来，升级我们的 Git Hook 脚本，让其在接收代码后，自动在本地进行 Docker 增量构建、推送至本地仓库，并通知 K3s 实施平滑滚动更新（Rolling Update）。

#!/bin/bash
# 终极自动化部署脚本：Git Hook + Docker + K3s
# 此文件位于远端服务器：/home/deploy/gateway.git/hooks/post-receive

# 1. 基础配置
TARGET_DIR="/var/www/llm-gateway"
GIT_DIR="/home/deploy/gateway.git"          
BRANCH="master"                               

# 2. 镜像与集群配置
REGISTRY="127.0.0.1:5000"                   
APP_NAME="llm-gateway"                      

while read oldrev newrev refname; do
    if [[ $refname == "refs/heads/$BRANCH" ]]; then
        echo "================================================="
        echo "🚀 触发全自动流水线：开始部署 $APP_NAME..."
        
        # 魔法1：动态版本号（提取 Git 提交记录前 7 位，如 v-a1b2c3d）
        VERSION="v-${newrev:0:7}"
        echo "🏷️ 当前发布版本号: $VERSION"
    
        # 魔法2：检出最新代码
        echo "📂 [1/4] 正在同步最新代码..."
        git --work-tree=$TARGET_DIR --git-dir=$GIT_DIR checkout -f$BRANCH
        cd $TARGET_DIR
    
        # 魔法3：Docker 本地增量构建（利用本地缓存，速度极快）
        echo "🔨 [2/4] 正在构建 Docker 镜像..."
        docker build -t $REGISTRY/$APP_NAME:$VERSION . -q
        
        # 魔法4：推送到本地镜像仓库
        echo "☁️ [3/4] 正在推送镜像到本地私有仓库..."
        docker push $REGISTRY/$APP_NAME:$VERSION -q
    
        # 魔法5：通知 K3s 实施部署更新
        echo "☸️ [4/4] 下发 K3s 更新指令，执行平滑滚动更新..."
        kubectl set image deployment/$APP_NAME gateway-container=$REGISTRY/$APP_NAME:$VERSION
        
        # 实时阻塞监控 K3s 流量切换进度
        echo "⏳ 等待线上服务无缝切换..."
        kubectl rollout status deployment/$APP_NAME
    
        echo "✅ 部署成功！线上服务已安全切换至 $VERSION 版本。"
        echo "================================================="
    fi
done

四、总结

运维测试本身如同是解决问题过程中的具体实践环节，需要打磨诸多细节。但对于个人科研、敏捷开发和小型工程应用而言，上述这套“Git Hook + 纯本地 Registry + K3s”的部署架构，已经能够以解决大多数部署问题，减少在运维中消耗额外的精力。

Edit page
Share this post:
Share this post on FacebookShare this post on XShare this post on TelegramShare this post on PinterestShare this post via email
Previous Post
AstroPaper 4.0
Next Post
AstroPaper 5.0