cfgd

状态： Alpha。API 可能会变更。

---

• 什么是 cfgd
• 工作原理
• 快速入门
• cfgd 的存在意义
• 可分享的模块
• cfgd 的比较
• 功能
• 文档
• 分发

---

什么是 cfgd

大多数点文件管理器都会跟踪文件。cfgd 管理整台机器。你可以在受版本控制的 YAML 中声明软件包、文件、机密信息和系统设置。cfgd 会对比你期望的状态与当前状态，生成计划并持续协调。如果配置发生偏移，系统会检测并修正。

工作原理

配置档案声明机器的期望状态：软件包、文件和系统设置。它们通过继承组合：在多台机器间共享通用基础配置，再根据不同场景进行专门配置。参见 docs/profiles.md。

             base
            ╱    ╲
        work    personal
       ╱    ╲
  laptop    devcontainer

模块是可分享、独立完整的配置包。你可以安装他人的开发环境，也可以发布自己的模块。跨平台的软件包解析会自动选择合适的软件包管理器。参见 docs/modules.md。

协调会持续确保机器符合声明的状态。系统会检测并报告配置偏移，并可选择自动修正。操作失败不会中止流程，而是记录日志并跳过。参见 docs/reconciliation.md，或观看两台机器通过守护进程逐步收敛到一致状态。

快速入门

# Install via Homebrew
brew install tj-smith47/tap/cfgd

# Or via install script
curl -fsSL https://github.com/tj-smith47/cfgd/releases/latest/download/install.sh | sh

# Or via cargo
cargo install cfgd

# Bring your config to a new machine in seconds
cfgd init --from [email protected]:you/machine-config.git

# Or start fresh
cfgd init

# Or let AI scan your system and generate config for you
export ANTHROPIC_API_KEY=sk-...
cfgd generate

# Set up shell completions (add to your shell's rc file)
source <(cfgd completion bash)  # .bashrc
source <(cfgd completion zsh)   # .zshrc
cfgd completion fish | source   # config.fish

cfgd 的由来

我最近换了工作，在上一份工作的最后一周里，我备份了脚本和点文件，筛出了公司专属信息，并打包成 tarball 进行迁移。到了新工作后，我又花了几天时间重新配置新机器。后来我不断发现自己漏掉了东西，也发现有些东西（比如系统设置）本该包含在备份里。整个过程既手动又不完整：我应该能够克隆一个仓库，就让整台工作站（软件包、脚本、点文件、系统设置）恢复熟悉的状态。更理想的是，还能让家里和工作用的笔记本电脑之间的部分配置保持同步。

另一个灵感来自 devcontainers。在上一家公司，我设置了自定义脚本，把点文件注入 devcontainer，让用户进入 Shell 后就能复现自己的开发环境。至少，我希望在任何临时容器中都能使用完整的 Neovim 配置，而不必修改每个团队仓库中的 devcontainer 配置来适配它。我需要一种能从外部将配置引导到任何环境的方式，不受我正在处理哪个仓库的影响。此外，我还有几位同事需要了解 vim-motions 的优越之处，因此想找一种快捷方式，分享完全一致的配置，连别名也不例外。

cfgd 借鉴了多种实践中的优秀理念：

• Kubernetes：声明式协调循环、KRM 资源模型
• Terraform：计划/应用工作流、状态跟踪、漂移检测
• Puppet：通过守护进程持续强制执行、模块生态系统
• Nix：通过单一事实来源实现可复现的机器状态
• Ansible：由 YAML 驱动的配置管理、幂等任务执行
• Kustomize：分层覆盖和补丁
• chezmoi：点文件管理

可分享的模块

这是我最喜欢的功能：一个适用于任何地方的工具配置包。

cfgd module create my-dev-env
cfgd profile update --module community/nvim

模块可以声明支持跨平台解析的软件包、配置文件、Shell 环境变量和别名，以及生命周期脚本：

apiVersion: cfgd.io/v1alpha1
kind: Module
metadata:
  name: nvim
  description: Neovim editor configuration
spec:
  depends: [node, python]
  packages:
    - name: neovim
      minVersion: "0.10"
      prefer: [brew, snap]
      deny: [apt]
    - name: ripgrep
    - name: fd
      aliases:
        apt: fd-find
        dnf: fd-find
    - name: gcc
      aliases:
        apt: build-essential
        dnf: "@development-tools"
      platforms: [linux]
  files:
    - source: files/init.lua
      target: ~/.config/nvim/init.lua
    - source: files/lua
      target: ~/.config/nvim/lua
  env:
    - name: EDITOR
      value: nvim
  aliases:
    - name: v
      command: nvim
  scripts:
    postApply:
      - nvim --headless '+Lazy! sync' '+MasonToolsInstallSync' +qa

