weaviate-ops

Weaviate 向量库的生产运维：认证、备份、多租户与索引。

补充说明

Weaviate 是支持 HNSW、混合检索和多租户的向量数据库。生产运维重点不是建表，而是认证、备份恢复、租户隔离、索引参数和容量监控。

基础用法见 weaviate；本页只写集群运维和故障处理。

安装与启动

docker run -d --name weaviate \
  -p 8080:8080 -p 50051:50051 -p 2112:2112 \
  -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=false \
  -e AUTHENTICATION_APIKEY_ENABLED=true \
  -e AUTHENTICATION_APIKEY_ALLOWED_KEYS="$WEAVIATE_API_KEY" \
  -e AUTHENTICATION_APIKEY_USERS=admin \
  -e AUTHORIZATION_ADMINLIST_ENABLED=true \
  -e AUTHORIZATION_ADMINLIST_USERS=admin \
  -e PROMETHEUS_MONITORING_ENABLED=true \
  -v weaviate-data:/var/lib/weaviate \
  semitechnologies/weaviate:"$WEAVIATE_VERSION"

生产要固定版本并使用外部对象存储/副本，不要依赖单容器和本地卷。

常用示例

检查存活、就绪和版本：

curl -s http://localhost:8080/v1/.well-known/ready
curl -s http://localhost:8080/v1/meta
curl -s http://localhost:2112/metrics | grep -E 'weaviate_(object|vector|request)'

创建启用多租户的集合，并添加租户：

curl -X POST http://localhost:8080/v1/schema \
  -H "Authorization: Bearer $WEAVIATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"class":"Docs","vectorizer":"none","multiTenancyConfig":{"enabled":true},"vectorIndexConfig":{"distance":"cosine","efConstruction":256,"maxConnections":32}}'

curl -X POST http://localhost:8080/v1/schema/Docs/tenants \
  -H "Authorization: Bearer $WEAVIATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"tenants":[{"name":"tenant-a"},{"name":"tenant-b"}]}'

按租户查询，租户名通过 GraphQL 参数传入：

curl -X POST http://localhost:8080/v1/graphql \
  -H "Authorization: Bearer $WEAVIATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ Get { Docs(tenant: \"tenant-a\", limit: 5) { title } } }"}'

备份到文件系统并查询进度（容器需设置 BACKUP_FILESYSTEM_PATH）：

curl -X POST http://localhost:8080/v1/backups/filesystem \
  -H "Authorization: Bearer $WEAVIATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"id":"backup-20261018","include":["Docs"]}'

curl -s http://localhost:8080/v1/backups/filesystem/backup-20261018 \
  -H "Authorization: Bearer $WEAVIATE_API_KEY"

易错点与排错

• 备份模块未启用时接口返回 422；文件系统备份要设置 BACKUP_FILESYSTEM_PATH，S3 备份要在 ENABLE_MODULES 中启用 backup-s3。
• 文件系统备份路径必须在持久卷上；容器重建后落在临时层里的备份会一起消失。
• S3 备份不读取 ~/.aws/credentials 或 AWS_PROFILE；只认环境变量、IAM 角色或认证代理，且访问密钥会覆盖 IAM 角色。
• 匿名访问关闭后，漏带 Authorization: Bearer 的客户端全部 401；健康检查端点与业务端点的认证策略要分别确认。
• 副本因子大于 1 需要多节点和最低副本配置；单节点设置 RF=2 会导致写入失败或一直等待。
• 多租户写入前租户必须已创建；租户不存在时返回 422，不会自动建租户。
• HNSW 的 efConstruction、maxConnections 等参数创建后不可改；调参要新建集合并重建索引。
• 不要在写入高峰期直接复制数据目录做备份；使用备份 API 保证一致性。

读完自测

合上页面，先回答，再展开对照。

1. 文件系统备份需要哪些前置配置？
2. 为什么 S3 备份读不到 ~/.aws/credentials？
3. 多租户查询为什么要显式传 tenant？

相关条目

• weaviate
• ragflow
• llamaindex
• dify
• deployment