GitHub Actions

3 篇包含标签 "GitHub Actions" 的文章

如何用 GitHub Actions 实现 Steam 自动化发布

2026年4月16日

如何用 GitHub Actions 实现 Steam 自动化发布

本文分享了 HagiCode Desktop 项目中实现 Steam 自动化发布的完整方案，从 GitHub Release 到 Steam 平台的全链路自动化流程，包括 Steam Guard 认证、多平台 Depot 上传等关键技术细节。

背景

Steam 平台的发布流程，其实和传统的应用分发方式挺不一样的。Steam 有自己的一套完整更新分发系统，开发者得通过 SteamCMD 工具把构建产物上传到 Steam 的 CDN 网络，而不是像其他平台那样直接丢个下载链接就完事了。

HagiCode Desktop 项目计划上架 Steam 平台，这也算是给我们的发布流程带来了点新挑战：

1. 需要把现有的构建产物转换成 Steam 兼容的格式
2. 得通过 SteamCMD 工具上传到 Steam 平台
3. 还必须处理 Steam Guard 认证这玩意儿
4. 需要支持多平台（Linux、Windows、macOS）的 Depot 上传
5. 还要实现从 GitHub Release 到 Steam 的自动化流转

项目此前已经实现了”便携版模式”（portable version mode），允许应用检测打包在 extra 目录中的固定服务载荷。我们的目标，其实就是让这套便携版模式和 Steam 分发能无缝集成罢了。

关于 HagiCode

本文分享的方案，来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 代码助手项目，支持桌面端运行，我们正在推进 Steam 平台的上架工作，因此才需要建立一套可靠的自动化发布流程。

架构设计

整个 Steam 发布流程的核心是一个 GitHub Actions 工作流，它把整个过程分为三个主要阶段：

┌─────────────────────────────────────────────────────────────┐
│ GitHub Actions Workflow (Steam Release)                      │
├─────────────────────────────────────────────────────────────┤
│ 1. 准备阶段:                                                 │
│    - 检出 portable-version 代码                             │
│    - 从 GitHub Release 下载构建产物                         │
│    - 解压并准备 Steam 内容目录                              │
│                                                             │
│ 2. SteamCMD 设置:                                           │
│    - 安装/复用 SteamCMD                                     │
│    - 使用 Steam Guard 进行认证                              │
│                                                             │
│ 3. 发布阶段:                                                 │
│    - 生成 Depot VDF 配置文件                                │
│    - 生成 App Build VDF 配置文件                            │
│    - 调用 SteamCMD 上传到 Steam                             │
└─────────────────────────────────────────────────────────────┘

这种设计的优势，怎么说呢：

• 复用现有的 GitHub Release 产物，避免重复构建，毕竟谁愿意重复劳动呢
• 通过自托管运行器实现安全隔离，多一层保障总是好的
• 支持预览模式和正式发布分支切换，灵活一点
• 完整的错误处理和日志记录，出问题的时候不至于太迷茫

工作流实现

触发参数设计

我们的工作流支持以下关键参数：

inputs:
  release:           # Portable Version 发布标签
    description: '要发布的版本标签（如 v1.0.0）'
    required: true
  steam_preview:     # 是否生成预览构建
    description: '是否为预览模式'
    required: false
    default: 'false'
  steam_branch:      # 设置为 live 的 Steam 分支
    description: '目标 Steam 分支'
    required: false
    default: 'preview'
  steam_description: # 构建描述覆盖
    description: '构建描述'
    required: false

自托管运行器配置

出于安全考虑，我们使用带 steam 标签的自托管运行器：

runs-on:
  - self-hosted
  - Linux
  - X64
  - steam

这样可以确保 Steam 发布在专用运行器上执行，保持敏感凭据的安全隔离。毕竟安全这事儿，多注意一点总是好的。

并发控制

为了避免同一版本的发布相互干扰，我们配置了并发控制：

concurrency:
  group: portable-version-steam-${{ github.event.inputs.release }}
  cancel-in-progress: false

注意这里设置 cancel-in-progress: false，因为 Steam 发布过程可能较长，我们也不想因为新的触发就取消正在进行的发布。毕竟发布个版本也不容易，总得让人家跑完不是？

核心脚本实现

准备发布输入

prepare-steam-release-input.mjs 脚本负责准备发布所需的输入：

