Docker: 使用 GitHub Actions 部署

了解如何通过 GitHub Actions 部署您的 Docker 容器

👋 欢迎来到 Stackhero 文档！

Stackhero 提供现成的 Docker 云 CaaS (Containers as a Service) 解决方案，具有众多优势，包括：

只需一个 docker-compose up，即可轻松将您的容器部署到生产环境。

使用 HTTPS 保护的可定制域名（例如，https://api.your-company.com，https://www.your-company.com，https://backoffice.your-company.com）。

由专用私有 VM提供的最佳性能和强大安全性。

只需点击即可轻松更新。

节省时间并简化您的生活：只需 5 分钟即可尝试 Stackhero 的 Docker CaaS 云托管解决方案，并将您的容器部署到生产环境！

GitHub Actions 让自动化任务变得简单，例如将您的 Docker 容器部署到生产服务器。在本指南中，您将学习如何安全可靠地配置 GitHub Actions，将 Docker 容器部署到预发布（staging）和生产（production）环境。

在此部署方案中，您需要维护两个分支：staging 和 production。每当您向其中任一分支推送代码时，系统会自动将其部署到相应的 Stackhero 实例。

拥有 staging 实例并非强制要求。您也可以仅使用生产实例来完成本指南。但为了降低风险并提升生产环境部署的信心，强烈建议同时拥有 staging 和 production 实例。这是业界标准和最佳实践，有助于避免许多潜在问题。

在开始之前，请确保您已拥有一个 GitHub 账号以及托管代码的仓库。

创建 Docker 服务

首先，登录您的 Stackhero 控制台，创建两个 Stackhero 服务：一个用于 staging，一个用于 production。为便于管理和减少出错，建议将这两个服务分别重命名为“Staging”和“Production”。

还没有 Stackhero 账号？您可以在两分钟内免费注册一个账号，然后只需几步即可创建您的 Docker cloud 服务。

Docker 服务示例

配置环境变量和密钥（secrets）

获取域名和证书密码

为了让 GitHub Actions 能连接到您的 Stackhero Docker 服务，您需要准备两个信息：服务的域名和证书密码。

在 Stackhero 控制台，选择您的“production” Docker 服务，点击“Configure”按钮。

获取服务设置
复制“Domain name”和“Docker certificates password”，以便后续步骤使用。

获取服务设置

在 GitHub 中设置域名和证书密码

在 GitHub 打开您的项目。
进入 Settings > Environments，点击 New environment。

配置 GitHub 环境
在 Name 字段输入“production”，并确认。

设置环境
点击 No restriction 按钮，选择 Selected branches and tags。

设置环境限制
点击 Add deployment branch or tag rule，在 Name pattern 字段输入“production”，然后点击 Add rule。

设置环境分支设置环境分支
在 Environment secrets 下，点击 Add secret。

添加密钥
密钥名称填写为 STACKHERO_CERTIFICATES_PASSWORD，并将您的证书密码粘贴到 Value 字段。

设置证书密码密钥
在 Environment variables 下，点击 Add variable。

设置变量
名称填写为 STACKHERO_ENDPOINT，并将您的 Docker 服务 endpoint 粘贴到 Value 字段。您可以在 Stackhero 控制台找到该 endpoint。

设置 endpoint 变量

如果您自定义了服务的域名，请记得使用您的自定义域名，而不是 <XXXXXX>.stackhero-network.com。

自定义 Docker Compose 配置文件

如果您的 docker-compose.yml 文件已在项目根目录且无需自定义，可以跳过本节。

默认情况下，GitHub Actions 会在项目根目录查找 docker-compose.yml 文件。如果您需要使用其他文件或自定义配置，可以调整部署命令。例如，如果您使用我们的 Node.js 和 Docker 入门模板，可以新建一个名为 STACKHERO_DEPLOY_COMMAND 的环境变量，并设置为：

docker compose --env-file env.list --file docker/docker-compose.yml --file docker/docker-compose.production.yml up --build --remove-orphans -d

配置 GitHub Actions 工作流

在本地机器上，进入您的 Git 仓库，创建 .github/workflows 目录。在该目录下新建名为 deploy-to-stackhero.yml 的文件，内容如下：

# File: .github/workflows/deploy-to-stackhero.yml

name: Deploy to Stackhero
description: Deploy branch "${{ github.ref_name }}" to Stackhero

