Karakeep 在 Kubernetes 上的部署实战：Kustomize 清单、环境变量与 TLS 配置

Karakeep 在 Kubernetes 上的部署实战Kustomize 清单、环境变量与 TLS 配置【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder本文是一份以仓库kubernetes/目录为核心、面向 Kubernetes 用户的完整部署指南。Karakeep原 Hoarder是一个可自托管的收藏一切应用书签、笔记与图片并具备基于 AI 的自动标签与全文搜索能力。读完本文你将掌握如何基于仓库自带的 Kustomize 清单完成环境变量与密钥填充、OpenAI/Ollama 推理配置、LoadBalancer 与 Ingress 访问、TLS 证书挂载以及版本升级的完整操作流程。部署架构总览在动手之前先了解这套 Kubernetes 清单所编排的三个核心组件全部集中在karakeep命名空间组件镜像作用关联清单webghcr.io/karakeep-app/karakeep主应用Next.js 服务暴露 3000 端口web-deployment.yaml、web-service.yamlchromeghcr.io/karakeep-app/karakeep-chrome:release无头浏览器服务供网页截图/预读使用暴露 9222 端口chrome-deployment.yaml、chrome-service.yamlmeilisearchgetmeili/meilisearch:v1.41.0全文搜索引擎暴露 7700 端口meilisearch-deployment.yaml、meilisearch-service.yaml从 web-deployment.yaml 的容器环境变量可以看出三个组件如何互联MEILI_ADDRhttp://meilisearch:7700web 通过集群内 DNS 访问 MeilisearchBROWSER_WEB_URLhttp://chrome:9222web 通过集群内 DNS 访问无头浏览器DATA_DIR/data数据目录挂载到名为data-pvc的持久卷上。此外Meilisearch 容器通过MEILI_NO_ANALYTICStrue关闭了遥测并将其数据目录/meili_data挂载到独立的meilisearch-pvc。两个持久卷声明>git clone 仓库地址 cp -r kubernetes /path/to/your/karakeep-k8skubernetes/目录下除清单文件外还包含两个模板文件与一个 MakefileMakefile封装了make build/make deploy/make clean三个常用目标.env_sample环境变量模板.secrets_sample密钥模板。第 2 步填充环境变量与密钥环境变量.env复制模板并修改为你自己的配置cp .env_sample .env.env_sample默认内容如下# Put your configuration options here NEXTAUTH_URLhttp://localhost:3000 KARAKEEP_VERSIONrelease两个关键变量NEXTAUTH_URL必须改为你的服务器实际访问地址如https://karakeep.example.com否则登录态回调会失败KARAKEEP_VERSIONrelease表示始终拉取最新稳定版。若希望控制升级节奏建议固定为具体版本号如KARAKEEP_VERSION0.10.0。版本号会通过 kustomization.yaml 中的replacements段自动注入到 web Deployment 的镜像 tag 中见下文版本注入机制。其余可用的配置项如OPENAI_API_KEY、OLLAMA_BASE_URL等可追加到.env中完整参数含义可参考仓库内的配置文档 docs/docs/03-configuration/01-environment-variables.md。密钥.secrets复制模板并替换为自行生成的随机串cp .secrets_sample .secrets.secrets_sample默认内容如下# Use openssl rand -base64 36 to generate the random strings NEXTAUTH_SECRETgenerated_secret MEILI_MASTER_KEYgenerated_secret NEXT_PUBLIC_SECRETmy-super-duper-secret-string⚠️务必修改这些随机字符串。推荐用openssl rand -base64 36生成高强度随机值避免使用模板中的示例值。Kustomize 如何消费这两个文件kubernetes/kustomization.yaml 通过 Kustomize 的两个生成器把本地文件转化为集群资源secretGenerator读取.secrets生成名为karakeep-secrets的 SecretconfigMapGenerator读取.env生成名为karakeep-configuration的 ConfigMap。web 与 meilisearch 两个 Deployment 均通过envFrom同时引用这两个资源见 web-deployment.yaml 与 meilisearch-deployment.yaml因此修改.env/.secrets后需要重新执行make deploy才会生效。第 3 步配置 AI 推理自动标签方式一OpenAI推荐自动标签功能默认依赖 OpenAI按以下步骤配置可选但强烈建议参照 OpenAI 官方帮助获取 API Key在.env文件中加入OPENAI_API_KEYkey关于使用 OpenAI 的费用说明可阅读 docs/docs/06-administration/03-openai.md。方式二实验性Ollama 本地推理如果希望完全本地化推理可以用 Ollama 替代 OpenAI。注意标签质量取决于所选模型质量且本地模型推理是较新特性未经 OpenAI 那样充分的实战验证可能遇到一定比例的推理失败请谨慎使用。配置步骤确保 Ollama 服务已运行在.env中设置OLLAMA_BASE_URL指向 Ollama API 地址设置INFERENCE_TEXT_MODEL指定文本推理模型例如mistral设置INFERENCE_IMAGE_MODEL指定图片推理模型例如llava确保已用ollama pull拉取上述模型。完成配置后web 容器会通过环境变量感知推理后端无需改动任何清单文件。第 4 步部署服务在kubernetes/目录下直接运行make deploy该命令等价于依次执行见 kubernetes/Makefilekustomize build . _manifest.yaml把全部清单、ConfigMap、Secret 与镜像版本替换渲染成一个合并清单kubectl apply -f _manifest.yaml一次性下发到集群。也可以不依赖 Makefile手动执行kustomize build . | kubectl apply -f -部署完成后可通过以下命令观察资源状态kubectl -n karakeep get pods kubectl -n karakeep get services第 5 步访问服务方式一LoadBalancer IP默认默认情况下web 服务以LoadBalancer类型暴露见 web-service.yaml。运行kubectl get services找到 web 服务的负载均衡 IP然后访问http://loadbalancer-ip:3000即可看到 Sign In 登录页。提示根据你的环境也可以改用 Ingress 或其他方式暴露服务。方式二Ingress如果需要用域名访问可基于 ingress_sample.yaml 修改host为你的 DNS 名称。该示例将karakeep.example.com的根路径转发到web服务的 3000 端口pathType: Prefix。同时应将 web 服务改为ClusterIP类型使其仅能通过 Ingress 访问。若已部署过服务可直接 patchkubectl -n karakeep patch service web -p {spec:{type:ClusterIP}}随后应用 Ingress 资源即可通过你的域名访问。方式三为服务配置 HTTPS如需安全访问可让 Ingress 使用预置的 TLS 证书。前提是你已拥有证书文件.crt与.key。首先在karakeep命名空间中创建 TLS Secretsecret 名称可自定义但必须与 Ingress 定义中的secretName一致kubectl --namespace karakeep create secret tls karakeep-web-tls --cert/path/to/crt --key/path/to/key然后在 Ingress 的 spec 中追加 TLS 配置spec: tls: - hosts: - karakeep.example.com secretName: karakeep-web-tls⚠️注意tls段中的hosts必须与 HTTP 路由规则中的host完全一致否则证书校验会失败。第 6 步可选配置快速收藏扩展部署完成后可前往快速收藏quick sharing文档页 docs/docs/04-using-karakeep/quick-sharing.md安装移动端 App 与浏览器扩展从而在浏览网页时一键收藏内容。升级 Karakeep修改版本号并重新部署编辑kustomization.yaml或.env中的KARAKEEP_VERSION变量.env中的值会经replacements注入镜像 tag然后运行make clean deploymake clean会删除上次生成的_manifest.yaml确保重新构建时不残留旧内容。镜像版本注入机制KARAKEEP_VERSION之所以能控制镜像 tag依赖 kubernetes/kustomization.yaml 中的replacements段它从karakeep-configurationConfigMap 的KARAKEEP_VERSION字段取值以:为分隔符、index: 1定位替换 web Deployment 容器镜像的 tag 部分。因此你无需手工编辑web-deployment.yaml 中的image: ghcr.io/karakeep-app/karakeep字段。关于release标签的说明如果你选择release作为镜像标签由于 web Deployment 设置了imagePullPolicy: Always见 web-deployment.yaml每次 Pod 重建都会强制从镜像仓库拉取最新镜像。此时可以通过删除 web Pod 触发升级kubectl -n karakeep delete pod -l appkarakeep-web常见问题与排查思路修改配置后未生效.env与.secrets由 Kustomize 生成器消费修改后必须重新执行make deploy或kustomize build . | kubectl apply -f -重建 ConfigMap/Secret并滚动重启相关 Pod。登录跳转异常确认NEXTAUTH_URL与你的实际访问地址含协议与端口一致。持久化数据位置应用数据与 Meilisearch 索引分别存放在data-pvc与meilisearch-pvc两块 PVC 上删除 Pod 不影响数据如需扩容调整 PVC 的storage字段并重新应用。镜像拉取失败三个镜像均托管在公共镜像仓库请确认集群节点具备外网拉取能力使用releasetag 时尤其要注意拉取策略。小结通过仓库kubernetes/目录自带的 Kustomize 清单Karakeep 的整套服务web、无头浏览器、Meilisearch可以在一个命名空间内一键部署并支持通过环境变量/密钥注入、镜像版本替换、LoadBalancer/Ingress/TLS 三种访问方式以及make clean deploy的升级流程。这套部署方式完全贴合仓库默认配置是自托管用户快速上手的推荐路径。【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考