Skip to content

README.md

Latest commit

 

History

History
281 lines (203 loc) · 9 KB

README.md

File metadata and controls

281 lines (203 loc) · 9 KB
Raw

Docker Auto Build

基于 GitHub Actions 的自动化 Docker 多镜像构建工具

克隆源码或下载 Release → 构建 linux/amd64 + linux/arm64 镜像 → 推送 DockerHub / GHCR，并在下次运行时自动跳过无更新的项目。

工作流程

push / 手动触发
    │
    ▼
prepare job          ← 读取 config.yaml，生成 JSON 构建矩阵
    │
    ▼
build job × N（并行）
    │
    ├─ [1] 检查更新 ──── 比较源仓库最新 commit/tag 与上次记录，无变化则跳过
    ├─ [2] 克隆源码 ──── repo 模式 git clone --depth 1
    ├─ [3] 下载 Release ─ 匹配并下载最新 Release 产物
    ├─ [4] 路径预检 ──── 校验 Dockerfile 中 COPY/ADD 路径
    ├─ [5] 构建推送 ──── buildx 多平台构建 → 推送到 registry
    ├─ [6] 提交状态 ──── 将版本标记写入 .build-state/ 提交回仓库
    └─ [7] 更新描述 ──── 同步源仓库 README 到 DockerHub 描述页

快速开始

1. 准备 Token

Registry Token 说明
DockerHub 自建 PAT Account Settings → Personal Access Tokens → 勾选 Read / Write / Delete
GHCR GITHUB_TOKEN 自动提供，无需配置

2. 配置 Secrets

仓库 Settings → Secrets and variables → Actions → New repository secret：

Secret 值
DOCKERHUB_USERNAME DockerHub 用户名
DOCKERHUB_TOKEN 上一步创建的 PAT

3. 编写 config.yaml

repositories:
  - name: my-app
    repo_url: https://github.com/owner/repo.git

4. 推送触发

git add . && git commit -m "add my-app" && git push

镜像地址：<username>/<name>:latest + :<YYYYMMDD>

目录结构

.
├── config.yaml                        # 核心：所有仓库的构建配置
├── .github/workflows/docker-build.yml # CI 定义
├── .build-state/                      # 自动生成：各项目上次构建时的源码版本标记
│   ├── realm.txt
│   └── my-app.txt
├── README.md
└── dockerfiles/                       # 本地构建文件（按需）
    └── <name>/
        ├── Dockerfile                 # 本地 Dockerfile
        ├── config.toml                # 其他依赖
        └── entrypoint.sh

dockerfiles/<name>/repo/ 和 dockerfiles/<name>/release/ 是 CI 临时目录（.gitignore 排除）。

配置参考

完整字段

repositories:
  - name: service-name           # 必填
    build_type: repo             # 可选，默认 repo
    repo_url: https://github.com/owner/repo.git
    branch: main                 # 可选，不填自动检测
    release_name: binary.tar.gz  # 可选
    dockerfile: path/in/repo     # 可选，源仓库内 Dockerfile 路径
    context: /custom/path        # 可选，覆盖构建上下文
    registry: both               # 可选，默认 dockerhub
    build_args:                  # 可选
      VERSION: 1.0

字段一览

字段 默认 说明
name 必填 镜像名 = <username>/<name>，目录对应 dockerfiles/<name>/，含大写自动转小写
build_type repo dockerfile：不克隆仓库，用本地 Dockerfile + Release 构建；repo：克隆源码编译
repo_url - Git 仓库地址，支持 .git 结尾或省略
branch 仓库默认分支 不填时通过 GitHub API 自动获取
release_name - 从最新 Release 模糊匹配下载，.tar.gz 自动解压
dockerfile Dockerfile repo 模式下指定源仓库内 Dockerfile 的位置
context 自动推断 手动覆盖 Docker 构建上下文目录
registry dockerhub 推送目标：dockerhub / ghcr / both
build_args - 键值对 → docker build --build-arg KEY=VALUE

registry 取值

值 DockerHub GHCR 示例镜像名
dockerhub ✓ ✗ <user>/<name>
ghcr ✗ ✓ ghcr.io/<owner>/<name>
both ✓ ✓ 同时推送到两个 registry

配置示例

repositories:
  # dockerfile 模式 + Release 二进制 → 仅 GHCR
  - name: realm
    build_type: dockerfile
    repo_url: https://github.com/zhboner/realm.git
    release_name: realm-x86_64-unknown-linux-musl.tar.gz
    registry: ghcr

  # repo 模式 + 源仓库自带 Dockerfile → 双 registry
  - name: mermaid-live-editor
    build_type: repo
    repo_url: https://github.com/mermaid-js/mermaid-live-editor.git
    branch: develop
    registry: both

  # repo 模式 + 本地 Dockerfile → DockerHub
  - name: reality
    build_type: repo
    repo_url: https://github.com/XTLS/Xray-core.git
    registry: dockerhub
    # 在 dockerfiles/reality/Dockerfile 编写，COPY ./repo/... 引用源码

