Dify 1.18.0 踩坑实录：13 个坑，劝你别硬升- 大数跨境

AI4SE

2026-10-28

导读：大家好，我是你们的 AI 老司机。上一篇我们聊了 Dify 1.18.0 的重磅亮点——Agent 自主选路、.ifpkg 打包、嵌套工作流下钻，确实香。

大家好，我是你们的 AI 老司机。

上一篇我们聊了 Dify 1.18.0 的重磅亮点——Agent 自主选路、.ifpkg 打包、嵌套工作流下钻，确实香。但发布这几天，GitHub Issues 和各大社群里「升级翻车」的反馈也集中爆发了。

这篇只聊一件事：坑。

我把官方升级指南、社区 Issue 和实测反馈扒了一遍，按「升级阶段」整理出 13 个高频坑，每条都带上报错关键字和救命解法，方便你对着日志排查。

建议先点赞收藏，升级前逐条对照，能帮你避开一次深夜救火。

一张图看懂升级顺序

全量备份 → 维护窗口 → 配齐沙箱令牌 → 四件套同版本拉新
        → 跑数据库迁移（老库补刀）→ 放在途任务、再换 worker → 验证登录和 Agent

记住这个口诀，下面的坑基本都绕得开。我们按升级的真实时间线一个个来。

一、启动阶段：容器直接起不来

⚠️ 坑 1：local_sandbox 无限重启 / Exited（最高频）

现象：docker compose ps 里 local_sandbox 反复退出，日志出现 --require-auth-token 相关报错。
根因：1.18 强制沙箱使用非空令牌 DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN，缺失 / 为空 / 纯空格都会在初始化前直接退出。
两个隐藏雷：

令牌必须写进共享插值源（docker/.env、当前 shell 或 --env-file），让 agent_backend 和 local_sandbox 拿到同一个值。只写在 docker/envs/xxx.env 里不生效——Compose 的显式 environment 会覆盖它，哪怕值是空的也覆盖。
旧的 1.17.1 沙箱镜像根本不认 --require-auth-token，必须 docker compose pull 拉到配套的 1.18.0 镜像。

⚠️ 坑 2：Agent 组件半新半旧，会话快照读不回

现象：Agent 节点报错、历史会话恢复失败、直连 backend 的服务返回协议错误。
根因：/runs 接口只收 composition v2、拒绝 v1；会话快照一旦被新版保存为 v2，旧运行时永久读不回来。
解法：API / worker / agent_backend / runtime 四个镜像必须同窗口、同版本一起换，禁止滚动升级；外部直连 Agent Backend 的程序同步改造请求格式。

⚠️ 坑 3：Agent Backend 起不来或报 base_url 错误

报错关键字：ValueError: base_url is required when creating a real Agent backend client
解法：确认 AGENT_BACKEND_BASE_URL=http://agent_backend:5050；自定义部署时检查 agent_backend 依赖的 redis、plugin_daemon 是否在同一 Docker 网络。

二、登录阶段：全员登不进去

⚠️ 坑 4：PASSWORD_PEPPER 手滑开启 → 密码哈希全失效

老库原本没配 pepper，升级时这个变量必须留空。一旦手贱填了新值，现有账号密码哈希立刻全部失效，只能走全员重置密码。
真要启用：所有 api / worker 实例用同一个值、随数据库一起备份，Compose 里建议放 docker/envs/core-services/api.env，别让无关服务拿到。
同类提醒：SECRET_KEY 也别乱换，更换会导致已有会话 / 加密数据异常，且 api 与 api_websocket 必须一致。

三、数据库 / 迁移阶段

⚠️ 坑 5：plugin daemon 循环重启（跳级升级经典雷）

报错关键字：SQLSTATE 23505、duplicate plugin_unique_identifier（Issue #38276）
解法：到 dify_plugin.plugins 表对重复标识去重（保留最新一条），再重启 daemon。

⚠️ 坑 6：只跑 upgrade-db 不够，老库还要补数据迁移

1.15.0 之前的库，除了 flask upgrade-db，还要依次执行：

docker compose exec api flask data-migrate legacy-model-types          # 先 dry-run
docker compose exec api flask data-migrate legacy-model-types --apply
docker compose exec api flask backfill-plugin-auto-upgrade              # 必须在 upgrade-db 之后

否则可能出现模型类型显示异常、插件自动升级策略缺失。

⚠️ 坑 7：Weaviate 1.27 老用户躲不掉分段升级

1.18 内置向量库只从 1.39.2 小版本升到 1.39.13。
你要是还停在 1.27，必须先按 1.17.1 要求的逐段路径升到 1.39，再上 1.18；直接跳级可能损坏向量索引，导致知识库检索全废。

四、功能阶段：起来了，但行为不对

⚠️ 坑 8：历史 Agent 人工确认（HITL）表单无法恢复

旧的 Agent 专用 AskHuman 工具和延迟恢复路径已被删除，升级前处于挂起状态的 Agent 表单直接作废（共享工作流里的 Human Input 节点不受影响）。
建议：升级前先把在途的 Agent 人工确认任务全部处理完。

⚠️ 坑 9：Agent V2 的几个「反直觉」限制

默认只在 Workflow 中出现，Chatflow 里被隐藏（不支持多轮上下文），强开需 NEXT_PUBLIC_ENABLE_AGENT_V2_IN_CHATFLOW=true。
输出路由（Output Routes）至少 2 条分支；开启后不能再配节点级默认值容错；路由结果是缓冲输出，不会逐字流式。
用 vLLM / 部分自建模型：function calling 默认关闭，要加 --enable-auto-tool-choice --tool-call-parser <parser>；工具名不能带点（shell.run 已改名 shell_run）。
pydantic-ai 在 api 和 dify-agent 两端版本必须锁成一致，错配会出现「Agent 跑通了但回答为空」的诡异现象。

