Docker: 使用 GitHub Actions 部署

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

欢迎查阅 Stackhero 文档

Stackhero 提供即开即用的 Docker 云端 CaaS（容器即服务）平台，专为快速、可靠的容器部署而设计：

只需一条 docker-compose up 命令即可部署到生产环境，无需额外配置：直接启动您的容器。

可自定义您的域名，并自动通过 HTTPS 实现安全保护（例如：https://api.your-company.com、https://www.your-company.com 或 https://backoffice.your-company.com）。

依托专属私有基础设施，享受高性能与强大安全保障。

一键应用更新，维护简单高效。

您的容器大约五分钟即可上线生产环境。Stackhero 为您管理基础设施、更新和安全，让您专注于应用交付。详细了解 Docker CaaS 云主机服务。

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

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

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

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

创建 Docker 服务

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

还没有 Stackhero 账号？您只需两分钟即可免费注册一个账号，然后通过几次点击即可创建您的 Docker 云服务。

Docker 服务示例

配置环境变量和密钥

获取域名和证书密码

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

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

获取服务设置
复制“域名”和“Docker 证书密码”，以便在后续步骤中使用。

获取服务设置

在 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 会自动将其部署到您的生产 Stackhero 实例。您可以在 GitHub 项目的 Actions 标签页中查看部署进度。

GitHub Actions 已部署到生产环境

就是这样。现在您已配置好通过 GitHub Actions 自动部署代码到生产环境。

创建 staging 环境

staging 环境的配置步骤与生产环境完全相同。只需重复上述流程，将 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 平台测试，再上线到生产环境）。