两种构建模式

dockerfile 模式

不克隆源码 → 下载 Release → COPY ./release/xxx → 构建
  • Dockerfile 必须在 dockerfiles/<name>/Dockerfile
  • 构建上下文：dockerfiles/<name>/
  • 适合只需要预编译二进制的项目

repo 模式

git clone → 源码在 dockerfiles/<name>/repo/ → 编译 → 构建
  • Dockerfile 可选，优先级：本地 → config.dockerfile → 源仓库根目录
  • 本地 Dockerfile 上下文：dockerfiles/<name>/（用 ./repo/ 引用源码）
  • 源仓库 Dockerfile 上下文：dockerfiles/<name>/repo/

路径约定

Dockerfile 中 COPY 源路径的根 = 构建上下文（Context）：

场景 Context COPY 写法 解析为
dockerfile 模式 dockerfiles/realm/ COPY ./release/realm /bin/ dockerfiles/realm/release/realm
repo + 本地 Dockerfile dockerfiles/app/ COPY ./repo/src/ ./ dockerfiles/app/repo/src/
repo + 源仓库 Dockerfile dockerfiles/app/repo/ COPY package.json ./ dockerfiles/app/repo/package.json

构建前会自动预检所有 COPY 路径，MISS 的会打印上下文目录结构。

增量构建

每次 Push 触发时，CI 先检查源仓库是否有更新：

模式 检测方式 基准值
repo 分支最新 commit SHA a1b2c3d...
dockerfile + release_name Release 最新 tag v2.9.4
本地 dockerfiles/<name>/ git diff HEAD~1 有文件变更即触发
  • 标记存入 .build-state/<name>.txt，构建成功后提交回仓库
  • Push 和手动触发均遵循增量判断；PR 始终强制构建
  • 无更新时输出 源码无更新，跳过构建

镜像标签

每次构建生成两个标签，一次构建同时打四个标签（both 模式）：

DockerHub: <user>/<name>:latest   <user>/<name>:20260704
GHCR:      ghcr.io/<owner>/<name>:latest   ghcr.io/<owner>/<name>:20260704

DockerHub 描述同步

构建成功后自动将源仓库 README 同步为 DockerHub full_description：

  • 简短描述：Auto-built from <repo_url>
  • 完整描述：仓库 URL + --- + README 全文（上限 25000 字符）
  • 仅当 registry 包含 dockerhub 时执行

触发条件

触发 条件 push 镜像 更新描述 增量跳过
Push 推送到 main/master，变更 dockerfiles/**/config.yaml/workflow ✓ ✓ ✓
手动 Actions → Run workflow ✓ ✓ ✓
PR PR 到 main/master ✗ ✗ ✗（始终构建）

所需权限

workflow 级 permissions

permissions:
  contents: write   # 提交 .build-state/ 状态文件
  packages: write   # 推送 GHCR

DockerHub Token

DOCKERHUB_TOKEN 必须是 Personal Access Token，权限勾选 Read / Write / Delete。

常见问题

Q: DockerHub 描述更新 401/403？ A: Token 需要 Read + Write + Delete 三项全勾选。DockerHub → Personal Access Tokens → Edit Permissions。

Q: 镜像名含大写报错？ A: Docker 要求镜像名全小写。CI 会自动将 91Writing → 91writing。

Q: repo_url 没写 .git 报错？ A: 支持 .git 结尾或省略，如 https://github.com/owner/repo 同样可用。

Q: Release 下载报 "无法获取 Release 信息"？ A: 未认证 GitHub API 限额 60 次/小时，矩阵并行任务的 API 调用可能超限。等待一小时重试。

Q: repo 模式下 Dockerfile 路径报 MISS？ A: 检查预检日志中的上下文目录结构。本地 Dockerfile 的 COPY 路径相对于 dockerfiles/<name>/，源仓库 Dockerfile 相对于 repo/。

Q: 构建状态文件在哪里？ A: .build-state/ 目录，每个项目一个 txt 文件。构建成功后会由 CI 自动提交推送，无需手动维护。

Q: GHCR 镜像是 private？ A: 默认继承仓库可见性。GitHub → Packages → 对应的包 → Settings → Change visibility → Public。

Q: registry: both 会构建两次吗？ A: 不会。docker buildx build 一次构建，通过多个 -t 标签同时推送到两个 registry。