Dify 新手入门指南｜附完整命令

在大模型应用快速发展的今天，很多团队都希望用更低的成本、更快的速度构建自己的 AI 应用，例如智能客服、知识库问答、文本生成工具、工作流自动化助手等。Dify 正是一个非常适合新手入门的开源大模型应用开发平台。

Dify 集成了大模型调用、Prompt 编排、Agent、工作流、知识库、API 发布、应用管理等能力。对于没有太多工程经验的新手来说，它可以通过可视化界面快速搭建 AI 应用；对于开发者来说，它也提供了 API、Docker 部署、插件扩展等能力，方便集成到现有系统中。

本文将从零开始介绍 Dify 的基本概念、安装部署方式、常用命令、模型配置、应用创建、知识库使用以及常见问题处理，帮助你快速完成 Dify 入门。

一、Dify 是什么？

Dify 是一个开源的 LLMOps 平台，可以理解为“大模型应用开发与运营平台”。它的核心目标是让用户更简单地创建、发布和管理 AI 应用。

你可以使用 Dify 来构建以下类型的应用：

• 智能客服机器人
• 企业知识库问答系统
• AI 写作助手
• 文档总结工具
• SQL 查询助手
• 工作流自动化工具
• 多步骤 Agent 应用
• 接入微信公众号、网站、内部系统的 AI 服务

相比直接调用 OpenAI、Claude、通义千问、智谱、DeepSeek 等模型 API，Dify 的优势在于它提供了更完整的应用层能力。

例如，你不需要自己从零开发：

• 用户输入界面
• Prompt 管理
• 知识库检索
• 向量化处理
• 模型配置
• API 封装
• 日志追踪
• 多轮对话管理
• 工作流编排

这些功能在 Dify 中都可以直接使用。

二、Dify 适合哪些人？

Dify 非常适合以下几类用户：

1. AI 应用新手

如果你刚开始学习大模型应用开发，不想一上来就写大量代码，那么 Dify 是一个很好的选择。你可以通过可视化界面快速理解大模型应用的基本流程。

2. 企业内部工具开发者

企业可以使用 Dify 构建内部知识库助手、客服机器人、文档分析工具等，提高员工效率。

3. 独立开发者

如果你想快速做一个 AI 小产品，Dify 可以帮助你快速完成原型验证，并通过 API 接入到自己的前端或后端系统中。

4. 产品经理和运营人员

即使不懂代码，也可以通过 Dify 创建 Prompt 应用、工作流应用和知识库问答应用，用来测试 AI 产品方案。

三、Dify 的核心功能

在正式安装之前，我们先了解一下 Dify 的几个核心模块。

1. 应用

Dify 中的“应用”是最终面向用户使用的 AI 服务。常见应用类型包括：

• 聊天助手
• 文本生成应用
• Agent 应用
• 工作流应用
• 知识库问答应用

每个应用都可以单独配置模型、Prompt、知识库、变量、发布方式等。

2. Prompt 编排

Prompt 是大模型应用的核心。Dify 提供了可视化 Prompt 编排能力，你可以设置系统提示词、用户输入变量、上下文内容等。

3. 工作流

工作流是 Dify 中非常强大的功能。你可以把一个复杂任务拆解成多个步骤，例如：

1. 用户输入问题；
2. 判断问题类型；
3. 查询知识库；
4. 调用大模型总结；
5. 格式化输出结果。

通过工作流，可以实现比普通聊天机器人更复杂的业务逻辑。

4. 知识库

知识库功能可以让 Dify 读取你的文档，并将内容切分、向量化、存储，然后在用户提问时进行检索，最后结合大模型生成答案。

常见可上传的文档包括：

• PDF
• TXT
• Markdown
• Word 文档
• 网页内容
• 企业内部资料

5. API 发布

Dify 创建的应用不仅可以在平台中测试，也可以通过 API 形式提供给外部系统调用。这对于开发者来说非常有用。