// 下载 GitHub Release 的构建清单和产物清单
const buildManifest = await downloadBuildManifest(releaseTag);
const artifactInventory = await downloadArtifactInventory(releaseTag);

// 下载各平台的压缩包
for (const platform of ['linux-x64', 'win-x64', 'osx-universal']) {
  const artifactUrl = getArtifactUrl(artifactInventory, platform);
  await downloadArtifact(artifactUrl, platform);
}

// 解压到 Steam 内容目录结构
await extractToSteamContent(sources, contentRoot);

Steam Guard 认证

Steam 要求使用 Steam Guard 保护账户，我们实现了基于共享密钥的代码生成算法：

function generateSteamGuardCode(sharedSecret, timestamp = Date.now()) {
  const secret = decodeSharedSecret(sharedSecret);
  const time = Math.floor(timestamp / 1000 / 30);

  const timeBuffer = Buffer.alloc(8);
  timeBuffer.writeBigUInt64BE(BigInt(time));

  // 使用 HMAC-SHA1 生成时间基础的一次性代码
  const hash = crypto.createHmac('sha1', secret)
    .update(timeBuffer)
    .digest();

  // 转换为 5 字符的 Steam Guard 代码
  const code = steamGuardCode(hash);
  return code;
}

这个实现基于 Steam Guard 的 TOTP（Time-based One-Time Password）机制，每 30 秒生成一个新的验证码。毕竟安全这东西，还是得用靠谱的方式才行。

VDF 配置生成

VDF（Valve Data Format）是 Steam 使用的配置格式，我们需要生成两种类型的 VDF 文件：

Depot VDF 用于配置各个平台的内容：

function buildDepotVdf(depotId, contentRoot) {
  return [
    '"DepotBuildConfig"',
    '{',
    `  "DepotID" "${escapeVdf(depotId)}"`,
    `  "ContentRoot" "${escapeVdf(contentRoot)}"`,
    '  "FileMapping"',
    '  {',
    '    "LocalPath" "*"',
    '    "DepotPath" "."',
    '    "recursive" "1"',
    '  }',
    '}'
  ].join('\n');
}

App Build VDF 用于配置整个应用构建：

function buildAppBuildVdf(appId, depotBuilds, description, setLive) {
  const vdf = [
    '"appbuild"',
    '{',
    `  "appid" "${appId}"`,
    `  "desc" "${escapeVdf(description)}"`,
    `  "contentroot" "${escapeVdf(contentRoot)}"`,
    '  "buildoutput" "build_output"',
    '  "depots"',
    '  {'
  ];

  for (const [depotId, depotVdfPath] of Object.entries(depotBuilds)) {
    vdf.push(`    "${depotId}" "${depotVdfPath}"`);
  }

  if (setLive) {
    vdf.push(`  }`);
    vdf.push(`  "setlive" "${setLive}"`);
  }

  vdf.push('}');
  return vdf.join('\n');
}

SteamCMD 调用

最后，通过调用 SteamCMD 执行上传：

await runCommand(steamcmdPath, [
  '+login', steamUsername, steamPassword, steamGuardCode,
  '+run_app_build', appBuildPath,
  '+quit'
]);

这一步算是整个流程的最后一跃，跨过去就完成了…

多平台 Depot 处理

Steam 使用 Depot 系统管理不同平台的内容，我们支持三种主要的 Depot：

平台	Depot 标识	架构支持
Linux	linux-x64	x64_64
Windows	win-x64	x64_64
macOS	osx-universal	universal, x64_64, arm64

每个 Depot 都有独立的内容目录和 VDF 配置文件，这样可以确保不同平台的用户只下载自己需要的内容。毕竟流量也是钱，能省一点是一点。

发布流程

步骤 1：准备 GitHub Release

首先需要在 portable-version 仓库创建一个 GitHub Release，包含：

• 各平台的压缩包
• 构建清单（{tag}.build-manifest.json）
• 产物清单（{tag}.artifact-inventory.json）

步骤 2：触发 Steam 发布工作流

通过 GitHub Actions 手动触发工作流，填写必要参数：

• release: 要发布的版本标签（如 v1.0.0）
• steam_branch: 目标分支（如 preview 或 public）
• steam_preview: 是否预览模式

步骤 3：自动执行发布流程

