Dify 上手指南：从零搭建 AI Agent 工作流，私有部署实战

适用人群

这份指南适合三类用户：准备用 Dify 搭企业 AI 应用平台的开发者、已经装了 Dify 但工作流编排不知道从哪下手的团队、在 Dify / Coze / FastGPT 之间做技术选型、需要跑一遍 POC 的架构师。

目标是在 1 小时内完成私有部署 → 创建第一个应用 → 编排一个真实工作流 → 发布 API，并且知道生产环境要踩哪些坑。

前置条件

在开始之前，确认以下条件：

• 一台 Linux 服务器（阿里云 / 腾讯云 / 自建均可），最低 2C4G + 30GB 硬盘。推荐 4C8G 起步，企业级日活上千需 8C16G+。
• 已装 Docker 24+ 和 Docker Compose 2.20+。
• 至少一个可用的 LLM API Key——OpenAI / Anthropic / DeepSeek / Qwen / 智谱 / 豆包均可，Dify 支持 40+ 提供商。
• 一个真实想解决的业务场景——不要用"你好"测试 Dify，浪费部署时间也看不出工作流编排的价值。

Docker 部署（10 分钟）

Dify 社区版是 Apache 2.0 协议，完全免费可商用。官方提供 Docker Compose 一键部署：

git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
docker compose up -d
# 默认 http://localhost

启动后访问 http://<服务器IP>，首次进入会引导创建管理员账号。登录后第一件事：改默认密码 + 在"设置 → 模型供应商"里配置至少一个 LLM 和一个 Embedding 模型。

端口冲突处理：如果服务器有其他服务占用 80/443 端口，编辑 docker-compose.yaml 里 Nginx 服务的 ports:，把宿主机端口改成 8080 或其他没冲突的端口。

国内镜像加速：Docker 镜像在国内拉取可能很慢。在 .env 文件里或 Docker daemon 配置里加阿里云 / 网易 registry 镜像加速：

# /etc/docker/daemon.json
{
  "registry-mirrors": ["https://registry.cn-hangzhou.aliyuncs.com"]
}

改完执行 sudo systemctl restart docker 后重新 docker compose up -d。

配置模型

进入后台 → 设置 → 模型供应商，Dify 通过插件市场接入 40+ 提供商。必须同时配置两类模型：

1. 对话模型 LLM：GPT-5 / Claude Sonnet 4 / DeepSeek-V3 / Qwen / 豆包-Pro / Kimi K2 都行
2. 嵌入模型 Embedding：text-embedding-3-large（OpenAI）、bge-large-zh-v1.5（中文首选，可本地部署）

常见坑：只配对话模型没配嵌入模型，上传知识库后无法索引，界面显示"处理中"永远不结束。请务必两类都配。

国产模型原生支持是 Dify 在国内 toB 场景的关键优势——不像 FastGPT 需要中转，Dify 直接接 DeepSeek / Qwen / 智谱 / 文心。同一个工作流里可以"GPT-5 做复杂推理 + DeepSeek 跑日常省成本 + Ollama 本地跑敏感数据"，按任务步骤选最合适的模型。

预算敏感组合推荐：DeepSeek-V3（对话）+ bge-large-zh（嵌入 + 本地），token 便宜、中文强、完全国内闭环。

创建第一个应用

Dify 1.0 把应用拆成四种类型：

第一个应用选 Chatbot，10 分钟跑通：

1. 左侧"工作室" → "创建空白应用" → 选"聊天助手"
2. 起个名字（如"技术文档助手"）
3. 编排 prompt：写清楚角色、能力边界、输出格式
4. 可选：关联知识库（下一步会讲）
5. 调试：右侧预览窗口输入问题，看回答效果
6. 右上**"发布"** → 选渠道（Web App / API / 嵌入网页）

关键认知：Chatbot 只是热身。Dify 的真正价值在 Workflow 和 Chatflow——当你需要"多步骤逻辑 + 条件分支 + 外部工具调用"时，才需要工作流编排。