四、部署前准备

本文推荐使用 Docker Compose 部署 Dify，这是最适合新手的方式。相比源码部署，Docker 部署更加简单，环境依赖也更少。

1. 服务器要求

建议服务器最低配置如下：

如果只是本地体验，也可以使用个人电脑安装 Docker Desktop 后运行。

2. 必备软件

需要提前安装：

• Git
• Docker
• Docker Compose

下面以 Ubuntu 系统为例，给出完整安装命令。

五、安装 Docker 和 Docker Compose

如果你的服务器还没有 Docker，可以按照下面步骤安装。

1. 更新系统软件包

sudo apt update
sudo apt upgrade -y

2. 安装基础依赖

sudo apt install -y ca-certificates curl gnupg lsb-release git

3. 添加 Docker 官方 GPG 密钥

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

4. 添加 Docker 软件源

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

5. 安装 Docker

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

6. 启动 Docker 并设置开机自启

sudo systemctl start docker
sudo systemctl enable docker

7. 检查 Docker 版本

docker --version
docker compose version

如果能正常显示版本号，说明 Docker 安装完成。

六、下载 Dify 源码

Dify 官方仓库地址为：

https://github.com/langgenius/dify

使用 Git 克隆项目：

git clone https://github.com/langgenius/dify.git

进入 Dify 项目目录：

cd dify

Dify 的 Docker 部署文件位于 docker 目录中，因此继续进入该目录：

cd docker

七、配置 Dify 环境变量

Dify 提供了环境变量示例文件。首次部署时，需要复制一份 .env 配置文件。

cp .env.example .env

你可以使用 nano 或 vim 编辑配置文件。

nano .env

或者：

vim .env

对于新手来说，通常不需要修改太多配置，默认配置即可启动。但如果你要部署到公网环境，建议重点关注以下配置项。

1. 站点访问地址

根据版本不同，配置项名称可能略有变化。常见配置包括：

CONSOLE_WEB_URL=http://你的服务器IP
APP_WEB_URL=http://你的服务器IP
SERVICE_API_URL=http://你的服务器IP

如果你绑定了域名，可以配置为：

CONSOLE_WEB_URL=https://dify.example.com
APP_WEB_URL=https://dify.example.com
SERVICE_API_URL=https://dify.example.com

2. 数据库密码

生产环境中建议修改默认数据库密码，例如：

DB_USERNAME=postgres
DB_PASSWORD=your_strong_password

3. Redis 密码

如果配置文件中存在 Redis 密码字段，也建议修改：

REDIS_PASSWORD=your_redis_password

4. Secret Key

生产环境建议设置强随机密钥。可以使用下面命令生成随机字符串：

openssl rand -base64 42

然后写入配置文件中的相关密钥字段。

八、启动 Dify

在 dify/docker 目录下执行以下命令启动服务：

docker compose up -d

该命令会自动拉取所需镜像并启动多个容器，包括：

• API 服务
• Web 前端
• Worker 服务
• PostgreSQL 数据库
• Redis
• Nginx
• 向量数据库相关组件

首次启动需要下载镜像，耗时取决于服务器网络情况。

启动完成后，可以查看容器状态：

docker compose ps

如果所有服务状态为 running 或 healthy，说明 Dify 已经正常运行。

也可以查看日志：

docker compose logs -f

如果只想查看某个服务日志，例如 API 服务：

docker compose logs -f api

查看 Web 服务日志：

docker compose logs -f web

查看 Worker 服务日志：

docker compose logs -f worker

九、访问 Dify 控制台

默认情况下，Dify 会通过 Nginx 暴露 Web 服务。

如果你是在服务器上部署，可以在浏览器访问：

http://服务器IP

如果你是在本地电脑部署，可以访问：

http://localhost

首次访问时，系统会引导你创建管理员账户。按照页面提示填写邮箱、用户名和密码即可。

创建完成后，你就可以进入 Dify 控制台。

