ClawdBot CI/CD：GitHub Actions 自动构建 Docker 镜像并推送私有仓库

在本地跑起一个 AI 助手，听起来很酷，但每次更新代码、换模型、改配置，都要手动拉代码、重打包、推镜像、重启服务——三分钟热度很快就被重复操作浇灭。ClawdBot 和 MoltBot 这类轻量级开源 AI 应用，真正落地的关键，不是“能不能跑”，而是“能不能稳、能不能快、能不能少操心”。

本文不讲模型原理，也不堆参数调优，就聚焦一个工程师每天真实面对的问题：如何让 ClawdBot 的每一次代码提交，自动完成构建、测试、打包、推送全过程，最终一键部署到你的树莓派、NAS 或云服务器？ 我们将基于 GitHub Actions，从零搭建一套开箱即用的 CI/CD 流水线，支持：

• 自动检测 Dockerfile 变更或 main 分支推送
• 构建多平台兼容镜像（amd64/arm64，适配 Mac M 系列、树莓派 4）
• 安全注入敏感配置（Telegram Bot Token、API Key 等）
• 推送至私有 Harbor / Docker Registry / 甚至本地局域网 registry
• 附带构建状态通知与失败诊断提示

全程无需服务器运维经验，所有脚本可直接复用。

1. 为什么需要自动化构建？——从手动折腾到静默交付

你可能已经成功用 docker run 跑起了 ClawdBot，也试过 docker-compose up -d 启动 MoltBot。但现实是：

• 每次上游更新（比如 ClawdBot 发布 v2026.1.24-3），你得手动 git pull、改 Dockerfile 中的镜像标签、重新 docker build；
• 换了个 ARM 设备，发现之前构建的 x86 镜像根本跑不起来，又得配 QEMU、折腾交叉编译；
• 给朋友分享时，对方卡在“找不到 clawdbot.json 模板”或“vllm 启动报端口冲突”，你得截图发 5 条命令解释；
• 更别说 Telegram Bot Token 这类密钥，硬编码在 docker-compose.yml 里，一不小心 git push 就泄露。

这些问题，不是技术不够，而是缺少一层“确定性封装”。CI/CD 不是大厂专利，对个人项目而言，它意味着：

一次配置，永久省心：以后只需关注业务逻辑（比如加个新翻译引擎），构建和分发全自动；
环境一致，杜绝“我这能跑”：本地开发、测试、生产全部走同一套构建流程；
安全可控，密钥不落地：Token、API Key 全部由 GitHub Secrets 管理，构建机内存中临时注入，不留痕；
多平台原生支持：一条 workflow，同时产出 linux/amd64 和 linux/arm64 镜像，树莓派用户开箱即用。

这不是“过度工程”，而是把重复劳动交给机器后，你真正能腾出手来做的事：调教 Qwen3 提示词、给 MoltBot 加个方言识别、或者——干脆去喝杯咖啡。

2. 构建前准备：4 个必须确认的基线条件

在写第一行 YAML 之前，请花 2 分钟确认以下 4 项已就绪。跳过任一环节，后续构建大概率失败。

2.1 项目结构标准化（关键！）

ClawdBot 和 MoltBot 均需满足以下最小结构，否则 GitHub Actions 无法识别构建上下文：

your-repo/
├── Dockerfile              # 必须存在，且路径为根目录或明确指定
├── docker-compose.yml      # 可选，但推荐用于定义默认服务依赖
├── .github/
│   └── workflows/
│       └── ci-cd.yml       # 即将编写的 Actions 配置文件
└── README.md

特别注意：

• 若 Dockerfile 不在根目录（如放在 ./deploy/Dockerfile），需在 workflow 中显式指定 context: ./deploy；
• docker-compose.yml 中所有镜像引用请统一使用 local/clawdbot:latest 这类本地标签，不要写 ghcr.io/xxx/clawdbot:main —— 构建阶段它还不存在。

2.2 私有仓库访问凭证（Harbor / 自建 Registry）

你需要一个可写入的 Docker Registry 地址。支持三类常见场景：

场景	示例地址	凭证要求
自建 Harbor	harbor.yourdomain.com	HARBOR_USERNAME + HARBOR_PASSWORD（GitHub Secrets）
腾讯云 TCR / 阿里云 ACR	ccr.ccs.tencentyun.com/your-ns/clawdbot	TCR_USERNAME + TCR_PASSWORD（Secrets）
局域网 registry（推荐新手）	192.168.1.100:5000/clawdbot	无需密码（需确保 Actions runner 能直连该 IP）

