寫在前面：使用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: 切換。

工作流主要步驟

1. 檢出代碼。
2. 設置 Buildx 并構建 Docker 鏡像（linux/amd64），導出為 your-project-server.tar。
3. 將 CONFIG_YAML_PROD 寫入 configs/config.prod.yaml（同時拷貝一份到 configs/config.dev.yaml 以兜底）。
4. 通過 SCP 上傳 your-project-server.tar、docker-compose.yml 與配置文件到服務器的 REMOTE_PATH。
5. 通過 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: Deployon:push:branches: [ main ]            # 推送到 main 分支時觸發jobs:deploy:runs-on: ubuntu-lateststeps:- name: Checkoutuses: actions/checkout@v4- name: Set up Docker Buildxuses: 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 secretshell: bashrun: |mkdir -p configs# 將機密里的生產配置寫入文件printf "%s" "$CONFIG_YAML" > configs/config.prod.yaml# 同步一份為 dev 以兜底（容器內默認 dev 時也能跑）cp configs/config.prod.yaml configs/config.dev.yamlenv:CONFIG_YAML: ${{ secrets.CONFIG_YAML_PROD }}  # 從 Secrets 注入完整 YAML 文本- name: Upload files to server (image, compose, configs)uses: appleboy/scp-action@v0.1.7with: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 SSHuses: appleboy/ssh-action@v1.2.0with:host: ${{ secrets.SSH_HOST }}username: ${{ secrets.SSH_USER }}password: ${{ secrets.SSH_PASSWORD }}port: ${{ secrets.SSH_PORT }}script: |set -euo pipefailcd ${{ secrets.REMOTE_PATH }}mkdir -p configs logschmod 777 logs || true# 先下線舊容器再加載新鏡像并啟動docker compose down || truedocker load < your-project-server.tardocker compose up -d# 簡易健康檢查（可按需替換為 curl https://.../health）docker compose pscurl -sf http://127.0.0.1:8080/health || true

與 docker-compose.yml 的配合

當前 docker-compose.yml 中推薦包含以下內容，固定生產環境并授權日志目錄（將鏡像名、容器名替換為 PROJECT_NAME）：

services:api:image: your-project-server:latestcontainer_name: your-project-apiports:- "8080:8080"environment:- GIN_MODE=release- APP_ENV=prod               # 固定使用生產配置volumes:- ./configs:/app/configs:ro  # 將服務器上的配置目錄掛載到容器- ./logs:/app/logsuser: "0:0"restart: unless-stoppedhealthcheck:test: ["CMD", "curl", "-f", "http://localhost:8080/health"]interval: 30stimeout: 10sretries: 3start_period: 40s

小結

• 將敏感配置放入 GitHub Secrets，流水線運行時再渲染成文件。
• 通過 SCP/SSH 將鏡像與配置投遞到服務器，并用 Docker Compose 管理生命周期。
• 若有多環境，復制工作流并切換 Secrets 或使用 GitHub Environments 管理。
• 如要查看調試信息，到github對應項目下的Actions中即可查看、排錯。