如何用 app-migration-wizard 将 Dify 的 workflow 与 advanced-chat 应用连同自定义工具迁移到另一环境-迪斯科星球

如何用 app-migration-wizard 将 Dify 的 workflow 与 advanced-chat 应用连同自定义工具迁移到另一环境

【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify

当你要把一个 Dify 工作空间里的 workflow 应用、advanced-chat（chatflow）应用，以及它们引用的自定义 API 工具、workflow 工具一并搬到另一个 Dify 环境（例如从 staging 到 production）时，官方文档给出的推荐路径是：在源环境运行交互式导出向导app-migration-wizard生成迁移包 JSON，再把该 JSON 复制到目标环境用import-app-migration导入。整个过程只支持单源工作空间导出，源与目标工作空间名称不需要一致。完整操作依据见 docs/cross-env-app-migration/README.md。

迁移包能带走什么

在开始之前需要明确边界，这决定了导入后哪些东西能直接跑、哪些要在目标环境补配置：

workflow 应用和 advanced-chat 应用本身；
自定义 API 工具提供者（Custom API tool providers）；
workflow 工具提供者（workflow tool providers）；
MCP 工具提供者：只有在导出时显式选择了包含密钥（Include secrets in output JSON?选yes）才会完整导出；
MCP 工具、内置工具、插件工具在没有密钥导出时只记录为依赖元数据——这些工具必须已经在目标环境安装并配置好。

源环境：运行导出向导

在源环境的 Dify 代码目录下执行（以下命令来自文档，source .venv/bin/activate为文档给出的 venv 激活方式）：

cd api source .venv/bin/activate uv run flask app-migration-wizard

该命令没有任何 CLI 选项，全部通过交互式输入完成。交互步骤依次为：

Source tenant：列出所有工作空间（名称 + ID），按编号选择要导出的源工作空间。
App selection：列出该空间下所有workflow与advanced-chat应用（名称、模式、ID），输入all、单个编号或逗号分隔的编号完成选择。
Automatically export tools referenced by selected apps?：推荐选yes（默认即y）。向导会扫描所选应用的工作流图和 agent 工具配置，自动发现并去重被引用的自定义 API 工具、workflow 工具和 MCP 工具引用，降低"导出的应用引用了目标环境缺失的提供者"的概率。
Export additional tools manually?：可选（默认n）。仅当你需要迁移未被所选应用引用的工具时才选yes，随后按类别（Custom API tools / Workflow tools / MCP tools）编号勾选。
Include secrets in output JSON?：默认no。选no时，workflow/app DSL 的密钥值会被省略或掩码、API 工具凭据被省略、MCP 提供者只导出依赖元数据；选yes时要按敏感数据对待该 JSON（包内可能含 API 工具凭据、DSL 密钥值、MCP 服务器 URL、headers、认证数据和缓存的工具列表）。
Create or reuse app API tokens during import?：默认no。选yes时，导入会为没有 token 的已导入应用创建 app API token，或复用已有 token。
Import ID strategy：preserve-id（默认，保留源端 ID，跨环境迁移时能更好地保持 workflow 引用稳定）或generate-new-id（由目标环境生成新 ID，并通过迁移 ID 映射重写引用）。
Import conflict strategy：目标资源已存在时的处理方式——fail（遇冲突即停，已提交资源不回滚）、skip（保留目标资源、跳过该项）、update（就地更新），向导默认update。
Output path：迁移包输出路径，默认migration-data-YYYYMMDD-HHMMSS.json；若文件已存在会追问是否覆盖。
Write migration package?：向导先打印完整摘要（源租户、所选应用、自动与手动工具清单、secrets、token、ID 策略、冲突策略、输出路径），确认后才真正写出 JSON，并输出一份导出报告。

命令成功后终端会打印Output written to <文件名>（文档实现见 api/commands/data_migration.py）。记下实际生成的 JSON 文件名，下一步导入要用到。

目标环境：导入迁移包

把上一步生成的 JSON 复制到目标环境，执行：

cd api source .venv/bin/activate uv run flask import-app-migration \ --input migration-data-20260528-120000.json \ --target-tenant "production Workspace"

migration-data-20260528-120000.json是文档中的示例文件名，替换为你在源环境向导实际生成的文件名；--target-tenant填写目标工作空间名称或 UUID。

常用可选参数：

--input：必填，迁移包 JSON 路径；
--target-tenant：当包元数据中已含目标租户时可省略；显式指定会覆盖包元数据，对需要复用的包更稳妥；
--operator-email：指定目标租户中执行导入的账号邮箱；省略时使用目标租户中最早的 owner 账号；
--id-strategy、--conflict-strategy：临时覆盖包内记录的 ID 策略与冲突策略，取值含义同向导中的说明；
--create-app-api-token-on-import/--no-create-app-api-token-on-import：覆盖导入时的 app API token 创建行为。

如何判断导入结果

导入完成后命令会打印一份报告，包含：解析后的目标租户与操作者、created/updated/skipped 的资源清单、未解析的依赖（unresolved dependencies）、app API token 数量，以及用于重写引用的 ID 映射。核对报告时的判读方式：

标记为dependency-only、skipped或unresolved的条目通常需要人工跟进；
使用preserve-id时重点看 ID mappings 部分，确认源到目标的 ID 对应关系符合预期；
若导入因冲突停止（conflict_strategy=fail），已提交的部分不会回滚，需要查看报告确认哪些资源已落库后决定改用skip还是update重新导入。

按文档的要求，导入完成不代表可以直接投产：如果导出时include_secrets为no，需要在目标工作空间里重新填写自定义 API 工具凭据、手工创建或配置对应的 MCP 提供者，并逐个复核已迁移 workflow/chatflow 的工具节点、agent 工具配置、环境变量、应用变量和凭据相关设置后再投入生产。

目标环境的两个前置条件

内置工具与插件工具不会被序列化进迁移包，只作为依赖记录。导入前请确认目标环境已安装并配置好所需的内置/插件工具；
MCP 提供者在include_secrets=false时是 dependency-only，必须在运行已迁移 workflow 前在目标空间手工配置好对应的 MCP 提供者。如果希望包直接携带完整 MCP 连接配置，用include_secrets=true重新导出，并按敏感数据传输该 JSON（文档建议：仅在受控的一次性迁移中这样做，导入后按安全策略删除该包）。

可选：脚本化导出用于重复自动化

如果同样的迁移需要可重复执行而不是人工交互，文档给出的替代路径是：

cd api source .venv/bin/activate uv run flask app-migration-template --output export-config.json

编辑生成的export-config.json（关键字段：source_tenant.name/source_tenant.id、apps.modes支持workflow与advanced-chat、apps.all、include_referenced_tools、additional_tools、include_secrets，以及import_options下的create_app_api_token_on_import、id_strategy、conflict_strategy），然后：

uv run flask export-app-migration \ --input export-config.json \ --output migration-package.json

再按上节同样方式执行import-app-migration --input migration-package.json --target-tenant "..."。注意模板里source_tenant.mode必须保持single；source_tenant.id与name同时填写时两者必须匹配；--output指向已存在文件时命令会失败，需加--overwrite。

已知限制

只支持单源工作空间导出，不能把多个源空间的混在一起打包；
conflict_strategy=fail停止时不回滚已提交资源；同名 ID 在目标端被不同资源复用时，使用update前必须人工确认；
generate-new-id下，workflow DSL 中的提供者引用会"尽可能"通过 ID 映射重写，但 dependency-only 的依赖（如未带密钥导出的 MCP）仍然需要目标端手工配置，内置/插件工具也永远不做映射。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析