Dify

Dify 是一个 LLM 应用开发与编排平台，支持构建对话、Agent 与工作流等应用。Dify 自身不依赖 GPU，可以运行在未配置 NVIDIA 环境的节点上。只有下游推理服务需要 GPU 时，才要求对应的推理实例满足 GPU 条件。

快速开始

创建 Dify Agent实例大致分为以下几步：

1. 导入 Agent模板：控制台 人工智能 → Agent → Agent模板，导入 社区目录中的 Dify，生成镜像与默认模板。
2. 创建 Agent实例：控制台 人工智能 → Agent → Agent实例，新建并选择刚导入的 Dify 模板。
3. 访问并完成初始化：进入实例详情页「连接信息」获取访问地址，用浏览器打开 Dify 初始化页面，完成管理员账号与工作空间初始化。
4. 安装模型插件并配置模型供应商：如需对接 OpenAI、OpenAI 兼容服务，或平台内的 vLLM 等下游推理服务，先在 Dify Web 后台的 插件 → Marketplace 安装对应插件，再配置模型供应商与下游推理服务。
5. 验证应用链路：在 Dify 中创建一个最小对话应用或工作流，发起一次调用，确认应用、模型和工具链路都正常。

1. 导入 Agent模板

1. 进入 人工智能 → Agent → Agent模板，点击 导入。

2. 在社区目录中选择 Dify 对应条目，按需确认规格后提交。

3. 导入成功后，平台会生成对应的 Agent镜像 与默认 Agent模板。

提示

导入后如需调整镜像、规格或高级环境变量，可对模板执行 修改；字段说明见 Agent模板。

2. 创建 Agent实例

控制台入口为 人工智能 → Agent → Agent实例。

1. 点击 新建。
2. 选择刚导入的 Dify 模板。
3. 填写实例名称，并按页面要求选择项目、区域、网络等通用配置。
4. 确认模板、镜像、规格和高级配置后提交创建。

页面里的通用字段按实际场景选择即可：

• 网络：可使用自动分配，也可指定已有 IP 子网
• 高级配置：
  • 宿主机(可选)：可选择指定的宿主机运行 Dify 容器实例，不选则会自动调度

提示

Dify 是多容器应用。除了前端和 API，还会同时启动数据库、Redis、向量库、插件守护进程、代码执行沙箱等组件。它虽然不依赖 GPU，但 CPU、内存和数据盘仍要留出足够余量。

3. 访问并完成初始化

实例创建成功后，进入实例详情页，打开 连接信息，即可获取 Dify 的访问地址。按当前平台实现，外部访问入口走 nginx 容器，对外默认暴露 80 端口。

通过浏览器打开访问地址后，通常会看到 Dify 的首次初始化向导。你可以按页面提示完成以下动作：

1. 创建管理员账号。
2. 使用管理员账号登录

平台会自动为 Dify 内部组件生成所需的内部密钥，一般不需要手工填写。比如 SECRET_KEY、内部 API key、Plugin Server Key 和 Weaviate 的内部认证 key，都会在部署阶段准备好。

提示

Dify 的 Web 页面、API、文件访问等路径默认共用同一个外部入口地址。除了浏览器访问首页，后续调用 Dify API 时，通常也是在同一个地址下访问 /api、/v1、/files 等路径。

4. 安装模型插件并配置模型供应商

Dify 本身不直接挂载模型目录，也不直接运行模型权重。它更像应用编排平台，真正的模型推理由外部模型供应商或平台内其它推理实例承担。

完成初始化后，建议先确认下游推理服务已经可用。无论你要对接外部 OpenAI、其它 OpenAI 兼容服务，还是平台内的 推理部署，通常都需要先在 Dify Web 后台安装对应的模型插件，再进入模型供应商页面完成接入。常见方式包括：

• 通过 OpenAI 或 OpenAI-API-compatible 插件，对接外部模型服务，如 OpenAI 或其它兼容 OpenAI API 的服务。
• 对接平台内已就绪的 推理部署（如 vLLM / SGLang 类型）。

推荐操作流程：

