Weaviate 迁移指南：升级到客户端 v4 和服务器 1.27+

⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考英文原版。

本指南说明如何从 Weaviate 客户端 v3 迁移到 v4.17.0，并将 Weaviate 服务器从 1.19.0 版本升级到 1.27.0 或更高版本。此迁移适用于包含 weaviate-client v4 升级的 Dify 版本。

概述

从即将发布的 Dify 版本开始，weaviate-client 已从 v3 升级到 v4.17.0。此升级带来了显著的性能改进和更好的稳定性，但需要 Weaviate 服务器版本 1.27.0 或更高版本。

**破坏性变更：**新的 weaviate-client v4 与 1.27.0 以下的 Weaviate 服务器版本不向后兼容。如果你正在运行 1.19.0 或更旧版本的自托管 Weaviate 实例，则必须在升级 Dify 之前升级 Weaviate 服务器。

谁会受到影响？

此迁移影响：

运行低于 1.27.0 版本的自托管 Weaviate 实例的自托管 Dify 用户
当前使用 Weaviate 服务器版本 1.19.0-1.26.x 的用户
升级到包含 weaviate-client v4 的 Dify 版本的用户

不受影响：

云托管 Weaviate 用户（Weaviate Cloud 管理服务器版本）
已经使用 Weaviate 1.27.0+ 的用户可以直接升级 Dify，无需额外步骤
运行 Dify 默认 Docker Compose 设置的用户（Weaviate 版本会自动更新）

破坏性变更

客户端 v4 要求

weaviate-client v4 引入了几个破坏性变更：

**最低服务器版本：**需要 Weaviate 服务器 1.27.0 或更高版本
**API 变更：**新的导入结构（weaviate.classes 而不是 weaviate.client）
**gRPC 支持：**默认在端口 50051 上使用 gRPC 以提高性能
**身份验证变更：**更新的身份验证方法和配置

为什么要升级？

**性能：**通过 gRPC (50051) 显著加快查询和导入操作
**稳定性：**更好的连接处理和错误恢复
**未来兼容性：**访问最新的 Weaviate 功能和持续支持
**安全性：**Weaviate 1.19.0 已经超过一年，不再接收安全更新

版本兼容性矩阵

Dify 版本	weaviate-client 版本	兼容的 Weaviate 服务器版本
≤ 1.9.1	v3.x	1.19.0 - 1.26.x
≥ 1.9.2*	v4.17.0	1.27.0+（已测试至 1.32.11）

*包含 weaviate-client v4 的确切 Dify 版本可能有所不同。请查看你特定版本的发布说明。此迁移适用于任何使用 weaviate-client v4.17.0 或更高版本的 Dify 版本。

Weaviate 服务器版本 1.19.0 在一年多前发布，现已过时。升级到 1.27.0+ 可访问性能、稳定性和功能方面的众多改进。

前提条件

在开始迁移之前，请完成以下步骤：

检查当前的 Weaviate 版本
```
curl http://localhost:8080/v1/meta
```
在响应中查找 version 字段。
备份数据
- 创建 Weaviate 数据的完整备份
- 如果使用 Docker Compose，请备份 Docker 卷
- 记录当前的配置设置
检查系统要求
- 确保有足够的磁盘空间用于数据库迁移
- 验证 Dify 和 Weaviate 之间的网络连接
- 如果使用外部 Weaviate，确认 gRPC 端口 (50051) 可访问
计划停机时间
- 迁移将需要服务停机
- 如果在生产环境中运行，请通知用户
- 在流量较低的时段安排迁移

迁移路径

选择与你的部署设置匹配的迁移路径：

路径 A：Docker Compose 用户（推荐）

这是通过 Docker Compose 运行 Dify 并使用捆绑的 Weaviate 实例的用户的最简单路径。

如果你使用 Dify 的标准 Docker Compose 设置，升级 Dify 时 Weaviate 版本会自动更新。无需手动配置。

步骤 1：备份数据

导航到 Dify 项目目录并备份 Docker 卷：

cd /path/to/dify/docker
docker compose down
tar -cvf ../weaviate-backup-$(date +%s).tgz volumes/weaviate

将备份文件存储在项目目录外的安全位置。如果迁移失败需要回滚，你将需要它。

步骤 2：更新 Dify

拉取包含 weaviate-client v4 和 Weaviate 1.27.0+ 的最新 Dify 版本：