工作流会自动执行以下步骤：

1. 下载并解压 GitHub Release 产物
2. 安装/更新 SteamCMD
3. 生成 Steam VDF 配置文件
4. 使用 Steam Guard 认证
5. 上传内容到 Steam CDN
6. 设置指定分支为 live

这一套流程走下来，也算是把该做的都做了。

配置指南

必需的 Secrets 配置

在 GitHub 仓库设置中配置以下密钥：

Secret 名称	说明
STEAM_USERNAME	Steam 账户用户名
STEAM_PASSWORD	Steam 账户密码
STEAM_SHARED_SECRET	Steam Guard 共享密钥（可选）
STEAM_GUARD_CODE	Steam Guard 代码（可选）
STEAM_APP_ID	Steam 应用 ID
STEAM_DEPOT_ID_LINUX	Linux Depot ID
STEAM_DEPOT_ID_WINDOWS	Windows Depot ID
STEAM_DEPOT_ID_MACOS	macOS Depot ID

这些配置项，其实也没什么特别的，就是该有的都得有罢了。

环境变量配置

变量名称	说明	默认值
PORTABLE_VERSION_STEAMCMD_ROOT	SteamCMD 安装目录	~/.local/share/portable-version/steamcmd

最佳实践

Steam Guard 认证管理

首次运行需要手动输入 Steam Guard 代码，之后建议配置共享密钥自动生成代码。这样可以避免每次发布都需要手动干预，毕竟谁也不想每次都重复同样的操作。

SteamCMD 会保存登录令牌，后续可以复用。但要注意令牌的有效期，过期后还是得重新认证的，这也没办法。

内容目录结构

确保 Steam 内容目录结构正确：

steam-content/
├── linux-x64/     # Linux 平台内容
├── win-x64/       # Windows 平台内容
└── osx-universal/ # macOS 通用二进制内容

每个目录下应该包含对应平台的完整应用文件。这点倒也没什么好说的，该怎么做就怎么做。

预览模式使用

预览模式不会设置任何分支为 live，适合测试验证：

if [ "$STEAM_PREVIEW_INPUT" = 'true' ]; then
  cmd+=(--preview)
fi

这样可以先上传到 Steam 平台进行验证，确认无误后再切换到正式分支。多一层验证，总是好的。

错误处理和日志

脚本包含了完善的错误处理和日志记录：

• 验证 GitHub Release 存在性
• 检查必需的元数据文件
• 确保平台内容存在
• 生成 GitHub Actions 摘要报告

这些信息对于调试和审计都非常有价值，毕竟出问题的时候能有个线索，总比一头雾水要好。

产物管理

工作流生成两种产物：

• portable-steam-release-preparation-{tag}: 发布准备元数据
• portable-steam-build-metadata-{tag}: Steam 构建元数据

这些产物可以用于后续的审计和调试，保存时间建议设置为 30 天。反正也不占多少地方，留着也无妨。

实际应用

在 HagiCode 项目中，这套自动化发布流程已经成功运行了多个版本。从 GitHub Release 到 Steam 平台的整个链路完全自动化，无需人工干预。

这大大提高了我们的发布效率和可靠性。之前手动发布一个版本需要 30 分钟以上的时间，现在只需要几分钟就能完成整个流程。时间这东西，省下来总归是好的。

更重要的是，自动化流程减少了人为错误的可能性，每次发布都是标准化的流程，结果也更加可预测。毕竟重复的事情交给机器去做，人也轻松点。

总结

通过本文分享的方案，我们实现了：

1. 从 GitHub Release 到 Steam 平台的完全自动化
2. 支持多平台的 Depot 上传
3. 基于 Steam Guard 的安全认证
4. 预览模式和正式发布的灵活切换
5. 完善的错误处理和日志记录

这套方案不仅适用于 HagiCode 项目，也可以为其他计划上架 Steam 平台的项目提供参考。如果你也在考虑 Steam 自动化发布，希望本文的实践能够对你有所帮助。

其实技术这东西，说复杂也复杂，说简单也简单。关键是找到适合自己的方式罢了。

如果本文对你有帮助，欢迎来 HagiCode 的 GitHub 仓库给个 Star，或者访问官网了解更多信息。

参考资料

