尧图网站建设 
Karakeep Kubernetes 部署实战基于 Kustomize 的自托管部署、Ingress 与 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导读本文以 Karakeep原 Hoarder仓库中 04-kubernetes.md 为骨架结合仓库根目录 kubernetes/ 下的真实清单文件与 环境变量文档系统讲解在 Kubernetes 集群上通过 Kustomize 一键部署 Karakeep 的完整流程。你将掌握清单获取、环境变量与密钥注入、自动打标AI tagging配置、LoadBalancer 与 Ingress 两种访问方式、HTTPS 证书挂载以及版本升级的标准化操作。一、部署前置条件在开始之前请确保你的环境中具备以下三样东西需求说明Kubernetes 集群任意可用的集群均可清单中未绑定特定云厂商kubectl与集群版本兼容的命令行工具用于执行apply/patch等操作kustomizeKustomize 构建工具。若你的 kubectl 版本 ≥ 1.14其内置的kubectl kustomize子命令亦可替代独立二进制仓库还额外提供了make封装见 kubernetes/Makefile因此make也是推荐的辅助工具可免去手动记忆 kustomize 命令的负担。二、获取部署清单Karakeep 的 Kubernetes 部署清单全部集中在仓库根目录的 kubernetes/ 目录中。你可以直接克隆仓库后将该目录复制到任意工作目录使用git clone https://gitcode.com/GitHub_Trending/ho/hoarder.git cp -r kubernetes /your/deploy/dir/目录内包含的清单文件及其职责如下均已确认存在于仓库文件职责namespace.yaml创建独立的karakeep命名空间web-deployment.yamlKarakeep 主应用 Deployment暴露 3000 端口web-service.yaml主应用 Service默认类型为 LoadBalancerchrome-deployment.yaml无头 Chrome 浏览器 Deployment用于网页截图与 JS 渲染chrome-service.yamlChrome 内部 ServiceClusterIP9222 端口meilisearch-deployment.yamlMeilisearch 全文搜索引擎v1.41.0meilisearch-service.yamlMeilisearch 内部 Service7700 端口data-pvc.yaml主应用持久化卷声明1GiReadWriteOncemeilisearch-pvc.yaml搜索引擎持久化卷声明1GiReadWriteOnceingress_sample.yaml示例 Ingresshost 为karakeep.example.com.env_sample环境变量模板.secrets_sample敏感密钥模板Makefile封装了kustomize build与kubectl apply的构建部署流程kustomization.yamlKustomize 入口串联全部资源与变量注入逻辑三、注入环境变量与密钥Karakeep 在 Kubernetes 部署中采用双通道配置注入非敏感配置走 ConfigMap敏感密钥走 Secret二者均由 Kustomize 的secretGenerator/configMapGenerator从本地文件自动生成。3.1 配置环境变量.env复制模板并编辑cp .env_sample .env模板默认内容如下# Put your configuration options here NEXTAUTH_URLhttp://localhost:3000 KARAKEEP_VERSIONrelease两个必填项说明NEXTAUTH_URL必须修改为你的服务器实际地址域名或 IP。根据 环境变量文档该变量应指向服务地址未正确设置时应用虽能运行但在退出登录signout等场景会重定向到错误地址。KARAKEEP_VERSION镜像版本控制变量。设为release会拉取最新稳定版更推荐固定到具体版本号如KARAKEEP_VERSION0.10.0以便精确控制升级节奏。最新的版本标签可在项目容器镜像发布页查看。版本号之所以能通过.env驱动镜像秘密在于 kustomization.yaml 中的replacements段它从名为karakeep-configuration的 ConfigMap 读取data.KARAKEEP_VERSION字段以:为分隔符、取 index 1 覆盖webDeployment 中容器镜像的 tag 部分。3.2 配置密钥.secretscp .secrets_sample .secrets模板默认内容# 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各密钥用途依据 环境变量文档密钥必填性用途NEXTAUTH_SECRET必填用于签名 JWT 令牌的随机字符串MEILI_MASTER_KEY生产环境启用搜索时必填Meilisearch 的 master key官方建议用openssl rand -base64 36 \| tr -dc A-Za-z0-9生成以规避特殊字符NEXT_PUBLIC_SECRET必填应用公共加密密钥3.3 其他可用配置除上述变量外web-deployment.yaml 中已硬编码了三个环境变量与内网组件对接MEILI_ADDRhttp://meilisearch:7700—— 指向 Meilisearch 内部 Service根据环境变量文档若未设置则搜索功能会被禁用。BROWSER_WEB_URLhttp://chrome:9222—— 指向无头 Chrome 的调试地址若BROWSER_WEB_URL与BROWSER_WEBSOCKET_URL均未设置worker 将退化为纯 HTTP 请求跳过截图与 JavaScript 执行。DATA_DIR/data—— 持久化数据目录挂载自data-pvc数据库存放于此资产assets默认存放在${DATA_DIR}/assets除非另行设置ASSETS_DIR。完整的配置项清单请查阅 环境变量文档它包含了数百项变量的默认值、必填性与详细说明是深度调优时的权威参考。四、配置 OpenAI可选但强烈推荐自动打标automatic tagging功能依赖 AI 推理能力。虽然这是可选项但它是 Karakeep 的核心体验之一强烈建议启用。前往 OpenAI 官方帮助中心获取你的 API Key。将 API Key 追加到.env文件OPENAI_API_KEYkey依据 环境变量文档OPENAI_API_KEY与OLLAMA_BASE_URL二者必须至少设置其一自动打标才会启用否则该流程会被跳过。关于 OpenAI 的使用成本可参考 OpenAI 成本说明若希望使用其他 AI 提供方例如用 Ollama 做本地推理请参阅 不同 AI 提供方配置指南。提示由于webDeployment 通过envFrom注入 ConfigMap见 web-deployment.yamlOPENAI_API_KEY只需追加进.env即可随 ConfigMap 自动注入无需改动任何 YAML。五、一键部署在包含.env、.secrets和全部 YAML 的目录中执行make deploymake deploy实际执行的是 Makefile 中定义的两步操作deploy: $(OUTPUT_FILE) kubectl apply -f $(OUTPUT_FILE)即先用kustomize build .将全部清单渲染为_manifest.yaml再通过kubectl apply -f应用到集群。若不使用 make可等价执行kustomize build . | kubectl apply -f -Kustomize 渲染时会自动完成三件关键事情见 kustomization.yaml将全部资源置于karakeep命名空间下从.secrets生成 Secretkarakeep-secrets从.env生成 ConfigMapkarakeep-configuration通过replacements将KARAKEEP_VERSION注入webDeployment 的镜像 tag。应用启动后整个系统由四个 Pod 协作构成web主服务 worker监听 3000、chrome无头浏览器9222、meilisearch全文搜索7700以及为二者提供持久化的 PVC。六、访问服务6.1 通过 LoadBalancer IP 访问默认情况下web-service.yaml 将应用暴露为LoadBalancer类型的 Servicetype: LoadBalancer部署完成后查看负载均衡器地址kubectl get services找到web服务对应的 LoadBalancer IP或 External IP然后访问http://loadbalancer-ip:3000此时应能看到 Sign In登录页面。注意具体集群如裸金属、云厂商分配 LoadBalancer 地址的方式各不相同你也可以根据实际情况改用 Ingress 或其他访问方式。6.2 通过 Ingress 访问如果你希望使用域名访问仓库提供了示例 ingress_sample.yamlapiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: karakeep-web-ingress namespace: karakeep spec: rules: - host: karakeep.example.com http: paths: - path: / pathType: Prefix backend: service: name: web port: number: 3000自定义步骤将host改为你选择的 DNS 域名将webService 的类型改为ClusterIP使其仅能被 Ingress 内部访问。若已经部署过服务无需修改文件直接在线 patchkubectl -n karakeep patch service web -p {spec:{type:ClusterIP}}应用 Ingresskubectl apply -f ingress_sample.yaml之后即可通过你设定的 URL 访问服务。注意 Ingress 的host与 Service 类型变更需配合 DNS 解析一并完成。6.3 配置 HTTPS 访问为 Karakeep 启用 HTTPS 需要一份预先准备好的证书文件.crt与.key。流程如下在karakeep命名空间中创建 TLS Secretsecret 名称可自定但必须与 Ingress 定义中的引用一致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必须保持一致否则证书校验与路由匹配会失败。七、可选安装快捷分享扩展部署完成后可前往 快捷分享指南 安装移动端 App 与浏览器扩展它们能帮助你更快速地收藏hoard内容与本文的 Kubernetes 服务端构成完整的收藏链路。八、版本升级Karakeep 的升级操作被刻意设计得简单可控8.1 固定版本升级推荐编辑kustomization.yaml中的KARAKEEP_VERSION变量实际来自.env然后执行make clean deployclean会先删除之前生成的_manifest.yaml确保以最新配置重新渲染后再应用。8.2 release 标签滚动更新如果你在.env中选择了release作为镜像 tag由于 web-deployment.yaml 中设置了imagePullPolicy: Always每次 Pod 重建都会强制从镜像仓库拉取最新镜像。此时只需删除 web Pod 触发重建即可拿到最新版本kubectl -n karakeep delete pod -l appkarakeep-web这一机制保证了release模式下始终运行最新稳定版代价是无法像固定版本那样精确回溯。九、架构小结与排查建议从清单结构可以清晰还原 Karakeep 在 Kubernetes 中的部署拓扑客户端 ── LoadBalancer / Ingress ── web (3000) │ ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ meilisearch (7700) chrome (9222) contenteditable="false">【免费下载链接】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 Kubernetes 部署实战：基于 Kustomize 的自托管部署、Ingress 与 TLS 配置指南
Karakeep Kubernetes 部署实战基于 Kustomize 的自托管部署、Ingress 与 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导读本文以 Karakeep原 Hoarder仓库中 04-kubernetes.md 为骨架结合仓库根目录 kubernetes/ 下的真实清单文件与 环境变量文档系统讲解在 Kubernetes 集群上通过 Kustomize 一键部署 Karakeep 的完整流程。你将掌握清单获取、环境变量与密钥注入、自动打标AI tagging配置、LoadBalancer 与 Ingress 两种访问方式、HTTPS 证书挂载以及版本升级的标准化操作。一、部署前置条件在开始之前请确保你的环境中具备以下三样东西需求说明Kubernetes 集群任意可用的集群均可清单中未绑定特定云厂商kubectl与集群版本兼容的命令行工具用于执行apply/patch等操作kustomizeKustomize 构建工具。若你的 kubectl 版本 ≥ 1.14其内置的kubectl kustomize子命令亦可替代独立二进制仓库还额外提供了make封装见 kubernetes/Makefile因此make也是推荐的辅助工具可免去手动记忆 kustomize 命令的负担。二、获取部署清单Karakeep 的 Kubernetes 部署清单全部集中在仓库根目录的 kubernetes/ 目录中。你可以直接克隆仓库后将该目录复制到任意工作目录使用git clone https://gitcode.com/GitHub_Trending/ho/hoarder.git cp -r kubernetes /your/deploy/dir/目录内包含的清单文件及其职责如下均已确认存在于仓库文件职责namespace.yaml创建独立的karakeep命名空间web-deployment.yamlKarakeep 主应用 Deployment暴露 3000 端口web-service.yaml主应用 Service默认类型为 LoadBalancerchrome-deployment.yaml无头 Chrome 浏览器 Deployment用于网页截图与 JS 渲染chrome-service.yamlChrome 内部 ServiceClusterIP9222 端口meilisearch-deployment.yamlMeilisearch 全文搜索引擎v1.41.0meilisearch-service.yamlMeilisearch 内部 Service7700 端口data-pvc.yaml主应用持久化卷声明1GiReadWriteOncemeilisearch-pvc.yaml搜索引擎持久化卷声明1GiReadWriteOnceingress_sample.yaml示例 Ingresshost 为karakeep.example.com.env_sample环境变量模板.secrets_sample敏感密钥模板Makefile封装了kustomize build与kubectl apply的构建部署流程kustomization.yamlKustomize 入口串联全部资源与变量注入逻辑三、注入环境变量与密钥Karakeep 在 Kubernetes 部署中采用双通道配置注入非敏感配置走 ConfigMap敏感密钥走 Secret二者均由 Kustomize 的secretGenerator/configMapGenerator从本地文件自动生成。3.1 配置环境变量.env复制模板并编辑cp .env_sample .env模板默认内容如下# Put your configuration options here NEXTAUTH_URLhttp://localhost:3000 KARAKEEP_VERSIONrelease两个必填项说明NEXTAUTH_URL必须修改为你的服务器实际地址域名或 IP。根据 环境变量文档该变量应指向服务地址未正确设置时应用虽能运行但在退出登录signout等场景会重定向到错误地址。KARAKEEP_VERSION镜像版本控制变量。设为release会拉取最新稳定版更推荐固定到具体版本号如KARAKEEP_VERSION0.10.0以便精确控制升级节奏。最新的版本标签可在项目容器镜像发布页查看。版本号之所以能通过.env驱动镜像秘密在于 kustomization.yaml 中的replacements段它从名为karakeep-configuration的 ConfigMap 读取data.KARAKEEP_VERSION字段以:为分隔符、取 index 1 覆盖webDeployment 中容器镜像的 tag 部分。3.2 配置密钥.secretscp .secrets_sample .secrets模板默认内容# 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各密钥用途依据 环境变量文档密钥必填性用途NEXTAUTH_SECRET必填用于签名 JWT 令牌的随机字符串MEILI_MASTER_KEY生产环境启用搜索时必填Meilisearch 的 master key官方建议用openssl rand -base64 36 \| tr -dc A-Za-z0-9生成以规避特殊字符NEXT_PUBLIC_SECRET必填应用公共加密密钥3.3 其他可用配置除上述变量外web-deployment.yaml 中已硬编码了三个环境变量与内网组件对接MEILI_ADDRhttp://meilisearch:7700—— 指向 Meilisearch 内部 Service根据环境变量文档若未设置则搜索功能会被禁用。BROWSER_WEB_URLhttp://chrome:9222—— 指向无头 Chrome 的调试地址若BROWSER_WEB_URL与BROWSER_WEBSOCKET_URL均未设置worker 将退化为纯 HTTP 请求跳过截图与 JavaScript 执行。DATA_DIR/data—— 持久化数据目录挂载自data-pvc数据库存放于此资产assets默认存放在${DATA_DIR}/assets除非另行设置ASSETS_DIR。完整的配置项清单请查阅 环境变量文档它包含了数百项变量的默认值、必填性与详细说明是深度调优时的权威参考。四、配置 OpenAI可选但强烈推荐自动打标automatic tagging功能依赖 AI 推理能力。虽然这是可选项但它是 Karakeep 的核心体验之一强烈建议启用。前往 OpenAI 官方帮助中心获取你的 API Key。将 API Key 追加到.env文件OPENAI_API_KEYkey依据 环境变量文档OPENAI_API_KEY与OLLAMA_BASE_URL二者必须至少设置其一自动打标才会启用否则该流程会被跳过。关于 OpenAI 的使用成本可参考 OpenAI 成本说明若希望使用其他 AI 提供方例如用 Ollama 做本地推理请参阅 不同 AI 提供方配置指南。提示由于webDeployment 通过envFrom注入 ConfigMap见 web-deployment.yamlOPENAI_API_KEY只需追加进.env即可随 ConfigMap 自动注入无需改动任何 YAML。五、一键部署在包含.env、.secrets和全部 YAML 的目录中执行make deploymake deploy实际执行的是 Makefile 中定义的两步操作deploy: $(OUTPUT_FILE) kubectl apply -f $(OUTPUT_FILE)即先用kustomize build .将全部清单渲染为_manifest.yaml再通过kubectl apply -f应用到集群。若不使用 make可等价执行kustomize build . | kubectl apply -f -Kustomize 渲染时会自动完成三件关键事情见 kustomization.yaml将全部资源置于karakeep命名空间下从.secrets生成 Secretkarakeep-secrets从.env生成 ConfigMapkarakeep-configuration通过replacements将KARAKEEP_VERSION注入webDeployment 的镜像 tag。应用启动后整个系统由四个 Pod 协作构成web主服务 worker监听 3000、chrome无头浏览器9222、meilisearch全文搜索7700以及为二者提供持久化的 PVC。六、访问服务6.1 通过 LoadBalancer IP 访问默认情况下web-service.yaml 将应用暴露为LoadBalancer类型的 Servicetype: LoadBalancer部署完成后查看负载均衡器地址kubectl get services找到web服务对应的 LoadBalancer IP或 External IP然后访问http://loadbalancer-ip:3000此时应能看到 Sign In登录页面。注意具体集群如裸金属、云厂商分配 LoadBalancer 地址的方式各不相同你也可以根据实际情况改用 Ingress 或其他访问方式。6.2 通过 Ingress 访问如果你希望使用域名访问仓库提供了示例 ingress_sample.yamlapiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: karakeep-web-ingress namespace: karakeep spec: rules: - host: karakeep.example.com http: paths: - path: / pathType: Prefix backend: service: name: web port: number: 3000自定义步骤将host改为你选择的 DNS 域名将webService 的类型改为ClusterIP使其仅能被 Ingress 内部访问。若已经部署过服务无需修改文件直接在线 patchkubectl -n karakeep patch service web -p {spec:{type:ClusterIP}}应用 Ingresskubectl apply -f ingress_sample.yaml之后即可通过你设定的 URL 访问服务。注意 Ingress 的host与 Service 类型变更需配合 DNS 解析一并完成。6.3 配置 HTTPS 访问为 Karakeep 启用 HTTPS 需要一份预先准备好的证书文件.crt与.key。流程如下在karakeep命名空间中创建 TLS Secretsecret 名称可自定但必须与 Ingress 定义中的引用一致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必须保持一致否则证书校验与路由匹配会失败。七、可选安装快捷分享扩展部署完成后可前往 快捷分享指南 安装移动端 App 与浏览器扩展它们能帮助你更快速地收藏hoard内容与本文的 Kubernetes 服务端构成完整的收藏链路。八、版本升级Karakeep 的升级操作被刻意设计得简单可控8.1 固定版本升级推荐编辑kustomization.yaml中的KARAKEEP_VERSION变量实际来自.env然后执行make clean deployclean会先删除之前生成的_manifest.yaml确保以最新配置重新渲染后再应用。8.2 release 标签滚动更新如果你在.env中选择了release作为镜像 tag由于 web-deployment.yaml 中设置了imagePullPolicy: Always每次 Pod 重建都会强制从镜像仓库拉取最新镜像。此时只需删除 web Pod 触发重建即可拿到最新版本kubectl -n karakeep delete pod -l appkarakeep-web这一机制保证了release模式下始终运行最新稳定版代价是无法像固定版本那样精确回溯。九、架构小结与排查建议从清单结构可以清晰还原 Karakeep 在 Kubernetes 中的部署拓扑客户端 ── LoadBalancer / Ingress ── web (3000) │ ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ meilisearch (7700) chrome (9222) contenteditable="false">【免费下载链接】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），仅供参考