cd /path/to/dify
git fetch origin
git checkout <version-with-weaviate-v4>  # 检查发布说明以获取正确版本
cd docker
docker compose pull
docker compose up -d

更新的 Docker Compose 配置包括：

Weaviate 服务器 1.27.0+ 镜像
weaviate-client v4.17.0（在 Dify 容器中自动安装）
正确的 gRPC 端口配置 (50051)

步骤 3：监控启动

观察日志以确保服务正确启动：

# 观察 Weaviate 启动
docker compose logs -f weaviate

# 观察 Dify API 启动
docker compose logs -f api

等待 Weaviate 显示”ready to serve requests”，Dify API 成功连接。

步骤 4：验证迁移

请参阅下面的验证步骤部分。

路径 B：外部/自托管 Weaviate

适用于在单独服务器、托管实例或 Weaviate Cloud 上运行 Weaviate 的用户。

此路径适用于单独管理 Weaviate 实例的用户。如果你通过 Docker Compose 使用 Dify 捆绑的 Weaviate，请改用路径 A。

步骤 1：备份 Weaviate 数据

使用 Weaviate 的备份 API 创建完整备份：

# 创建备份
curl -X POST \
  "http://your-weaviate-host:8080/v1/backups/filesystem" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "dify-backup-'$(date +%s)'",
    "include": ["*"]
  }'

# 检查备份状态
curl "http://your-weaviate-host:8080/v1/backups/filesystem/{backup-id}"

有关详细的备份说明，请参阅 Weaviate 备份文档。

步骤 2：停止 Weaviate 实例

# 对于 Docker 用户
docker stop weaviate

# 对于 systemd 用户
sudo systemctl stop weaviate

# 对于 Kubernetes 用户
kubectl scale deployment weaviate --replicas=0

步骤 3：升级 Weaviate 服务器

对于 Docker：

docker pull cr.weaviate.io/semitechnologies/weaviate:1.27.0
docker run -d \
  --name weaviate \
  -p 8080:8080 \
  -p 50051:50051 \
  -v /path/to/data:/var/lib/weaviate \
  -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=false \
  -e AUTHENTICATION_APIKEY_ENABLED=true \
  -e AUTHENTICATION_APIKEY_ALLOWED_KEYS=your-secret-key \
  -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
  -e QUERY_DEFAULTS_LIMIT=20 \
  -e DEFAULT_VECTORIZER_MODULE=none \
  cr.weaviate.io/semitechnologies/weaviate:1.27.0

对于 Kubernetes： 更新你的 Helm 值或清单：

image:
  registry: cr.weaviate.io
  repository: semitechnologies/weaviate
  tag: 1.27.0

然后应用：

helm upgrade weaviate weaviate/weaviate -f values.yaml
# 或
kubectl apply -f weaviate-deployment.yaml

对于二进制安装： 从 Weaviate 发布页面下载并安装新版本。

步骤 4：验证 Weaviate 升级

检查 Weaviate 是否运行正确版本：

curl http://your-weaviate-host:8080/v1/meta | jq '.version'

你应该看到版本 1.27.0 或更高。

步骤 5：更新 Dify 配置

更新 Dify 环境变量以配置外部 Weaviate 连接：

VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://your-weaviate-host:8080
WEAVIATE_API_KEY=your-api-key
WEAVIATE_GRPC_ENABLED=true
WEAVIATE_GRPC_ENDPOINT=your-weaviate-host:50051

WEAVIATE_GRPC_ENDPOINT 应采用 hostname:port 格式，不带任何协议前缀（无 grpc:// 或 http://）。

步骤 6：更新 Dify

cd /path/to/dify
git fetch origin
git checkout <version-with-weaviate-v4>
cd docker
docker compose pull
docker compose up -d

步骤 7：验证迁移

请参阅下面的验证步骤部分。

旧版本的数据迁移

如果从 Weaviate 1.19.0 升级到 1.27.0+，版本差距很大。虽然 Weaviate 通常会自动处理架构迁移，但你应该仔细监控升级并准备好备份。

自动迁移

在大多数情况下，Weaviate 1.27.0 会自动从 1.19.0 迁移数据：

停止 Weaviate 1.19.0
使用相同的数据目录启动 Weaviate 1.27.0
Weaviate 将检测旧格式并自动迁移
监控日志以了解迁移进度和任何错误

手动迁移（如果自动迁移失败）

如果自动迁移失败，请使用 Weaviate 的导出/导入工具：

