KarakeepHoarderKubernetes 部署指南基于 Kustomize 的清单化安装、配置与升级【免费下载链接】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/hoarderKarakeep原 Hoarder是一款可自托管的收藏一切应用支持链接、笔记与图片的保存并提供基于 AI 的自动标签与全文搜索能力。本文以官方 Kubernetes 安装文档docs/versioned_docs/version-v0.30.0/02-installation/04-kubernetes.md为主线结合仓库内完整的 Kustomize 清单kubernetes 目录系统讲解在 Kubernetes 集群上部署、暴露、加密访问与滚动升级 Karakeep 的完整实操路径。读完本文你将掌握清单获取、环境变量与密钥填充、AI 推理配置OpenAI/Ollama、LoadBalancer 与 Ingress 两种访问方式、HTTPS/TLS 配置以及基于镜像 Tag 的平滑升级策略。部署前置条件在动手之前请确保你的环境满足以下三项要求一个可用的Kubernetes 集群本指南使用kubectl apply与kustomize build完成资源下发理论上适用于任意发行版集群kubectl与集群 API Server 通信的 CLI 工具用于应用清单、查询 Service 与 Pod 状态kustomize清单模板化工具。仓库中的Makefile实际调用kustomize build .将目录内的多份 YAML 渲染为单一清单文件后再交由kubectl apply见 kubernetes/Makefile。较新版本的 kubectl1.14内置了kubectl kustomize子命令若你未单独安装 kustomize 二进制可将 Makefile 中的构建命令替换为kubectl kustomize build .。本部署方案默认使用命名空间karakeep所有资源Deployment、Service、PVC、Secret、ConfigMap均由 kubernetes/kustomization.yaml 统一归入该命名空间避免与集群内其他应用冲突。第一步获取部署清单Karakeep 的 Kubernetes 部署清单以kubernetes目录形式内嵌在仓库根目录中。你可以直接克隆仓库然后将整个kubernetes目录复制到你选择的任意工作目录git clone https://gitcode.com/GitHub_Trending/ho/hoarder.git cp -r kubernetes /your/preferred/directory/复制后你将在该目录下看到以下核心文件文件作用kustomization.yamlKustomize 入口声明 namespace、Secret/ConfigMap 生成器、资源列表与镜像 Tag 替换规则.env_sample环境变量模板非敏感配置.secrets_sample敏感密钥模板namespace.yamlkarakeep命名空间定义web-deployment.yaml主应用Next.js 全栈服务Deploymentweb-service.yaml主应用 Service默认类型为LoadBalancer端口 3000chrome-deployment.yaml无头 Chrome网页抓取Deploymentchrome-service.yaml无头 Chrome Service类型为ClusterIP端口 9222meilisearch-deployment.yamlMeilisearch 全文搜索引擎 Deploymentmeilisearch-pvc.yaml /># Put your configuration options here NEXTAUTH_URLhttp://localhost:3000 KARAKEEP_VERSIONrelease两个变量的含义与修改建议NEXTAUTH_URL必须改为你的服务器对外地址如https://karakeep.example.com用于 NextAuth 会话回调与 OAuth 流程填错会导致登录/回调失败KARAKEEP_VERSION镜像 Tag。设置为release表示始终拉取最新稳定版若你希望控制升级节奏应固定为具体版本号例如KARAKEEP_VERSION0.10.0。更多可用配置项请参考完整的环境变量文档docs/docs/03-configuration/01-environment-variables.md。例如需要启用 AI 自动打标时直接在.env中追加OPENAI_API_KEYkey即可详见下文第三步。配置密钥将.secrets_sample复制为.secrets并将示例随机串替换为你自己生成的值cp .secrets_sample .secrets模板内容如下kubernetes/.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三个密钥的用途NEXTAUTH_SECRETNextAuth 会话签名密钥用于加密 JWT 会话MEILI_MASTER_KEYMeilisearch 的主密钥保护搜索引擎 APINEXT_PUBLIC_SECRET应用内部使用的公共密钥。⚠️务必修改这些随机字符串。官方推荐使用openssl rand -base64 36生成高强度的随机串。若所有实例共享同一份默认密钥存在严重的安全隐患。这些文件会被 Kustomize 分别注入到所有相关 Pod 的envFrom中主应用通过secretRef: karakeep-secrets与configMapRef: karakeep-configuration加载见 kubernetes/web-deployment.yamlMeilisearch 同样加载两者以便读取MEILI_MASTER_KEY等配置见 kubernetes/meilisearch-deployment.yaml。第三步配置 AI 推理自动打标Karakeep 的 AI 自动打标功能需要配置推理后端。官方文档将其分为两种情况。使用 OpenAI推荐前往 OpenAI 获取 API Key在.env文件中添加OPENAI_API_KEYkey关于使用 OpenAI 的成本详情可参考成本说明文档docs/docs/06-administration/03-openai.md若希望使用其他 AI 提供商如本地推理可参阅不同 AI 提供商的配置指南docs/docs/03-configuration/02-different-ai-providers.md。使用 Ollama 做本地推理实验性展开查看 Ollama 本地推理配置实验性功能注意打标质量取决于你选择的模型质量。本地模型推理是近期新增的能力成熟度不如 OpenAI使用过程中可能遇到较多推理失败请谨慎启用并做好预期。确保 Ollama 服务已运行设置OLLAMA_BASE_URL环境变量为 Ollama API 地址设置INFERENCE_TEXT_MODEL为文本推理所用模型例如mistral设置INFERENCE_IMAGE_MODEL为图片推理所用模型例如llava确保你已通过ollama pull拉取所需模型。这些变量与 OpenAI 一样直接写入.env文件由 ConfigMap 注入到 web 容器。从实现上看这些推理相关变量会在推理 Worker 启动时读取用于构建文本/图片打标请求相关推理逻辑位于 packages/shared/inference.ts其测试用例见 packages/shared/inference.test.ts因此配置后无需改动任何清单文件。第四步部署服务完成.env与.secrets的配置后一键部署make deploymake deploy的完整行为链如下见 kubernetes/Makefilekustomize build .将整个目录渲染为单一清单文件_manifest.yaml该文件同时包含 namespace、Deployment、Service、PVC、ConfigMap、Secret 等所有资源且已被写入.gitignorekubectl apply -f _manifest.yaml将渲染结果应用到集群make clean在构建前删除旧的_manifest.yaml避免叠加过期内容。若你想先审查最终清单而不直接部署可执行make build生成_manifest.yaml后自行检查。部署完成后用以下命令确认各组件 Pod 状态kubectl -n karakeep get pods kubectl -n karakeep get all第五步访问服务方式一通过 LoadBalancer IP默认情况下web Service 类型为LoadBalancer见 kubernetes/web-service.yaml云厂商或支持 LoadBalancer 的裸机环境如 MetalLB会为它分配一个外部 IP。执行kubectl get services找到web服务对应的 LoadBalancer 地址然后在浏览器访问http://loadbalancer-ip:3000你应该会看到 Karakeep 的 Sign In登录页面。提示根据你的集群环境你可能更希望使用 Ingress 暴露服务或有其他访问方式如 Port-Forward、NodePort。方式二通过 Ingress如果你想使用 Ingress可以基于仓库中的示例清单kubernetes/ingress_sample.yaml进行定制将host改为你自己的 DNS 名称。示例清单将/路径pathType: Prefix路由到web服务的 3000 端口。使用 Ingress 时应将 web Service 改为ClusterIP类型使其仅在集群内部可达、由 Ingress 统一对外kubectl -n karakeep patch service web -p {spec:{type:ClusterIP}}补丁完成后应用你的 Ingress 清单即可通过所选 URL 访问服务kubectl apply -f ingress_sample.yaml注意Ingress 需要在集群中已部署 Ingress Controller如 NGINX Ingress Controller、Traefik才能正常工作。配置 HTTPS 访问为 Karakeep 配置安全的 HTTPS 访问需要预先准备 TLS 证书文件.crt与.key。步骤如下创建 TLS Secret在部署完 Karakeep 清单后在karakeep命名空间中创建 TLS Secret。Secret 名称可自定义但必须与 Ingress 定义中的secretName保持一致kubectl --namespace karakeep create secret tls karakeep-web-tls --cert/path/to/crt --key/path/to/key修改 Ingress 的 spec在 Ingress 清单中启用 TLS示例如下spec: tls: - hosts: - karakeep.example.com secretName: karakeep-web-tls⚠️ 注意TLS spec 中的hosts必须与 HTTP spec 中的host保持一致否则证书匹配会失败。若你更习惯自动化证书管理也可以参考仓库中 Kustomize 的replacements机制见 kubernetes/kustomization.yaml自行扩展将 Ingress 的 host 与 TLS 配置参数化例如用环境变量统一管理域名与 Secret 名称。可选安装快速分享扩展部署完成后你可以安装官方提供的浏览器扩展与移动端 App实现更快速的收藏体验。具体安装步骤参见快速分享指南docs/docs/04-using-karakeep/quick-sharing.md。浏览器扩展与移动端通过 API 与 Karakeep 服务交互可帮助你更快地囤积内容。更新与升级Karakeep 的升级策略围绕KARAKEEP_VERSION变量展开其底层机制值得重点说明。固定版本升级编辑 kubernetes/kustomization.yaml 中的KARAKEEP_VERSION变量或直接修改.env中的同名变量二者在构建时等效然后执行make clean deploymake clean会先删除旧的_manifest.yaml确保重新渲染的清单包含新版本号。镜像 Tag 替换机制从源码结构看KARAKEEP_VERSION是通过 Kustomize 的replacements特性写入 web Deployment 镜像 Tag 的见 kubernetes/kustomization.yamlreplacements: - source: fieldPath: data.KARAKEEP_VERSION kind: ConfigMap name: karakeep-configuration version: v1 targets: - fieldPaths: - spec.template.spec.containers.0.image options: delimiter: : index: 1 select: group: apps kind: Deployment name: web version: v1即Kustomize 从karakeep-configurationConfigMap 中读取KARAKEEP_VERSION的值以:为分隔符替换 web Deployment 中容器镜像的 Tag 部分ghcr.io/karakeep-app/karakeep:tag。这也是为什么只需改一个变量就能完成镜像版本切换。使用releaseTag 的滚动拉取如果你选择release作为镜像 Tag即始终跟随最新稳定版由于 kubernetes/web-deployment.yaml 中设置了imagePullPolicy: AlwaysPod 每次重建时都会从镜像仓库拉取最新镜像。此时只需删除 web Pod 即可触发重新拉取kubectl -n karakeep delete pod web-pod-nameDeployment 会自动重建 Pod并拉取最新的release镜像从而完成升级无需修改任何清单。提示官方推荐的升级路径仍是固定具体版本号 make clean deploy以精确控制升级时机并规避意外破坏性变更。小结本文基于官方 Kubernetes 安装文档完整梳理了 Karakeep 的 Kustomize 化部署全流程从获取 kubernetes 目录清单、配置.env环境变量与.secrets密钥、接入 OpenAI/Ollama 实现 AI 自动打标到make deploy一键下发再到 LoadBalancer / Ingress / TLS 三种访问方式最后讲解了KARAKEEP_VERSION驱动的镜像 Tag 替换与升级策略。整体架构上web、无头 Chrome抓取与 Meilisearch搜索三者通过集群内 Service DNS 协作kubernetes/web-deployment.yaml而 Kustomize 的configMapGenerator/secretGenerator/replacements三件套让配置、密钥与镜像版本的管理高度集中且可审计。无论你是想在云上快速体验还是在裸机集群上部署生产实例这套清单都能作为可靠的起点。【免费下载链接】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），仅供参考 Karakeep（Hoarder）Kubernetes 部署指南：基于 Kustomize 的清单化安装、配置与升级
KarakeepHoarderKubernetes 部署指南基于 Kustomize 的清单化安装、配置与升级【免费下载链接】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/hoarderKarakeep原 Hoarder是一款可自托管的收藏一切应用支持链接、笔记与图片的保存并提供基于 AI 的自动标签与全文搜索能力。本文以官方 Kubernetes 安装文档docs/versioned_docs/version-v0.30.0/02-installation/04-kubernetes.md为主线结合仓库内完整的 Kustomize 清单kubernetes 目录系统讲解在 Kubernetes 集群上部署、暴露、加密访问与滚动升级 Karakeep 的完整实操路径。读完本文你将掌握清单获取、环境变量与密钥填充、AI 推理配置OpenAI/Ollama、LoadBalancer 与 Ingress 两种访问方式、HTTPS/TLS 配置以及基于镜像 Tag 的平滑升级策略。部署前置条件在动手之前请确保你的环境满足以下三项要求一个可用的Kubernetes 集群本指南使用kubectl apply与kustomize build完成资源下发理论上适用于任意发行版集群kubectl与集群 API Server 通信的 CLI 工具用于应用清单、查询 Service 与 Pod 状态kustomize清单模板化工具。仓库中的Makefile实际调用kustomize build .将目录内的多份 YAML 渲染为单一清单文件后再交由kubectl apply见 kubernetes/Makefile。较新版本的 kubectl1.14内置了kubectl kustomize子命令若你未单独安装 kustomize 二进制可将 Makefile 中的构建命令替换为kubectl kustomize build .。本部署方案默认使用命名空间karakeep所有资源Deployment、Service、PVC、Secret、ConfigMap均由 kubernetes/kustomization.yaml 统一归入该命名空间避免与集群内其他应用冲突。第一步获取部署清单Karakeep 的 Kubernetes 部署清单以kubernetes目录形式内嵌在仓库根目录中。你可以直接克隆仓库然后将整个kubernetes目录复制到你选择的任意工作目录git clone https://gitcode.com/GitHub_Trending/ho/hoarder.git cp -r kubernetes /your/preferred/directory/复制后你将在该目录下看到以下核心文件文件作用kustomization.yamlKustomize 入口声明 namespace、Secret/ConfigMap 生成器、资源列表与镜像 Tag 替换规则.env_sample环境变量模板非敏感配置.secrets_sample敏感密钥模板namespace.yamlkarakeep命名空间定义web-deployment.yaml主应用Next.js 全栈服务Deploymentweb-service.yaml主应用 Service默认类型为LoadBalancer端口 3000chrome-deployment.yaml无头 Chrome网页抓取Deploymentchrome-service.yaml无头 Chrome Service类型为ClusterIP端口 9222meilisearch-deployment.yamlMeilisearch 全文搜索引擎 Deploymentmeilisearch-pvc.yaml /># Put your configuration options here NEXTAUTH_URLhttp://localhost:3000 KARAKEEP_VERSIONrelease两个变量的含义与修改建议NEXTAUTH_URL必须改为你的服务器对外地址如https://karakeep.example.com用于 NextAuth 会话回调与 OAuth 流程填错会导致登录/回调失败KARAKEEP_VERSION镜像 Tag。设置为release表示始终拉取最新稳定版若你希望控制升级节奏应固定为具体版本号例如KARAKEEP_VERSION0.10.0。更多可用配置项请参考完整的环境变量文档docs/docs/03-configuration/01-environment-variables.md。例如需要启用 AI 自动打标时直接在.env中追加OPENAI_API_KEYkey即可详见下文第三步。配置密钥将.secrets_sample复制为.secrets并将示例随机串替换为你自己生成的值cp .secrets_sample .secrets模板内容如下kubernetes/.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三个密钥的用途NEXTAUTH_SECRETNextAuth 会话签名密钥用于加密 JWT 会话MEILI_MASTER_KEYMeilisearch 的主密钥保护搜索引擎 APINEXT_PUBLIC_SECRET应用内部使用的公共密钥。⚠️务必修改这些随机字符串。官方推荐使用openssl rand -base64 36生成高强度的随机串。若所有实例共享同一份默认密钥存在严重的安全隐患。这些文件会被 Kustomize 分别注入到所有相关 Pod 的envFrom中主应用通过secretRef: karakeep-secrets与configMapRef: karakeep-configuration加载见 kubernetes/web-deployment.yamlMeilisearch 同样加载两者以便读取MEILI_MASTER_KEY等配置见 kubernetes/meilisearch-deployment.yaml。第三步配置 AI 推理自动打标Karakeep 的 AI 自动打标功能需要配置推理后端。官方文档将其分为两种情况。使用 OpenAI推荐前往 OpenAI 获取 API Key在.env文件中添加OPENAI_API_KEYkey关于使用 OpenAI 的成本详情可参考成本说明文档docs/docs/06-administration/03-openai.md若希望使用其他 AI 提供商如本地推理可参阅不同 AI 提供商的配置指南docs/docs/03-configuration/02-different-ai-providers.md。使用 Ollama 做本地推理实验性展开查看 Ollama 本地推理配置实验性功能注意打标质量取决于你选择的模型质量。本地模型推理是近期新增的能力成熟度不如 OpenAI使用过程中可能遇到较多推理失败请谨慎启用并做好预期。确保 Ollama 服务已运行设置OLLAMA_BASE_URL环境变量为 Ollama API 地址设置INFERENCE_TEXT_MODEL为文本推理所用模型例如mistral设置INFERENCE_IMAGE_MODEL为图片推理所用模型例如llava确保你已通过ollama pull拉取所需模型。这些变量与 OpenAI 一样直接写入.env文件由 ConfigMap 注入到 web 容器。从实现上看这些推理相关变量会在推理 Worker 启动时读取用于构建文本/图片打标请求相关推理逻辑位于 packages/shared/inference.ts其测试用例见 packages/shared/inference.test.ts因此配置后无需改动任何清单文件。第四步部署服务完成.env与.secrets的配置后一键部署make deploymake deploy的完整行为链如下见 kubernetes/Makefilekustomize build .将整个目录渲染为单一清单文件_manifest.yaml该文件同时包含 namespace、Deployment、Service、PVC、ConfigMap、Secret 等所有资源且已被写入.gitignorekubectl apply -f _manifest.yaml将渲染结果应用到集群make clean在构建前删除旧的_manifest.yaml避免叠加过期内容。若你想先审查最终清单而不直接部署可执行make build生成_manifest.yaml后自行检查。部署完成后用以下命令确认各组件 Pod 状态kubectl -n karakeep get pods kubectl -n karakeep get all第五步访问服务方式一通过 LoadBalancer IP默认情况下web Service 类型为LoadBalancer见 kubernetes/web-service.yaml云厂商或支持 LoadBalancer 的裸机环境如 MetalLB会为它分配一个外部 IP。执行kubectl get services找到web服务对应的 LoadBalancer 地址然后在浏览器访问http://loadbalancer-ip:3000你应该会看到 Karakeep 的 Sign In登录页面。提示根据你的集群环境你可能更希望使用 Ingress 暴露服务或有其他访问方式如 Port-Forward、NodePort。方式二通过 Ingress如果你想使用 Ingress可以基于仓库中的示例清单kubernetes/ingress_sample.yaml进行定制将host改为你自己的 DNS 名称。示例清单将/路径pathType: Prefix路由到web服务的 3000 端口。使用 Ingress 时应将 web Service 改为ClusterIP类型使其仅在集群内部可达、由 Ingress 统一对外kubectl -n karakeep patch service web -p {spec:{type:ClusterIP}}补丁完成后应用你的 Ingress 清单即可通过所选 URL 访问服务kubectl apply -f ingress_sample.yaml注意Ingress 需要在集群中已部署 Ingress Controller如 NGINX Ingress Controller、Traefik才能正常工作。配置 HTTPS 访问为 Karakeep 配置安全的 HTTPS 访问需要预先准备 TLS 证书文件.crt与.key。步骤如下创建 TLS Secret在部署完 Karakeep 清单后在karakeep命名空间中创建 TLS Secret。Secret 名称可自定义但必须与 Ingress 定义中的secretName保持一致kubectl --namespace karakeep create secret tls karakeep-web-tls --cert/path/to/crt --key/path/to/key修改 Ingress 的 spec在 Ingress 清单中启用 TLS示例如下spec: tls: - hosts: - karakeep.example.com secretName: karakeep-web-tls⚠️ 注意TLS spec 中的hosts必须与 HTTP spec 中的host保持一致否则证书匹配会失败。若你更习惯自动化证书管理也可以参考仓库中 Kustomize 的replacements机制见 kubernetes/kustomization.yaml自行扩展将 Ingress 的 host 与 TLS 配置参数化例如用环境变量统一管理域名与 Secret 名称。可选安装快速分享扩展部署完成后你可以安装官方提供的浏览器扩展与移动端 App实现更快速的收藏体验。具体安装步骤参见快速分享指南docs/docs/04-using-karakeep/quick-sharing.md。浏览器扩展与移动端通过 API 与 Karakeep 服务交互可帮助你更快地囤积内容。更新与升级Karakeep 的升级策略围绕KARAKEEP_VERSION变量展开其底层机制值得重点说明。固定版本升级编辑 kubernetes/kustomization.yaml 中的KARAKEEP_VERSION变量或直接修改.env中的同名变量二者在构建时等效然后执行make clean deploymake clean会先删除旧的_manifest.yaml确保重新渲染的清单包含新版本号。镜像 Tag 替换机制从源码结构看KARAKEEP_VERSION是通过 Kustomize 的replacements特性写入 web Deployment 镜像 Tag 的见 kubernetes/kustomization.yamlreplacements: - source: fieldPath: data.KARAKEEP_VERSION kind: ConfigMap name: karakeep-configuration version: v1 targets: - fieldPaths: - spec.template.spec.containers.0.image options: delimiter: : index: 1 select: group: apps kind: Deployment name: web version: v1即Kustomize 从karakeep-configurationConfigMap 中读取KARAKEEP_VERSION的值以:为分隔符替换 web Deployment 中容器镜像的 Tag 部分ghcr.io/karakeep-app/karakeep:tag。这也是为什么只需改一个变量就能完成镜像版本切换。使用releaseTag 的滚动拉取如果你选择release作为镜像 Tag即始终跟随最新稳定版由于 kubernetes/web-deployment.yaml 中设置了imagePullPolicy: AlwaysPod 每次重建时都会从镜像仓库拉取最新镜像。此时只需删除 web Pod 即可触发重新拉取kubectl -n karakeep delete pod web-pod-nameDeployment 会自动重建 Pod并拉取最新的release镜像从而完成升级无需修改任何清单。提示官方推荐的升级路径仍是固定具体版本号 make clean deploy以精确控制升级时机并规避意外破坏性变更。小结本文基于官方 Kubernetes 安装文档完整梳理了 Karakeep 的 Kustomize 化部署全流程从获取 kubernetes 目录清单、配置.env环境变量与.secrets密钥、接入 OpenAI/Ollama 实现 AI 自动打标到make deploy一键下发再到 LoadBalancer / Ingress / TLS 三种访问方式最后讲解了KARAKEEP_VERSION驱动的镜像 Tag 替换与升级策略。整体架构上web、无头 Chrome抓取与 Meilisearch搜索三者通过集群内 Service DNS 协作kubernetes/web-deployment.yaml而 Kustomize 的configMapGenerator/secretGenerator/replacements三件套让配置、密钥与镜像版本的管理高度集中且可审计。无论你是想在云上快速体验还是在裸机集群上部署生产实例这套清单都能作为可靠的起点。【免费下载链接】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），仅供参考