• SteamCMD Documentation
• Steamworks SDK
• HagiCode 项目地址
• HagiCode 官网
• HagiCode 安装指南
• HagiCode Desktop 桌面端

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。 本内容采用人工智能辅助协作,最终内容由作者审核并确认。

• 本文作者: newbe36524
• 原文链接: https://docs.hagicode.com/blog/2026-04-16-steam-release-automation-github-actions/
• 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

标签:

• GitHub Actions
• Steam
• 自动化发布
• DevOps
• CI/CD

HagiCode 实践:如何利用 GitHub Actions 实现 Docusaurus 自动部署

2026年1月26日

为 HagiCode 添加 GitHub Pages 自动部署支持

本项目早期代号为 PCode，现已正式更名为 HagiCode。本文记录了如何为项目引入自动化静态站点部署能力，让内容发布像喝水一样简单。

背景/引言

在 HagiCode 的开发过程中，我们遇到了一个很现实的问题：随着文档和提案越来越多，如何高效地管理和展示这些内容成了当务之急。我们决定引入 GitHub Pages 来托管我们的静态站点，但是手动构建和部署实在是太麻烦了——每次改动都要本地构建、打包，然后手动推送到 gh-pages 分支。这不仅效率低下，还容易出错。

为了解决这个问题（主要是为了偷懒），我们需要一套自动化的部署流程。本文将详细记录如何为 HagiCode 项目添加 GitHub Actions 自动部署支持，让我们只需专注于内容创作，剩下的交给自动化流程。

关于 HagiCode

嘿，介绍一下我们正在做的东西

我们正在开发 HagiCode——一款 AI 驱动的代码智能助手，让开发体验变得更智能、更便捷、更有趣。

智能——AI 全程辅助，从想法到代码，让编码效率提升数倍。便捷——多线程并发操作，充分利用资源，开发流程顺畅无阻。有趣——游戏化机制和成就系统，让编码不再枯燥，充满成就感。

项目正在快速迭代中，如果你对技术写作、知识管理或者 AI 辅助开发感兴趣，欢迎来 GitHub 看看～

目标分析

在动手之前，我们得先明确这次任务到底要干啥。毕竟（这里打错了，应该是毕竟）磨刀不误砍柴工嘛。

核心需求

1. 自动化构建：当代码推送到 main 分支时，自动触发构建流程。
2. 自动部署：构建成功后，自动将生成的静态文件部署到 GitHub Pages。
3. 环境一致性：确保 CI 环境和本地构建环境一致，避免”本地能跑，线上报错”的尴尬。

技术选型

考虑到 HagiCode 是基于 Docusaurus 构建的（一种非常流行的 React 静态站点生成器），我们可以利用 GitHub Actions 来实现这一目标。

配置 GitHub Actions 工作流

GitHub Actions 是 GitHub 提供的 CI/CD 服务。通过在代码仓库中定义 YAML 格式的工作流文件，我们可以定制各种自动化任务。

创建工作流文件

我们需要在项目根目录下的 .github/workflows 文件夹中创建一个新的配置文件，比如叫 deploy.yml。如果文件夹不存在，记得先手动创建一下。

这个配置文件的核心逻辑如下：

1. 触发条件：监听 main 分支的 push 事件。
2. 运行环境：最新版的 Ubuntu。
3. 构建步骤：
   • 检出代码
   • 安装 Node.js
   • 安装依赖 (npm install)
   • 构建静态文件 (npm run build)
4. 部署步骤：使用官方提供的 action-gh-pages 将构建产物推送到 gh-pages 分支。

关键配置代码

以下是我们最终采用的配置模板：

name: Deploy to GitHub Pages

# 触发条件：当推送到 main 分支时
on:
  push:
    branches:
      - main
    # 可以根据需要添加路径过滤，比如只有文档变动才构建
    # paths:
    #   - 'docs/**'
    #   - 'package.json'

# 设置权限，这对于部署到 GitHub Pages 很重要
permissions:
  contents: read
  pages: write
  id-token: write

# 并发控制：取消同一分支的旧构建
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        # 注意：必须设置 fetch-depth: 0，否则可能导致构建版本号不准确
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20 # 建议与本地开发环境保持一致
          cache: 'npm'     # 启用缓存可以加速构建过程

      - name: Install dependencies
        run: npm ci
        # 使用 npm ci 而不是 npm install，因为它更快、更严格，适合 CI 环境

      - name: Build website
        run: npm run build
        env:
          # 如果你的站点构建需要环境变量，在这里配置
          # NODE_ENV: production
          # PUBLIC_URL: /your-repo-name

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./build # Docusaurus 默认输出目录

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

