Dify 1.19.0 升级实操：嵌套工作流逐层追踪、App 包 v2 带走 Workflow Tools 与 ops_trace_v2 滚动队列

生产里最难受的 Dify 排障，是工作流套工作流：外层看着正常，里面某次工具调用悄悄跑偏，控制台只能看到一层结果。1.19.0 把这条链路补上了——外部追踪工具现在能看到被调用 Workflow Tool 内部的执行步骤；同时导出的应用包会把工具背后的工作流一起带走。代价是这次升级牵动镜像、插件守护进程、环境变量分层和追踪队列，属于需要停机窗口的运维操作。本教程按官方 v1.19.0 发布说明六步走完，每一步都给出可核对的命令与验收点。

🧩 适合谁：自托管 Dify 的平台 / 运维工程师，尤其是跑嵌套工作流或需要跨工作区迁移应用的团队。前置准备：Docker Compose 部署的 Dify 实例、可停机维护窗口、数据库与向量库与上传文件的备份空间、一个已配置好的外部追踪服务商（如 Langfuse）、目标工作区具备工具管理权限与应用配额。纯云端版用户用不到升级步骤，可直接跳到 Step 5 与 Step 6 了解新能力。

先弄清：1.19.0 到底改了哪三层

官方发布说明的标题是「Trace Your Workflows, Layer by Layer」，三条主线各自对应一类运维动作：

变化	官方说明	本教程落在哪步
嵌套工作流追踪	外部追踪包含被调用 Workflow Tool 内部持久化的执行帧，挂在调用它的 Tool span 下	Step 5
Workflow Tools 随 App 包走	`.ifpkg` 包含工具背后的工作流（绑定版本、含传递依赖），导入时复用已有 / 重建缺失	Step 6
部署面调整	Compose 最低 2.35.0、插件守护进程 0.6.14-local、env 分层、追踪队列切换	Step 1 到 4

先读官方 Upgrade guide 再动手：发布说明用 Important 标出「部署前阅读升级指南」，并明确要求保留已有环境文件、组件一起升级、滚动部署期间使用新的追踪队列。本教程是对该指南的落地拆解，不替代原文；生产实例请以官方发布页与升级指南为最终依据。

Step 1：备份并核对版本门槛

1 Compose 版本、备份清单、维护窗口

官方把备份放在升级指南的开头：数据库、向量库数据、上传文件、Agent 快照与工作区存储、部署密钥、环境文件都要留。另外 1.19.0 把 Docker Compose 最低版本提到 2.35.0，原因是根级 .env 覆盖需要它才能正确生效。

# 核对 Compose 版本，必须 >= 2.35.0
docker compose version

# 发布标签核对（在 dify 仓库目录内）
git fetch --tags
git tag -l "1.19*"

# 备份清单（按官方升级指南逐项确认已落盘）
# 1. 数据库            2. 向量库数据      3. 上传文件
# 4. Agent 快照 / 工作区存储
# 5. 部署密钥 secrets  6. 全部环境文件 env / .env
# 建议用维护窗口做单栈升级，不要在业务高峰滚动

🔎 从 1.18.0 升到 1.19.0 会应用 六个迁移 revision，官方给出的终点是 53c10126d551。保持 MIGRATION_ENABLED=true 让 API 启动时自动跑完整链，或用你自己的托管迁移流程跑完再起 worker——两者选一，不要混用。

备份必须可恢复：只导出数据库而不留向量库、上传文件与 Agent 工作区，恢复后会出现检索缺块、文件丢失。官方还要求保留已有的 Local sandbox 认证 token 与 PASSWORD_PEPPER 不变；这两项一旦变了，已有会话与沙箱鉴权会失效。

Step 2：切换到 1.19.0，组件版本对齐

2 停服、切标签、拉镜像、起服务

官方给的是单栈部署的标准序列。重点是镜像版本要成组对齐：API、worker、web、Agent Backend、Local sandbox 都是 1.19.0，插件守护进程单独是 0.6.14-local。

cd dify/docker
docker compose stop -t -1
git fetch --tags
git checkout 1.19.0
# 在这一步把必需的配置变更合并进已有的 env 文件
docker compose pull
docker compose up -d

# 保持启动时迁移开启（或用托管迁移流程跑完再起 worker）
# MIGRATION_ENABLED=true

# 插件凭据在根 docker/.env 中成对配置
# PLUGIN_DAEMON_KEY=...
# PLUGIN_DIFY_INNER_API_KEY=...

