2026 年 9 月 12 日，Dify 发布 1.17.1。这是一次覆盖面很广的稳定性更新：新增知识库 API 密钥范围控制、工作流键盘移动、插件市场创作者主页等功能，同时集中修复了知识库文档解析、模型供应商迁移、工作流人机交互、Agent 会话记忆、服务 API 分页、OpenAPI 合约、并发死锁等大量问题。
但这次升级有一个必须先看的风险点：使用内置 Weaviate 的自托管部署，在启动 1.17.1 之前必须手动、分阶段升级，否则可能静默且永久性地破坏向量检索能力。这篇教程按「先自查、再备份、后升级、终校验」的顺序，把每一步写清楚。
Step 1：先判断你属于哪一类部署
升级前先把部署形态搞清楚，这决定了后面要不要做分阶段升级：
| 部署形态 | 是否受影响 | 要不要分阶段升级 Weaviate |
|---|---|---|
| 使用内置 Weaviate（默认 docker-compose 常见形态） | 受影响 | 必须 |
| 使用外部 Weaviate | 不受影响 | 不需要 |
| 使用其他向量数据库（如 pgvector 等） | 不受影响 | 不需要 |
| 全新部署 1.17.1 | 不受影响 | 不需要 |
# ① 看当前 Dify 版本
docker compose exec api cat /app/api/VERSION 2>/dev/null || \
docker compose images | grep -i dify
# ② 看向量库类型：docker-compose 里是否有 weaviate 服务
grep -n -i "weaviate\|VECTOR_STORE" docker-compose.yaml .env 2>/dev/null
# ③ 看内置 Weaviate 当前镜像 tag
docker compose images | grep -i weaviate如果第 ② 步显示 VECTOR_STORE=weaviate 且第 ③ 步看到内置 weaviate 容器，请务必按 Step 3 做分阶段升级。直接拉新镜像重启的后果不是报错，而是向量检索「看起来正常、实际失效」——这种静默故障最难排查。
Step 2：升级前备份
# 停掉服务（避免备份期间写入）
docker compose down
# 备份 PostgreSQL
docker compose up -d db
docker compose exec -T db pg_dump -U postgres dify > backup_dify_$(date +%Y%m%d).sql
# 备份关键数据卷（名称以 docker volume ls 实际输出为准）
docker volume ls | grep -i "weaviate\|dify"
docker run --rm -v <weaviate_volume>:/data -v "$PWD":/backup alpine \
tar czf /backup/backup_weaviate_$(date +%Y%m%d).tar.gz -C /data .ls -lh backup_*）。升级翻车时，能不能在半小时内回到原状态，取决于这一步做没做。Step 3：分阶段升级内置 Weaviate（关键步骤）
内置 Weaviate 服务将从 1.27.0 升级至 1.39.2，跨越 12 个小版本。官方明确说明：直接跳过中间版本并不受支持。正确做法是沿着官方升级指南，逐段推进，每一段都让数据完成迁移后再进入下一段。
# 思路示意（具体中间版本号与步骤务必照官方升级指南执行）
# 1) 固定当前版本，确认数据完好
docker compose images | grep -i weaviate
# 2) 按官方指南逐段提升 tag，每段：改 tag → 启动 → 等待迁移完成 → 校验 → 再进下一段
# 例如 1.27.x → 1.28.x → ... → 1.39.2（不要跳段）
# 修改 .env 或 docker-compose 中的 weaviate 镜像 tag 后：
docker compose up -d weaviate
docker compose logs -f weaviate # 观察迁移日志，出现错误立即停这是本篇最不能省的一步。跳过中间版本可能导致向量索引结构损坏，且损坏是静默的——应用能启动、接口能返回，但检索结果开始变得不准确。等你发现「回答质量下降」时，往往已经过了很久，排查成本极高。若你不确定中间版本序列，请先查阅官方升级指南再动手，不要凭猜测推进。
Step 4：升级 Dify 到 1.17.1
# 拉取 1.17.1 镜像（tag 以官方发布为准）
docker compose pull
# 启动
docker compose up -d
# 跟踪 API 日志，确认数据库迁移与插件初始化完成
docker compose logs -f api | tail -1001.17.1 的修复面很广，其中和工作流稳定性直接相关的有：工作流人机交互（human-in-the-loop）问题、Agent 会话记忆问题、服务 API 分页、并发死锁。如果你此前被这些 bug 困扰过，升级后建议按原复现路径各回归一遍，确认确实修好了。
Step 5：升级后必做——知识库重新导入
这次更新修复了知识库部分多种「内容在没有报错的情况下被错误索引」的问题。关键在于：已经建立的索引文本不会自动修复，升级完成后需要重新导入。受影响的文档类型包括 CSV、Notion、Excel、PDF、网页抓取、Markdown。
| 文档类型 | 升级后动作 | 验收方式 |
|---|---|---|
| CSV / Excel | 重新导入并重建索引 | 抽一行已知数据，确认能被检索命中 |
| Notion / 网页抓取 | 重新同步 | 用原文里的特有短语做检索测试 |
| PDF / Markdown | 重新上传解析 | 确认分段边界正常，无整段丢失 |
Step 6：顺手把知识库密钥权限收紧
1.17.1 新增了知识库 API 密钥的范围控制。过去密钥以整个工作区为范围授权，一个密钥可以读写租户下的全部知识库；要让某个集成访问一个知识库，实际上等于给了它访问所有知识库的权限。现在可以按知识库范围授权。
# 落地建议（界面操作，示意流程）
# 1) 列出所有外部集成与其实际需要访问的知识库
# 2) 为每个集成新建一个「仅限该知识库」的密钥
# 3) 替换旧的宽权限密钥，观察一周无异常后吊销旧密钥
# 4) 把密钥登记进密钥管理系统，不要散落在配置文件里替换密钥时注意灰度。直接吊销旧密钥会让线上集成立刻失败。建议新旧并存一段时间，确认调用方全部切换后再吊销，并保留操作记录便于回溯。
常见问题 FAQ
Q1：我用外部 Weaviate，还需要分阶段升级吗？
不需要。本次跨 12 个版本的升级只针对内置 Weaviate。使用外部 Weaviate 或其他向量数据库的部署不受影响，按常规流程升级 Dify 本体即可。
Q2：全新部署会踩这个坑吗？
不会。全新部署直接以 1.39.2 初始化，没有历史数据需要迁移。风险只存在于「已有内置 Weaviate 数据、想原地升级」的场景。
Q3：升级后检索变慢或不准，先查什么？
按这个顺序排查：① 内置 Weaviate 是否真的完成了逐段迁移（看容器日志）；② 受影响的知识库是否已重新导入（旧索引不会自动修复）；③ 检索参数是否在升级中被重置。前两项是本次升级的特有原因，优先排查。
Q4：能不能直接跳过 1.17.1，等下一个版本？
如果当前版本运行稳定、也没有被上述 bug 影响，可以等。但要注意后续版本可能同样要求分阶段升级 Weaviate，拖延只会让跨越的版本数变多。建议在低峰期按官方指南做一次，把技术债清掉。
Q5：回滚方案是什么？
用 Step 2 的数据库与数据卷备份回滚。注意：如果 Weaviate 已经完成部分迁移，回滚时需要把数据卷一起恢复，只回滚应用镜像会导致版本不匹配。目前官方及行业暂未披露更多细节，后续将持续跟进迭代动态。