工作流编排：Dify 的核心

这是 Dify 最强的一块，也是它和 FastGPT 拉开差距的地方。进入"工作室" → 创建"工作流"应用，你会看到一块可视化画布。

节点类型

编排一个真实工作流：智能客服路由

以"电商智能客服"为例，演示 LLM 节点 + 知识检索 + 条件分支的组合：

1. 开始节点：输入变量 user_question（用户提问）
2. 问题分类节点：用 LLM 判断意图——售后退换 / 物流查询 / 商品咨询 / 其他
3. 条件分支：按分类结果路由
   • 售后退换 → 知识检索节点（查退换政策知识库）→ LLM 节点（基于检索结果生成回复）
   • 物流查询 → HTTP 请求节点（调物流 API 查运单）→ LLM 节点（格式化物流信息）
   • 商品咨询 → 知识检索节点（查商品 FAQ）→ LLM 节点（生成回复）
   • 其他 → LLM 节点（兜底回复 + 建议转人工）
4. 变量聚合节点：把四个分支的结果统一成 answer
5. 结束节点：输出 answer

这个工作流把"意图路由 + RAG 检索 + 外部 API + 兜底策略"串成一条链路。用代码写这套逻辑至少 200 行，用 Dify 拖拽 20 分钟搞定，且每一步可视化可观测。

代码执行节点的边界

代码节点用 Sandbox 执行 Python / JS，但有严格限制：

• 执行超时默认 10 秒，复杂计算会超时
• 内存限制小（默认 128MB），大列表操作会 OOM
• 不能安装第三方库，只能用标准库
• 网络请求受限（Sandbox 隔离）

生产建议：代码节点只做轻量数据转换（JSON 解析、格式化、简单计算）。复杂逻辑改成 HTTP 请求节点调外部服务——把重逻辑放在你自己的 API 里，Dify 只负责编排。

RAG 知识库配置

RAG 是 Dify 的重要能力，虽然极致精度弱于 FastGPT，但 1.0 的混合检索已经补上了主要短板。

创建知识库

1. 进入"知识库" → "创建知识库"
2. 上传文档（PDF / Word / Markdown / TXT / 网页 URL）
3. 分块设置：

4. 索引方式：选"高质量"（用 embedding 模型向量化），不要选"经济"（仅关键词）
5. 检索设置：选"混合检索"（向量 + 全文 + 重排），召回率最高

混合检索调参

1.0 的 RAG 从纯向量升级到混合检索 + 重排序：

• 向量检索：语义相似度，适合意图理解
• 全文检索：BM25 关键词匹配，适合专业术语、编号
• 重排序 Rerank：把初步召回的前 20 段进一步排序，选出最相关的 5-10 段

Rerank 模型选择：BGE Reranker（本地，中文好）或 Cohere Rerank（云端，多语言）。Rerank 对精度提升明显，但每次调用增加 200-500ms 延迟。

社区版 vs 企业版差距：多路召回 + 重排在企业版才完整解锁。社区版默认是基础语义检索，RAG 精度上限有限。如果你的核心场景就是知识库 QA 且要极致精度，FastGPT 社区版的 RAG 链路每步都可调，上限更高。

知识库避坑

• 文件大小限制：社区版默认 15MB，超过会失败。改 .env 的 UPLOAD_FILE_SIZE_LIMIT 并重启容器
• 大 PDF 处理慢：单文件 > 50MB 时切分占用大量内存，先本地拆成小 PDF 再上传
• 切片太碎：默认 500 字符对代码 / 长条款不友好，改成 800 字符 + overlap 100
• 只调 prompt 不调切片：答案不准 90% 是切片问题，先看召回段是否正确，再改 prompt

API 发布

Dify 是 API-first 平台，每个应用自动暴露 REST API。

