基于GitOps的家庭Kubernetes集群：从k3s到全栈自动化实践

1. 项目概述：一个声明式的家庭Kubernetes集群

如果你和我一样，对在家庭环境中运行一个稳定、可观测且完全自动化的Kubernetes集群有执念，那么这篇分享可能会让你找到共鸣。这个项目，我称之为“家庭实验室集群”（HomeLab Cluster），它不仅仅是在几台树莓派上跑个k3s那么简单。它的核心思想是GitOps：将整个集群的期望状态，从操作系统配置、Kubernetes组件到所有应用服务，全部用代码（YAML、Ansible Playbook等）定义，并存储在Git仓库中。任何对生产环境的变更，都始于一次代码提交，然后由自动化工具（如Flux）安全地同步到集群。这彻底改变了家庭运维的体验，从手动敲命令的“运维工匠”，变成了声明式管理的“架构园丁”。

我的集群运行在基于Rock Pi 4B单板计算机的节点上，通过PoE供电，全部采用1TB NVMe存储。整个体系由k3s提供Kubernetes运行时，由Flux担任GitOps引擎，Renovate负责依赖更新，OpenClaw作为运维助手，再辅以一套完整的可观测性栈（VictoriaMetrics, Grafana, Alertmanager）。这一切的目标是构建一个“不可变基础设施”式的家庭云平台：可靠、可追溯、且几乎无需手动干预。

2. 核心架构与工具选型解析

为什么选择这套技术栈？每个选择背后都是对家庭环境特定约束（如有限资源、断电风险、无人值守）的考量，以及对运维效率的极致追求。

2.1 基石：k3s 而非完整 K8s 或 Talos

最初，我曾考虑使用Talos Linux——一个为Kubernetes而生的极简、不可变操作系统。它对Rock Pi 4B有官方支持，理念先进。但实际测试中，遇到了与NVMe存储相关的驱动问题，导致系统不稳定。这在家用场景下是致命的，我需要的是“睡得着觉”的稳定性。

于是退而求其次，选择了更成熟的方案：标准的Linux发行版（如Ubuntu Server或Debian） + k3s。k3s是Rancher（现为SUSE）推出的轻量级Kubernetes发行版，相比原生K8s，它：

• 资源消耗极低：单个节点内存占用可控制在512MB以内，非常适合资源受限的单板计算机。
• 简化部署：一个二进制文件包含所有K8s核心组件，简化了依赖管理和故障排查。
• 对边缘和IoT优化：内置了SQLite作为可选存储后端（但我仍使用etcd以保证高可用特性），更适合可能面临网络分区的环境。

实操心得：在ARM架构的单板计算机上，务必从k3s的GitHub Release页面下载对应架构（arm64）的二进制文件，或使用其提供的安装脚本。通过系统服务（systemd）管理k3s，比用docker run方式更便于集成到后续的自动化配置流程中。

2.2 大脑：Flux 实现 GitOps 工作流

GitOps的核心是“声明式”和“持续同步”。Flux正是这一理念的践行者。它部署在集群内，持续监视指定的Git仓库（或OCI仓库）。当仓库中的YAML清单文件发生变化时，Flux会自动将这些变更应用到集群中。

在我的架构里，./kubernetes/目录下的所有K8s资源定义（Deployments, Services, ConfigMaps等）都由Flux管理。它的工作流程如下：

1. 监视（Watch）：Flux监控Git仓库的主分支。
2. 拉取（Pull）：检测到新提交后，拉取变更。
3. 构建（Build）：可选步骤，如果需要，可以使用Kustomize进行资源定制。
4. 验证（Validate）：可选步骤，使用准入控制器（如Kyverno）进行策略检查。
5. 应用（Apply）：计算差异，并将变更安全地应用到集群。

注意事项：务必为Flux使用的Git仓库配置只读的Deploy Key（SSH密钥），而非个人账户的访问令牌。这遵循了最小权限原则。此外，在初始化Flux引导（flux bootstrap）时，使用--private-key-file参数指定密钥，可以避免密钥被存入集群Secret的风险。

