Web Analytics

setup-distributed-nix-builds

⭐ 1 stars Vietnamese by Misaka13514

🌐 Ngôn ngữ

❄️ Thiết lập Xây dựng Nix Phân tán

Một GitHub Action để cung cấp tức thời một cụm Xây dựng Nix Phân tán đa nền tảng, tạm thời bằng cách sử dụng các GitHub Hosted Runners tiêu chuẩn được kết nối bảo mật qua Tailscale.

Action này cho phép bạn khởi tạo một ma trận các runner phụ của GitHub (gọi là Builders) và kết nối chúng với runner chính (gọi là Coordinator) một cách liền mạch qua Tailscale SSH. Coordinator sẽ tự động cấu hình Nix để sử dụng các node này làm máy xây dựng từ xa, tối đa hóa hiệu suất xây dựng đồng thời mà không cần quản lý hạ tầng bên ngoài! Rất phù hợp để xây dựng các gói đa kiến trúc hoặc mở rộng quy mô ngang các đóng hệ thống NixOS nặng trên nhiều runner x86.

Tính năng

Cách hoạt động

Quy trình làm việc chia runners thành hai vai trò: builder và coordinator.

sequenceDiagram
  participant GH as GitHub Actions
  participant Coord as Coordinator (Ubuntu)
  participant B1 as Builder 1 (Ubuntu ARM)
  participant B2 as Builder 2 (macOS)
  participant TS as Tailscale Network
  GH->>B1: Spawn Builder Node
  GH->>B2: Spawn Builder Node
  GH->>Coord: Spawn Coordinator Node
  B1->>TS: Auth & Idle Wait
  B2->>TS: Auth & Idle Wait
  Coord->>TS: Auth & Wait for Builders
  TS-->>Coord: Builders Online!
  Note over Coord: Tests Nix connection &
Updates /etc/nix/machines
  Coord->>B1: Send aarch64-linux build tasks via SSH
  Coord->>B2: Send aarch64-darwin build tasks via SSH
  B1-->>Coord: Return Build Artifacts
  B2-->>Coord: Return Build Artifacts
  Note over Coord: Build Completes
  Coord->>B1: Send Teardown Signal
  Coord->>B2: Send Teardown Signal

Yêu cầu trước

Trước khi sử dụng hành động này, bạn cần cấu hình một mạng Tailscale để các runner có thể giao tiếp an toàn.

Đảm bảo bạn đã tạo nhóm thẻ trong Tailscale và ACLs cho phép coordinator SSH vào các builder một cách liền mạch bằng Tailscale SSH. Thêm nội dung sau vào Kiểm soát truy cập Tailscale:

Nhấn để xem cấu hình ACLs cần thiết của Tailscale

{
  "grants": [
    {
      "src": ["tag:nix-ci-builder", "tag:nix-ci-coordinator"],
      "dst": ["tag:nix-ci-builder", "tag:nix-ci-coordinator"],
      "ip": ["*"]
    }
  ],
  "ssh": [
    {
      "src": ["tag:nix-ci-coordinator"],
      "dst": ["tag:nix-ci-builder"],
      "users": ["autogroup:nonroot", "root"],
      "action": "accept"
    }
  ],
  "tagOwners": {
    "tag:nix-ci-coordinator": ["autogroup:admin", "tag:nix-ci-coordinator"],
    "tag:nix-ci-builder": ["autogroup:admin", "tag:nix-ci-builder"]
  }
}

Tạo một OAuth Client Secret trong Bảng điều khiển quản trị Tailscale, với quyền ghi auth_keys và các thẻ nix-ci-builder, nix-ci-coordinator. Thêm secret này vào Secrets của Repository GitHub của bạn với tên TS_OAUTH_SECRET.

Tham số đầu vào

| Tham số | Mô tả | Bắt buộc | Mặc định | | ------------------- | ---------------------------------------------------------------------------------------------- | -------- | ------------ | | tailscale_authkey | Secret OAuth client hoặc Auth Key của Tailscale. | Có | N/A | | tailscale_hostname| Tên máy chủ sẽ đăng ký với Tailscale. | Có | N/A | | tailscale_tags | Thẻ để quảng bá tới Tailscale (ví dụ: tag:nix-ci-builder). | Có | N/A | | role | Vai trò của job hiện tại: "builder" hoặc "coordinator". | Có | "builder" | | builders | Danh sách tên máy builder đầy đủ, phân tách bởi dấu cách, để chờ. (_Bắt buộc nếu là coordinator_)| Không | "" | | builder_timeout | Thời gian tối đa (giây) builder sẽ chờ trước khi tự kết thúc. | Không | "300" | | extra_nix_config | Cấu hình Nix bổ sung để thêm vào /etc/nix/nix.conf. | Không | "" |

Cách sử dụng

Ví dụ build phân tán hoàn chỉnh

