Zeabur 自动重启方案

背景

在使用 Zeabur 部署 Docker 容器时，常见的 CI/CD 流程是：

代码推送到 GitHub
GitHub Actions 构建 Docker 镜像
推送镜像到 Docker Hub
手动在 Zeabur Dashboard 点击重启服务

本文介绍如何通过 Zeabur 的 GraphQL API 自动化最后一步，实现完全自动化的部署流程。

技术方案

方案概述

利用 Zeabur 提供的 GraphQL API，在 GitHub Actions 中通过 restartService mutation 自动触发服务重启。

核心技术点

Zeabur GraphQL API: https://api.zeabur.com/graphql
Mutation: restartService(serviceID: String!, environmentID: String!)
认证方式: Bearer Token (API Key)
触发时机: Docker 镜像推送成功后

实施步骤

第一步：获取必要信息

1.1 创建 Zeabur API Token

访问 Zeabur API Key 文档
在 Zeabur Dashboard 创建 API Key
复制生成的 Token 并妥善保存

1.2 获取 Service ID 和 Environment ID

在 Zeabur Dashboard 中找到你的服务，URL 格式如下：

plaintext

      https://zeabur.com/projects/{PROJECT_ID}/services/{SERVICE_ID}?envID={ENV_ID}

从 URL 中提取：

Service ID: {SERVICE_ID} 部分
Environment ID: envID= 后面的部分

示例：

plaintext

      https://zeabur.com/projects/6864ba60b01537fe5f8fe0af/services/689ca41b70b8f4ff5c0c2319?envID=6864ba6035c94175e84f51d5

Service ID: 689ca41b70b8f4ff5c0c2319
Environment ID: 6864ba6035c94175e84f51d5

第二步：配置 GitHub Secret

使用 GitHub CLI 添加 Secret：

bash

      gh secret set ZEABUR_API_TOKEN
# 然后粘贴你的 Zeabur API Token

或者通过 GitHub Web UI：

进入仓库 → Settings → Secrets and variables → Actions
点击 “New repository secret”
Name: ZEABUR_API_TOKEN
Value: 你的 Zeabur API Token

第三步：修改 GitHub Actions Workflow

在你的 .github/workflows/docker-deploy.yml 中添加以下步骤：

yaml

1234567891011121314151617181920212223242526272829

      # 在 Docker 镜像推送成功后添加此步骤
- name: Wait and restart Zeabur service
  if: success()
  run: |
    echo "⏳ Waiting 5 seconds for Docker Hub to process..."
    sleep 5

    echo "🔄 Triggering Zeabur service restart..."
    RESPONSE=$(curl -s -X POST https://gateway.zeabur.com/graphql \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${{ secrets.ZEABUR_API_TOKEN }}" \
      -d '{
        "query": "mutation { restartService(serviceID: \"YOUR_SERVICE_ID\", environmentID: \"YOUR_ENV_ID\") }"
      }')

    echo "Zeabur API Response: $RESPONSE"

    if echo "$RESPONSE" | grep -q "error"; then
      echo "❌ Zeabur restart failed!"
      echo "$RESPONSE"
      exit 1
    fi

    echo "✅ Zeabur service restart triggered successfully!"
    echo "" >> $GITHUB_STEP_SUMMARY
    echo "### 🔄 Zeabur 自动重启" >> $GITHUB_STEP_SUMMARY
    echo "- **状态**: ✅ 已触发服务重启" >> $GITHUB_STEP_SUMMARY
    echo "- **Service ID**: \`YOUR_SERVICE_ID\`" >> $GITHUB_STEP_SUMMARY
    echo "- **Environment ID**: \`YOUR_ENV_ID\`" >> $GITHUB_STEP_SUMMARY

重要提醒：

将 YOUR_SERVICE_ID 替换为你的实际 Service ID
将 YOUR_ENV_ID 替换为你的实际 Environment ID

完整 Workflow 示例

yaml

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667

      name: Build and Deploy to Docker Hub

on:
  push:
    branches:
      - main

env:
  DOCKER_USERNAME: your-dockerhub-username
  DOCKER_REPO: your-dockerhub-username/your-repo-name

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      # 1. 检出代码
      - name: Checkout code
        uses: actions/checkout@v4

      # 2. 设置 Docker Buildx
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      # 3. 登录 Docker Hub
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ env.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      # 4. 构建并推送 Docker 镜像
      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64
          push: true
          tags: ${{ env.DOCKER_REPO }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

      # 5. 等待并触发 Zeabur 重启
      - name: Wait and restart Zeabur service
        if: success()
        run: |
          echo "⏳ Waiting 5 seconds for Docker Hub to process..."
          sleep 5

          echo "🔄 Triggering Zeabur service restart..."
          RESPONSE=$(curl -s -X POST https://gateway.zeabur.com/graphql \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer ${{ secrets.ZEABUR_API_TOKEN }}" \
            -d '{
              "query": "mutation { restartService(serviceID: \"YOUR_SERVICE_ID\", environmentID: \"YOUR_ENV_ID\") }"
            }')

          echo "Zeabur API Response: $RESPONSE"

          if echo "$RESPONSE" | grep -q "error"; then
            echo "❌ Zeabur restart failed!"
            echo "$RESPONSE"
            exit 1
          fi

          echo "✅ Zeabur service restart triggered successfully!"

GraphQL API 详解

API 端点

plaintext

      POST https://gateway.zeabur.com/graphql

请求头

http

      Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

Mutation 格式

graphql

123

      mutation RestartService($serviceId: ObjectID!, $environmentId: ObjectID!) {
  restartService(serviceID: $serviceId, environmentID: $environmentId)
}

cURL 示例

bash

123456

      curl -X POST https://gateway.zeabur.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "query": "mutation { restartService(serviceID: \"YOUR_SERVICE_ID\", environmentID: \"YOUR_ENV_ID\") }"
  }'