密钥务必存入 GitHub Secrets：进入仓库 → Settings → Secrets and variables → Actions → New repository secret。名称建议用 REGISTRY_USERNAME / REGISTRY_PASSWORD，值填对应账号密码。

2.3 多平台构建支持（arm64 / amd64）

ClawdBot 默认依赖 vllm，而 vllm 的 wheel 包对架构敏感。为确保树莓派 4（ARM64）也能构建成功，请在 Dockerfile 开头添加平台声明：

# syntax=docker/dockerfile:1
FROM --platform=linux/amd64 python:3.11-slim-bookworm AS builder
# ... 后续构建步骤保持不变

并在 workflow 中启用 Buildx（见下文），它会自动处理跨平台依赖下载与编译。

2.4 GitHub Actions Runner 环境

GitHub 托管的 ubuntu-latest runner 已预装 Docker 和 Buildx，无需额外配置。但请注意：

• ubuntu-latest 当前为 22.04，内核 ≥5.15，完美支持 buildx build --platform linux/arm64,linux/amd64；
• 若你使用自建 runner（如树莓派上的 self-hosted runner），请确保已安装 docker-ce 和 qemu-user-static（用于模拟构建）；
• 所有敏感操作（如登录私有 registry）均通过 docker/login-action@v3 完成，不暴露明文密码。

确认以上四点后，我们正式进入核心环节。

3. 核心 Workflow 编写：一份可直接复制的 .github/workflows/ci-cd.yml

以下是一个经过实测、兼顾安全性与易用性的完整 CI/CD 配置。它支持：

• 仅当 Dockerfile 或 docker-compose.yml 变更时触发；
• 自动推送到私有 registry，并打上 latest + commit-hash 双标签；
• 构建失败时自动发送 Slack / 邮件通知（可选开启）；
• 支持手动触发（Draft Release 时点击 “Run workflow”）。

# .github/workflows/ci-cd.yml
name: Build & Push ClawdBot/MoltBot Image

on:
  # 自动触发：main 分支推送，且变更了 Docker 相关文件
  push:
    branches: [main]
    paths:
      - 'Dockerfile'
      - 'docker-compose.yml'
      - '.github/workflows/ci-cd.yml'
  # 手动触发：发布 Release 时可选运行
  workflow_dispatch:
    inputs:
      tag:
        description: 'Image tag (e.g., v1.0.0 or latest)'
        required: false
        default: 'latest'

env:
  IMAGE_NAME: ${{ secrets.REGISTRY_URL }}/clawdbot  # 如 harbor.yourdomain.com/clawdbot
  # 若为 MoltBot，改为 moltbot；若用 TCR，改为 ccr.ccs.tencentyun.com/ns/moltbot

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        id: buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to private registry
        uses: docker/login-action@v3
        with:
          registry: ${{ secrets.REGISTRY_URL }}
          username: ${{ secrets.REGISTRY_USERNAME }}
          password: ${{ secrets.REGISTRY_PASSWORD }}

      - name: Extract metadata (tags, labels)
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.IMAGE_NAME }}
          tags: |
            type=raw,value=latest
            type=sha,value=short
            type=ref,event=branch
            type=ref,event=tag

      - name: Build and push
        id: build-and-push
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Image digest
        run: echo "Digest: ${{ steps.build-and-push.outputs.digest }}"

3.1 关键配置逐行解读

步骤	作用	为什么重要
Set up Docker Buildx	启用 Buildx 构建器，支持多平台、缓存、高级输出格式	没它，--platform linux/arm64 会报错
Log in to private registry	安全登录私有仓库，凭据来自 GitHub Secrets	避免密码硬编码，符合最小权限原则
Extract metadata	自动生成 latest、sha-abc123、main 等标签	无需手动维护版本号，Release 时还能打 v1.0.0
Build and push	真正执行构建：拉取基础镜像、安装依赖、打包、推送	cache-from/to: gha 利用 GitHub Actions 缓存，二次构建提速 70%+

3.2 实际效果演示

提交一次 Dockerfile 修改后，Actions 页面显示：

 Build & Push ClawdBot/MoltBot Image
  ├─ Checkout code
  ├─ Set up Docker Buildx
  ├─ Log in to private registry
  ├─ Extract metadata
  └─ Build and push → pushed to harbor.yourdomain.com/clawdbot:latest
                          pushed to harbor.yourdomain.com/clawdbot:sha-885167d

此时，在你的服务器上执行：

# 拉取最新镜像（自动匹配当前 CPU 架构）
docker pull harbor.yourdomain.com/clawdbot:latest