Dưới đây là một workflow hoàn chỉnh (nix-build.yml) sẽ khởi tạo động nhiều runner với các kiến trúc khác nhau (Ubuntu x86, Ubuntu ARM, macOS x86, macOS Apple Silicon), kết nối chúng với nhau và thực hiện một build Nix phân tán.

Nếu bạn đang build một cấu hình NixOS nặng và chỉ muốn tăng tốc thông qua mở rộng ngang, bạn có thể thay đổi BUILDER_COUNTS để khởi tạo nhiều runner x86 giống nhau. Ví dụ: BUILDER_COUNTS: '{"ubuntu-24.04": 4}' Điều này sẽ giúp bạn có ngay một build farm với 16 nhân CPU (4 runner × 4 nhân) để xử lý các derivation song song.

Vì các GitHub Hosted Runner là tạm thời, tất cả artifact build trong Nix store sẽ bị mất khi workflow kết thúc. Để tận dụng kết quả build phân tán cho các lần chạy CI sau hoặc trên máy local, rất khuyến nghị bạn đẩy kết quả lên binary cache như Cachix hoặc Attic.

name: Distributed Nix Build
on:
  workflow_dispatch:
env:
  # Define exactly how many runners of each OS type you want
  BUILDER_COUNTS: '{"ubuntu-24.04": 1, "ubuntu-24.04-arm": 1, "macos-26-intel": 1, "macos-26": 1}'
jobs:
  config:
    runs-on: ubuntu-slim
    outputs:
      builder_matrix: ${{ steps.set.outputs.builder_matrix }}
      builders_list: ${{ steps.set.outputs.builders_list }}
      run_suffix: ${{ steps.set.outputs.run_suffix }}
    steps:
      
  • id: set
    • 
        
run: |
          SUFFIX=$(openssl rand -hex 3)
          echo "run_suffix=$SUFFIX" >> "$GITHUB_OUTPUT"
          # Dynamically generate the Matrix JSON based on BUILDER_COUNTS
          MATRIX_JSON=$(echo '${{ env.BUILDER_COUNTS }}' | jq -c '[
              to_entries[] | .key as $os | .value as $count |
              range(1; $count + 1) | { os: $os, id: "\($os)-\(.)" }
            ]
          ')
          echo "builder_matrix=$MATRIX_JSON" >> "$GITHUB_OUTPUT"
          # Create a space-separated list of hostnames for the coordinator
          BUILDERS_LIST=$(echo "$MATRIX_JSON" | jq -r --arg suffix "$SUFFIX" 'map("nix-builder-\($suffix)-\(.id)") | join(" ")')
          echo "builders_list=$BUILDERS_LIST" >> "$GITHUB_OUTPUT"
  builder:
    needs: config
    name: Builder ${{ matrix.builder.id }} (${{ needs.config.outputs.run_suffix }})
    runs-on: ${{ matrix.builder.os }}
    strategy:
      fail-fast: false
      matrix:
        builder: ${{ fromJSON(needs.config.outputs.builder_matrix) }}
    steps:
      
  • name: Setup Distributed Nix Builder
    • 
        
uses: Misaka13514/setup-distributed-nix-builds@main
        with:
          tailscale_authkey: ${{ secrets.TS_OAUTH_SECRET }}
          tailscale_hostname: nix-builder-${{ needs.config.outputs.run_suffix }}-${{ matrix.builder.id }}
          tailscale_tags: tag:nix-ci-builder
          role: builder
      # Optionally configure your Cachix/Attic or other caching here
      # - uses: cachix/cachix-action@v17
  coordinator:
    needs: config
    name: Coordinator (${{ needs.config.outputs.run_suffix }})
    runs-on: ubuntu-24.04
    steps:
      
  • name: Setup Coordinator & Connect Builders
    • 
        
uses: Misaka13514/setup-distributed-nix-builds@main
        with:
          tailscale_authkey: ${{ secrets.TS_OAUTH_SECRET }}
          tailscale_hostname: nix-coordinator-${{ needs.config.outputs.run_suffix }}
          tailscale_tags: tag:nix-ci-coordinator
          role: coordinator
          builders: ${{ needs.config.outputs.builders_list }}
      # Optionally configure your Cachix/Attic or other caching here
      # - uses: cachix/cachix-action@v17
  • name: Execute Distributed Build
    • 
        
run: |
          # Your build command here. Because builders are registered in /etc/nix/machines,
          # Nix will automatically offload tasks to the correct architecture node.
          nix build -L --max-jobs 0 .#my-package
      # Signal builders to terminate if they are not needed anymore
      
  • name: Teardown Builders
    • 
        
run: stop-nix-builders
      # Push build results to Cachix/Attic or other cache here if desired
      # - name: Push to Cachix
      #   run: cachix push mycache --all

Giấy phép

Dự án này được cấp phép theo Giấy phép MIT.

--- Tranlated By Open Ai Tx | Last indexed: 2026-03-27 ---

Original README: View on GitHub

Translated by OpenAiTx | Last updated: 2026-03-27