使用 GitHub Actions 与 Docker 实现 CaptchaVision API 持续集成

本文详细讲解如何利用 GitHub Actions 自动化工作流，配合 Docker 容器化技术，将基于 CaptchaVision 项目的 AI 验证码识别服务持续集成并推送到 阿里云容器镜像服务（ACR） 。

前言

持续集成（CI）是现代软件开发的关键实践。通过 GitHub Actions，我们可以在代码推送到仓库时，自动完成 构建镜像、登录仓库、推送镜像 等繁琐步骤。

项目基础： 本文以 github.com/abining/Cap... 开源项目为例，该项目通常包含一个用于 AI 识别和图像预处理的 Python 服务。
目标工作流： 提交代码到 main 分支 → GitHub Actions 自动构建 Docker 镜像 → 镜像推送至阿里云 ACR。

第一步：环境与机密信息配置

为了让 GitHub Actions 能够自动登录阿里云 ACR 并使用您的仓库信息，我们需要在 GitHub 中配置机密信息（Secrets）。

1. 存储阿里云凭证和仓库信息

我们将机密信息分为两类：

存储库机密 (Repository Secrets)： 适用于整个仓库。
- REPO_NAME: 镜像仓库名称，例如 captcha_vision。
环境机密 (Environment Secrets)： 专用于部署环境，安全性更高。

在 GitHub 仓库中，进入 Settings → Security → Secrets and variables → Actions。

密钥名称	类型	存储值示例	用途
`ALI_DOCKER_HUB_REGISTRY`	环境机密	`crpi-<hashstring>.cn-hangzhou.personal.cr.aliyuncs.com`	阿里云 ACR 区域 Registry 地址。
`ALI_DOCKER_HUB_USN`	环境机密	`您的阿里云用户名`	登录阿里云 ACR 的用户名。
`ALI_DOCKER_HUB_PWD`	环境机密	`您的阿里云密码或访问令牌`	登录阿里云 ACR 的密码/令牌。
`REPO_NAME`	存储库机密	`captcha_vision`	用于构建 `tags` 的镜像仓库名称。

⚠️ 注意： 您的机密信息（如 ALI_DOCKER_HUB_PWD 和 ALI_DOCKER_HUB_USN）被关联到名为 ALI_DOCKER_HUB_REGISTRY 的环境。因此，在 YAML 中我们必须指定 environment: ALI_DOCKER_HUB_REGISTRY 才能解锁这些机密。

2. 创建阿里云镜像仓库

在阿里云控制台cr.console.aliyun.com/cn-hangzhou... 进行以下操作：

访问 容器镜像服务 (Container Registry)。
进入 实例/仓库管理 ，创建新的镜像仓库（例如，命名为 chouvelgis/captchavision）。
将代码源设置为手动上传 ，并记录您的 Registry 地址。

💻 第二步：编写 GitHub Actions 工作流文件

在项目根目录下创建 .github/workflows/deploy.yml 文件。以下是您的部署脚本，它将实现自动构建、登录、推送的完整 CI 过程。

YAML 复制代码

# 工作流程名称
name: Docker 部署 CaptchaVision API

# 触发条件：当代码推送到 main 分支时触发工作流
on:
  push:
    branches:
      - main

# 工作流程作业
jobs:
  deploy:
    runs-on: ubuntu-latest
    # 关键步骤：指定环境，以解锁环境机密（ALI_DOCKER_HUB_USN/PWD）
    environment: ALI_DOCKER_HUB_REGISTRY
    
    steps:
      # 1. 迁出代码
      - name: 迁出代码
        uses: actions/checkout@v4

      # 2. 设置 Docker Buildx (用于高效构建和缓存)
      - name: 设置 Docker Buildx
        uses: docker/setup-buildx-action@v3

      # 3. 登录到阿里云容器镜像服务 (使用环境机密)
      - name: 登录到阿里云容器镜像服务
        uses: docker/login-action@v3
        with:
          registry: ${{ secrets.ALI_DOCKER_HUB_REGISTRY }}
          username: ${{ secrets.ALI_DOCKER_HUB_USN }}
          password: ${{ secrets.ALI_DOCKER_HUB_PWD }}

      # 4.构建并推送 Docker 镜像
      - name: 构建并推送 Docker 镜像
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ${{ secrets.ALI_DOCKER_HUB_REGISTRY }}/chouvelgis/${{ secrets.REPO_NAME }}:latest
            ${{ secrets.ALI_DOCKER_HUB_REGISTRY }}/chouvelgis/${{ secrets.REPO_NAME }}:${{ github.sha }}
            ${{ secrets.ALI_DOCKER_HUB_REGISTRY }}/chouvelgis/${{ secrets.REPO_NAME }}:v${{ github.run_number }}
          cache-from: type=gha # 从 GHA 缓存中拉取历史构建层
          cache-to: type=gha,mode=max # 推送新的构建层到 GHA 缓存

      # 5. 部署完成通知
      - name: 部署完成
        run: echo "Docker 部署完成，镜像已推送到 Aliyun ACR！"

📈 第三步：查看工作流日志与后续部署

1. 查看工作流日志

代码提交到 main 分支后：

进入 GitHub 仓库的 Actions 菜单。
找到名为 Docker 部署 CaptchaVision API 的工作流。
点击查看日志，所有步骤（如"登录到阿里云容器镜像服务"、"构建并推送 Docker 镜像"）都应显示绿色勾选（✅）。

2. 部署到服务器（CD)

一旦镜像推送成功，您的 CI 任务就完成了。接下来的 CD（持续部署）需要在您的目标服务器上执行。

在服务器终端，使用以下命令拉取并启动最新的容器：

直接去cr.console.aliyun.com/cn-hangzhou... 控制台，找到对应镜像仓库，查看相关文档即可拉取镜像。如果使用阿里云的ECS，可以使用镜像仓库内网地址，加快速度。

bash 复制代码

# 假设您已登录阿里云 ACR

# 停止并移除旧容器 (如果存在)
docker stop captchavision-api
docker rm captchavision-api

# 拉取最新的镜像 (使用 latest 标签)
docker pull ${{ secrets.ALI_DOCKER_HUB_REGISTRY }}/chouvelgis/${{ secrets.REPO_NAME }}:latest

# 启动容器 (注意：如果应用需要 API Key，请在运行时注入 -e 参数)
docker run -d \
  -p 8011:8011 \
  --name=captchavision-api \
  -e GEMINI_API_KEY="您的Gemini API Key" \
  ${{ secrets.ALI_DOCKER_HUB_REGISTRY }}/chouvelgis/${{ secrets.REPO_NAME }}:latest

总结

通过这一套流程，您实现了从代码提交到镜像推送的完全自动化，极大地提高了开发效率和部署一致性。