十、常用 Docker 管理命令

下面这些命令在日常使用中非常重要，建议保存。

1. 启动服务

cd dify/docker
docker compose up -d

2. 停止服务

cd dify/docker
docker compose down

3. 重启服务

cd dify/docker
docker compose restart

4. 查看服务状态

cd dify/docker
docker compose ps

5. 查看所有日志

cd dify/docker
docker compose logs -f

6. 查看指定服务日志

docker compose logs -f api
docker compose logs -f web
docker compose logs -f worker
docker compose logs -f nginx

7. 重新拉取镜像

docker compose pull

8. 后台重新启动

docker compose up -d

9. 停止并删除容器

docker compose down

10. 停止并删除容器、网络和数据卷

注意：该命令可能删除数据库等持久化数据，新手谨慎执行。

docker compose down -v

11. 查看 Docker 占用空间

docker system df

12. 清理无用镜像和缓存

docker system prune -a

执行清理前建议确认没有误删重要镜像。

十一、配置大模型供应商

Dify 本身不提供大模型能力，它需要连接模型供应商。常见模型供应商包括：

• OpenAI
• Azure OpenAI
• Anthropic Claude
• Google Gemini
• DeepSeek
• 通义千问
• 智谱 AI
• 百度千帆
• 腾讯混元
• 火山方舟
• Ollama 本地模型

进入 Dify 控制台后，通常可以在以下位置配置模型：

设置 → 模型供应商

不同版本的菜单名称可能略有差异，但大体流程一致。

配置步骤

1. 登录 Dify 控制台；
2. 进入“设置”；
3. 找到“模型供应商”；
4. 选择你要使用的模型平台；
5. 填写 API Key；
6. 选择默认聊天模型、文本生成模型、Embedding 模型；
7. 保存并测试。

以 DeepSeek 为例

如果你使用 DeepSeek，需要先在 DeepSeek 平台创建 API Key，然后在 Dify 中添加对应配置。

通常需要填写：

API Key
模型名称
接口地址

如果 Dify 已内置 DeepSeek 供应商，直接选择 DeepSeek 并填入 API Key 即可。

以 OpenAI 为例

常见配置包括：

API Key: sk-xxxxxx
Model: gpt-4o-mini / gpt-4.1 / gpt-4o
Embedding Model: text-embedding-3-small

保存后，可以在应用中选择该模型。

十二、创建第一个聊天助手

下面我们创建一个最简单的 AI 聊天助手。

1. 新建应用

进入 Dify 首页，点击：

创建应用

选择：

聊天助手

填写应用名称，例如：

我的第一个 AI 助手

2. 设置 Prompt

可以填写如下系统提示词：

你是一个专业、耐心、简洁的 AI 助手。
请使用中文回答用户问题。
如果用户的问题不明确，请先向用户确认。
如果涉及专业知识，请给出清晰的步骤和注意事项。

3. 选择模型

在模型设置中选择你已经配置好的模型，例如：

DeepSeek Chat
GPT-4o mini
通义千问
智谱 GLM

4. 调试应用

在右侧调试窗口输入：

请帮我写一份周报模板

如果模型配置正确，你应该可以看到 AI 返回内容。

5. 发布应用

调试满意后，点击发布。Dify 会提供一个可访问的 Web 应用页面，也可以通过 API 调用。

十三、创建知识库问答应用

知识库问答是 Dify 最常见的使用场景之一。例如你可以上传公司制度、产品手册、接口文档，然后让 AI 基于这些资料回答问题。

1. 创建知识库

进入：

知识库 → 创建知识库

填写名称，例如：

公司产品文档知识库

2. 上传文档

可以上传 PDF、TXT、Markdown、Word 等文件。

上传后，Dify 会进行：

• 文档解析
• 文本切分
• 向量化
• 存储入库

3. 选择 Embedding 模型

知识库检索依赖 Embedding 模型。你需要在模型供应商中配置可用的 Embedding 模型。

