s34nj0hn/lab

# Homelab 基础设施 4 节点 K3s 集群部署于裸金属。这是一个真实的平台 — 通过 Flux 实现 GitOps，使用 SOPS/age 加密密钥，Authentik 提供 SSO，Longhorn 实现分布式存储，Renovate 自动化依赖管理。我在此运行实际的工作负载。 一些值得说明的决策：我选择了 MetalLB 而非 Cilium。Cilium 是当前最流行的选择，我明白这一点。但我需要 mDNS — 我希望在不经过 DNS 服务器的情况下直接访问本地负载均衡器。MetalLB 解决了这个问题。相比 ArgoCD，我更倾向 Flux，因为我不希望在协调循环中引入 UI。Renovate 会自动合并补丁版本更新，这意味着我无需每次新版本发布时手动更新容器版本。 我花了十年时间观察企业环境在平台建成后才匆忙添加安全措施。这就是本实验实验室的出发点。我想要理解从设计之初就融入安全性的样子；有时，真正了解它的唯一方式就是亲自构建它。 ## 架构 | 层级 | 实现方式 | |------|----------| | **编排** | K3s v1.33，部署在 4 台 Lenovo M715Q（AMD Ryzen 5 PRO 2400GE，16GB 内存，64GB 总存储） | | **操作系统** | Ubuntu 25.10 Server | | **GitOps** | Flux v2.7，配合 Kustomize 覆盖层、HelmRelease 管理、基础/预发布环境推广 | | **密钥管理** | SOPS + age 加密集成到 Flux 解密流程 | | **身份认证** | Authentik 部署，依赖 PostgreSQL/Redis 后端（SSO 正向认证集成进行中） | | **网络** | 通过 EdgeRouter X 实现 VLAN 分段，Flannel CNI，MetalLB 二层负载均衡，Traefik 入口 | | **存储** | Longhorn 分布式块存储，NFS PV（QNAP NAS），local-path-provisioner | | **可观测性** | kube-prometheus-stack — Prometheus（7 天保留期）、Grafana、Alertmanager | | **安全** | 每个命名空间默认拒绝网络策略，显式允许列表；入口作用域限定到特定命名空间与 VLAN CIDR；出口策略默认阻止 RFC 1918 私有地址 | | **依赖管理** | Renovate，对容器级补丁更新启用自动合并 | | **配置管理** | Ansible（角色、剧本、清单）用于节点供应 | | **外部访问** | Cloudflare Tunnels（无需端口转发），限速访问 | ### 集群节点 | 节点 | 角色 | IP | |------|------|----| | messier | 控制平面 | 10.10.10.103 | | cygnus | 工作节点 | 10.10.10.102 | | phoenix | 工作节点 | 10.10.10.105 | | gaia | 工作节点 | 10.10.10.107 | 支持基础设施：树莓派 5（DNS、PXE 启动）、QNAP NAS（NFS/SMB 持久化存储）。 ## 仓库结构 ``` ├── GitOps/ │ ├── clusters/staging/ # Flux bootstrap and Kustomization entry points │ ├── apps/ # Application workloads (base + staging overlays) │ │ └── base/ # Jellyfin, media-arr (Sonarr/Radarr/Sabnzbd), │ │ Audiobookshelf, Calibre-Web, Linkding, n8n, │ │ Homarr, Renovate, ikigai (personal project) │ ├── infrastructure/ # Platform components (base + staging overlays) │ │ └── base/ # Authentik, MetalLB, Traefik, Longhorn, │ │ Docker registry, external-mDNS │ └── monitoring/ # kube-prometheus-stack (base + staging overlays) ├── ansible/ # Node provisioning: roles, playbooks, inventory └── docs/ # KCS-methodology documentation ├── architecture.md # Full architecture deep-dive ├── FluxCD.md # GitOps operations and troubleshooting ├── Service-Access-Patterns.md ├── network/ # Topology and VLAN design ├── operations/ ├── troubleshooting/ ├── setup-guides/ └── reference/ ``` ## 安全态势 每个命名空间都强制执行默认拒绝的网络策略，并设有明确的允许列表。入口作用域限定到特定源命名空间与 VLAN CIDR 块。出口策略限制仅允许访问 DNS、NFS 以及明确授权的外部目标 — 默认情况下阻止私有 RFC 1918 地址段。 密钥永远不会以明文形式出现在 Git 中。SOPS 使用 age 密钥加密 `data` 与 `stringData` 字段，Flux 在协调期间执行解密。`.gitignore` 排除凭据、密钥、令牌、金库文件以及云提供商配置，仅保留 SOPS 加密的密钥和文档引用。 当前服务使用内置身份验证。服务要么仅限内部访问，要么通过限速的 Cloudflare Tunnels 暴露，不进行直接的端口转发。将 Authentik 接入作为 Traefik 的前向认证中间件是下一步的安全计划。 ## 文档 我采用知识中心服务（KCS）方法论 — 与在 F5 面向客户文档时相同的框架。真实的故障排查过程被即时记录。模块化文章包含实际的错误信息、可用的配置，旨在解决未来的问题。 [`/docs`](./docs) 目录包含架构概述、FluxCD 操作指南、服务访问模式、网络拓扑与 VLAN 设计文档、设置指南、故障排查文章以及参考材料。 ## 工作流程 我正在构建一个 AI 原生的工作流 — 使用 Claude Code 加速迭代并探索架构，但每一步都进行验证。如果我在系统故障时无法进行排查，或无法向团队成员解释其原理，该功能就不会发布。 ## 当前重点 - 所有服务的 Authentik SSO 前向认证集成 - Kubernetes 安全基础（CIS 基准、Pod 安全标准） - 日志聚合（Loki） - 可转化为生产环境的基础设施即代码模式

标签：age, Alertmanager, Authentik, CNI, EdgeRouter, Flannel, Flux, GitOps, Grafana, Helm, Homelab, Ingress, JSONLines, K3s, kube-prometheus-stack, Kustomize, L2, Longhorn, mDNS, MetalLB, NetworkPolicy, NFS, Observability, PV, PVC, Renovate, Secrets, SOPS, SSO, Traefik, VLAN, 从零构建, 企业级, 依赖管理, 分布式存储, 加密, 单点登录, 存储, 学习平台, 安全, 安全左移, 开源, 架构设计, 漏洞扫描器, 系统提示词, 网络, 网络安全, 网络调试, 自动化, 自动合并, 裸金属, 负载均衡, 超时处理, 隐私保护, 集群, 零信任, 默认拒绝