实施过程中的坑点

在实际操作中，我们遇到了一些问题，这里分享出来希望大家能避开（或者提前准备好解决方案）。

1. GitHub Token 权限问题

最开始配置的时候，部署总是报错 403 (Forbidden)。查了好久才发现，是因为 GitHub 默认的 GITHUB_TOKEN 并没有写入 Pages 的权限。

解决方案：在仓库的 Settings -> Actions -> General -> Workflow permissions 中，务必选择 “Read and write permissions”。

2. 构建目录路径错误

Docusaurus 默认把构建好的静态文件放在 build 目录。但是有些项目（比如 Create React App 默认是 build，Vite 默认是 dist）可能配置不一样。如果在 Actions 中报错找不到文件，记得去 docusaurus.config.js 里检查一下输出路径配置。

3. 子路径问题

如果你的仓库不是用户主页（即不是 username.github.io），而是项目主页（比如 username.github.io/project-name），你需要配置 baseUrl。

在 docusaurus.config.js 中：

module.exports = {
  // ...
  url: 'https://hagicode.com', // 你的 Hagicode URL
  baseUrl: '/', // 根路径部署
  // ...
};

这一点很容易被忽略，配置不对会导致页面打开全是白屏，因为资源路径加载不到。

验证成果

配置完所有东西并推送代码后，我们就可以去 GitHub 仓库的 Actions 标签页看戏了。

你会看到黄色的圆圈（工作流正在运行），变绿就代表成功啦！如果变红了，点击进去查看日志，通常都能排查出问题（大部分时候是拼写错误或者路径配置不对）。

构建成功后，访问 https://<你的用户名>.github.io/<仓库名>/ 就能看到崭新的站点了。

总结

通过引入 GitHub Actions，我们成功实现了 HagiCode 文档站的自动化部署。这不仅节省了手动操作的时间，更重要的是保证了发布流程的标准化。现在不管是哪位小伙伴更新了文档，只要合并到 main 分支，几分钟后就能在线上看到最新的内容。

核心收益：

• 效率提升：从”手动打包、手动上传”变成”代码即发布”。
• 降低错误：消除了人为操作失误的可能性。
• 体验优化：让开发者更专注于内容质量，而不是被繁琐的部署流程困扰。

虽然配置 CI/CD 刚开始有点麻烦（尤其是各种权限和路径问题），但这是一次性投入，长期回报巨大的工作。强烈建议所有静态站点项目都接入类似的自动化流程。

参考资料