完整规范（包括 git 文件源、注册表和依赖解析）请参阅 docs/modules.md。

cfgd 对比

	cfgd	chezmoi	Nix Home Manager	Ansible	Puppet
侧重点	完整机器状态	点文件	点文件 + 软件包（Nix）	通用自动化	服务器/基础设施状态
软件包	18 种管理器	无	仅 Nix	任意（通过任务）	任意（通过提供程序）
漂移检测	持续（守护进程）	手动	重建时	手动	持续（Agent）
跨平台解析	按软件包映射管理器	不适用	仅 Nix	按任务设置条件	按操作系统提供 Hiera 数据
可分享的模块	一等支持	仅模板	Flakes	角色（Galaxy）	Forge（面向服务器）
团队配置	策略层级 + Crossplane	不适用	Flake 输入	不适用	Puppet Enterprise
基础设施	单个二进制文件，无需服务器	单个二进制文件	Nix 守护进程	SSH（或 AWX）	PuppetServer + PuppetDB + CA
学习曲线	YAML + CLI	Go 模板	Nix 语言	YAML + Jinja2	Puppet DSL（Ruby）

从理念上说，Puppet 最为接近：声明式状态、持续强制执行、模块生态系统。如果你认同这种模式，但不想在 2026 年为了管理点文件而搭建 JVM 服务器、编写 Ruby 时代的 DSL，那么 cfgd 就是从头为开发者工作站重新打造的这一理念。

如果你需要跨平台机器引导的一行命令、可分享的开发环境模块、在机器之间或订阅源之间持续协调，或者带策略强制执行的团队配置分发，那么 cfgd 就很适合你。

功能

面向开发者：

• 单命令引导：在新机器上运行 cfgd init --from <repo> --apply
• AI 引导生成：cfgd generate 会扫描系统并构建配置档案/模块；提供 MCP 服务以集成 AI 编辑器
• MCP 服务：cfgd mcp 将 CLI 本身作为工具提供服务，让助手能够协调机器，而不仅仅是为机器编写配置
• 编写技能：cfgd skill install 可教会你的编码 Agent（Claude Code、Gemini、Copilot、Codex、Cursor）编写高质量的 cfgd 资源
• 可共享模块：支持跨平台的开发环境包，具备依赖解析和注册表
• 18 种包管理器：brew、apt、dnf、pacman、cargo、npm、pipx、snap 等，并支持自动感知平台的解析
• 密钥：SOPS/age 加密，以及 1Password、Bitwarden、HashiCorp Vault；由密钥提供支持的环境变量
• Tera 模板：使用变量、操作系统检测和自定义函数渲染点文件
• 持续漂移检测：守护进程监控变更、自动同步，并发送通知或自动纠正

面向平台和基础设施工程师：

• 多源配置：通过策略层级（锁定/必需/推荐/可选）发布团队基线配置
• Kubernetes 运算符：提供 MachineConfig、ConfigPolicy、ClusterConfigPolicy、DriftAlert、BackupPolicy、Module 的 CRD；准入 Webhook；带有集群仪表板的设备网关
• 节点配置：sysctl、内核模块、containerd、kubelet、AppArmor、seccomp、证书
• CSI 驱动程序：通过卷将基于 OCI 的模块注入 Pod
• Crossplane 集成：用于自助分发团队环境的 TeamConfig XR
• kubectl 插件：使用 kubectl cfgd debug/exec/inject/status 检查节点

面向安全与合规：

• 合规快照：持续捕获机器状态，并导出 JSON/YAML 供 Vanta、Drata 或自定义集成使用
• 密钥配置：声明式 SSH 密钥生成、GPG 密钥管理和 Git 签名配置
• 强制加密：逐文件设置加密要求，并验证 SOPS/age 后端
• 策略执行：锁定文件、必需软件包，以及目标路径上的加密约束
• 漂移修复：守护进程检测并自动纠正配置漂移，并应用各模块的策略
• 集群可视性：设备网关汇总已登记机器的合规评分

文档