2.3 自动化生态：Renovate 与 OpenClaw

GitOps解决了“如何部署”的问题，但“何时更新”和“如何维护”同样重要。

• Renovate：这是一个依赖更新机器人。它扫描代码仓库中的依赖文件（如helm-release.yaml中的chart版本、容器镜像标签），自动创建Pull Request来更新它们。对于家庭集群，我配置它：

  • 每周扫描一次。
  • 对次要版本和补丁版本自动合并。
  • 对主要版本更新则创建PR并等待手动审核，避免破坏性变更。
  • 这确保了集群内运行的应用和安全补丁能持续更新，而无需我手动跟踪每个项目的Release。

• OpenClaw：这是一个相对新颖但理念很棒的工具。你可以把它理解为一个“基于Git的运维助手”。当集群出现问题时（如Pod崩溃、节点NotReady），传统的做法是kubectl describe、查日志。OpenClaw则允许你定义“诊断剧本”（同样是代码），在触发条件时自动执行一系列检查，并将结果报告或修复建议提交到Git仓库。这为“无人值守”的家庭集群提供了初步的自愈和诊断能力。

2.4 网络与安全：Cilium 与 cert-manager

• Cilium：我选择它作为CNI（容器网络接口），而非常见的Flannel或Calico。原因在于其基于eBPF的内核级性能和高可观测性。对于家庭集群，其内置的网络策略可视化和Hubble网络流量监控功能尤为宝贵，可以清晰看到服务间的通信关系，排查网络问题事半功倍。
• cert-manager：家庭服务也需要HTTPS。cert-manager自动从Let‘s Encrypt申请和续签免费的SSL证书，并注入到Ingress资源中。我配合CloudFlare的DNS API，使用DNS-01挑战方式验证域名所有权，这样无需将家庭网络暴露在公网也能签发证书。

2.5 可观测性栈：VictoriaMetrics 全家桶

监控是家庭集群的“眼睛”。我没有使用经典的Prometheus + Thanos方案，而是选择了VictoriaMetrics。

• 单二进制，资源友好：VictoriaMetrics将所有组件（存储、查询）融合在一个二进制中，内存和CPU消耗远低于同等数据量的Prometheus，非常适合资源紧张的家庭环境。
• 高压缩比：存储效率极高，1TB的NVMe盘可以存储非常长时间的历史监控数据。
• 与PromQL兼容：完全兼容Prometheus的查询语言，Grafana数据源无缝切换。
• Alertmanager：负责接收VictoriaMetrics的告警，并通过Pushover这个轻量级推送服务，将告警实时发送到我的手机。Pushover成本极低，且比自建邮件或短信网关稳定得多。

3. 硬件配置与底层系统准备

声明式管理要从底层开始。我的目标是：从裸机到一个完整的K8s节点，全部通过代码自动化完成。

3.1 硬件清单与考量

踩坑实录：最初尝试用USB 3.0移动硬盘盒连接NVMe，但频繁出现IO错误和掉盘。原因是许多硬盘盒主控芯片在持续读写下不稳定。最终解决方案是使用JMS583芯片的转接板，并确保其有良好的散热，问题得以解决。

3.2 操作系统部署与自动化配置

我使用Ansible作为系统配置管理工具。所有节点的初始设置，包括操作系统安装后的所有配置，都通过Ansible Playbook完成。

1. 操作系统安装：为每块NVMe硬盘刷入Ubuntu Server 22.04 LTS（ARM64）的镜像。这个过程目前仍需手动完成，但可以借助Raspberry Pi Imager等工具批量写卡。
2. 初始网络配置：首次启动后，通过路由器DHCP或手动设置，为每台设备分配一个固定的IP地址，并记录其MAC地址。
3. Ansible清单准备：在Ansible控制机（可以是你日常用的电脑）上，创建inventory.ini文件，定义所有节点。

   [cluster_nodes] rockpi-01 ansible_host=192.168.1.101 ansible_user=ubuntu rockpi-02 ansible_host=192.168.1.102 ansible_user=ubuntu rockpi-03 ansible_host=192.168.1.103 ansible_user=ubuntu [k3s_master] rockpi-01 [k3s_workers] rockpi-02 rockpi-03