• GitHub Actions 官方文档
• Docusaurus 部署指南
• [actions-gh-pages Action 使用说明](https://github.com peaceiris/actions-gh-pages)

---

互动引导

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

AI 辅助声明

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

元信息

• 本文作者: newbe36524
• 本文链接: https://hagicode.com/blog/2026/01/25/docusaurus-auto-deployment-with-github-actions
• 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

标签:

• Docusaurus
• GitHub Actions
• GitHub Pages
• 自动化部署
• CI/CD

如何使用 GitHub Actions + image-syncer 实现 Docker Hub 到 Azure ACR 的自动化镜像同步

2026年1月25日

实现 Docker Hub 到 Azure ACR 的自动化镜像同步

本文介绍了如何使用 GitHub Actions 和 image-syncer 工具，实现 Docker Hub 镜像到 Azure Container Registry 的自动化同步，解决了国内及部分 Azure 区域访问 Docker Hub 速度慢的问题，提升了镜像的可用性和 Azure 环境的部署效率。

背景/引言

HagiCode 项目使用 Docker 镜像作为核心运行时组件，主要镜像托管在 Docker Hub。随着项目发展和 Azure 环境部署需求的增加，我们遇到了以下痛点：

• 镜像拉取速度慢，Docker Hub 在国内及部分 Azure 区域访问受限
• 依赖单一镜像源存在单点故障风险
• Azure 环境下使用 Azure Container Registry 能获得更好的网络性能和集成体验

为解决这些问题，我们需要建立一个自动化的镜像同步机制，将 Docker Hub 的镜像定期同步到 Azure ACR，确保用户能够在 Azure 环境中获得更快的镜像拉取速度和更高的可用性。

关于 HagiCode

我们正在开发 HagiCode——一款 AI 驱动的代码智能助手，让开发体验变得更智能、更便捷、更有趣。

智能——AI 全程辅助，从想法到代码，让编码效率提升数倍。便捷——多线程并发操作，充分利用资源，开发流程顺畅无阻。有趣——游戏化机制和成就系统，让编码不再枯燥，充满成就感。

项目正在快速迭代中，如果你对技术写作、知识管理或者 AI 辅助开发感兴趣，欢迎来 GitHub 看看。

技术方案对比

在制定解决方案时，我们对比了多种技术方案：

1. image-syncer（最终选择）

• 增量同步：仅同步变更的镜像层，显著减少网络传输
• 断点续传：网络中断后可恢复同步
• 并发控制：支持配置并发线程数，提升大镜像同步效率
• 完善的错误处理：内置失败重试机制（默认 3 次）
• 轻量级部署：单二进制文件，无依赖
• 多仓库支持：兼容 Docker Hub、Azure ACR、Harbor 等

2. Docker CLI

• 不支持增量同步：每次都需要拉取完整的镜像内容
• 效率较低：网络传输量大，时间长
• 简单易用：使用熟悉的 docker pull/push 命令

3. Azure CLI

• 复杂度高：需要配置 Azure CLI 认证
• 功能限制：az acr import 功能相对单一
• 原生集成：与 Azure 服务集成良好

架构设计决策

决策 1：同步频率设置为每日 UTC 00:00

• 平衡镜像新鲜度和资源消耗
• 避开业务高峰期，减少对其他操作的影响
• Docker Hub 镜像通常在每日构建后更新

决策 2：同步所有镜像标签

• 保持与 Docker Hub 的完全一致性
• 为用户提供灵活的版本选择
• 简化同步逻辑，避免复杂的标签过滤规则

决策 3：使用 GitHub Secrets 存储认证信息

• GitHub Actions 原生支持，安全性高
• 配置简单，易于管理和维护
• 支持仓库级别的访问控制

风险评估与缓解

风险 1：Azure ACR 认证信息泄露

• 使用 GitHub Secrets 加密存储
• 定期轮换 ACR 密码
• 限制 ACR 用户权限为仅推送
• 监控 ACR 访问日志

风险 2：同步失败导致镜像不一致

• image-syncer 内置增量同步机制
• 自动失败重试（默认 3 次）
• 详细的错误日志和失败通知
• 断点续传功能

风险 3：资源消耗过大

• 增量同步减少网络传输
• 可配置并发线程数（当前设置为 10）
• 监控同步的镜像数量和大小
• 在非高峰时段运行同步

核心解决方案

我们采用 GitHub Actions + image-syncer 的自动化方案，实现从 Docker Hub 到 Azure ACR 的镜像同步。

实施步骤

1. 准备阶段

• 在 Azure Portal 中创建或确认 Azure Container Registry
• 创建 ACR 访问密钥（用户名和密码）
• 确认 Docker Hub 镜像仓库访问权限

2. 配置 GitHub Secrets

在 GitHub 仓库设置中添加以下 Secrets：

• AZURE_ACR_USERNAME: Azure ACR 用户名
• AZURE_ACR_PASSWORD: Azure ACR 密码

3. 创建 GitHub Actions 工作流

在 .github/workflows/sync-docker-acr.yml 中配置工作流：

• 定时触发：每天 UTC 00:00
• 手动触发：支持 workflow_dispatch
• 额外触发：publish 分支推送时触发（用于快速同步）

4. 工作流执行流程

顺序	参与方	动作	说明
1	GitHub Actions	触发工作流	由定时、手动或 publish 分支推送触发
2	GitHub Actions → image-syncer	下载并执行同步工具	进入实际同步阶段
3	image-syncer → Docker Hub	获取镜像 manifest 与标签列表	读取源仓库元数据
4	image-syncer → Azure ACR	获取目标仓库已存在镜像信息	判断目标侧当前状态
5	image-syncer	对比源与目标差异	识别需要同步的镜像层
6	image-syncer → Docker Hub	拉取变更的镜像层	仅传输需要更新的内容
7	image-syncer → Azure ACR	推送变更的镜像层	完成增量同步
8	image-syncer → GitHub Actions	返回同步统计信息	包含结果、差异和错误信息
9	GitHub Actions	记录日志并上传 artifact	便于后续审计与排查

GitHub Actions 工作流实现

以下是实际运行的工作流配置（.github/workflows/sync-docker-acr.yml）：

name: Sync Docker Image to Azure ACR

on:
  schedule:
    - cron: "0 0 * * *" # 每天 UTC 00:00
  workflow_dispatch: # 手动触发
  push:
    branches: [publish]

permissions:
  contents: read

jobs:
  sync:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Download image-syncer
        run: |
          # 下载 image-syncer 二进制文件
          wget https://github.com/AliyunContainerService/image-syncer/releases/download/v1.5.5/image-syncer-v1.5.5-linux-amd64.tar.gz
          tar -zxvf image-syncer-v1.5.5-linux-amd64.tar.gz
          chmod +x image-syncer

      - name: Create auth config
        run: |
          # 生成认证配置文件 (YAML 格式)
          cat > auth.yaml <<EOF
          hagicode.azurecr.io:
            username: "${{ secrets.AZURE_ACR_USERNAME }}"
            password: "${{ secrets.AZURE_ACR_PASSWORD }}"
          EOF

      - name: Create images config
        run: |
          # 生成镜像同步配置文件 (YAML 格式)
          cat > images.yaml <<EOF
          docker.io/newbe36524/hagicode: hagicode.azurecr.io/hagicode
          EOF

      - name: Run image-syncer
        run: |
          # 执行同步 (使用新版 --auth 和 --images 参数)
          ./image-syncer --auth=./auth.yaml --images=./images.yaml --proc=10 --retries=3

      - name: Upload logs
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: sync-logs
          path: image-syncer-*.log
          retention-days: 7

配置说明

1. 触发条件

• 定时触发：cron: “0 0 * * *” - 每天 UTC 00:00 执行
• 手动触发：workflow_dispatch - 允许用户在 GitHub UI 手动运行
• 推送触发：push: branches: [publish] - 发布分支推送时触发（用于快速同步）

2. 认证配置 (auth.yaml)

hagicode.azurecr.io:
  username: "${{ secrets.AZURE_ACR_USERNAME }}"
  password: "${{ secrets.AZURE_ACR_PASSWORD }}"

3. 镜像同步配置

docker.io/newbe36524/hagicode: hagicode.azurecr.io/hagicode

此配置表示将 docker.io/newbe36524/hagicode 的所有标签同步到 hagicode.azurecr.io/hagicode

4. image-syncer 参数

• —auth=./auth.yaml: 认证配置文件路径
• —images=./images.yaml: 镜像同步配置文件路径
• —proc=10: 并发线程数为 10
• —retries=3: 失败重试 3 次

GitHub Secrets 配置清单

在 GitHub 仓库的 Settings → Secrets and variables → Actions 中配置：

Secret 名称	描述	示例值	获取方式
AZURE_ACR_USERNAME	Azure ACR 用户名	hagicode	Azure Portal → ACR → Access keys
AZURE_ACR_PASSWORD	Azure ACR 密码	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	Azure Portal → ACR → Access keys → Password

使用说明

1. 手动触发同步

1. 访问 GitHub 仓库的 Actions 标签页
2. 选择 Sync Docker Image to Azure ACR 工作流
3. 点击 Run workflow 按钮
4. 选择分支并点击 Run workflow 确认

2. 查看同步日志

1. 在 Actions 页面点击具体的工作流运行记录
2. 查看各个步骤的执行日志
3. 在页面底部的 Artifacts 区域下载 sync-logs 文件

3. 验证同步结果

# 登录到 Azure ACR
az acr login --name hagicode

# 列出镜像及其标签
az acr repository show-tags --name hagicode --repository hagicode --output table

注意事项和最佳实践

1. 安全建议

• 定期轮换 Azure ACR 密码（建议每 90 天）
• 使用专用的 ACR 服务账户，限制权限为仅推送
• 监控 ACR 的访问日志，及时发现异常访问
• 不要在日志中输出认证信息
• 不要将认证信息提交到代码仓库

2. 性能优化

• 调整 —proc 参数：根据网络带宽调整并发数（建议 5-20）
• 监控同步时间：如果同步时间过长，考虑减少并发数
• 定期清理日志：设置合理的 retention-days（当前为 7 天）

3. 故障排查

问题 1：认证失败

Error: failed to authenticate to hagicode.azurecr.io

解决方案：

1. 检查 GitHub Secrets 是否正确配置
2. 验证 Azure ACR 密码是否过期
3. 确认 ACR 服务账户权限是否正确

问题 2：网络超时

Error: timeout waiting for response

解决方案：

1. 检查网络连接
2. 减少并发线程数（—proc 参数）
3. 等待网络恢复后重新触发工作流

问题 3：镜像同步不完整

Warning: some tags failed to sync

解决方案：

1. 检查同步日志，识别失败的标签
2. 手动触发工作流重新同步
3. 验证 Docker Hub 源镜像是否正常

4. 监控和告警

• 定期检查 Actions 页面，确认工作流运行状态
• 设置 GitHub 通知，及时获取工作流失败通知
• 监控 Azure ACR 的存储使用情况
• 定期验证镜像标签一致性

常见问题和解决方案

Q1: 如何同步特定标签而不是所有标签？

修改 images.yaml 配置文件：

# 仅同步 latest 和 v1.0 标签
docker.io/newbe36524/hagicode:latest: hagicode.azurecr.io/hagicode:latest
docker.io/newbe36524/hagicode:v1.0: hagicode.azurecr.io/hagicode:v1.0

Q2: 如何同步多个镜像仓库？

在 images.yaml 中添加多行配置：

docker.io/newbe36524/hagicode: hagicode.azurecr.io/hagicode
docker.io/newbe36524/another-image: hagicode.azurecr.io/another-image

Q3: 同步失败后如何重试？

• 自动重试：image-syncer 内置重试机制（默认 3 次）
• 手动重试：在 GitHub Actions 页面点击 Re-run all jobs

Q4: 如何查看同步的详细进度？

• 在 Actions 页面查看实时日志
• 下载 sync-logs artifact 查看完整日志文件
• 日志文件包含每个标签的同步状态和传输速度

Q5: 同步需要多长时间？

• 首次全量同步：根据镜像大小，通常需要 10-30 分钟
• 增量同步：如果镜像变更小，通常 2-5 分钟
• 时间取决于网络带宽、镜像大小和并发设置

扩展功能建议

1. 添加同步通知

在工作流中添加通知步骤：

- name: Notify on success
  if: success()
  run: |
    echo "Docker images synced successfully to Azure ACR"

2. 实现镜像标签过滤

在工作流中添加标签过滤逻辑：

- name: Filter tags
  run: |
    # 仅同步以 v 开头的标签
    echo "docker.io/newbe36524/hagicode:v* : hagicode.azurecr.io/hagicode:v*" > images.yaml

3. 添加同步统计报告

- name: Generate report
  if: always()
  run: |
    echo "## Sync Report" >> $GITHUB_STEP_SUMMARY
    echo "- Total tags: $(grep -c 'synced' image-syncer-*.log)" >> $GITHUB_STEP_SUMMARY
    echo "- Sync time: ${{ steps.sync.outputs.duration }}" >> $GITHUB_STEP_SUMMARY

总结

通过本文介绍的方法，我们成功实现了从 Docker Hub 到 Azure ACR 的自动化镜像同步。这个方案利用 GitHub Actions 的定时触发和手动触发功能，结合 image-syncer 的增量同步和错误处理机制，确保了镜像的及时同步和一致性。

我们还讨论了安全最佳实践、性能优化、故障排查等方面的内容，帮助用户更好地管理和维护这个同步机制。希望本文能够为需要在 Azure 环境中部署 Docker 镜像的开发者提供有价值的参考。

参考资料

• HagiCode 项目 GitHub 仓库
• image-syncer 官方文档
• Azure Container Registry 官方文档
• GitHub Actions 官方文档

---

互动引导

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

AI 辅助声明

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

元信息

• 本文作者: newbe36524
• 本文链接: https://hagicode.com/blog/2026/01/25/how-to-sync-docker-hub-to-azure-acr-with-github
• 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

标签:

• Docker Hub
• Azure ACR
• GitHub Actions
• 镜像同步
• DevOps