从 GitHub Actions 迁移到 Blacksmith 指南

将 CI/CD 工作流从 GitHub 托管 runner 迁移到 Blacksmith ↗ 非常简单直观。因为 Blacksmith 是作为无缝替代方案（drop-in replacement）设计的，你无需重写流水线、更换平台或修改核心 YAML 语法。

本文将介绍 Blacksmith 的核心优势、前置条件，以及在 5 分钟内完成迁移的两种简单方法。

GitHub 托管 Runner 的痛点#

随着项目规模的扩大，CI/CD 流水线的运行时间往往会成为开发效率的瓶颈。GitHub 标准 runner（ubuntu-latest）在 vCPU 算力和 I/O 吞吐量方面存在局限：

构建速度受限: Docker 镜像层缓存依赖网络传输，无法直接利用高速本地 NVMe 存储。
使用成本高昂: GitHub 上高配置 runner 的分钟数计费较为昂贵。
资源瓶颈: 大型测试套件容易因为 vCPU 资源限制而导致挂起或变慢。

flowchart LR
    A[Commit Code] --> B[GitHub Workflow Triggered]
    B --> C{Runner Selection}
    C -->|标准配置| D[GitHub Standard Runner\n- 普通速度\n- 网络缓存]
    C -->|Blacksmith Drop-in| E[Blacksmith High-Perf Runner\n- 高性能 vCPU\n- 本地 NVMe 缓存]
    D --> F[Build Time: 10-15 分钟]
    E --> G[Build Time: 3-5 分钟]

前置条件（Prerequisites）#

在开始迁移之前，请确保满足以下基础设施要求：

仅限 GitHub Organization 账户: Blacksmith 专为 GitHub 组织设计，暂不支持个人用户仓库（Personal Account）。
网络访问（IP 白名单）: 如果你的组织启用了严格的 IP Allowlist，请先将 Blacksmith 控制平面的 IP 加入白名单。

方法一：使用自动迁移向导（推荐）#

最便捷的迁移方式是使用 Blacksmith 内置的向导，它会自动为你的仓库创建 Pull Request。

注册账号: 访问 Blacksmith Dashboard 并创建账号。
关联 GitHub: 授权 Blacksmith 访问你的 GitHub Organization。
运行向导: 在 Dashboard 控制台选择需要迁移的仓库。
审查 PR: 向导会自动扫描 .github/workflows/ 目录并提交一个 Pull Request。
合并 PR: 检查修改并合并 Pull Request，随后的提交即可直接在 Blacksmith Runner 上运行。

方法二：手动迁移（仅需修改一行代码）#

如果你更倾向于手动更新工作流，只需要在 YAML 配置文件中修改 runs-on 属性。

打开你的工作流文件（例如 .github/workflows/ci.yml），将 ubuntu-latest 替换为指定的 Blacksmith runner：

.github/workflows/ci.yml

# 修改前：使用 GitHub 标准 runner
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

# 修改后：使用 Blacksmith 高性能 runner
jobs:
  test:
    runs-on: blacksmith-4vcpu-ubuntu-2404 // [!code ++]
    steps:
      - uses: actions/checkout@v4

yaml

[!TIP] 无需修改任何步骤（steps）的代码，所有现有 GitHub Actions 语法完全兼容。

可用 Runner 规格#

根据具体的 Job 负载选择最适合的 Runner 配置：

blacksmith-4vcpu-ubuntu-2404: 适用于标准工作负载。
blacksmith-8vcpu-ubuntu-2404: 适用于中等负载或 Docker 构建。
blacksmith-16vcpu-ubuntu-2404: 适用于大型测试套件与复杂代码编译。

[!NOTE] 如果项目有特定需求，Blacksmith 同样提供基于 Ubuntu 22.04 与 ARM64 架构的规格。

迁移后的优势与体验#

极速原生缓存: 现有的 actions/cache 无需修改即可直接工作，充分利用 Blacksmith 本地 NVMe 存储大幅提升下载速度。
Docker 镜像构建优化: docker/setup-buildx-action 等构建步骤会自动享受优化的缓存机制，显著缩短镜像构建耗时。
实时数据分析: 任务运行完成后，登录 Blacksmith Dashboard 可实时查看运行历史对比、提速幅度与成本节省数据。

sequenceDiagram
    autonumber
    participant Dev as Developer
    participant GH as GitHub Actions
    participant BS as Blacksmith Runner
    participant NVMe as Local NVMe Cache

    Dev->>GH: Push Commit / PR
    GH->>BS: 触发 Job (runs-on: blacksmith)
    BS->>NVMe: 从本地 NVMe 读取缓存
    NVMe-->>BS: 返回缓存层
    BS->>BS: 执行 Build & Test
    BS-->>GH: 上报任务状态