on:
  push:
    # 这些分支在 push 时会触发部署操作。
    # 请确保在 GitHub（Settings > Environments）中创建与分支同名的环境。
    # 然后在该环境中添加密钥 STACKHERO_CERTIFICATES_PASSWORD 和变量 STACKHERO_ENDPOINT。
    branches: [ "production", "staging" ]

jobs:
  Deploy:
    environment: ${{ github.ref_name }}
    runs-on: ubuntu-latest
    steps:
    - uses: stackhero-io/github-actions-deploy-docker-containers-to-stackhero@v1
      with:
        # 密钥 STACKHERO_CERTIFICATES_PASSWORD 和变量 STACKHERO_ENDPOINT 应在对应分支环境中定义。
        certificates_password: ${{ secrets.STACKHERO_CERTIFICATES_PASSWORD }}
        endpoint: ${{ vars.STACKHERO_ENDPOINT }}
        # deployment_command 为可选项。如需自定义 Docker Compose 命令可使用。
        deployment_command: ${{ vars.STACKHERO_DEPLOY_COMMAND }}

您可以通过以下命令提交更改：

git add -A .
git commit -m "Add GitHub Actions to deploy to Stackhero"

要创建 production 分支，可以运行：

git checkout -b production

然后将 production 分支推送到 GitHub：

git push --set-upstream origin production

代码推送后，GitHub Actions 会自动将其部署到您的 production Stackhero 实例。您可以在 GitHub 项目的 Actions 标签页中监控部署进度。

GitHub Actions 部署到生产环境

就是这样。现在您已成功配置自动化生产部署流程。

创建 staging 环境

staging 环境的配置步骤与 production 环境相同。只需重复上述流程，将 production 替换为 staging 即可。

然后，通过以下命令创建 staging 分支：

git checkout -b staging

并将 staging 分支推送到 GitHub：

git push --set-upstream origin staging

完成后，GitHub Actions 会自动将 staging 分支部署到指定的 staging Docker 实例。

在 docker-compose.yml 中使用环境变量

您可以在 GitHub 项目中定义环境变量，这些变量会在 docker-compose.yml 文件中被访问。这对于在不同域名下部署（例如 staging.my-company.com 用于预发布，my-company.com 用于生产）非常有用。

在 GitHub，进入 Settings > Environments，新建名为 WEBSITE_DOMAIN 的环境变量。
对于 staging 环境，将 WEBSITE_DOMAIN 设置为“staging.my-company.com”。
对于 production 环境，将 WEBSITE_DOMAIN 设置为“my-company.com”。

接下来，更新 .github/workflows/deploy-to-stackhero.yml 文件，将 WEBSITE_DOMAIN 变量传递给 Stackhero GitHub Action：

name: Deploy to Stackhero
description: Deploy branch "${{ github.ref_name }}" to Stackhero

on:
  push:
    branches: [ "production", "staging" ]

jobs:
  Deploy:
    environment: ${{ github.ref_name }}
    runs-on: ubuntu-latest
    steps:
    - uses: stackhero-io/github-actions-deploy-docker-containers-to-stackhero@v1
      with:
        certificates_password: ${{ secrets.STACKHERO_CERTIFICATES_PASSWORD }}
        endpoint: ${{ vars.STACKHERO_ENDPOINT }}
        deployment_command: ${{ vars.STACKHERO_DEPLOY_COMMAND }}
      env:
        WEBSITE_DOMAIN: ${{ vars.WEBSITE_DOMAIN }}

然后，更新您的 docker-compose.yml 文件，使用 WEBSITE_DOMAIN 变量替换硬编码的域名：

services:
  test:
    image: nginx
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.test.rule=Host(`${WEBSITE_DOMAIN}`)" # 使用 WEBSITE_DOMAIN 环境变量作为域名。
      - "traefik.http.routers.test.tls.certresolver=letsencrypt"

深入实践

建议对 production 和 staging 分支启用分支保护，防止直接推送。启用分支保护后，所有更改都需通过 Pull Request，由有权限的成员审核并合并。这样可以确保新功能先在 staging 平台验证，审核通过后再推广到生产环境。

遵循此工作流，您可以同时保障安全性（只有授权团队成员才能部署到 staging 和 production）和可靠性（新功能先在 staging 平台测试，再上线生产环境）。