常见选择：

text-embedding-3-small
bge-m3
text-embedding-v2

4. 等待索引完成

文档上传后需要等待处理完成。如果文档较大，可能需要几分钟。

5. 在应用中引用知识库

创建聊天应用后，在上下文或知识库设置中选择刚才创建的知识库。

然后设置提示词：

你是一个企业知识库助手。
请优先根据知识库内容回答用户问题。
如果知识库中没有相关信息，请明确说明“知识库中没有找到相关内容”，不要编造答案。
回答时请尽量引用原文依据，并保持简洁清晰。

6. 测试问答

输入一个和文档相关的问题，例如：

公司的报销流程是什么？

如果配置正确，Dify 会先检索知识库，再结合模型生成回答。

十四、使用工作流构建复杂应用

工作流适合处理多步骤任务。例如，我们可以创建一个“文章生成工作流”：

1. 用户输入主题；
2. AI 生成文章大纲；
3. AI 根据大纲生成正文；
4. AI 检查错别字；
5. 输出最终文章。

在 Dify 中，你可以通过拖拽节点完成工作流设计。

常见节点包括：

• 开始节点
• LLM 节点
• 条件分支节点
• 知识检索节点
• HTTP 请求节点
• 代码执行节点
• 结束节点

示例工作流 Prompt

文章大纲节点：

请根据用户输入的主题，生成一份中文文章大纲。
要求：
1. 结构清晰；
2. 包含标题、导语、正文小节和结尾；
3. 适合新手阅读。

用户主题：{{topic}}

正文生成节点：

请根据以下文章大纲生成一篇完整中文文章。
要求：
1. 语言自然；
2. 内容详细；
3. 适合公众号发布；
4. 使用 Markdown 格式。

文章大纲：
{{outline}}

工作流的优势是可控性更强，非常适合企业业务场景。

十五、通过 API 调用 Dify 应用

Dify 发布应用后，可以通过 API 调用。通常需要先获取应用的 API Key。

在应用页面中找到：

API 访问

创建 API Key 后，即可使用命令调用。

以下是一个通用的 curl 示例：

curl -X POST 'http://你的服务器IP/v1/chat-messages' \
--header 'Authorization: Bearer app-你的APIKey' \
--header 'Content-Type: application/json' \
--data-raw '{
  "inputs": {},
  "query": "你好，请介绍一下 Dify",
  "response_mode": "blocking",
  "conversation_id": "",
  "user": "user-001"
}'

如果使用流式响应，可以将：

"response_mode": "blocking"

改为：

"response_mode": "streaming"

示例：

curl -X POST 'http://你的服务器IP/v1/chat-messages' \
--header 'Authorization: Bearer app-你的APIKey' \
--header 'Content-Type: application/json' \
--data-raw '{
  "inputs": {},
  "query": "请用三句话介绍知识库问答系统",
  "response_mode": "streaming",
  "conversation_id": "",
  "user": "user-001"
}'

如果是文本生成类应用，接口可能为：

curl -X POST 'http://你的服务器IP/v1/completion-messages' \
--header 'Authorization: Bearer app-你的APIKey' \
--header 'Content-Type: application/json' \
--data-raw '{
  "inputs": {
    "topic": "Dify 入门"
  },
  "response_mode": "blocking",
  "user": "user-001"
}'

具体接口以 Dify 应用内的 API 文档为准。

十六、升级 Dify

Dify 更新较快，建议定期关注官方版本。升级前务必备份数据。

1. 进入项目目录

cd dify

2. 拉取最新代码

git pull

3. 进入 Docker 目录

cd docker

4. 拉取最新镜像

docker compose pull

5. 重启服务

docker compose down
docker compose up -d

6. 查看状态

docker compose ps

7. 查看日志

docker compose logs -f

如果升级后出现问题，可以查看官方 release note，确认是否需要调整 .env 配置。

十七、备份 Dify 数据