💡 官方说明：端口、卷路径、profiles、健康检查调度仍属于根级配置项；插件守护进程与其客户端要拿到一致的 PLUGIN_DAEMON_KEY 与 PLUGIN_DIFY_INNER_API_KEY。若从 1.18.0 之前升上来，还要先照 1.18.0 的升级指南操作一遍。

别只升 API：官方明确要求 API、worker、web、Agent Backend、Local sandbox 用同一版本镜像一起升，并单独指定插件守护进程 0.6.14-local。版本错配是这类升级里最常见的问题来源；另外发布说明提到，滚动部署要走单独的追踪队列顺序，不要把新旧消费者混在同一批里。

Step 3：理清 env 分层，别覆盖本地配置

3 defaults、api-worker.env、shared.env 的优先级

1.19.0 把环境文件做了一次归类。官方说明：跟踪的 defaults 会自动加载，服务级自定义写对应的本地 .env，根级 docker/.env 放部署输入与显式覆盖；旧的 shared.env 仍受支持，但优先级低于新的 api-worker.env。

# 读取顺序（官方 Upgrade guide 第 5 条）
# 1. docker/envs/core-services/shared.env      （旧，仍兼容）
# 2. docker/envs/core-services/api-worker.env  （新，冲突时覆盖旧值）
# 3. 根 docker/.env                            （最高优先级）

# 跟踪的默认值文件会自动加载，不必手工复制
docker/envs/**/*.defaults
docker/envs/core-services/api-worker.defaults

# 升级动作：保留现有 .env 就地修改，不要用新模板整份覆盖
# 顺手检查：被旧模板固定下来的空赋值与过期值

✅ 官方给了一个省事做法：保留一份未改动的 api-worker.defaults，就能让已有的 shared.env 自定义继续生效。改配置前先备份，逐项对照 defaults 文件里写明的覆盖路径。

整份覆盖模板是高风险操作：把新版本模板直接盖到本地 .env，会丢掉你改过的端口、密钥与卷路径。官方要求「保留已有 env 文件并就地编辑」，并提醒复查意外的空赋值与旧模板固定下来的值。

Step 4：追踪队列滚动迁移，新旧并行到排空

4 OPS_TRACE_QUEUE 与自定义队列清单

这是本次升级最容易翻车的一步。新任务默认进 ops_trace_v2，API、worker、Beat 三处必须一致；如果你自定义过 CELERY_QUEUES、CELERY_WORKER_QUEUES 或 --queues，要手动把新队列加进去。

# 新增环境变量（官方 Environment variables 表）
OPS_TRACE_QUEUE=ops_trace_v2
OPS_TRACE_EXPORT_MAX_ATTEMPTS=6
ENABLE_TRACE_PAYLOAD_SWEEP_TASK=true
APP_PACKAGE_MAX_WORKFLOW_TOOLS=20

# 自定义过队列的，把新队列加进三处清单
# CELERY_QUEUES / CELERY_WORKER_QUEUES / --queues

# 滚动升级期间：旧 worker 继续守 ops_trace
# 直到旧生产者与其排队 / 活动 / 预留 / 定时 / 重试任务全部完成
# 不要 purge 旧队列，也不要让已退役的 handler 去导出旧消息

# 已移除的旧变量，别再留在配置里
# OPS_TRACE_UNIFIED_ENABLED
# OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES
# OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS
# OPS_TRACE_PARENT_CONTEXT_TTL_SECONDS

🔎 其它新变量：OPS_TRACE_EXPORT_MAX_ATTEMPTS 默认 6 次总尝试，ENABLE_TRACE_PAYLOAD_SWEEP_TASK 默认开启每日清理孤儿追踪载荷，APP_PACKAGE_MAX_WORKFLOW_TOOLS 默认 20，GUNICORN_KEEP_ALIVE 默认 10 秒。追踪凭据保持只写：留空即保留已存值，但改了目标 host、endpoint 或 URL 就得重新填一次密钥。

新旧消费者别混跑：官方说明新管线与旧管线用不同的导出处理器，提前 purge 旧队列或让新处理器消费旧消息都会丢追踪数据。单栈部署按 Step 2 一次切完更简单；真要滚动，严格照官方 tracing rollout guide 的顺序执行，并确认 API、worker、Beat 对 OPS_TRACE_QUEUE 的取值一致。

Step 5：打开嵌套工作流追踪并验收

5 外部追踪里能看到 Tool 内部的子步骤

1.18.0 先在控制台里做了下钻，1.19.0 把它带到外部追踪：被调用 Workflow Tool 内部持久化的执行帧，会挂在调用它的 Tool span 之下，重复调用与失败调用各自保留位置，格式化提示词、响应、token 用量与追踪链接都跟着每次 LLM 调用。