1. 登录 Dify 控制台。
2. 进入 插件 → Marketplace。
3. 在 Marketplace 中搜索并安装对应插件，例如 OpenAI、OpenAI-API-compatible 或 vLLM。
4. 插件安装完成后，进入模型供应商的模型配置页面。
5. 选择要接入的供应商类型。
6. 按页面提示填写 Base URL、模型名称、API Key 或其它鉴权字段。
7. 先执行一次连接测试，再保存。

按不同供应商类型，可以这样理解：

• 对接 vLLM：可以使用 vLLM 插件，也可以通过 OpenAI 或 OpenAI-API-compatible 插件接入其 OpenAI 兼容接口。多数情况下 Base URL 需要指向该服务的 /v1 根路径，具体以 Dify 当前页面字段说明为准。
• 对接 OpenAI 或 OpenAI 兼容服务：通常先在 插件 → Marketplace 安装 OpenAI 或 OpenAI-API-compatible 插件；完成后在模型供应商页选择对应类型，再按页面要求填写官方地址或兼容服务的 Base URL、模型名称与 API Key。

提示

模型供应商的 API Key 通常在 Dify Web 后台配置和存储，而不是通过Agent模板直接挂载模型文件。对 Dify 来说，关键是它能访问到目标推理服务，模型供应商配置也填对。

提示

如果下游为 GPU 推理服务，推理服务所在节点仍需按 配置 NVIDIA 与 CUDA 环境 完成 GPU 环境准备。

5. 验证应用链路

完成模型供应商配置后，建议创建一个最小应用做联调验证。可以按下面的方式检查：

1. 在 Dify 中新建一个最简单的聊天应用，或新建一个只包含基础 LLM 节点的工作流。
2. 选择刚刚配置好的模型。
3. 输入一句简单提示词，例如“请用一句话介绍你自己”。
4. 点击调试或预览，观察返回结果是否正常。

如果模型能正常返回结果，说明下面这几段链路基本已经打通：

• Dify Web 与 API 正常
• Dify 到下游模型供应商的网络连通正常
• 模型供应商配置正确
• Dify 的后端任务链路和存储依赖可以正常工作

平台内置组件

按当前平台实现，Dify 不是单容器应用，而是一组协同工作的内置组件。常见组件如下：

组件	作用	主要端口或入口	持久化路径
nginx	对外统一入口，代理 Web、API、文件与插件回调路径	80	/etc/nginx/conf.d
web	Dify 前端界面	内部 Web 服务	无专用持久化目录
api	Dify 后端 API 与核心业务逻辑	内部 5001	/app/api/storage
worker	异步任务执行	内部任务队列	/app/api/storage
worker-beat	定时任务调度	内部任务队列	无专用持久化目录
plugin	插件守护进程与插件安装运行	5002 / 5003	/app/storage
sandbox	代码执行沙箱	8194	/conf、/dependencies
ssrf	代理与隔离网络访问，供沙箱与部分外部访问链路使用	3128	无专用持久化目录
postgres	元数据与配置存储	5432	/var/lib/postgresql/data
redis	缓存与队列	6379	/data
weaviate	默认向量存储	内部 8080	/var/lib/weaviate

这些组件会由平台一起拉起并自动启动，不需要再额外手动执行“启动 Dify”命令。外部通常只需要访问一个入口地址，平台会由 nginx 将 /、/api、/v1、/files 等路径转发到对应内部服务。

存储与持久化

Dify 的关键数据主要分布在以下几类目录中：

• Postgres 数据目录：/var/lib/postgresql/data
• Redis 数据目录：/data
• Dify API 存储目录：/app/api/storage
• Plugin 守护进程存储目录：/app/storage
• Weaviate 数据目录：/var/lib/weaviate
• Sandbox 配置与依赖目录：/conf、/dependencies
• Nginx 配置目录：/etc/nginx/conf.d

建议重点关注以下几类数据的持久化与备份：

• 数据库元数据和工作空间配置
• 知识库、文件上传与应用运行时数据
• 插件安装目录与插件缓存
• 向量库数据

提示