1. 进入应用 → "访问 API"
2. 右上**"API Server"** → 获取 API Key
3. 查看自动生成的 OpenAPI Schema 和调用示例
4. 复制 curl / Python / Node.js 示例代码直接集成

Workflow 应用的 API 调用：

curl -X POST 'https://your-dify/v1/workflows/run' \
  -H 'Authorization: Bearer app-xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {"user_question": "我的订单什么时候发货？"},
    "response_mode": "blocking",
    "user": "user-123"
  }'

多平台发布：除了 API，Dify 还支持发布到 Web App、Slack、Discord、微信公众号企业版。一次配置多处触达，不用每个平台单独写集成代码。

MCP 双向支持：1.0 起 Dify 可作为 MCP Server 暴露工具——让 Claude Code / Cursor 调用 Dify 里的 workflow；也能消费外部 MCP Server——在 workflow 里调 GitHub / Slack / 自家内部系统。这让 Dify 不再是孤岛，而是 MCP 生态的中间层。

私有化部署注意事项

私有化是 Dify 最深的护城河，但运维成本不能忽视。

组件与资源

Dify 的 Docker Compose 包含多个组件：API Server、Web 前端、Worker、Sandbox、PostgreSQL、Redis、向量库（Weaviate）。链路比 FastGPT 长，资源占用更大。

版本升级

大版本升级会破坏数据库 schema。跨大版本（如 0.x → 1.x）务必：

1. 先备份 PostgreSQL 卷：docker exec dify-db pg_dump dify > backup.sql
2. 在 staging 环境验证升级流程
3. 生产升级前确认 release notes 的 breaking changes
4. 升级后跑一遍核心 workflow 确认无 regression

环境变量

.env 改完要 docker compose down && docker compose up -d，不是 docker compose restart——后者不重新加载 env。这是最常见的"改了配置不生效"的原因。

安全加固

• 管理员默认密码已改
• 服务器只开必要端口，80/443 走 Nginx 反代 + HTTPS
• PostgreSQL 数据卷已定期备份
• LLM API Key 走 secret 管理，不写到代码里
• 限流：单用户 QPM、单应用 QPS 都有上限
• 内网 DNS 已配好，员工能通过友好域名访问

5 个可直接复用的工作流模板

1. 智能客服路由

开始(user_question) → 问题分类(售后/物流/商品/其他) → 条件分支
  ├ 售后 → 知识检索(退换政策) → LLM(生成回复)
  ├ 物流 → HTTP请求(查运单API) → LLM(格式化)
  ├ 商品 → 知识检索(商品FAQ) → LLM(生成回复)
  └ 其他 → LLM(兜底+转人工)
→ 变量聚合(answer) → 结束

2. 文档问答 + 引用溯源

开始(question) → 知识检索(Top-5 chunk) → LLM(基于chunk回答+标注引用段号) → 结束(answer + sources)

3. 多模型 A/B 测试

开始(input) → 条件分支(按用户ID取模分流)
  ├ 分支A → LLM(GPT-5)
  └ 分支B → LLM(DeepSeek-V3)
→ 变量聚合 → 结束(记录哪个模型+用户满意度)

4. 数据 ETL + 报告生成

开始(raw_data) → 代码执行(清洗+统计) → LLM(生成分析报告) → HTTP请求(发飞书) → 结束

5. 意图路由 + Agent 自主决策

开始(user_input) → 问题分类(简单/复杂)
  ├ 简单 → LLM(直接回答) → 结束
  └ 复杂 → Agent节点(自主调工具+多步推理) → 结束

相关阅读

• Dify 深度评测：开源 AI Agent 平台私有部署首选？
• FastGPT vs Dify：国内企业级 RAG 与 Agent 平台怎么选
• FastGPT 部署与知识库搭建实战
• Coze 上手指南：从零搭建第一个 AI Bot
• Dify 工具卡 · FastGPT 工具卡 · Coze 工具卡