我的Homelab架构全景：双K3s集群的IaC与GitOps实践

为什么写这篇文章#

从 2024 年用 Docker Compose 起步，到现在运行着两个 K3s 集群、16 个服务、完整的 GitOps 流水线——这个 Homelab 项目已经迭代了很多轮。每次新增功能都会写一篇专题博客，但一直缺少一篇把所有东西串起来的全景文章。

这篇文章就是那张地图。它不会深入每个组件的部署细节（那些在各自的博客里），而是回答一个问题：这些东西是怎么组合在一起工作的？

整体架构#

整个 Homelab 分为五层：

┌─────────────────────────────────────────────────────────────────┐
│  Layer 5: GitOps                                                │
│  ArgoCD — 自动同步 Git → 集群，3 分钟轮询                         │
├─────────────────────────────────────────────────────────────────┤
│  Layer 4: External Access & Security                            │
│  Cloudflare Tunnel + DNS + WAF ← Terraform                      │
│  ZITADEL SSO + oauth2-proxy ForwardAuth                         │
├─────────────────────────────────────────────────────────────────┤
│  Layer 3: Applications                                          │
│  Helm Charts + Raw K8s Manifests                                │
│  16 个服务分布在两个集群                                          │
├─────────────────────────────────────────────────────────────────┤
│  Layer 2: Kubernetes                                            │
│  K3s 单节点集群 × 2（Ansible 安装）                                │
│  Tailscale 跨集群 Pod/Service 网络互通                             │
├─────────────────────────────────────────────────────────────────┤
│  Layer 1: Infrastructure                                        │
│  Proxmox VE (本地) + Oracle Cloud (远端) ← Terraform              │
└─────────────────────────────────────────────────────────────────┘

Layer 1: 基础设施#

Proxmox 虚拟机（本地集群）#

Homelab 的物理基础是一台旧 Laptop，运行 Proxmox VE 虚拟化平台。通过 Terraform 在上面创建一台 Ubuntu 虚拟机：

proxmox/
├── terraform/    # IaC: VM 规格、网络、磁盘
├── ansible/      # 下载 cloud image、生成 VM 模板

• 节点 IP: 10.10.10.10（LAN）/ 100.107.254.112（Tailscale）
• Proxmox 主机: 192.168.50.3
• 存储: NFS 服务器 192.168.50.106:/export，通过 nfs-client StorageClass 提供 PV

Oracle Cloud（远端集群）#

利用 Oracle Cloud 的永久免费 ARM 实例，通过 Terraform 创建一台 VM：

cloud/oracle/
├── terraform/    # OCI VM 资源
├── ansible/      # 节点初始化
├── manifests/    # 工作负载 YAML

• 节点 IP: 10.0.0.26（VCN）/ 100.107.166.37（Tailscale）

两个节点通过 Tailscale 互联，形成一个跨地域的虚拟网络。

Layer 2: Kubernetes#

两个集群都使用 K3s（轻量级 K8s 发行版），通过 Ansible 自动安装：

cd k8s/ansible && just setup-k8s       # homelab 集群
cd cloud/oracle/ansible && just setup   # oracle-k3s 集群

跨集群网络：Tailscale Subnet Routing#

这是架构中最关键的网络设计。两个集群通过 Tailscale 的子网路由功能实现 Pod/Service 网络互通：

homelab 广播:     10.42.0.0/16 (Pod)    10.43.0.0/16 (Service)
oracle-k3s 广播:  10.52.0.0/16 (Pod)    10.53.0.0/16 (Service)

效果：oracle-k3s 上的 Pod 可以直接访问 homelab 的 ClusterIP（如 10.43.158.192 — ArgoCD），反之亦然。延迟约 80ms，对于监控和异步通信完全够用。

这使得很多有趣的架构成为可能：

• Uptime Kuma（oracle-k3s）通过 ClusterIP 直接监控 homelab 的所有服务
• 信息管道中的 Redpanda Connect（oracle-k3s）直接推送通知到 Gotify（homelab）
• 集中式 Vault（homelab）为两个集群的 ExternalSecret 提供密钥

Layer 3: 应用服务#

服务全景#