# 启动（使用你自己的 docker-compose.yml）
docker-compose up -d

整个过程，从代码提交到服务更新，无需 SSH 登录服务器，无需手动输入任何命令。

4. 进阶技巧：让 CI/CD 更懂你的需求

上面的基础 workflow 已足够日常使用。但如果你希望进一步提升效率或适配特殊场景，这里提供 3 个即插即用的增强模块。

4.1 模型热替换：不重建镜像，只更新模型权重

ClawdBot 的核心价值在于模型能力，但 vllm/Qwen3-4B-Instruct-2507 这类模型体积达 2~3GB，每次构建都重新下载极其耗时。更优解是：镜像中只放运行时环境，模型文件挂载为 volume。

修改 docker-compose.yml：

services:
  clawdbot:
    image: harbor.yourdomain.com/clawdbot:latest
    volumes:
      - ./models:/app/models:ro  # 模型目录映射
      - ./config:/app/config:ro  # 配置文件映射
    environment:
      - VLLM_MODEL=/app/models/Qwen3-4B-Instruct-2507

然后在 workflow 中增加一步：自动同步模型到服务器（使用 rsync 或 scp）。这样，更新模型只需 rsync -av models/ user@server:/path/to/models，完全绕过镜像重建。

4.2 构建结果通知：失败时立刻知道

在 build-and-push 步骤后添加：

      - name: Notify on failure
        if: ${{ failure() }}
        uses: dawidd6/action-send-mail@v3
        with:
          server_address: smtp.gmail.com
          server_port: 465
          username: ${{ secrets.EMAIL_USER }}
          password: ${{ secrets.EMAIL_APP_PASSWORD }}
          subject: ❌ Failed: ${{ github.repository }} CI/CD
          body: |
            Job failed at ${{ github.run_id }}.
            Commit: ${{ github.sha }}
            Branch: ${{ github.head_ref }}
            Logs: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          to: your@email.com
          from: CI Bot <no-reply@ci>

提示：Gmail 需开启“App Password”，国内用户可用企业邮箱 SMTP 或钉钉机器人（dingtalk-action）。

4.3 多应用统一管理：ClawdBot + MoltBot 共享流水线

你可能同时维护多个 AI 应用。与其为每个项目写一份 workflow，不如用矩阵策略统一管理：

strategy:
  matrix:
    app: [clawdbot, moltbot]
    platform: [linux/amd64, linux/arm64]

env:
  IMAGE_NAME: ${{ secrets.REGISTRY_URL }}/${{ matrix.app }}

steps:
  - uses: actions/checkout@v4
  - name: Checkout ${{ matrix.app }} submodules
    run: git submodule update --init --recursive
  # ... 后续构建步骤保持不变

只需在仓库根目录下建立 clawdbot/ 和 moltbot/ 子目录，即可单 workflow 管理双项目。

5. 故障排查：5 个高频问题与速查方案

即使配置无误，构建仍可能失败。以下是根据真实案例整理的 Top 5 问题及解决方法：

5.1 ERROR: failed to solve: rpc error: code = Unknown desc = failed to solve with frontend dockerfile.v0: failed to create LLB definition: no match for platform in manifest

原因：基础镜像（如 python:3.11-slim）未提供目标平台（如 arm64）的 manifest。
解法：在 Dockerfile 中强制指定平台，或改用 --platform=linux/arm64 显式拉取：

FROM --platform=linux/arm64 python:3.11-slim-bookworm

5.2 denied: requested access to the resource is denied

原因：GitHub Secrets 中 REGISTRY_USERNAME / REGISTRY_PASSWORD 填写错误，或 registry 未开启匿名读写。
解法：进入 Secrets 页面，重新输入凭证；若用 Harbor，检查项目是否开启“公开”或用户是否有 push 权限。

5.3 qemu: unshare failed: Operation not permitted

原因：自建 runner（如树莓派）未正确注册 QEMU。
解法：在 runner 主机执行：

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

5.4 构建超时（> 60 分钟）

原因：vllm 编译耗时过长，尤其在 ARM 设备上。
解法：改用预编译 wheel（推荐）：

RUN pip install --find-links https://vllm.ai/wheels --no-index vllm

5.5 Gateway not reachable 类错误（ClawdBot 启动后报错）

原因：CI 构建的镜像中 clawdbot.json 配置未生效，或 vllm 服务未监听 0.0.0.0:8000。
解法：在 Dockerfile 中加入验证步骤：

RUN clawdbot models list | grep "Qwen3" || (echo "Model check failed!" && exit 1)

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。