成功响应示例

json

12345

      {
  "data": {
    "restartService": true
  }
}

错误响应示例

json

12345678910

      {
  "errors": [
    {
      "message": "Service not found",
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}

常见问题

Q1: 为什么需要等待 5 秒？

A: Docker Hub 处理镜像推送需要一定时间。等待 5 秒确保 Zeabur 重启时能拉取到最新的镜像。你可以根据实际情况调整等待时间。

Q2: 如果 Zeabur API 调用失败怎么办？

A: 脚本中已包含错误检测逻辑：

bash

12345

      if echo "$RESPONSE" | grep -q "error"; then
  echo "❌ Zeabur restart failed!"
  echo "$RESPONSE"
  exit 1
fi

如果 API 返回错误，GitHub Actions 会失败并显示详细错误信息。

Q3: 是否支持其他 mutation？

A: 是的，Zeabur 还提供其他 mutations，如：

redeployService: 重新部署服务（拉取最新代码重新构建）
suspendService: 暂停服务
更多请参考 Zeabur Apollo Explorer

Q4: 如何查看 Zeabur 的完整 GraphQL Schema？

A: 访问 Zeabur 的 Apollo Explorer：

plaintext

      https://gateway.zeabur.com/graphql

在浏览器中打开后，可以查看所有可用的 queries 和 mutations。

最佳实践

1. 使用 GitHub Environment

对于多环境部署（开发/生产），建议使用 GitHub Environment：

yaml

1234567

      environment:
  name: production

- name: Restart Zeabur service
  env:
    ZEABUR_SERVICE_ID: ${{ secrets.PROD_SERVICE_ID }}
    ZEABUR_ENV_ID: ${{ secrets.PROD_ENV_ID }}

2. 添加通知

在重启成功/失败后发送通知（如 Slack、钉钉）：

yaml

12345678910111213

      - name: Notify on success
  if: success()
  run: |
    curl -X POST YOUR_WEBHOOK_URL \
      -H "Content-Type: application/json" \
      -d '{"text": "✅ Zeabur 服务重启成功！"}'

- name: Notify on failure
  if: failure()
  run: |
    curl -X POST YOUR_WEBHOOK_URL \
      -H "Content-Type: application/json" \
      -d '{"text": "❌ Zeabur 服务重启失败！"}'

3. 健康检查

在重启后添加健康检查：

yaml

12345678910111213

      - name: Health check
  run: |
    echo "Waiting for service to be ready..."
    sleep 10

    HEALTH_STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://your-app.zeabur.app/health)

    if [ "$HEALTH_STATUS" = "200" ]; then
      echo "✅ Service is healthy!"
    else
      echo "❌ Service health check failed! Status: $HEALTH_STATUS"
      exit 1
    fi

安全建议

妥善保管 API Token
- 不要将 Token 硬编码在代码中
- 使用 GitHub Secrets 存储
- 定期轮换 Token
最小权限原则
- Zeabur API Token 只授予必要的权限
- 不同环境使用不同的 Token
审计日志
- 定期检查 GitHub Actions 运行日志
- 监控 Zeabur 服务重启记录

参考资料

总结

通过 Zeabur 的 GraphQL API，我们实现了：

✅ 全自动化部署流程：代码 push → 构建 → 推送 → 自动重启 ✅ 零手动操作：无需登录 Dashboard 手动重启 ✅ 错误处理：自动检测并报告失败 ✅ 可扩展性：可轻松集成通知、健康检查等功能

这种方案特别适合需要频繁部署的项目，大大提高了开发效率。

作者: Frankie 日期: 2025-10-19 版本: 1.0

解决 Zeabur 应用自动休眠问题

背景

技术方案

方案概述

核心技术点

实施步骤

第一步：获取必要信息

1.1 创建 Zeabur API Token

1.2 获取 Service ID 和 Environment ID

第二步：配置 GitHub Secret

第三步：修改 GitHub Actions Workflow

完整 Workflow 示例

GraphQL API 详解

API 端点

请求头

Mutation 格式

cURL 示例

成功响应示例

错误响应示例

常见问题

Q1: 为什么需要等待 5 秒？

Q2: 如果 Zeabur API 调用失败怎么办？

Q3: 是否支持其他 mutation？

Q4: 如何查看 Zeabur 的完整 GraphQL Schema？

最佳实践

1. 使用 GitHub Environment

2. 添加通知

3. 健康检查

安全建议

参考资料

总结