# 官方列出的共享追踪接口服务商（择一，沿用你已有的那套）
# Langfuse / LangSmith / Opik / Weave / Arize / Phoenix
# Aliyun / MLflow / Databricks / Tencent

# 验收动作（在应用侧操作，不是 CLI 命令）
# 1. 升级后新建一个含 Workflow Tool 的工作流并运行
# 2. 打开外部追踪，展开 Tool span
# 3. 应能看到内层执行步骤、格式化消息与 token 用量
# 4. 同一工具调用两次，确认两次的子步骤都在且位置正确
# 5. 保存的 provider 设置继续生效，无需重新配置

✅ 预期效果：从外层工作流一路点到内层 LLM 调用，层级完整；失败的那次调用仍留在追踪树里，不会被成功调用盖掉。可重试的导出会用确定性标识重发同一追踪单元，避免重复记录。

三个限制写进验收单：① 更丰富的层级只对新执行生效，历史追踪不会回填，升级后要重新积累数据；② 独立发起的嵌套工作流运行仍是单独 trace，只通过父标识关联；③ 追踪凭据是只写的，界面不回显明文。把「历史查不到」当成升级失败去回滚，是这一版最常见的误判。

Step 6：导出带工具的 App 包，并用 difyctl 管 Skill

6 .ifpkg v2 与六条 Skill 命令

导出应用时，.ifpkg 现在会把 Workflow Tools 背后的工作流按绑定版本一起打包，含传递依赖；导入时复用目标工作区已有的工具，缺失的会被重建、发布、注册并重映射引用。所有应用导出统一升级为 package format v2。

# 官方给出的六条 difyctl Skill 命令
difyctl get skill                     # 列出，支持关键词与标签过滤
difyctl describe skill                # 详情、草稿哈希、最新已发布版本
difyctl get skill version             # 列出已发布版本
difyctl export skill                  # 导出草稿或指定已发布版本为 ZIP
difyctl import skill --files <dir>    # 从本地文件新建或覆盖草稿
difyctl publish skill                 # 把草稿发布为新版本

# 升级配套命令
difyctl help                          # 发现当前服务端的操作目录
difyctl install skills <dir>          # 刷新已安装的 agent skills
# 工作流 / Chatflow 自动化改用 stop.run；消息类应用用 stop.task

💡 导入行为按官方说明有四个前提：目标端 importer 要先升级到能读 v2；导入需要工具管理权限与足够的应用配额；默认最多打包 20 个工具工作流；v1 导入仍受支持，但显式 YAML 导出不携带工具依赖。导入失败时，已创建的应用会被清理。

Skill 操作的两个坑：这些操作需要账号调用者、对应工作区权限且 Skills 已启用；import 不会自动 publish，而覆盖已有 Skill 在官方操作目录里被归类为破坏性操作。先在测试工作区跑一遍 export / import / publish，再动生产 Skill。

常见问题 FAQ

现象	原因与处理
升级后追踪仍只有一层	层级只对新执行生效；重新运行一次工作流再看，历史 trace 不回填
导入 v2 包被拒绝	目标端 importer 版本过旧，先把目标实例升到 1.19.0 再导入
导入后工具还是缺	检查工具管理权限、应用配额，以及单包 20 个工具工作流的默认上限
滚动升级后追踪断档	API / worker / Beat 的 `OPS_TRACE_QUEUE` 不一致，或自定义队列清单漏了新队列
服务起不来且报配置错	确认 Compose 已到 2.35.0，且没有用新模板整份覆盖本地 env 文件
源码部署编译失败	官方要求 Python 3.13、Node.js 24.22.1 或更高的 24.x、pnpm 12.16.1，且 pnpm 不再代装 Node

做到哪一步算成功

四条验收线：① docker compose version 不低于 2.35.0，服务按 1.19.0 镜像组正常起来且迁移链完成；② 追踪里能从外层工作流展开到内层 LLM 调用，重复与失败调用各占其位；③ 导出一个含 Workflow Tool 的应用，在另一个已升级的工作区导入后工具可直接使用；④ difyctl get skill 能列出工作区 Skill，且你在测试工作区完成过一次 export / import / publish 闭环。

源码部署补充：官方给出的源码路线是 uv sync --project api --frozen、uv run --directory api flask db upgrade、pnpm install --frozen-lockfile，随后重建 web 并用同一版本重启 API、worker、scheduler 与 Agent 服务。全链路涉及停服与真实密钥，请先在预发环境完整演练。

← 返回教程中心