4. 编写基础Playbook：创建一个如base_setup.yaml的Playbook，执行以下任务：
   • 更新系统：apt update && apt upgrade -y
   • 安装必备工具：vim, curl, wget, git, htop
   • 配置SSH密钥登录：禁用密码登录，提高安全性。
   • 优化系统参数：调整vm.swappiness（降低至10）、fs.inotify.max_user_watches（增加）等内核参数，更适合容器负载。
   • 配置防火墙：安装ufw，仅开放SSH（22）和Kubernetes API（6443）等必要端口。
   • 配置NTP：确保所有节点时间同步，这对K8s集群至关重要。
   • 挂载NVMe：正确格式化并挂载NVMe硬盘到/var/lib/rancher/k3s（k3s数据目录）和/var/lib/longhorn（如果使用Longhorn存储）等路径。

核心技巧：使用Ansible的become和serial参数。对于需要重启服务的任务（如修改内核参数后生效），设置serial: 1可以避免所有节点同时重启导致Ansible连接中断。对于k3s安装这类关键任务，使用ansible-playbook --limit参数先在一台机器上验证。

3.3 k3s集群的自动化安装

这是Ansible Playbook的核心部分。我编写了一个deploy_k3s.yaml的Playbook。

Master节点安装：

- name: Install k3s on master node hosts: k3s_master become: yes tasks: - name: Download and install k3s shell: | curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable traefik --disable servicelb --cluster-init --tls-san {{ ansible_host }}" sh - args: creates: /usr/local/bin/k3s # 幂等性检查，如果已安装则跳过 - name: Retrieve k3s node-token shell: cat /var/lib/rancher/k3s/server/node-token register: k3s_token no_log: true # 防止token在输出中泄露 - name: Set fact for token set_fact: k3s_master_token: "{{ k3s_token.stdout }}"

• --disable traefik --disable servicelb：我选择后续安装更灵活的Ingress Controller（如nginx-ingress）和MetalLB。
• --cluster-init：使用嵌入式etcd启动一个高可用的控制平面。
• --tls-san：添加主节点的IP或域名到TLS证书中，方便后续通过该地址访问API。

Worker节点加入：

- name: Install k3s on worker nodes hosts: k3s_workers become: yes vars: k3s_master_url: "https://{{ hostvars['rockpi-01'].ansible_host }}:6443" tasks: - name: Join worker to cluster shell: | curl -sfL https://get.k3s.io | K3S_URL={{ k3s_master_url }} K3S_TOKEN={{ hostvars['rockpi-01'].k3s_master_token }} sh - args: creates: /usr/local/bin/k3s

执行这个Playbook后，一个基础的k3s集群就搭建完成了。通过kubectl get nodes验证所有节点状态应为Ready。

4. GitOps实践：用Flux管理整个集群

有了基础的K8s集群，接下来就是注入“灵魂”——Flux。

4.1 Flux引导与仓库结构

在本地开发机上，我已经准备好了Git仓库。其结构如下：

hl-cluster/ ├── .github/ │ └── workflows/ # GitHub Actions 自动化工作流 ├── infrastructure/ │ ├── ansible/ # Ansible Playbooks 和 Roles │ └── terraform/ # （可选）云资源定义，如DNS记录 ├── kubernetes/ # Flux监视的核心目录 │ ├── flux-system/ # Flux自身的配置（命名空间、源、Kustomization） │ ├── base/ # 跨环境的通用资源（如命名空间定义） │ ├── core/ # 核心基础设施组件（Cilium, cert-manager, 监控栈） │ ├── apps/ # 业务应用（Nextcloud, Home Assistant, *arr套件等） │ └── clusters/ │ └── production/ # 针对本集群的特定配置和补丁（Kustomize） ├── .flux.yaml # （旧版）或 flux-system 目录下的配置文件 └── README.md

执行引导命令，让Flux自行在集群中安装并配置自己：