16 个服务分布在两个集群中：

集群分工原则#

• homelab：运行基础设施服务（Vault、ArgoCD、Grafana）和需要 NFS 持久化存储的应用（Calibre-Web、Kopia）
• oracle-k3s：运行无状态或轻量有状态的面向用户服务（工具类、RSS、Homepage），利用 Oracle Cloud 免费的公网带宽

可观测性：LGTM Stack#

Homelab 集群运行完整的 LGTM 可观测性栈：

• Prometheus — 指标采集（homelab 本地 scrape）
• Loki — 日志聚合
• Tempo — 分布式追踪
• Grafana — 统一仪表盘

多集群监控的关键设计：所有指标都携带 cluster 标签。

• homelab：Prometheus scrapeClasses 为所有本地指标添加 cluster=homelab
• oracle-k3s：不部署 Prometheus，而是用一个 OTel Collector DaemonSet 同时采集日志和指标，通过 prometheusremotewrite 推送到 homelab 的 Prometheus，自动附加 cluster=oracle-k3s

homelab:                                oracle-k3s:
┌────────────┐                         ┌──────────────────┐
│ Prometheus │◄─── scrape ───          │  OTel Collector  │
│ (本地指标)  │                         │ (DaemonSet)      │
│            │◄── remote write ────────│  logs → Loki     │
│            │                         │  metrics → Prom  │
├────────────┤                         └──────────────────┘
│   Loki     │◄── OTLP HTTP ──────────
│   Tempo    │
│  Grafana   │
└────────────┘

密钥管理：Vault + ESO#

HashiCorp Vault 是所有密钥的唯一真实来源。External Secrets Operator (ESO) 自动将 Vault 中的 Secret 同步到 K8s Secret：

Vault (homelab)                K8s Cluster
┌─────────────┐               ┌────────────────┐
│ secret/      │               │ ExternalSecret  │
│   homelab/   │◄──── ESO ────│   spec:         │
│     grafana  │    同步       │     key: ...    │
│     cloudflare│               │                 │
│   oracle-k3s/│               │ → K8s Secret    │
│     ...      │               └────────────────┘
└─────────────┘