⚠️ 坑 10：KnowledgeFS 新 Agent 知识库不是开箱即用

默认 Compose 关闭，需要独立数据库与迁移、Dify 签名密钥、embedding / reasoning / rerank 全套模型配置、工作区切换开关。
就绪探针必须过 /ready，只看 /health 不算数。
当前默认镜像只有 amd64 架构，ARM 服务器（含部分国产芯片 / Mac 服务器）直接跑不起来；标准 API 镜像里也不含 KnowledgeFS 引擎。
结论：先在测试环境跑通，生产别急着开。

五、性能 / 稳定性（社区长期高频）

⚠️ 坑 11：插件守护进程 worker 耗尽，Agent 卡死拖垮整个 API

默认 SERVER_WORKER_AMOUNT=1，单个慢 LLM 调用可能同步阻塞长达 600 秒；叠加 gevent 与 httpcore 连接池不协作的问题，4~8 个并发就可能偶发 httpx.ConnectError（Issue #38912、讨论 #39381）。
建议：并发量大的环境适当调高 worker 数量，并在上量前做压测。

⚠️ 坑 12：schedule_poller 常驻 Worker 的 Redis 空闲连接堆积

有生产用户观测到 Redis 连接数累积破万，原因是结果订阅的 drainer 在取消订阅后仍存活、连接不释放。
建议：长跑实例务必监控 Redis 连接数，必要时定期重启常驻 Worker 或升级到已修复版本。

⚠️ 坑 13：流程已停止，队列里的节点却仍被拉起

StopAwareReadyQueue 旧逻辑在 get() 取任务时不校验停止态，并行分支 + 单 worker 场景下，已入队任务照样执行。
这也是为什么官方强调：先等在途任务跑完、再替换旧 worker——旧消费者没有新版取消保护，可能把你「已停止」的流程又激活。

六、配置 / 认知类（不一定报错，但一样坑人）

废弃变量静默失效：GRAPH_ENGINE_MIN_WORKERS、GRAPH_ENGINE_SCALE_UP_THRESHOLD、GRAPH_ENGINE_SCALE_DOWN_IDLE_TIME 三个参数已删除，GRAPH_ENGINE_MAX_WORKERS 改为每个引擎实例的固定 worker 数（默认 10），以前的自动伸缩调优全部作废，需要重新评估。
退出码 125：开启 SHELLCTL_ENABLE_PATH_ISOLATION 后，Landlock 初始化失败会直接以退出码 125 终止任务，而不是继续执行——排障时要认识这个码。
限流桶被共用：内置 Nginx 会用解析到的地址覆盖 X-Forwarded-For。如果 Nginx 前面还挂着负载均衡或 Cloudflare，却没配「可信真实 IP」，多个访客可能共用代理的一个 IP，被塞进同一个限流桶，莫名触发 429。
权限边界收紧：启用 RBAC 后，新建知识库不再默认对全体工作区成员可见；插件默认仅工作区所有者 / 管理员可安装。团队协作要重新核对权限。
历史脏数据不会自动修：丢失的触发器订阅要手动重新绑定并重新发布；受旧版文档解析 Bug 影响的资料要重新导入 / 重建索引；内置元数据只对「已启用 + 未归档 + 索引完成」的文档重写，没有一次性回填。
源码部署门槛抬高：API 需要 Python 3.13，前端需要 Node.js 24.x + pnpm 12.10.1；新版 difyctl 必须重新 login，旧脚本里硬编码的命令路径要改成从服务端操作目录动态发现。

七、救命 Checklist（建议截图保存）

升级前

⬜完整备份：数据库、向量库、上传文件、Agent 快照 / 工作区存储、所有密钥与 env 文件
⬜安排维护窗口，通知用户暂停使用
⬜处理完在途任务与挂起的 Agent 人工确认表单
⬜Weaviate 仍在 1.27 的，先分段升到 1.39
⬜确认服务器架构（KnowledgeFS 仅 amd64）

升级中

⬜ 在共享插值源配齐在共享插值源配齐 `DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN`
⬜PASSWORD_PEPPER`PASSWORD_PEPPER` 老库保持为空
⬜API / worker / agent_backend / runtime 四件套同版本一起拉新
⬜ 优雅停止旧栈 → checkout 1.18.0 → docker compose pull →优雅停止旧栈 → checkout 1.18.0 → `docker compose pull` → `up -d`
⬜ 保持 MIGRATION_ENABLED=true，老库补跑 data-migrate 和保持 `MIGRATION_ENABLED=true`，老库补跑 `data-migrate` 和 `backfill-plugin-auto-upgrade`
⬜在途任务跑完后再替换旧 worker / resume consumer

升级后

⬜验证能正常登录（密码未失效）
⬜验证 Agent 节点、输出路由、插件调用正常
⬜检查知识库检索（向量索引完好）
⬜核对 Nginx 真实 IP / 限流、RBAC 知识库权限
⬜监控 Redis 连接数、worker 负载、插件 daemon 状态
⬜difyctl 重新登录，更新自动化脚本

标准 Compose 升级命令（执行前务必先读完官方当版 Upgrade Guide）：

cd dify/docker
docker compose stop -t -1       # 优雅停止旧栈
git fetch --tags
git checkout 1.18.0
# 在这里把必需的环境变量变更合并进现有 env 文件
docker compose pull
docker compose up -d