Kubernetes部署Weaviate向量数据库教程-Golang-PHP中文网

生产级weaviate kubernetes部署必须显式配置replicas:3、image.tag锁定版本、grpc启用并设loadbalancer、持久化启用且指定storageclassname；缺一不可，否则api不响应或启动即崩。

kubernetes部署weaviate向量数据库教程

直接上生产环境的 Kubernetes 部署，weaviate 不能只靠 helm install weaviate/weaviate 一把梭——不配资源限制、不开 gRPC、没设多副本、没挂持久卷，跑起来就崩。

确认集群基础能力是否达标

Weaviate 对底层 Kubernetes 有硬性依赖，缺一不可。不是“能跑就行”，而是“不满足就拒绝启动”：

kubectl version 必须 ≥ v1.24（v1.23 有已知 TLS 握手兼容问题）
必须存在至少一个 StorageClass，且支持 ReadWriteOnce 模式（hostPath 仅限单节点测试，生产禁用）
helm version 必须是 v3.x，v4 不兼容当前 Weaviate Chart
所有节点需启用 systemd-resolved 或等效 DNS 缓存，否则模块间服务发现超时（尤其 text2vec-openai 等远程模块）

values.yaml 中必须显式覆盖的 4 个关键项

默认 values.yaml 是开发配置，生产必须改这四点，否则会触发静默失败（Pod Running 但 API 不响应）：

Kubernetes Skills

针对 Kubernetes 仪表板和 Web UI 的浏览器自动化。适用于与 Kubernetes Dashboard、Grafana、ArgoCD UI 或其他 Web 界面交互。需要设置 MCP_BROWSER_ENABLED=true。

下载

replicas: 3 —— 单副本无 Raft 日志同步，故障即丢数据；3 是最小可用数
image.tag: "1.27.0" —— 必须锁死版本，latest 在 Helm 中不可控，易引发模块 ABI 不兼容
service.grpc.enabled: true 和 service.grpc.type: LoadBalancer —— 不开 gRPC，客户端无法复用连接池，QPS 上不去；LoadBalancer 类型才允许集群外调用（如 Dify 直连）
persistence.enabled: true + persistence.storageClassName: "nfs" —— Weaviate 数据目录 /var/lib/weaviate 必须落盘，否则 Pod 重建后全量索引丢失

模块启用与资源限制要成对设置

启用 text2vec-openai 这类远程模块看似只需加 enabled_modules，但漏掉对应资源限制，会导致 OOMKilled 后反复 CrashLoopBackOff：

在 modules.text2vec-openai.resources 下必须填 requests.memory: "512Mi"（最低要求），limits.memory: "1Gi"
text2vec-transformers 本地模型更吃内存，limits.memory 至少设为 "4Gi"，否则加载模型时卡死在 Initializing module
所有模块的 resources 块必须显式声明，Helm 不继承全局 resources 配置
验证方式：kubectl logs -n weaviate weaviate-0 | grep "module.*ready"，没有该日志=模块未真正加载

网络和权限的两个隐藏陷阱

部署成功 ≠ 可用。这两个点不检查，API 调用永远返回 503 Service Unavailable：

gRPC 端口 50051 的 Service 必须带 port: 50051 和 targetPort: 50051，缺一不可；若用 NodePort，宿主机防火墙必须放行该端口（不只是 8080）
AUTHENTICATION_APIKEY_ENABLED=true 必须通过 env 注入，不能写在 extraEnv 里——Weaviate 启动时只读取顶层 env 字段，extraEnv 会被忽略
验证命令别用 curl http://localhost:8080/v1/meta，要换成 curl http://<loadbalancer-ip>:8080/v1/meta -H "Authorization: Bearer your-key"</loadbalancer-ip>，否则绕过认证层测不出真实权限流

最常被跳过的一步：Weaviate 的 cluster.hostname 必须和实际访问域名/LoadBalancer IP 完全一致，哪怕差一个端口（比如配了 weaviate.example.com 却用 IP:8080 访问），gRPC 连接就会因 TLS SNI 不匹配而断开。这个值一旦写进 values.yaml，就不能靠环境变量覆盖。