1. 从旧版本导出数据

使用 Cursor API 或备份功能导出所有数据。对于大型数据集，请使用 Weaviate 的备份 API：

# 使用备份 API（推荐）
curl -X POST "http://localhost:8080/v1/backups/filesystem" \
  -H "Content-Type: application/json" \
  -d '{"id": "pre-migration-backup"}'

2. 将数据导入新版本

升级到 Weaviate 1.27.0 后，恢复备份：

curl -X POST "http://localhost:8080/v1/backups/filesystem/pre-migration-backup/restore" \
  -H "Content-Type: application/json"

有关全面的迁移指导，特别是对于复杂架构或大型数据集，请参阅官方 Weaviate 迁移指南。

配置变更

新环境变量

以下新环境变量在包含 weaviate-client v4 的 Dify 版本中可用：

WEAVIATE_GRPC_ENDPOINT

**描述：**指定 Weaviate 连接的 gRPC 端点。使用 gRPC 可显著提高批处理操作和查询的性能。 格式：hostname:port（无协议前缀） 默认端口：

不安全：50051
安全 (TLS)：443

示例：

# Docker Compose（内部网络）
WEAVIATE_GRPC_ENDPOINT=weaviate:50051

# 外部服务器（不安全）
WEAVIATE_GRPC_ENDPOINT=192.168.1.100:50051

# 具有自定义端口的外部服务器
WEAVIATE_GRPC_ENDPOINT=weaviate.example.com:9090

# Weaviate Cloud（端口 443 上的安全/TLS）
WEAVIATE_GRPC_ENDPOINT=your-instance.weaviate.cloud:443

不要在 WEAVIATE_GRPC_ENDPOINT 值中包含协议前缀，如 grpc:// 或 http://。仅使用 hostname:port。

更新的环境变量

所有现有的 Weaviate 环境变量保持不变：

**WEAVIATE_ENDPOINT：**Weaviate 的 HTTP 端点（例如 http://weaviate:8080）
**WEAVIATE_API_KEY：**用于身份验证的 API 密钥（如果启用）
**WEAVIATE_BATCH_SIZE：**导入的批处理大小（默认：100）
**WEAVIATE_GRPC_ENABLED：**启用/禁用 gRPC（v4 中默认：true）

完整配置示例

# docker/.env 或环境配置
VECTOR_STORE=weaviate

# HTTP 端点（必需）
WEAVIATE_ENDPOINT=http://weaviate:8080

# 身份验证（如果在 Weaviate 实例上启用）
WEAVIATE_API_KEY=your-secret-api-key

# gRPC 配置（推荐以提高性能）
WEAVIATE_GRPC_ENABLED=true
WEAVIATE_GRPC_ENDPOINT=weaviate:50051

# 批量导入设置
WEAVIATE_BATCH_SIZE=100

验证步骤

完成迁移后，验证一切是否正常工作：

1. 检查 Weaviate 连接

验证 Weaviate 可访问并运行正确版本：

# 检查 HTTP 端点和版本
curl http://your-weaviate-host:8080/v1/meta | jq '.version'

# 应返回 1.27.0 或更高

2. 验证 Dify 连接

检查 Dify 日志以确认成功连接 Weaviate：

docker compose logs api | grep -i weaviate

查找指示成功连接的消息，没有”No module named ‘weaviate.classes‘“错误。

3. 测试知识库创建

登录 Dify 实例
导航到知识库部分
创建新知识库
上传测试文档（PDF、TXT 或 MD）
等待索引完成
检查状态是否从”QUEUING”→“INDEXING”→“AVAILABLE”

如果文档卡在”QUEUING”状态，请检查 Celery worker 是否正在运行：docker compose logs worker

4. 测试向量搜索

创建或打开具有知识库集成的聊天应用程序
提出应从知识库检索信息的问题
验证返回的相关结果具有正确的分数
检查引用/来源链接是否正常工作

5. 验证 gRPC 性能

如果启用了 gRPC，你应该看到性能改进：

# 检查 gRPC 端口是否可访问
docker exec -it dify-api-1 nc -zv weaviate 50051

# 在日志中监控查询时间
docker compose logs -f api | grep -i "query_time\|duration"

正确配置 gRPC 后，与仅使用 HTTP 的连接相比，向量搜索查询应快 2-5 倍。

故障排除

问题：“No module named ‘weaviate.classes’”