Dify 的很多关键状态并不在浏览器本地，而是在 Postgres、API 存储目录和向量库中。生产环境建议务必使用持久化存储，并建立备份与清理策略。

配置

模板、镜像与规格

• 规格选择：参考 Agent模板，重点关注 CPU、内存与数据盘，而不是 GPU。
• 多组件特性：Dify 一次部署会拉起多个组件，规格过小往往不是单个进程慢，而是数据库、队列、向量库和后端任务一起受限。
• 镜像选择：如果平台允许在模板中调整组件镜像，应优先在模板层统一修改；Dify 属于多镜像应用，不建议临时只改外部入口而忽略其它依赖组件版本。

推理对接与密钥

• 不直接挂模型：Dify 不支持像 vLLM 那样直接挂载模型目录来提供模型能力。
• 模型供应商配置位置：模型 API Key、模型地址等，通常在 Dify Web 后台的模型供应商配置页内完成。
• OpenAI / OpenAI 兼容服务：通常也需要先在 Dify 的 插件 → Marketplace 安装 OpenAI 或 OpenAI-API-compatible 插件，再填写官方地址或兼容服务地址；如对接 vLLM 且走 OpenAI 兼容接口，常见形式是 <service-url>/v1。
• vLLM 联动：如果对接平台内的推理部署，建议先完成其可用性验证，再到 Dify 的 插件 → Marketplace 安装对应插件，最后回到模型供应商页做接入。

网络与运维

• 网络连通性：确保 Dify 到下游模型服务、插件市场以及所需外部 API 的网络连通性。
• 插件与代码执行：插件安装依赖 plugin 组件，代码执行依赖 sandbox 与 ssrf 组件；如果这些功能异常，通常不仅仅是前端配置问题。
• 沙箱网络：按当前平台默认配置，代码执行沙箱允许网络访问，但访问链路会经过 ssrf 代理；如果代码节点或插件访问外部资源失败，优先联查 sandbox 与 ssrf。
• 扩缩容：扩容时建议同时评估 API、Worker、数据库、向量库和下游模型服务的容量，而不是只关注前端访问量。
• 升级与回滚：通过 推理镜像 管理运行时版本；升级前建议备份关键数据目录和数据库。
• 观测：关注请求量、错误率、下游模型调用延迟、数据库与向量库存储容量；结合日志定位依赖不可用、超时和初始化失败等问题。

常见问题

初始化页面打不开，或者打开后出现 502

• 先检查实例状态是否为运行中。
• 检查 nginx、web、api 相关日志，确认前端与后端是否已经完成启动。
• 多容器应用第一次启动时，通常需要等待 Postgres、Redis、Weaviate、API、Web 全部就绪后，页面才会稳定可用。

下游模型调用超时或失败

• 检查 Dify 中配置的模型供应商地址、模型名称和 API Key 是否正确。
• 如果下游为平台内的 vLLM，先分别验证对应推理部署本身是否已经可用。
• 如果下游是 GPU 推理服务，确认 GPU 节点环境正常，并检查推理服务容量与日志。

插件安装失败，或者代码执行不可用

• 检查 plugin、sandbox、ssrf 相关容器是否正常运行。
• 检查节点到插件市场、包仓库和目标外部服务的网络连通性。
• 如果环境是内网或受限网络，需提前规划插件市场和依赖下载所需的访问策略。

怎么查看日志？

通过前端界面：点击对应的 Agent实例，进入详情页面，再点击 日志，就能查看 Dify 的服务输出日志，方便用于错误排查。

由于 Dify 是多容器应用，排查问题时通常优先关注这些组件的日志：

• api
• worker
• plugin
• nginx
• postgres
• weaviate

怎么进入容器？

通过实例详情页面中的 终端 可以直接进入容器，适合用于查看存储目录、环境变量和运行日志。

按当前平台实现，Dify 的主容器通常是 api 容器，因此从详情页进入终端时，通常更接近后端服务运行环境。

如果需要在容器内做基础检查，可优先查看：

env | grep -E 'DB_|REDIS_|WEAVIATE_|PLUGIN_|SANDBOX_'

ls -lah /app/api/storage