使用 k3d 在本地快速搭建 Kubernetes 开发集群并部署 Homepage【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage本篇技术指南讲解 Homepage 项目仓库中k3d/目录提供的本地 Kubernetes 开发环境方案利用 k3d 在 Docker 中创建轻量级 k3s 集群通过脚本完成一次性部署或借助 Tilt 搭建自动热更新的本地 CI 循环。读完本文你将掌握从零启动集群、构建镜像、使用 Helm 部署 Homepage以及用 Tilt 实现代码变更自动同步的完整实战流程。方案概述为什么选择 k3d k3sHomepage 是一个高度可定制的主页startpage / 应用仪表盘支持 Docker 与多种服务 API 集成。在开发、测试阶段直接在本地跑一个完整的多节点 Kubernetes 集群成本较高而仓库的 k3d/README.md 明确给出了简化方案借助 k3d 在 Docker 中创建 k3s 集群Homepage 随后既可以通过k3d-deploy.sh脚本部署也可以使用 Tilt 搭建本地 CI 循环实现部署随代码变更自动更新。整套配置围绕k3d目录展开共包含 6 个核心文件文件作用k3d.yamlk3d 集群定义节点拓扑、端口映射、内置镜像仓库等k3d-up.sh一键创建集群并导出 kubeconfigk3d-deploy.sh构建镜像、推送到 k3d 内置仓库并用 Helm 部署 Homepagek3d-down.sh删除集群并清理 kubeconfigk3d-helm-values.yamlHomepage Helm Chart 的定制值镜像、配置、Ingress、RBACTiltfileTilt 本地 CI 循环定义镜像构建、热更新、Helm 资源托管原文档特别强调本文所有命令都应从k3d目录下执行。前置工具清单开发环境需要以下工具括号内为可选工具说明Docker容器运行时k3d 依赖它承载集群节点kubectlKubernetes CLI用于与集群交互HelmKubernetes 包管理器用于部署 Homepage Chartk3d“Kubernetes on Docker”负责创建集群k9s可选Kubernetes 集群的命令行视图工具tilt可选本地 CI 循环自动化 Kubernetes 部署direnv可选通过.envrc自动加载kubeconfig省去手动 export其中 kubectl 可直接复用k3d-up.sh生成的kubeconfig文件若安装了 direnv可在k3d目录编写.envrc例如export KUBECONFIG$(pwd)/kubeconfig进入目录时自动加载集群凭据。一次性测试部署三步跑通第一步创建集群./k3d-up.sh脚本内容如下k3d/k3d-up.sh#!/bin/bash k3d cluster create --config k3d.yaml --wait k3d kubeconfig get homepage kubeconfig chmod 600 kubeconfig export KUBECONFIG$(pwd)/kubeconfig echo Waiting for traefik install job to complete (CTRLC is safe if youre impatient) kubectl wait jobs/helm-install-traefik -n kube-system --for conditioncomplete --timeout 90s echo Completed || echo Timed out (but it should still come up eventually)脚本执行了四件事依据 k3d/k3d.yaml 创建名为homepage的集群并等待就绪--wait导出集群的 kubeconfig 到当前目录的kubeconfig文件并收紧权限为 600将KUBECONFIG环境变量指向该文件使后续 kubectl 命令生效等待 k3s 自带的 Traefik Ingress 安装 Job 完成超时 90 秒超时也不影响最终结果。k3d.yaml定义的集群规格k3d/k3d.yamlkind: Simple apiVersion: k3d.io/v1alpha3 name: homepage servers: 1 agents: 2 kubeAPI: hostIP: 0.0.0.0 hostPort: 6443 image: rancher/k3s:v1.25.5-k3s1 volumes: - volume: /tmp:/tmp/k3d-homepage nodeFilters: - all ports: - port: 8080:80 nodeFilters: - loadbalancer - port: 0.0.0.0:8443:443 nodeFilters: - loadbalancer options: k3d: wait: true timeout: 6m0s k3s: extraArgs: - arg: --tls-san127.0.0.1 nodeFilters: - server:* kubeconfig: updateDefaultKubeconfig: false switchCurrentContext: false runtime: serversMemory: 1024MiB agentsMemory: 1024MiB registries: create: name: k3d-registry hostPort: 55000 config: | mirrors: k3d-registry.localhost:55000: endpoint: - http://k3d-registry:5000关键点解读拓扑1 个 server 节点 2 个 agent 节点镜像固定为rancher/k3s:v1.25.5-k3s1端口集群负载均衡器将8080:80、0.0.0.0:8443:443映射到宿主机访问地址为http://homepage.k3d.localhost:8080/kubeconfig不更新默认 kubeconfig 也不切换当前 contextupdateDefaultKubeconfig: false避免污染宿主机 kubectl 配置这正是脚本单独导出 kubeconfig 的原因内置镜像仓库创建名为k3d-registry的本地 registry暴露在宿主机55000端口地址为k3d-registry.localhost:55000镜像 push 到该地址即可被集群节点拉取内存限制server 与 agent 各限制 1024MiB适合本地轻量运行。第二步构建并部署./k3d-deploy.sh脚本内容k3d/k3d-deploy.sh#!/bin/bash DOCKER_BUILDKIT1 docker build -t k3d-registry.localhost:55000/homepage:local .. docker push k3d-registry.localhost:55000/homepage:local HELM_REPO_NAMEjameswynn HELM_REPO_URLhttps://jameswynn.github.io/helm-charts if ! helm repo list | grep $HELM_REPO_URL /dev/null; then helm repo add $HELM_REPO_NAME $HELM_REPO_URL helm repo update fi helm upgrade --install homepage jameswynn/homepage -f k3d-helm-values.yaml执行流程使用 BuildKit 从仓库根目录..即Dockerfile所在处构建镜像打上本地 registry 的 tagk3d-registry.localhost:55000/homepage:localpush 到 k3d 内置 registry使集群节点能够拉取该镜像生产 Dockerfile 为 Dockerfile包含 builder 阶段 pnpm 安装依赖、pnpm run build构建 Next.js 应用以及 runner 阶段将.next/standalone产物复制进node:22-alpine运行时的完整流程检查并添加jameswynnHelm 仓库Homepage 官方维护的 Helm Chart 仓库使用k3d-helm-values.yaml覆盖默认值执行helm upgrade --install。说明Homepage 官方仓库的 Helm Chart 在 docs/installation/k8s.md 中也有对应的手工 Kubernetes Manifest 部署方式ServiceAccount / Secret / ConfigMap / ClusterRole / Deployment / Ingress如果你不想依赖 Helm Chart可参考该文档自行编写 manifest 后用kubectl apply -f应用。第三步访问部署xdg-open http://homepage.k3d.localhost:8080/浏览器将打开homepage.k3d.localhost:8080域名下的 Homepage 实例。该域名能正常解析并路由依赖于两个配置k3d-helm-values.yaml中为 Homepage 设置的环境变量HOMEPAGE_ALLOWED_HOSTShomepage.k3d.localhost:8080允许该 Host 访问应用k3d/k3d-helm-values.yaml同一文件中定义的 Ingress 规则将homepage.k3d.localhost的/路径转发到 Homepage 服务并带有gethomepage.dev/enabled: true等注解便于 Homepage 动态发现自身。深入 Helm 部署配置k3d-helm-values.yaml 是本次部署的核心定制文件值得逐段理解镜像与内置配置image: repository: k3d-registry.localhost:55000/homepage tag: local pullPolicy: Always镜像来自本地 k3d registrypullPolicy: Always保证每次部署都拉取最新构建的镜像。config: bookmarks: - Developer: - Github: - abbr: GH href: https://github.com/ services: - My First Group: - My First Service: href: http://localhost/ description: Homepage is awesome - My Second Group: - My Second Service: href: http://localhost/ description: Homepage is the best - My Third Group: - My Third Service: href: http://localhost/ description: Homepage is widgets: # show the kubernetes widget, with the cluster summary and individual nodes - kubernetes: cluster: show: true cpu: true memory: true showLabel: true label: cluster nodes: show: true cpu: true memory: true showLabel: true - search: provider: duckduckgo target: _blank kubernetes: mode: clusterChart 的config字段直接对应 Homepage 的bookmarks.yaml、services.yaml、widgets.yaml等内容预置了书签、三组示例服务、Kubernetes 集群信息组件展示集群与节点级别的 CPU/内存使用以及 DuckDuckGo 搜索组件。kubernetes.mode: cluster表示以集群模式读取 Kubernetes 资源这也是下文启用 RBAC 的原因。环境变量、RBAC 与 Ingressenv: - name: HOMEPAGE_ALLOWED_HOSTS value: homepage.k3d.localhost:8080 serviceAccount: create: true name: homepage enableRbac: true ingress: main: enabled: true annotations: gethomepage.dev/enabled: true gethomepage.dev/name: Homepage gethomepage.dev/description: Dynamically Detected Homepage gethomepage.dev/group: Dynamic gethomepage.dev/icon: homepage.png hosts: - host: homepage.k3d.localhost paths: - path: / pathType: PrefixHOMEPAGE_ALLOWED_HOSTS限制允许访问的 Host避免 Host 头注入serviceAccount.create: trueenableRbac: true创建带权限的 ServiceAccount使 Homepage 能读取集群信息对应官方 k8s 安装文档中的 ClusterRole/ClusterRoleBinding参见 docs/installation/k8s.mdIngress 注解gethomepage.dev/*是 Homepage 的“动态发现”机制Homepage 会扫描集群中的 Ingress将带这些注解的资源自动聚合到仪表盘中。持久化.next目录的巧思persistence: # this persists the .next directory which greatly improves successive pod startup times in Tilt, # but it breaks normal deployments, so it is disabled by default dotnext: enabled: false type: pvc accessMode: ReadWriteOnce size: 1Gi mountPath: /app/.next这段配置注释说明将 Next.js 构建产物目录.next挂载为 PVC可大幅缩短 Tilt 模式下连续 Pod 启动时间但因为它会破坏常规部署默认关闭enabled: false。Tiltfile 中通过--set persistence.dotnext.enabledtrue显式开启正好印证了这一设计意图。持续部署用 Tilt 搭建本地 CI 循环对于迭代开发脚本式的一次性部署效率偏低。原文档给出的做法是先./k3d-up.sh创建集群再执行tilt up然后按空格键打开 Tilt Web UI——它会非常直观地展示资源状态、日志和事件。最后同样通过xdg-open http://homepage.k3d.localhost:8080/访问。Tilt 的行为由 k3d/Tiltfile 定义docker_build(k3d-registry.localhost:55000/homepage:local, .., dockerfile ../Dockerfile-tilt, build_args{node_env: development}, #entrypointpnpm run nodemon /app/server.js, live_update[ sync(., /app), run(cd /app pnpm install, trigger[.package.json, ./pnpm-lock.yaml]) ] ) load(ext://helm_resource, helm_resource, helm_repo) helm_repo(jameswynn, https://jameswynn.github.io/helm-charts) helm_resource(homepage, jameswynn/homepage, image_deps[ k3d-registry.localhost:55000/homepage:local ], image_keys[ (image.repository, image.tag) ], flags[ -f, k3d-helm-values.yaml, --set, persistence.dotnext.enabledtrue ] )关键机制开发镜像使用 Dockerfile-tilt基于node:18-alpine构建时安装 pnpm/next 并执行pnpm fetchpnpm install -r --offline借助 BuildKit 缓存加速构建 tag 与k3d-deploy.sh完全一致保证镜像可被集群拉取live_update 热更新Tilt 会在检测到源码变更后将变更文件sync到运行中的容器/app当package.json或pnpm-lock.yaml变化时触发pnpm install重装依赖。这是“改代码 → 秒级生效”的核心无需重建镜像Helm 托管通过helm_repo声明 Chart 源helm_resource将jameswynn/homepageChart 作为 Tilt 管理资源并绑定镜像依赖与image.repository/image.tag两个 Helm 值的映射——镜像更新后 Tilt 自动触发 Helm 升级同时注入-f k3d-helm-values.yaml和--set persistence.dotnext.enabledtrue开启.nextPVC加快 Pod 重启。环境清理与常见操作开发结束后运行./k3d-down.sh脚本内容k3d/k3d-down.sh#!/bin/bash k3d cluster delete homepage rm kubeconfig它删除整个homepage集群并清理脚本生成的kubeconfig文件避免残留凭据。其余常用操作查看集群状态kubectl get nodes需先 export KUBECONFIG或配合 direnv 自动加载图形化浏览集群可选安装 k9s 后直接运行k9s查看 Homepage 部署kubectl get pods、kubectl logs deploy/homepage停止 Tilt在 Tilt 终端按CtrlC即可退出部署的资源不会自动删除可再执行k3d-down.sh整体清理。小结k3d/目录为 Homepage 的本地 Kubernetes 开发提供了一条完整链路k3d-up.sh负责拉起 1 server 2 agent 的 k3s 集群并导出独立 kubeconfigk3d-deploy.sh完成镜像构建、push 到内置 registry、Helm 部署三步走Tiltfile则在此基础上叠加了源码热同步与依赖自动安装的本地 CI 循环。从仓库实现看这套方案的每个环节都互相咬合镜像 tag 统一指向k3d-registry.localhost:55000/homepage:localIngress 域名与HOMEPAGE_ALLOWED_HOSTS一致Helm 值文件同时兼顾了 Kubernetes 组件的 RBAC 权限与动态发现注解是理解 Homepage 在 Kubernetes 环境下的部署方式与配置结构的绝佳参考。如果你需要更贴近生产的 Kubernetes 部署如多副本、Ingress 粘性会话、Traefik IngressRoute可以进一步阅读 docs/installation/k8s.md 获取官方 Manifest 示例。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考