flux bootstrap github \ --owner=tolkonepiu \ --repository=hl-cluster \ --branch=main \ --path=./clusters/production \ --personal

这个命令会：

1. 在集群中创建flux-system命名空间。
2. 部署Flux控制器。
3. 在Git仓库中生成一个./clusters/production/flux-system/目录，包含Flux自身的Kustomization配置。
4. 配置Flux监视本仓库的./clusters/production路径。

从此以后，你对./kubernetes/下任何资源的修改，提交并推送到GitHub后，Flux都会在几分钟内将其同步到集群。

4.2 分层部署与Kustomize

我采用分层部署模型来管理复杂度：

• base层：最底层的原始资源定义。例如，一个nginxDeployment的基本YAML。
• core/apps层：通过Kustomize引用base资源，并添加通用配置。例如，为所有应用添加统一的标签、资源限制。
• clusters/production层：环境特定配置。这是Flux监视的入口点。它通过kustomization.yaml文件，按顺序引用../../base、../../core、../../apps中的资源，并可以应用最后的补丁（patches）。例如，为生产环境覆盖特定的镜像标签、配置值或副本数。

这种结构的好处是清晰分离了“什么”（应用定义）和“在哪里/如何”（环境配置），便于管理多环境（如未来增加一个测试集群）。

4.3 配置示例：部署cert-manager

以部署cert-manager为例，展示Flux如何工作。

1. 在./kubernetes/core/cert-manager/目录下创建：
   • namespace.yaml：定义cert-manager命名空间。
   • helmrelease.yaml：定义HelmRelease资源，告诉Flux通过Helm来部署cert-manager。

   # ./kubernetes/core/cert-manager/helmrelease.yaml apiVersion: helm.toolkit.fluxcd.io/v2beta1 kind: HelmRelease metadata: name: cert-manager namespace: cert-manager spec: interval: 1h # 每隔1小时检查一次Chart更新 chart: spec: chart: cert-manager version: v1.13.x # Renovate会自动更新这个版本范围 sourceRef: kind: HelmRepository name: jetstack namespace: flux-system interval: 1h values: # 自定义values installCRDs: true prometheus: enabled: false # 在家庭集群中可关闭，用VictoriaMetrics抓取 resources: requests: memory: "64Mi" cpu: "50m"

2. 在./kubernetes/core/cert-manager/kustomization.yaml中声明这些资源：

   apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization namespace: cert-manager resources: - namespace.yaml - helmrelease.yaml

3. 在顶层的./clusters/production/kustomization.yaml中，将这个组件引入：

   apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization resources: - ../../flux-system - ../../base - ../../core/cert-manager - ../../core/cilium - ../../core/monitoring - ../../apps/home-automation # ... 其他组件

提交并推送这些更改后，Flux会自动在集群中创建HelmRelease资源，进而拉取并安装cert-manager的Helm chart。

5. 持续监控与告警实战

一个没有监控的集群就像在黑暗中开车。我的监控体系围绕VictoriaMetrics构建。

5.1 VictoriaMetrics集群部署

VictoriaMetrics单机版已能满足家庭集群需求。我同样使用Flux通过Helm进行部署：

# ./kubernetes/core/monitoring/victoriametrics/helmrelease.yaml apiVersion: helm.toolkit.fluxcd.io/v2beta1 kind: HelmRelease metadata: name: victoria-metrics-single namespace: monitoring spec: interval: 1h chart: spec: chart: victoria-metrics-single version: 0.x sourceRef: kind: HelmRepository name: victoriametrics namespace: flux-system values: server: persistentVolume: enabled: true size: 200Gi # 根据NVMe容量分配，存储监控数据 resources: requests: memory: "512Mi" cpu: "250m"

部署后，VictoriaMetrics的抓取目标（ServiceMonitor）会自动发现集群中需要监控的服务（如k3s组件、Node Exporter、各应用Pod）。

5.2 Grafana配置与仪表盘

Grafana作为可视化平台，其数据源和仪表盘配置也实现了代码化。

