一个 CLI 管理你的 Homelab：虚拟机 + 自动化 + 版本控制

一个 CLI 管理你的 Homelab：虚拟机 + 自动化 + 版本控制

基础设施即代码

前言：Homelab 管理的碎片化困境

玩 Homelab 的人都有类似的经历：

一开始是一台树莓派，然后加了一台 NAS，接着是几台二手服务器搭 Kubernetes 集群……不知不觉，你的"家庭实验室"已经变成了一个小型数据中心。

问题来了：每一部分都有自己的管理方式。

• 虚拟机：手写 Vagrantfile，配置散落各处
• 软件安装：Homebrew、apt、dnf、手动编译……每台机器重复一遍
• 自动化脚本：~/scripts 里堆满了各种 .sh 文件，半年后自己都看不懂

有没有一个统一的入口，把这些都管起来？

这就是 homelabctl 的由来。

homelabctl 是什么

homelabctl 是一个 Homelab 基础设施管理 CLI，它整合了：

homelabctl
├── vg     → Vagrant 虚拟机管理
├── vf     → 声明式 VM 配置
└── setup  → 软件安装与环境配置

它不是从零开始造轮子，而是基于我开发的两个底层框架：

三者形成一个完整的生态：

┌─────────────────────────────────────┐
│            homelabctl               │  ← 面向用户的 CLI
├─────────────────────────────────────┤
│    radp-vagrant-framework           │  ← YAML 虚拟机配置
├─────────────────────────────────────┤
│    radp-bash-framework              │  ← CLI 框架基座
└─────────────────────────────────────┘

功能一：声明式虚拟机管理

初始化项目

# 从模板创建 Kubernetes 集群配置
homelabctl vf init k8s-lab --template k8s-cluster
cd k8s-lab

生成的目录结构：

k8s-lab/
└── config/
    ├── vagrant.yaml          # 基础配置
    └── vagrant-k8s.yaml      # 集群定义

YAML 配置示例

# config/vagrant-k8s.yaml
radp:
  extend:
    vagrant:
      config:
        clusters:
          - name: k8s
            common:
              box:
                name: generic/ubuntu2204
              network:
                private-network:
                  enabled: true
                  type: static
            guests:
              - id: master
                provider:
                  mem: 8192
                  cpus: 4
                network:
                  private-network:
                    ip: 192.168.56.10
              - id: worker-1
                provider:
                  mem: 4096
                  cpus: 2
                network:
                  private-network:
                    ip: 192.168.56.11
              - id: worker-2
                provider:
                  mem: 4096
                  cpus: 2
                network:
                  private-network:
                    ip: 192.168.56.12

日常操作

# Vagrant 命令透传
homelabctl vg up                    # 启动所有 VM
homelabctl vg ssh k8s-master        # SSH 到指定 VM
homelabctl vg status                # 查看状态
homelabctl vg halt                  # 停止所有 VM
homelabctl vg destroy               # 销毁所有 VM

# RADP Vagrant Framework 命令
homelabctl vf list                  # 列出所有集群和节点
homelabctl vf info                  # 显示环境信息
homelabctl vf dump-config           # 导出合并后的配置
homelabctl vf validate              # 验证配置文件

功能二：跨平台软件安装

告别重复安装

每次配置新机器都要安装一堆工具？homelabctl 的 setup 模块解决这个问题。

# 查看可安装的软件
homelabctl setup list

# 按分类筛选
homelabctl setup list -c cli-tools
homelabctl setup list -c languages
homelabctl setup list -c devops

# 安装单个软件
homelabctl setup install fzf
homelabctl setup install nodejs -v 20
homelabctl setup install kubectl

Profile：一键配置环境

Profile 是一组预定义的软件包列表，适合快速搭建特定环境。

# 查看可用的 Profile
homelabctl setup profile list

# 查看 Profile 详情
homelabctl setup profile show osx-dev

输出：

Profile: osx-dev
Description: macOS 开发环境

Packages:
  cli-tools: fzf, bat, fd, ripgrep, eza, jq, yq
  editors: neovim
  languages: nodejs, python, go
  shell: zsh, starship, tmux

# 预览安装内容（不实际安装）
homelabctl setup profile apply linux-dev --dry-run

# 应用 Profile
homelabctl setup profile apply linux-dev

# 遇到错误继续安装其他软件
homelabctl setup profile apply linux-dev --continue

内置软件分类

自定义扩展

在 ~/.config/homelabctl/setup/ 目录下添加自定义配置：

# ~/.config/homelabctl/setup/registry.yaml
packages:
  my-tool:
    name: my-tool
    description: 我的自定义工具
    category: cli-tools
    install:
      darwin:
        method: brew
        package: my-tool
      linux:
        method: script
        url: https://example.com/install.sh

# ~/.config/homelabctl/setup/profiles/my-env.yaml
name: my-env
description: 我的个人开发环境
packages:
  - fzf
  - bat
  - neovim
  - my-tool

然后就可以使用：

homelabctl setup install my-tool
homelabctl setup profile apply my-env

安装方式

Homebrew（macOS/Linux，推荐）

# 安装底层框架
brew tap xooooooooox/radp
brew install radp-bash-framework

# 安装 homelabctl
brew install homelabctl

脚本安装

curl -fsSL https://raw.githubusercontent.com/xooooooooox/homelabctl/main/install.sh | bash

RPM 包（Fedora/RHEL/CentOS）

sudo dnf copr enable -y xooooooooox/radp
sudo dnf install -y radp-bash-framework homelabctl

Shell 补全

# Bash
homelabctl completion bash > ~/.local/share/bash-completion/completions/homelabctl

# Zsh
homelabctl completion zsh > ~/.zfunc/_homelabctl

补全支持动态提示软件包名、Profile 名、分类等。

实战场景

场景一：快速搭建 K8s 测试环境

# 1. 创建项目
homelabctl vf init k8s-test --template k8s-cluster
cd k8s-test

# 2. 启动集群
homelabctl vg up

# 3. 在 master 节点安装工具
homelabctl vg ssh k8s-master
homelabctl setup install kubectl
homelabctl setup install helm

# 4. 测试完成后销毁
homelabctl vg destroy -f

场景二：统一配置多台开发机

# 在每台机器上执行
homelabctl setup profile apply linux-dev

无论是 Ubuntu、Fedora 还是 CentOS，同一条命令自动适配。

场景三：管理多个 Homelab 项目

# 项目 A：数据库集群
cd ~/homelab/db-cluster
homelabctl vg status

# 项目 B：Web 服务
cd ~/homelab/web-stack
homelabctl vg status

# 或者设置环境变量全局管理
export RADP_VAGRANT_CONFIG_DIR=~/homelab/k8s/config
homelabctl vg status

与其他工具的对比

总结

homelabctl 解决的核心问题是 Homelab 管理的碎片化：

• ✅ 统一入口：一个 CLI 管理 VM、软件、配置
• ✅ 声明式配置：YAML 替代手写脚本
• ✅ 可复制性：Profile 让环境配置可重复
• ✅ 可扩展性：支持自定义软件包和 Profile

它不是要替代所有工具，而是提供一个 统一的管理层，让 Homelab 运维更加顺畅。

项目地址：

🔗 homelabctl: github.com/xooooooooox/homelabctl

🔗 radp-vagrant-framework: github.com/xooooooooox/radp-vagrant-framework

🔗 radp-bash-framework: github.com/xooooooooox/radp-bash-framework

三个项目均为 MIT 开源协议，欢迎 Star、Fork、提 Issue！

你的 Homelab 是怎么管理的？欢迎在评论区交流。