**原因：**未安装 weaviate-client v4，或仍在使用 v3。 解决方案：

# 对于 Docker 安装，请确保运行正确的 Dify 版本
docker compose pull
docker compose down
docker compose up -d

# 对于源码安装
pip uninstall weaviate-client
pip install weaviate-client==4.17.0

问题：gRPC 端口 (50051) 连接被拒绝

**原因：**端口 50051 未公开、不可访问，或 Weaviate 未在其上监听。 解决方案：

对于使用捆绑 Weaviate 的 Docker Compose 用户： 端口在容器之间内部可用。除非从 Docker 外部连接，否则无需操作。

对于外部 Weaviate：

# 检查 Weaviate 是否在 50051 上监听
docker ps | grep weaviate
# 查找"0.0.0.0:50051->50051/tcp"

# 如果未公开，请使用端口映射重启
docker run -p 8080:8080 -p 50051:50051 ...

检查防火墙规则：

# Linux
sudo ufw allow 50051/tcp

# 检查端口是否正在监听
netstat -tlnp | grep 50051

问题：身份验证错误（401 未授权）

**原因：**API 密钥不匹配或身份验证配置问题。 解决方案：

验证 Weaviate 和 Dify 中的 API 密钥匹配：

# 检查 Weaviate 身份验证
curl http://localhost:8080/v1/meta | jq '.authentication'

# 检查 Dify 配置
docker compose exec api env | grep WEAVIATE_API_KEY

如果使用匿名访问：

# Weaviate docker-compose.yaml
weaviate:
  environment:
    AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
    AUTHENTICATION_APIKEY_ENABLED: 'false'

然后从 Dify 配置中删除 WEAVIATE_API_KEY。

问题：文档卡在”QUEUING”状态

**原因：**Celery worker 未运行或未连接到 Redis。 解决方案：

# 检查 worker 是否正在运行
docker compose ps worker

# 检查 worker 日志
docker compose logs worker | tail -50

# 检查 Redis 连接
docker compose exec api redis-cli -h redis -p 6379 -a difyai123456 ping
# 应返回"PONG"

# 重启 worker
docker compose restart worker

问题：迁移后性能缓慢

**原因：**gRPC 未启用或配置不正确。 解决方案：

验证 gRPC 配置：

docker compose exec api env | grep WEAVIATE_GRPC

应显示：

WEAVIATE_GRPC_ENABLED=true
WEAVIATE_GRPC_ENDPOINT=weaviate:50051

测试 gRPC 连接：

docker exec -it dify-api-1 nc -zv weaviate 50051
# 应返回"succeeded"

如果仍然缓慢，请检查 Dify 和 Weaviate 之间的网络延迟

问题：架构迁移错误

**原因：**Weaviate 版本之间的架构变更不兼容或数据损坏。 解决方案：

检查 Weaviate 日志以获取特定错误消息：
```
docker compose logs weaviate | tail -100
```
列出当前架构：
```
curl http://localhost:8080/v1/schema
```

如有必要，删除损坏的集合（⚠️ 这会删除所有数据）：

# 先备份！
curl -X DELETE http://localhost:8080/v1/schema/YourCollectionName

重启 Dify 以重新创建架构：
```
docker compose restart api worker
```

删除集合会删除所有数据。只有在有备份并准备重新索引所有内容时才这样做。

问题：Docker 卷权限错误

**原因：**Docker 容器中的用户 ID 不匹配。 解决方案：

# 检查 Weaviate 数据目录的所有权
ls -la docker/volumes/weaviate/

# 修复权限（使用错误消息中显示的 UID）
sudo chown -R 1000:1000 docker/volumes/weaviate/

# 重启服务
docker compose restart weaviate

回滚计划

如果迁移失败并且你需要回滚：

步骤 1：停止服务

cd /path/to/dify/docker
docker compose down

步骤 2：恢复备份

# 删除当前卷
rm -rf volumes/weaviate

# 从备份恢复
tar -xvf ../weaviate-backup-TIMESTAMP.tgz

步骤 3：恢复 Dify 版本

cd /path/to/dify
git checkout <previous-version-tag>
cd docker
docker compose pull

步骤 4：重启服务

docker compose up -d

步骤 5：验证回滚

检查服务是否使用旧版本运行：

# 检查版本
docker compose exec api pip show weaviate-client
curl http://localhost:8080/v1/meta | jq '.version'

# 检查错误
docker compose logs | grep -i error