1. 数据源：通过ConfigMap定义VictoriaMetrics数据源的连接信息。
2. 仪表盘：将常用的仪表盘JSON文件（如Kubernetes集群监控、Node Exporter全指标）也存入ConfigMap，并通过sidecar容器自动加载到Grafana中。这样，即使Grafana Pod重建，仪表盘配置也不会丢失。
3. 告警规则：在VictoriaMetrics（或Prometheus）的配置中，定义告警规则（Alerting Rules）。例如：

   groups: - name: cluster-health rules: - alert: NodeDown expr: up{job="node-exporter"} == 0 for: 2m labels: severity: critical annotations: summary: "节点 {{ $labels.instance }} 宕机" description: "节点 {{ $labels.instance }} 已超过2分钟无法访问。"

5.3 Alertmanager与Pushover集成

告警产生后，由Alertmanager处理并路由。我配置Alertmanager将告警发送到Pushover。

# ./kubernetes/core/monitoring/alertmanager/config.yaml (部分) receivers: - name: 'pushover-notifications' pushover_configs: - user_key: <你的Pushover用户密钥> token: <你的Pushover应用令牌> title: '{{ template "pushover.default.title" . }}' message: '{{ template "pushover.default.message" . }}' priority: '{{ if eq .Status "firing" }}2{{ else }}0{{ end }}' # firing时紧急通知 retry: 30s expire: 1h

关键点：在Git中存储敏感信息（如API密钥）是危险的。绝对不要将明文密钥提交到仓库。正确的做法是使用Kubernetes的SealedSecrets（由Bitnami Labs开发）或SOPS（由Mozilla开发）等工具加密Secret，将加密后的文件存入Git。Flux在同步时，会在集群内使用对应的私钥进行解密。这是我实践GitOps时最重要的安全准则之一。

6. 日常运维、问题排查与优化心得

即使实现了高度自动化，日常的观察和偶尔的干预仍是必要的。

6.1 常用运维命令与工具

• 查看Flux同步状态：flux get all -A或flux logs --tail=50
• 手动触发同步：flux reconcile source git flux-system（当你想立即应用提交的更改时）。
• 排查应用部署问题：kubectl describe helmrelease <name> -n <namespace>查看Flux部署Helm时的详细事件和错误信息。
• 监控集群资源：kubectl top nodes和kubectl top pods -A快速查看资源使用情况。

6.2 常见问题与解决方案速查表

6.3 性能与稳定性优化点

1. k3s参数调优：在/etc/systemd/system/k3s.service的ExecStart命令中增加参数。
   • --kubelet-arg=eviction-hard=imagefs.available<5%,nodefs.available<5%：设置更激进的磁盘驱逐阈值，防止磁盘写满。
   • --kubelet-arg=max-pods=50：限制单节点Pod数量，避免资源竞争。
2. Longhorn存储：如果你在集群内运行有状态应用（如数据库），可以考虑部署Longhorn提供分布式块存储。它将每个节点的NVMe空间聚合为一个存储池，提供复制和快照功能。注意：Longhorn对IO性能有要求，在USB连接的NVMe上性能损耗需测试评估。
3. 资源限制与请求：为每一个Deployment/Pod都设置合理的resources.requests和resources.limits。这是保证集群调度公平和稳定的关键。可以通过VPA（Vertical Pod Autoscaler）或Goldilocks等工具辅助分析。
4. 定期备份：虽然Git仓库备份了配置，但应用数据（如数据库）需要额外备份。使用Velero可以备份整个命名空间或特定资源到S3兼容存储（如Backblaze B2或自建MinIO）。

构建和维护这样一个家庭GitOps集群，是一个持续学习和打磨的过程。它带来的回报是巨大的：你获得了一个高度自动化、可观测、且完全受控的私人云环境。最大的体会是，将运维工作转化为代码，不仅减少了重复劳动，更将配置变成了可版本控制、可审查、可回滚的资产。当半夜收到Pushover告警，你不再需要慌慌张张地SSH登录，而是可以冷静地查看Grafana面板，或者直接去Git仓库查看最近是否有相关变更，这种掌控感是传统运维方式无法比拟的。