两个集群的密钥都存在同一个 Vault 实例中（secret/homelab/* 和 secret/oracle-k3s/*），oracle-k3s 的 ESO 通过 Tailscale 跨集群访问 Vault。

Layer 4: 外部访问与安全#

Cloudflare Tunnel + DNS#

所有外部流量都通过 Cloudflare Tunnel 进入，不暴露任何公网端口：

Internet → Cloudflare DNS (CNAME) → Cloudflare Tunnel → Traefik → Service

两个集群各有一个独立的 Tunnel，DNS 和 Tunnel 配置全部由 Terraform 管理：

cloudflare/terraform/            # homelab tunnel:  argocd/auth/book/grafana/vault/...
cloud/oracle/cloudflare/         # oracle  tunnel:  home/tool/pdf/rss/status/keep/...

唯一的例外是 Kopia：gRPC 双向流在 Cloudflare Tunnel 中会 524 超时，所以通过 NodePort (31515) 直接暴露。

Cloudflare WAF#

Zone 级 WAF 规则保护 meirong.dev 下所有子域名（两个集群共享）：

全部在 cloudflare/terraform/waf.tf 中用 Terraform 管理。

SSO 单点登录#

ZITADEL（自托管 OIDC 身份提供者）+ oauth2-proxy（认证代理）实现全站 SSO：

浏览器 → Traefik → ForwardAuth 检查 → oauth2-proxy
                                          │
                                   cookie 有效？
                                   ├── 是 → 放行到后端服务
                                   └── 否 → 302 重定向到 ZITADEL 登录
                                              │
                                        登录成功 → 设置 .meirong.dev cookie
                                              → 7 天免登录

• 受保护服务：book / grafana / vault / argocd / backup / notify / home / tool / pdf / squoosh / keep
• 公开服务：status.meirong.dev（状态页）、rss.meirong.dev（Miniflux 自带登录）

Layer 5: GitOps#

ArgoCD#

ArgoCD 运行在 homelab 集群，每 3 分钟轮询 Git 仓库，自动同步变更到集群：

git push → ArgoCD 检测到变更 → 自动 apply YAML → 服务更新

ArgoCD 管理的应用（auto-sync + selfHeal）：

不由 ArgoCD 管理的组件：Vault（需手动 init/unseal）、Prometheus/Loki/Tempo（Helm release）、PostgreSQL（有状态）、NFS Provisioner（基础设施层）。

新增服务的标准流程#

1. 创建 manifests/<service>.yaml               — 定义 K8s 资源
2. 修改 manifests/gateway.yaml                 — 添加 HTTPRoute
3. 修改 argocd/applications/personal-services.yaml — include 列表
4. 修改 cloudflare/terraform/terraform.tfvars    — 添加子域名
5. git push                                     — ArgoCD 3分钟内自动部署
6. cd cloudflare/terraform && just apply         — 创建 DNS
7. 更新 Uptime Kuma provisioner                  — 添加健康检查

ArgoCD Image Updater#

对于需要自动跟踪镜像更新的服务（如 IT-Tools），使用 ArgoCD Image Updater 的 CRD 模式：检测到新镜像后自动写回 Kustomize overlay，触发 ArgoCD 同步。

信息管道#

一条跨集群的自动化信息流：

Miniflux (保存文章)
    ↓ Webhook
Redpanda Connect (oracle-k3s)
    ↓ KaraKeep API
KaraKeep (书签存档)
    ↓ 打标签 "telegram"
Redpanda Connect (轮询)
    ↓ Gotify API (跨集群 via Tailscale)
Gotify (homelab)
    ↓ Telegram Plugin
Telegram 频道

健康监控#

Uptime Kuma 运行在 oracle-k3s，监控两个集群的全部服务（14 个 monitor）。

• oracle-k3s 本地服务：通过 K8s DNS 直接访问（如 homepage.homepage.svc:3000）
• homelab 服务：通过 Tailscale 跨集群访问 ClusterIP（如 10.43.70.241 — Grafana）
• 公开状态页：status.meirong.dev（不受 SSO 保护）

所有 monitor 定义在 provisioner.yaml 的 Python 脚本中，以代码形式管理。

工具链#

项目结构#

homelab/
├── proxmox/              # Layer 1: Proxmox VM IaC
│   ├── terraform/
│   └── ansible/
├── cloud/oracle/          # Layer 1: Oracle Cloud VM IaC
│   ├── terraform/
│   ├── ansible/
│   ├── cloudflare/        # Oracle Tunnel DNS
│   └── manifests/         # oracle-k3s 工作负载
├── k8s/
│   ├── ansible/           # Layer 2: K3s 安装
│   └── helm/
│       ├── values/        # Layer 3: Helm values
│       └── manifests/     # Layer 3: K8s YAML
├── argocd/                # Layer 5: ArgoCD 配置
│   ├── install/
│   ├── projects/
│   └── applications/
├── cloudflare/terraform/  # Layer 4: DNS + Tunnel + WAF
├── tailscale/terraform/   # Layer 2: 跨集群网络
└── docs/                  # 文档、runbooks、plan 记录

演进历程#

回顾这个 Homelab 的发展路径：

接下来#

几个计划中的方向：

• Alertmanager：告警规则 → Gotify → Telegram，实现问题自动通知
• Kopia 自动化：CronJob 定时备份到异地存储
• Cert-Manager：自动证书管理（Let’s Encrypt + Cloudflare DNS-01）
• Vault Dynamic Secrets：PostgreSQL 动态凭证，自动轮换

相关文章#

这篇是架构全景，以下是各组件的深入专题：

• 将 homelab 从 docker 迁移到 kubernetes
• 使用 Terraform 为 Proxmox 创建虚拟机
• 使用 Terraform 和 Ansible 创建 K8s 集群
• 使用 Helm 添加 observability 服务
• 让 Tailscale 可以访问内网 IP 地址
• 在 K3s 上部署 ZITADEL 实现 SSO 单点登录
• 在 K3s 上构建信息管道：Miniflux → KaraKeep → Gotify → Telegram
• 用 Cloudflare WAF 为双 K3s 集群添加安全防护