Ghaf Infra

本仓库以声明式方式定义了 Ghaf CI/CD 基础设施的 NixOS 配置。所有主机配置（包括密钥）均在此处进行版本控制。

概述

该基础设施包括：

Jenkins CI 环境（prod、dev、release），托管于 Hetzner
用于 x86_64 和 aarch64 的多架构远程构建器
连接了硬件设备的本地测试代理
支持服务：监控、日志记录、身份验证、Nebula 覆盖网络、NetHSM 硬件签名以及 OCI 容器注册表
通过 sops-nix 进行的密钥管理（参见架构概述）

入门指南

本文档假设您拥有支持 flakes 的 nix。

克隆此仓库：

❯ git clone https://github.com/tiiuae/ghaf-infra.git
❯ cd ghaf-infra

使用所需的依赖项引导 nix shell：

❯ nix develop

文档中引用的所有命令均在 nix-shell 内执行。

开发

开发 shell 包含在 git commit 时自动运行的 pre-commit 钩子。有关完整列表，请参阅 nix/git-hooks.nix。要针对所有文件手动运行它们：

nix fmt

要评估所有 Nix 表达式并验证 NixOS 配置，而无需构建派生项（可捕获语法错误、类型不匹配以及缺失的属性）：

nix flake check --no-build

要运行包含构建在内的完整检查套件：

nix flake check

目录结构

ghaf-infra
├── docs/               # Documentation (see Documentation section below)
├── hosts/              # NixOS host configurations
│   ├── builders/       # Remote builder machines
│   ├── hetzci/         # Jenkins CI environments (see hetzci/README.md)
│   ├── testagent/      # On-prem test agents
│   ├── ghaf-*/         # Supporting services (monitoring, auth, registry, etc.)
│   └── machines.nix    # Canonical host inventory (modules, systems, deploy metadata, IPs, keys)
├── nix/                # Flake plumbing (deployments, apps, git-hooks)
├── scripts/            # Operational scripts
├── services/           # Shared NixOS service modules
├── users/              # Admin user configurations
└── tasks.py            # Invoke tasks (see docs/tasks.md)

文档

架构概览 — 各组件如何协同工作
添加新主机 — 主机接入的分步操作手册
部署任务 — 安装、重启及其他运维任务
使用 deploy-rs 进行部署 — 如何部署配置变更
监控 — Grafana 和 Prometheus 配置
Nebula 覆盖网络 — 主机间的网络连接
NetHSM 硬件签名 — 基于硬件的签名
Jenkins 身份验证 — Jenkins 身份验证配置
Jenkins 测试代理 — 本地测试代理
Jenkins CI 开发 — 开发 CI 环境

常见任务

部署配置变更 — deploy-rs
添加新主机 — 添加主机
添加远程构建用户 — 将其 SSH 密钥添加到 developers.nix，然后部署
接入新管理员 — 将其用户添加到 users/，可选地将其 age 密钥添加到 .sops.yaml 并运行 inv update-sops-files，然后部署
管理密钥 — 密钥管理
安装、重启及其他运维任务 — 任务

注意：主机可能随时被重新安装。请勿在本仓库配置之外的位置存储重要数据 — 包括主机上的 /home 目录。

许可证

本项目符合 REUSE 规范。请参阅 LICENSES/ 以及每个文件中的 SPDX 头。