文档	描述
配置	根配置（cfgd.yaml）、文件策略、别名、主题
配置档案	配置档案 YAML、继承、合并规则、变量
模块	模块规范、跨平台软件包、依赖项、Git 文件源、注册表
协调	阶段顺序、故障处理、状态存储
软件包	所有软件包管理器、跳过行为、试运行
模板	Tera 模板系统、上下文变量、自定义函数
密钥	SOPS/age 后端、1Password、Bitwarden、Vault
系统配置器	Shell、macOS 默认设置、systemd、sysctl、kubelet 等
来源	多来源配置、策略层级、组合、订阅
守护进程	文件监视、协调循环、同步、通知、服务安装
运维器	基于 CRD 的机器管理、设备网关、DaemonSet 节点 Agent
团队配置	由 Crossplane 驱动的团队配置分发
安全性	原子写入、备份、回滚、应用锁定、路径安全
声明式备份	spec.backups[] 快照、钩子顺序、保留、恢复
备份策略	全机群备份计划、优先级表、scheduleOwner
CLI 参考	完整的命令参考，包含标志和示例
安装	所有安装渠道、签名下载验证、自行升级
引导	cfgd init 流程、应用选项、安装脚本
AI 生成	AI 引导的配置生成，两个 MCP 服务（用于编写配置的 mcp-server，以及用于驱动 CLI 的 mcp）
编写技能	cfgd skill 安装程序、支持的 Agent 提供方、如何在生成与技能之间选择
发布	由 CI 执行的发布流程、预发布检查清单、故障恢复
镜像打包	将目录打包成 OCI 镜像卷、签名、固定部署版本
多租户	运维器的命名空间隔离和租户边界
生命周期脚本	run: 解析、钩子阶段、超时、交互式脚本

分发

除了将二进制文件发布到 GitHub Releases（Linux、macOS、Windows 支持 amd64 和 arm64；FreeBSD 支持 amd64）外，每个版本还会发布到：

渠道	制品
Homebrew	brew install tj-smith47/tap/cfgd
crates.io	cargo install cfgd（或使用预构建二进制文件的 cargo binstall cfgd）
AUR	yay -S cfgd（Arch Linux；从源代码构建）
winget	winget install --id TJSmith.cfgd
Scoop	scoop bucket add tj-smith47 https://github.com/tj-smith47/scoop-bucket; scoop install cfgd
Chocolatey	choco install cfgd
Nix	nix profile install github:tj-smith47/nix-pkgs#cfgd
deb / rpm / apk	静态二进制原生软件包，也镜像到 CloudSmith
GHCR	Docker 镜像：cfgd、cfgd-operator、cfgd-csi
Helm	helm install cfgd oci://ghcr.io/tj-smith47/charts/cfgd
Krew	kubectl krew install cfgd（用于节点调试和集群检查的 kubectl 插件）
OLM	适用于由 OLM 管理的集群的 Operator 捆绑包
Crossplane	用于团队配置分发的 function-cfgd 组合函数
MCP Registry	io.github.tj-smith47/cfgd：面向 AI Agent 和编辑器的 cfgd mcp-server 标准输入输出服务

CI/CD 集成：

集成	说明
cfgd Setup	GitHub Action：使用配置仓库中的模块引导运行器
cfgd Plan	GitHub Action：在 PR 上运行 cfgd plan，并将差异作为评论发布
GitLab CI	可引入的 .cfgd-ci.yml 模板，包含 .cfgd-plan 和 .cfgd-apply 作业
Tekton	适用于 Tekton Pipelines 的 cfgd-apply Task

# Example: set up your dev tools on a GitHub Actions runner
- uses: tj-smith47/cfgd/ecosystem/github-actions/setup@master
  with:
    source: [email protected]:you/machine-config.git
    module: dev-tools

# Example: plan config changes on every PR, comment the diff, gate the merge
- uses: tj-smith47/cfgd/ecosystem/github-actions/plan@master
  with:
    config-dir: .
    fail-on-error: true

模块也可以导出为 DevContainer Features，以便注入到开发容器中：

cfgd module export my-tool --as devcontainer

从源代码构建：

git clone https://github.com/tj-smith47/cfgd.git && cd cfgd
cargo build --release

许可证

可选择以下任一许可证：

• Apache License, Version 2.0（LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0）
• MIT license（LICENSE-MIT 或 http://opensource.org/licenses/MIT）

由你选择。

贡献

除非你明确另行说明，否则你根据 Apache-2.0 许可证定义、并有意提交以纳入本项目的任何贡献，均按上述双重许可证授权，且不附加任何条款或条件。