使用CI/CD部署后端项目（gin）-EW帮帮网

写在前面：使用CI/CD部署gin项目到服务器中

前端可以参考：使用CI/CD部署nextjs项目

使用 GitHub Actions 配置后端 CI/CD（含部署到服务器）

本文档介绍如何在 GitHub 仓库中配置 CI/CD，将 PROJECT_NAME 项目自动构建并部署到你的服务器。文末附有经过注释的 deploy.yml 工作流示例（已去除敏感信息，仅引用 Secrets 名称）。

前置条件

服务器已安装 Docker 与 Docker Compose（插件）。
服务器具备 SSH 访问能力（账号、密码或密钥）。
服务器目标目录可写，例如：/opt/PROJECT_NAME。
域名/反向代理（可选）：若通过 Nginx 暴露 443/80 端口，需提前配置好。

仓库 Secrets 与变量配置

在 GitHub 仓库中添加以下 Secrets（路径：Repository → Settings → Secrets and variables → Actions → New repository secret）：

CONFIG_YAML_PROD：生产环境配置文件内容（完整的 configs/config.prod.yaml 文本）。
SSH_HOST：服务器 IP 或域名。
SSH_PORT：SSH 端口（通常是 22）。
SSH_USER：SSH 用户名（如 root）。
SSH_PASSWORD：SSH 密码（若使用私钥方式，可改用 key 形式的 action）。
REMOTE_PATH：服务器部署目录，例如 /opt/jump3-end-v2。

说明：敏感值一律存放在 Secrets 中，不要提交到仓库。

工作流触发策略

示例工作流在 push 到 main 分支时触发。你也可以按需改成手动触发或仅在打 tag 时触发。

环境选择与配置文件

代码中已支持 APP_ENV 与 CONFIG_PATH 两种方式选择配置文件。
本示例将容器环境固定为 APP_ENV=prod，并通过 Secrets 注入生成 configs/config.prod.yaml。
如果你需要 Dev/Staging 环境，建议为每个环境建立独立的 Environment 与 Secrets，并复制一份 workflow，或使用 environment: 切换。

工作流主要步骤

检出代码。
设置 Buildx 并构建 Docker 镜像（linux/amd64），导出为 your-project-server.tar。
将 CONFIG_YAML_PROD 写入 configs/config.prod.yaml（同时拷贝一份到 configs/config.dev.yaml 以兜底）。
通过 SCP 上传 your-project-server.tar、docker-compose.yml 与配置文件到服务器的 REMOTE_PATH。
通过 SSH 在服务器上执行：
- docker compose down
- docker load < jump3-server.tar
- docker compose up -d
- 简单健康检查

故障排查建议

上传报错 tar: empty archive：确认 SCP action 的 source 传参为逗号分隔单行，并确保前面步骤确实生成了文件。
权限问题：确保服务器目标目录存在且可写；日志目录 logs 可设为 chmod 777 logs。
镜像平台：若服务器为 amd64，构建需加 --platform linux/amd64。
端口/防火墙：确认 8080 或反代端口已放行。
环境变量：生产强制 APP_ENV=prod，避免默认 dev。

deploy.yml（带注释，敏感信息由 Secrets 提供）

name: Deploy

on:
  push:
    branches: [ main ]            # 推送到 main 分支时触发

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build docker image (linux/amd64)
        run: |
          docker build --platform linux/amd64 -t your-project-server:latest .  # 构建镜像（将 your-project 替换为你的项目名）
          docker save your-project-server:latest > your-project-server.tar     # 导出镜像

      - name: Prepare config files from secret
        shell: bash
        run: |
          mkdir -p configs
          # 将机密里的生产配置写入文件
          printf "%s" "$CONFIG_YAML" > configs/config.prod.yaml
          # 同步一份为 dev 以兜底（容器内默认 dev 时也能跑）
          cp configs/config.prod.yaml configs/config.dev.yaml
        env:
          CONFIG_YAML: ${{ secrets.CONFIG_YAML_PROD }}  # 从 Secrets 注入完整 YAML 文本

      - name: Upload files to server (image, compose, configs)
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.SSH_HOST }}                 # 服务器地址（来自 Secrets）
          username: ${{ secrets.SSH_USER }}             # SSH 用户
          password: ${{ secrets.SSH_PASSWORD }}         # SSH 密码
          port: ${{ secrets.SSH_PORT }}                 # SSH 端口
          source: "your-project-server.tar,docker-compose.yml,configs/config.prod.yaml,configs/config.dev.yaml"  # 逗号分隔
          target: ${{ secrets.REMOTE_PATH }}            # 服务器目录
          overwrite: true                               # 覆盖同名文件

      - name: Deploy on server via SSH
        uses: appleboy/ssh-action@v1.2.0
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          password: ${{ secrets.SSH_PASSWORD }}
          port: ${{ secrets.SSH_PORT }}
          script: |
            set -euo pipefail
            cd ${{ secrets.REMOTE_PATH }}
            mkdir -p configs logs
            chmod 777 logs || true

            # 先下线旧容器再加载新镜像并启动
            docker compose down || true
            docker load < your-project-server.tar
            docker compose up -d

            # 简易健康检查（可按需替换为 curl https://.../health）
            docker compose ps
            curl -sf http://127.0.0.1:8080/health || true

与 docker-compose.yml 的配合

当前 docker-compose.yml 中推荐包含以下内容，固定生产环境并授权日志目录（将镜像名、容器名替换为 PROJECT_NAME）：

services:
  api:
    image: your-project-server:latest
    container_name: your-project-api
    ports:
      - "8080:8080"
    environment:
      - GIN_MODE=release
      - APP_ENV=prod               # 固定使用生产配置
    volumes:
      - ./configs:/app/configs:ro  # 将服务器上的配置目录挂载到容器
      - ./logs:/app/logs
    user: "0:0"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

小结

将敏感配置放入 GitHub Secrets，流水线运行时再渲染成文件。
通过 SCP/SSH 将镜像与配置投递到服务器，并用 Docker Compose 管理生命周期。
若有多环境，复制工作流并切换 Secrets 或使用 GitHub Environments 管理。
如要查看调试信息，到github对应项目下的Actions中即可查看、排错。

使用CI/CD部署后端项目（gin）