手把手教你在Kubernetes集群上安装Weaviate，新手必看教程 (2025年05月)

引言

Weaviate是一个开源的向量搜索引擎，它能够帮助你构建强大的语义搜索、推荐系统和问答应用。在Kubernetes上部署Weaviate可以让你轻松实现水平扩展和高可用性。本教程将带你从零开始，一步步在Kubernetes集群上安装Weaviate。

准备工作

在开始之前，请确保你已经具备以下条件：

1. 一个运行中的Kubernetes集群（可以是Minikube、k3s、EKS、AKS或GKE等）
2. kubectl命令行工具已安装并配置好访问集群的权限
3. Helm 3已安装（用于简化部署过程）
4. 至少4GB可用内存（Weaviate对内存有一定要求）

检查环境

# 检查kubectl是否正常工作
kubectl cluster-info

# 检查Helm版本
helm version

第一步：添加Weaviate Helm仓库

Helm是Kubernetes的包管理工具，我们可以用它来简化Weaviate的安装过程。

# 添加Weaviate官方Helm仓库
helm repo add weaviate https://weaviate.github.io/weaviate-helm
helm repo update

原理说明：这个命令将Weaviate的Helm图表仓库添加到本地，helm repo update确保我们获取最新的图表版本。

第二步：创建命名空间

为了保持集群整洁，我们为Weaviate创建一个独立的命名空间。

kubectl create namespace weaviate

第三步：安装Weaviate

现在我们可以使用Helm来安装Weaviate了。以下是基础安装命令：

helm install weaviate weaviate/weaviate \
  --namespace weaviate \
  --set persistence.enabled=true \
  --set persistence.size=10Gi \
  --set service.type=ClusterIP

参数解释：
– persistence.enabled=true：启用持久化存储，防止数据丢失
– persistence.size=10Gi：分配10GB存储空间（可根据需求调整）
– service.type=ClusterIP：设置服务类型为ClusterIP（默认内部访问）

高级配置示例

如果你需要更复杂的配置，可以使用values文件：

# weaviate-values.yaml
persistence:
  enabled: true
  size: 20Gi

service:
  type: LoadBalancer

modules:
  text2vec-transformers:
    enabled: true

resources:
  requests:
    memory: "4Gi"
    cpu: "1"

然后使用这个配置文件安装：

helm install weaviate weaviate/weaviate \
  -f weaviate-values.yaml \
  --namespace weaviate

注意事项：
1. text2vec-transformers模块需要更多资源，确保你的集群有足够容量
2. LoadBalancer类型会创建一个外部IP供访问（云提供商可能需要额外配置）

第四步：验证安装

安装完成后，检查Pod状态：

kubectl get pods -n weaviate -w

等待所有Pod状态变为”Running”。这可能需要几分钟时间，特别是第一次拉取镜像时。

检查服务状态：

kubectl get svc -n weaviate

如果看到类似下面的输出，说明安装成功：

NAME       TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
weaviate   ClusterIP   10.96.123.456   <none>        8080/TCP   5m23s

第五步：访问Weaviate

根据你的服务类型不同，访问方式也不同：

ClusterIP方式（默认内部访问）

# Port-forward到本地端口8080
kubectl port-forward svc/weaviate -n weaviate 8080:8080 &

然后在浏览器中访问 http://localhost:8080/v1/meta ，你应该能看到Weaviat的元数据信息。

LoadBalancer方式

如果你使用了LoadBalancer类型的服务：

# 获取外部IP地址（云提供商可能需要几分钟分配）
kubectl get svc -n weaviate -w

# EXTERNAL-IP列出现后即可通过该IP和端口8080访问
curl http://<EXTERNAL-IP>:8080/v1/meta

第六步：测试基本功能

让我们通过简单的API调用来测试Wevaiate是否正常工作：

# Create a schema (类定义)
curl -X POST http://localhost:8080/v1/schema -H 'Content-Type: application/json' -d '{
    "class": "Article",
    "description": "A collection of articles",
    "properties": [
        {
            "name": "title",
            "dataType": ["text"],
            "description": "The title of the article"
        },
        {
            "name": "content",
            "dataType": ["text"],
            "description": "The content of the article"
        }
    ]
}'

# Add an object (添加数据)
curl -X POST http://localhost:8080/v1/objects -H 'Content-Type: application/json' -d '{
    "class": "Article",
    "properties": {
        "title": "Getting Started with Wevaiate",
        "content": "This is a tutorial on how to use Wevaiate..."
    }
}'

# Query objects (查询数据)
curl -X GET http://localhost:8080/v1/objects?class=Article | jq .

如果这些命令都返回了预期的结果，说明你的Wevaiate实例已经成功运行！

常见问题解决

Pod无法启动或CrashLoopBackOff

1. 资源不足：

   代码片段 复制代码

   kubectl describe pod <pod-name> -n wevaiate | grep -A10 Events:
   

   查看是否有资源不足的错误。如果是，调整values.yaml中的resources部分并升级部署。

2. 持久化存储问题：

   代码片段 复制代码

   kubectl logs <pod-name> -n wevaiate | grep -i storage 
   

   确保你的集群支持动态存储供应或已正确配置PV/PVC。

API请求超时或无法连接

1. 检查服务状态：

   代码片段 复制代码

   kubectl describe svc wevaiate -n wevaiate 
   

2. 检查网络策略：

   代码片段 复制代码

   kubectl get networkpolicy -n wevaiate 
   

   如果有网络策略限制了流量，需要适当调整。

Kubernetes生产环境建议

对于生产环境部署，考虑以下增强措施：

1. 高可用性配置：

   代码片段 复制代码

   replicas: 3 
   autoscaling:
     enabled: true 
     minReplicas: &replicas 
     maxReplicas: &replicas *2 
   

2. 备份策略：

   代码片段 复制代码

   backup:
     enabled: true 
     schedule: "@daily" 
     bucketName: my-wevaiate-backups 
     endpointUrl: s3.amazonaws.com # or your own S3-compatible storage 
   

3. 监控集成：
   “`yaml
   metrics:
   enabled: true
   serviceMonitor:
   enabled: true # For Prometheus Operator integration
   interval: &interval *5s
   scrapeTimeout: &interval *4
   labels:
   release: prometheus-stack

resources:
limits:
memory:”8Gi” cpu:”2″ requests :memory:”4Gi” cpu:”1″

## Helm升级和卸载 

要升级现有部署:

``` bash helm upgrade --install my-release bitnami/wevaiate \ --namespace my-namespace \ --version x.y.z \ --values values-production.yaml  

要卸载:

“` bash helm uninstall my-release –namespace my-namespace

“`

##总结

通过本教程,你已经学会了:

*如何准备Kubernetes环境来部署 We v ai ate

*使用 Helm图表简化部署过程

*基本的验证和测试方法

*常见问题的排查技巧

*生产环境的优化建议

现在你已经拥有了一个运行中的 We v ai ate实例,可以开始构建你的语义搜索应用了!下一步可以探索 We v ai ate的向量搜索能力,或者集成其他模块如 qna-transformers来增强功能。