生产环境中一定要重视备份。Dify 的关键数据通常包括：

• PostgreSQL 数据
• Redis 数据
• 上传文件
• 向量数据库数据
• .env 配置文件

1. 备份整个 Docker 目录

cd dify
tar -czvf dify-docker-backup.tar.gz docker

2. 备份 PostgreSQL 数据库

先查看 PostgreSQL 容器名称：

docker compose ps

进入 dify/docker 目录后执行：

docker compose exec db pg_dump -U postgres dify > dify_backup.sql

如果你的数据库用户名或数据库名不同，请按 .env 配置修改命令。

3. 恢复数据库示例

cat dify_backup.sql | docker compose exec -T db psql -U postgres dify

恢复前请确保目标环境数据库状态正确，避免覆盖重要数据。

十八、常见问题与解决方法

1. 端口被占用

如果启动时报错端口冲突，可能是服务器已有 Nginx 或其他服务占用了 80 端口。

查看端口占用：

sudo lsof -i :80

或者：

sudo netstat -tulpn | grep :80

停止占用端口的服务：

sudo systemctl stop nginx

如果你不想停止原有 Nginx，可以修改 Dify 的端口映射配置。

2. 镜像拉取很慢

如果服务器网络较慢，可以配置 Docker 镜像加速器，或者更换网络环境。

重新拉取镜像：

docker compose pull

3. 容器启动失败

查看所有容器状态：

docker compose ps

查看详细日志：

docker compose logs -f

重点关注 api、worker、db、redis 等服务日志。

4. 页面打不开

可以依次检查：

docker compose ps

sudo ufw status

如果防火墙开启，需要放行端口：

sudo ufw allow 80
sudo ufw allow 443

如果是云服务器，还需要在云厂商安全组中放行 80 或 443 端口。

5. 模型调用失败

常见原因包括：

• API Key 填写错误；
• 账户余额不足；
• 模型供应商接口地址错误；
• 当前网络无法访问模型服务；
• 模型名称填写不正确。

可以先在本地用 curl 测试模型供应商接口，再回到 Dify 中配置。

十九、新手使用建议

对于刚入门的用户，建议按照以下顺序学习 Dify：

1. 先用 Docker 部署成功；
2. 配置一个可用的大模型；
3. 创建一个普通聊天助手；
4. 创建一个知识库问答应用；
5. 学习 Prompt 编排；
6. 尝试工作流；
7. 通过 API 接入自己的系统；
8. 最后再考虑生产环境优化和二次开发。

不要一开始就追求复杂功能。Dify 的功能很多，但核心逻辑并不难：用户输入问题，Dify 根据你的配置调用模型、检索知识库或执行工作流，最后返回结果。

二十、完整部署命令汇总

如果你只想快速部署，可以直接参考下面这组命令。

Ubuntu 快速部署 Dify

sudo apt update
sudo apt upgrade -y

sudo apt install -y ca-certificates curl gnupg lsb-release git

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo systemctl start docker
sudo systemctl enable docker

docker --version
docker compose version

git clone https://github.com/langgenius/dify.git

cd dify/docker

cp .env.example .env

docker compose up -d

docker compose ps

访问地址：

http://服务器IP

如果是本地部署：

http://localhost

二十一、结语

Dify 是目前非常适合新手学习和实践大模型应用开发的平台。它既能让非技术人员通过可视化界面快速搭建 AI 应用，也能让开发者通过 API、工作流和知识库能力构建更复杂的业务系统。

对于初学者来说，最重要的不是一开始就理解所有功能，而是先完成一次完整闭环：

部署 Dify → 配置模型 → 创建应用 → 测试对话 → 发布应用 → API 调用

当你跑通这个流程后，就已经具备了构建 AI 应用的基础能力。接下来，你可以继续探索知识库、工作流、Agent、多模型配置、私有化部署和企业集成等高级功能。

如果你想快速进入 AI 应用开发领域，Dify 是一个非常值得上手的工具。