mmrajput/kubernetes-platform-foundation

# Kubernetes 平台工程 - 基础 [](https://kubernetes.io/) [](https://www.proxmox.com/) [](https://ubuntu.com/) [](https://argoproj.github.io/cd/) [](https://prometheus.io/) [](https://grafana.com/) [](https://www.cloudflare.com/) [](LICENSE) ## 架构  ### 图例 - 灰色实线 用户请求流量（Cloudflare → ingress → 工作负载） - 灰色虚线 备份与灾难恢复流程（Velero → MinIO → rclone → OneDrive） - 蓝色虚线 GitOps 协调（GitHub → ArgoCD → 集群） - 紫色虚线 Webhook 证书配置与 SSO 认证 - 红色虚线 密钥注入（Vault → ESO → 工作负载） - 绿色虚线 指标采集与日志传输（Promtail → Loki） - 绿色实线 仪表板查询流（Grafana → Prometheus / Loki） 上图展示了完整的平台架构，该架构部署在一个使用 Calico CNI 的三节点 kubeadm v1.31 集群上。平台被组织成六个功能关注组，所有配置均通过 GitOps 声明式管理。 ### 外部层 - 平台工程师仅通过 Git 与集群交互——所有变更都是提交，绝不直接使用 `kubectl apply` - 代码更改被推送到 GitHub 作为唯一事实来源——ArgoCD 从此处持续协调集群状态 - 镜像推广工作流通过 GitHub Actions 手动触发，由在集群内运行的 ARC 自托管运行器执行 - 所有外部访问通过 **Cloudflare Tunnel** 路由，在家庭网络上提供安全的 ingress 而无需任何开放的入站端口 - TLS 在 Cloudflare 边缘终止——家庭网络上没有暴露的入站端口 ### 网络 · GitOps 管理 - **ingress-nginx** 使用基于主机的 Ingress 规则将所有外部流量路由到内部服务 - **cert-manager** 管理操作员准入 Webhook（CNPG, ESO）的 TLS 证书——外部流量的 TLS 在 Cloudflare 边缘终止 - **NetworkPolicies** 在每个命名空间强制执行默认拒绝策略——所有服务间通信都需显式声明，防止平台组件和工作负载之间的横向移动 ### CI/CD · GitOps 管理 - **ARC (Actions Runner Controller)** 以基于 Webhook 的缩容至零模式，在集群内运行自托管的 GitHub Actions 运行器 - **ArgoCD** 以轮询模式（每 120 秒）持续将集群状态与 Git 进行协调 - CI 流水线从 Docker Hub 拉取上游镜像，使用 Trivy 扫描，通过 crane 镜像到 ghcr.io，并将更新的镜像标签提交到 Git values 文件——不构建自定义镜像 - ArgoCD 检测到 Git 中的标签变更，并自动同步集群 ### 工作负载 · GitOps 管理 - **Nextcloud** 是主要的平台工作负载，为自主文件共享而部署 - **CloudNativePG** 管理 PostgreSQL 数据库，存储 Nextcloud 的元数据、用户账户和应用状态 - **Longhorn** 为用户文件存储提供复制持久卷（RF=2） - **Redis** 处理会话缓存和文件锁定，以防止并发访问时的写入冲突 - **Keycloak** 通过 Nextcloud 的 `user_oidc` 应用为其提供 SSO，在 Nextcloud 管理 UI 中进行配置 - 选择 Nextcloud 作为参考工作负载是因为它同时使用了每个平台层——存储、数据库、身份、密钥、可观察性、备份和网络 ### 数据 · 存储 · 备份 · GitOps 管理 - **Longhorn v1.7.2**（RF=2）是默认的 StorageClass，在工作节点间提供复制的块存储 - **CloudNativePG (CNPG)** 管理 PostgreSQL 集群，通过 Barman 将 WAL 持续归档到 MinIO 以实现时间点恢复 - **MinIO**（S3 兼容）是中央对象存储，支持 Loki 日志存储、Velero 备份快照和 CNPG WAL 归档 - **Velero** 通过 Kopia 备份 Kubernetes 资源和持久卷，将快照存储在 MinIO 中 - **rclone** 作为夜间 CronJob 运行，将两个 MinIO 存储桶同步到 OneDrive 以获得异地灾难恢复副本——完成 3-2-1 备份态势 ### 安全 · 身份 · GitOps 管理 - **HashiCorp Vault**（KV v2）是密钥后端，在组件命名空间路径下存储所有平台密钥 - **External Secrets Operator (ESO)** 将 Vault 中的密钥同步到工作负载、数据库和平台服务中，作为原生 Kubernetes Secret 对象——没有应用直接从 Vault 读取 - **Keycloak 26** 为平台提供集中的 OIDC 身份认证，通过 homelab realm 在 ArgoCD 和 Grafana 之间集成 SSO - **Falco** 通过 eBPF 系统调用检查（`modern_ebpf` 驱动）提供运行时威胁检测，通过 Falcosidekick 将警报转发到 Loki——与 Prometheus 指标一起显示在公共 Grafana 仪表板中 ### 可观察性 · GitOps 管理 - **Prometheus & Alertmanager** 从所有平台组件抓取指标并管理警报规则 - **Grafana** 在统一的仪表板上可视化来自 Prometheus 的指标和来自 Loki 的日志数据 - **Loki** 聚合来自整个集群的日志，由 MinIO 支持持久的日志块存储 - **Promtail** 作为 DaemonSet 在每个节点上运行，收集并传输容器和系统日志到 Loki ### 数据流摘要 ## | 流程 | 路径 | |------|------| | 外部流量 | Cloudflare → cloudflared → nginx-ingress → 工作负载 | | 密钥 | Vault → ESO → Kubernetes Secrets → 工作负载 · 数据库 · 平台服务 | | 用户文件 | 工作负载 → Longhorn PVC | | 数据库 | CNPG (PostgreSQL) → WAL 归档 → MinIO | | 备份 | Velero (Kopia) → MinIO · CNPG Barman → MinIO | | 异地灾备 | MinIO → rclone → OneDrive | | 指标 | 所有组件 → Prometheus → Grafana | | 日志 | 所有节点 → Promtail → Loki (MinIO 支持) → Grafana | ## 当前状态 | 阶段 | 描述 | 状态 | |-------|-------------|--------| | 阶段 1 | 架构设计与规划 | ✅ 完成 | | 阶段 2 | 虚拟化基础（Proxmox VE） | ✅ 完成 | | 阶段 3 | 虚拟机供应（cloud-init + Ansible） | ✅ 完成 | | 阶段 4 | Kubernetes 集群（kubeadm + Calico） | ✅ 完成 | | 阶段 5 | GitOps 与平台服务（ArgoCD） | ✅ 完成 | | 阶段 6 | 可观察性技术栈（Prometheus + Loki + Grafana） | ✅ 完成 | | 阶段 7 | 安全加固（cert-manager + NetworkPolicies + Vault + ESO + Falco） | ✅ 完成 | | 阶段 8 | 存储与备份（Longhorn + MinIO + Velero） | ✅ 完成 | | 阶段 9 | 身份与有状态工作负载（Keycloak + CloudNativePG + Nextcloud） | ✅ 完成 | | 阶段 10 | CI/CD 流水线（ARC + GitHub Actions） | ✅ 完成 | ## 平台技术栈 | 层 | 技术 | |-------|------------| | 虚拟化平台 | Proxmox VE 8.x | | 操作系统 | Ubuntu 24.04 LTS · cloud-init | | Kubernetes | v1.31 · kubeadm · 1 个控制平面 · 2 个工作节点 | | CNI | Calico | | GitOps | ArgoCD (App-of-Apps) | | Ingress | nginx-ingress · Cloudflare Tunnel | | 可观察性 | Prometheus · Grafana · Loki · Promtail | | 安全 | cert-manager · Vault · External Secrets Operator · Falco | | 身份 | Keycloak · CloudNativePG | | 存储 | Longhorn · MinIO · Velero | | CI/CD | GitHub Actions ARC · ghcr.io | | 工作负载 | Nextcloud · Homepage | ## 仓库结构 ``` bootstrap/namespaces/ # One-time namespace setup (kubectl apply, not ArgoCD) platform/ argocd/ # Root app + AppSets per category networking/ # cert-manager, nginx-ingress, NetworkPolicies security/ # Vault, Keycloak, External Secrets data/ # CNPG clusters, Longhorn, MinIO, Velero, rclone observability/ # Prometheus, Grafana, Loki, Promtail ci-cd/ # ARC systems + runners workloads/ # Helm values per app (staging / production) infra/ # Ansible + Proxmox scripts docs/ # ADRs, guides, runbooks, reference scripts/ # Dev shell, diagrams, helpers ``` ## 文档 | 文档 | 描述 | |----------|-------------| | [复现指南](docs/guides/homelab-reproduction-guide.md) | 从头复现此家庭实验室的端到端指南 | | [平台清单](docs/reference/platform-inventory.md) | 服务端点、ArgoCD 应用清单 | | [工作负载接入](docs/reference/workload-onboarding.md) | 添加工作负载的分步指南 | | [数据层](docs/reference/data-layer.md) | CNPG、Vault、ESO 密钥清单 | | [网络拓扑](docs/architecture/network-topology.md) | 网络架构、Calico、Cloudflare Tunnel、NetworkPolicy | | [架构决策记录](docs/adr/) | ADR 001–016，包含上下文和原理 | | [故障排除](docs/guides/troubleshooting.md) | 跨所有组件的平台级故障排除 | | [运维手册](docs/runbooks/) | 运维程序（备份、灾难恢复、Vault、证书） | ## 联系方式 - **LinkedIn:** [linkedin.com/in/mahmood-rajput](https://www.linkedin.com/in/mahmood-rajput/) - **Email:** mahmoodrajput.cloud@gmail.com *最后更新：2026年4月 · 德国阿尔特多夫 71155*

标签：API集成, DLL 劫持, GitOps, Kubernetes平台, Kubernetes集群, OISF, 云基础设施, 人工智能, 仪表板, 单点登录, 可观测性, 声明式配置, 备份与恢复, 大语言模型, 子域名突变, 安全, 容器编排, 操作系统, 数据库管理, 日志管理, 特权提升, 生产工程, 用户模式Hook绕过, 监控, 自动化部署, 自定义请求头, 虚拟化, 超时处理