如果可能，请始终先在暂存环境中测试回滚过程。在尝试重大迁移之前保留多个备份副本。

其他资源

官方文档

社区资源

迁移工具

总结

此迁移为 Dify 的向量存储功能带来了重要改进： ✓ **更好的性能：**gRPC 支持显著提高查询和导入速度（快 2-5 倍） ✓ **改进的稳定性：**增强的连接处理和错误恢复 ✓ **安全性：**访问 Weaviate 1.19.0 中不可用的安全更新和补丁 ✓ **面向未来：**访问最新的 Weaviate 功能和持续支持虽然这是一个破坏性变更，需要旧版本用户升级服务器，但其好处远远超过了迁移工作。大多数 Docker Compose 用户可以在 15 分钟内通过自动更新完成迁移。

如果你遇到本指南未涵盖的任何问题，请在 Dify GitHub Issues 页面上报告，并添加”weaviate”和”migration”标签。

快速开始

进阶部署

配置

平台指南

故障排除

​概述

​谁会受到影响？

​破坏性变更

​客户端 v4 要求

​为什么要升级？

​版本兼容性矩阵

​前提条件

​迁移路径

​路径 A：Docker Compose 用户（推荐）

​步骤 1：备份数据

​步骤 2：更新 Dify

​步骤 3：监控启动

​步骤 4：验证迁移

​路径 B：外部/自托管 Weaviate

​步骤 1：备份 Weaviate 数据

​步骤 2：停止 Weaviate 实例

​步骤 3：升级 Weaviate 服务器

​步骤 4：验证 Weaviate 升级

​步骤 5：更新 Dify 配置

​步骤 6：更新 Dify

​步骤 7：验证迁移

​旧版本的数据迁移

​自动迁移

​手动迁移（如果自动迁移失败）

​1. 从旧版本导出数据

​2. 将数据导入新版本

​配置变更

​新环境变量

​WEAVIATE_GRPC_ENDPOINT

​更新的环境变量

​完整配置示例

​验证步骤

​1. 检查 Weaviate 连接

​2. 验证 Dify 连接

​3. 测试知识库创建

​4. 测试向量搜索

​5. 验证 gRPC 性能

​故障排除

​问题：“No module named ‘weaviate.classes’”

​问题：gRPC 端口 (50051) 连接被拒绝

​问题：身份验证错误（401 未授权）

​问题：文档卡在”QUEUING”状态

​问题：迁移后性能缓慢

​问题：架构迁移错误

​问题：Docker 卷权限错误

​回滚计划

​步骤 1：停止服务

​步骤 2：恢复备份

​步骤 3：恢复 Dify 版本

​步骤 4：重启服务

​步骤 5：验证回滚

​其他资源

​官方文档

​社区资源

​迁移工具

​总结

概述

谁会受到影响？

破坏性变更

客户端 v4 要求

为什么要升级？

版本兼容性矩阵

前提条件

迁移路径

路径 A：Docker Compose 用户（推荐）

步骤 1：备份数据

步骤 2：更新 Dify

步骤 3：监控启动

步骤 4：验证迁移

路径 B：外部/自托管 Weaviate

步骤 1：备份 Weaviate 数据

步骤 2：停止 Weaviate 实例

步骤 3：升级 Weaviate 服务器

步骤 4：验证 Weaviate 升级

步骤 5：更新 Dify 配置

步骤 6：更新 Dify

步骤 7：验证迁移

旧版本的数据迁移

自动迁移

手动迁移（如果自动迁移失败）

1. 从旧版本导出数据

2. 将数据导入新版本

配置变更

新环境变量

WEAVIATE_GRPC_ENDPOINT

更新的环境变量

完整配置示例

验证步骤

1. 检查 Weaviate 连接

2. 验证 Dify 连接

3. 测试知识库创建

4. 测试向量搜索

5. 验证 gRPC 性能

故障排除

问题：“No module named ‘weaviate.classes’”

问题：gRPC 端口 (50051) 连接被拒绝

问题：身份验证错误（401 未授权）

问题：文档卡在”QUEUING”状态

问题：迁移后性能缓慢

问题：架构迁移错误

问题：Docker 卷权限错误

回滚计划

步骤 1：停止服务

步骤 2：恢复备份

步骤 3：恢复 Dify 版本

步骤 4：重启服务

步骤 5：验证回滚

其他资源

官方文档

社区资源

迁移工具

总结