Dify 源码本地部署启动及完整步骤解析

• 使用源码本地启动 Dify 1.4.0 版本

一、环境准备

1. 系统要求

• 推荐操作系统：Ubuntu 20.04+/Windows 10/11（通过WSL2运行Ubuntu子系统）
• 安装基础依赖：Git、Docker（20.10+）、Docker Compose（v2+）、Python 3.12/Node.js v22.x（前端需）
• Windows用户需启用WSL2并安装Ubuntu发行版，同时安装Docker Desktop。

2. Linux环境

# 安装 Docker，Docker 19.03 or later
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
systemctl enable --now docker
# 安装 docker-compose，Docker Compose 1.28 or later
curl -L https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
# 验证安装
docker -v
docker-compose -v
# 如失效，自行百度~

3. Windows环境

• 可以选择直接使用 WSL 2 后端在 Windows 中安装 Docker Desktop。
• 也可以直接在 WSL 2 中安装命令行版本的 Docker。
• 建议将源代码和其他数据绑定到 Linux 容器中时，将其存储在 Linux 文件系统中，而不是 Windows 文件系统中。
• 机器要求：CPU >= 2 Core，RAM >= 4 GiB

4. 克隆源码

# 克隆 Dify 源代码至本地环境，根据需要选择版本
git clone https://github.com/langgenius/dify.git --branch 1.4.0

• 拉取代码，一定要拉取稳定版

二、中间件部署

1. 修改 ddocker-compose.middleware.yaml 文件

• 由于默认镜像地址国内无法访问，可更换中间件的镜像地址

swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/postgres:15-alpine
swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/redis:6-alpine
swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/langgenius/dify-sandbox:0.2.12
swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/langgenius/dify-plugin-daemon:0.0.10-local
swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/ubuntu/squid:latest
swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/semitechnologies/weaviate:1.19.0

2. 使用 Docker Compose 启动中间件

• 进入docker目录，复制环境变量模板并启动中间件

cd docker 
cp middleware.env.example middleware.env 
docker compose -f docker-compose.middleware.yaml -p dify up -d
# 更换以下启动命令及参数解释
docker compose -f docker-compose.middleware.yaml --profile weaviate -p dify up -d
docker compose \ 
-f docker-compose.middleware.yaml \ # 使用指定的 YAML 文件 
--profile weaviate \ # 启用 weaviate profile 
-p dify \ # 设置项目名为 dify 
up -d # 启动服务并在后台运行

• -p dify设置项目的名称为 dify，项目名是 Docker Compose 管理资源（如容器、网络、卷等）时的一个命名前缀，所有相关资源都会以 dify 为前缀命名，便于区分不同项目的服务，生成的容器名可能是：dify-weaviate-1
• --profile weaviate启用名为 weaviate 的 profile，所以在服务定义中带有 profiles: - weaviate 的服务才会被启动

3. 中间件部署问题解决

3.1 PostgreSQL权限问题

• PostgreSQL权限问题（如/var/lib/postgresql/data/pgdata权限报错），具体报错如下：

initdb: error: could not change permissions of directory "/var/lib/postgresql/data/pgdata": Operation not permitted
2025-05-28 11:38:38 chmod: /var/lib/postgresql/data/pgdata: Operation not permitted

• 解决方法：编辑docker-compose.middleware.yaml，修改Docker卷挂载路径，调整宿主机目录权限，如下：

# 修改docker-compose.middleware.yaml db服务挂在路径
volumes:# - ${PGDATA_HOST_VOLUME:-./volumes/db/data}:/var/lib/postgresql/data- ${PGDATA_HOST_VOLUME:-/home/user/volumes/db/data}:/var/lib/postgresql/data# 停止Docker容器并清理旧数据
docker compose -f docker-compose.middleware.yaml -p dify down
# 重新创建目录并赋权
mkdir -p /home/user/volumes/db/data
chmod 777 /home/user/volumes/db/data  # 临时赋予完全读写权限（开发环境适用）
# 重新启动服务
docker compose -f docker-compose.middleware.yaml --profile weaviate -p dify up -d

• 生产环境建议使用更严格的权限，例如指定用户组`chown 999:999 /home/volumes/db/data（PostgreSQL容器默认UID为999）
• 若通过WSL2运行，确保数据目录位于WSL子系统内（如/home/user/dify/data），而非Windows原生路径（如/mnt/c/...）。

4.中间件解析

• Dify 所有中间件可以快速启动并协同工作，支持 Dify 的核心功能，这些中间件通过 Docker 容器运行，并通过环境变量和挂载卷进行配置

4.1 Postgres 数据库 (db)

• 作用: 提供关系型数据库服务，用于存储 Dify 的核心数据，例如用户信息、插件数据等。
• 配置:
  • 使用 postgres:15-alpine 镜像。
  • 配置了数据库密码 (POSTGRES_PASSWORD)、数据库名称 (POSTGRES_DB) 和数据存储路径 (PGDATA)。
  • 挂载了数据卷以持久化数据库数据。
  • 配置了多个数据库性能参数，例如最大连接数 (max_connections) 和缓存大小 (shared_buffers)。
• 端口: 默认暴露 5432 端口。

4.2 Redis 缓存 (redis)

• 作用: 提供缓存服务，用于加速数据访问和存储临时数据，例如会话信息、任务队列等。
• 配置:
  • 使用 redis:6-alpine 镜像。
  • 配置了 Redis 密码 (REDISCLI_AUTH)。
  • 挂载了数据卷以持久化 Redis 数据。
  • 启动时设置了密码保护 (--requirepass)。
• 端口: 默认暴露 6379 端口。

4.3 DifySandbox (sandbox)

• 作用: 提供一个沙盒环境，用于运行插件或代码片段。沙盒环境隔离了外部网络，确保安全性。
• 配置:
  • 使用 langgenius/dify-sandbox 镜像。
  • 配置了 API 密钥 (API_KEY)、代理设置 (HTTP_PROXY 和 HTTPS_PROXY)、沙盒端口 (SANDBOX_PORT) 等。
  • 挂载了依赖和配置文件目录。
• 端口: 默认暴露 8194 端口。

4.4 插件守护进程 (plugin_daemon)

• 作用: 管理插件的安装、运行和调试。它负责与数据库和 Redis 交互，并提供插件相关的 API 服务。
• 配置:
  • 使用 langgenius/dify-plugin-daemon 镜像。
  • 配置了数据库连接信息 (DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD) 和 Redis 连接信息 (REDIS_HOST, REDIS_PORT, REDIS_PASSWORD)。
  • 配置了插件存储路径、最大插件包大小等参数。
  • 挂载了存储目录以保存插件相关数据。
• 端口: 默认暴露 5002 和 5003 端口。

4.5 SSR Proxy (ssrf_proxy)

• 作用: 提供一个代理服务，用于防止 SSRF（服务器端请求伪造）攻击。它隔离了沙盒环境与外部网络。
• 配置:
  • 使用 ubuntu/squid 镜像。
  • 配置了代理端口 (HTTP_PORT 和 REVERSE_PROXY_PORT)。
  • 挂载了 Squid 配置文件和启动脚本。
• 端口: 默认暴露 3128 和 8194 端口。

4.6. Weaviate 向量存储 (weaviate)

• 作用: 提供向量数据库服务，用于存储和检索高维向量数据，例如文本嵌入向量。它是 Dify 的核心组件之一，用于支持搜索和推荐功能。
• 配置:
  • 使用 semitechnologies/weaviate 镜像。
  • 配置了持久化数据路径 (PERSISTENCE_DATA_PATH) 和默认向量化模块 (DEFAULT_VECTORIZER_MODULE)。
  • 配置了 API 密钥认证和管理员列表。
  • 挂载了数据卷以持久化向量数据。
• 端口: 默认暴露 8080 端口。

三、后端服务部署

1. 后端环境准备

• 推荐使用 pyenv 快速安装 Python 环境，需了解 Python 多版本管理工具 pyenv 使用
• 使用 uv 管理依赖，需了解Python 包管理工具 uv 使用

# pyenv install 安装 Python 3.12
pyenv install 3.12
# 切换到 “3.12” Python 环境
pyenv global 3.12

2. 配置环境变量

# 导航到 api 目录
cd api
# 准备环境变量配置文件
cp .env.example .env
# 生成随机密钥并替换 .env 文件中的 SECRET_KEY 值（以下命令任选其一）
sed -i "/^SECRET_KEY=/c\SECRET_KEY=$(openssl rand -base64 42)" .env
# 或使用awk
awk -v key="$(openssl rand -base64 42)" '/^SECRET_KEY=/ {sub(/=.*/, "=" key)} 1' .env > temp_env && mv temp_env .env

3. 安装所需依赖

# 使用 uv 安装所需依赖
uv sync

4. 数据库迁移

• 执行数据库迁移到最新版本，更新数据库结构以匹配最新的模型定义

uv run flask db upgrade

5. 启动API服务

• API 服务：为前端服务和 API 访问提供 API 请求服务

uv run flask run --host 0.0.0.0 --port=5001 --debug

• 预期输出

 * Running on all addresses (0.0.0.0)* Running on http://127.0.0.1:5001* Running on http://172.20.190.254:5001
2025-05-29 02:08:18,782 INFO [_internal.py:97]  Press CTRL+C to quit
2025-05-29 02:08:18,855 INFO [_internal.py:97]   * Restarting with stat
2025-05-29 02:08:30,642 INFO [utils.py:162]  NumExpr defaulting to 12 threads.
2025-05-29 02:08:46,269 WARNING [_internal.py:97]   * Debugger is active!
2025-05-29 02:08:46,386 INFO [_internal.py:97]   * Debugger PIN: 536-362-648

6. 启动Worker服务

• Worker 服务：为数据集处理、工作区、清理等异步任务提供服务

# 对于 macOS 或 Linux
uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,generation,mail,ops_trace
# 使用 Windows 系统启动 Worker 服务
uv run celery -A app.celery worker -P solo --without-gossip --without-mingle -Q dataset,generation,mail,ops_trace --loglevel INFO

• 预期输出

2025-05-29 02:21:09,59 INFO [connection.py:22]  Connected to redis://:**@localhost:6379/1
2025-05-29 02:21:09,70 INFO [mingle.py:40]  mingle: searching for neighbors
2025-05-29 02:21:10,102 INFO [mingle.py:49]  mingle: all alone
2025-05-29 02:21:10,163 INFO [pidbox.py:111]  pidbox: Connected to redis://:**@localhost:6379/1.
2025-05-29 02:21:10,165 INFO [worker.py:176]  celery@DESKTOP-5NH1BBM ready.

7. 后端服务功能

7.1 API服务功能

• API 服务是 Dify 对外提供服务的接口层，负责接收来自前端或其他外部系统的请求，并根据请求类型进行相应的处理和响应。它提供了丰富的接口，涵盖了应用开发、模型交互、数据管理等多个方面，方便开发者将 Dify 集成到自己的业务逻辑中。
• 具体功能包括：
  • 用户交互操作：处理用户的消息反馈、获取应用参数、文件上传、文本转语音等请求。例如，dify/sdks/python-client/dify_client/client.py 中的 message_feedback 方法用于处理用户对消息的反馈，file_upload 方法用于处理文件上传请求。
  • 模型交互：提供与大语言模型的交互接口，如创建完成消息、创建聊天消息等。dify/sdks/nodejs-client/index.js 中的 CompletionClient 和 ChatClient 类分别提供了创建完成消息和创建聊天消息的接口。
  • 工作流管理：提供工作流的运行和停止接口，如 WorkflowClient 类中的 run 和 stop 方法，用于运行和停止工作流。
  • 与前端的交互：前端通过发送 HTTP 请求调用 API 服务的接口，API 服务接收到请求后进行处理，并将处理结果以 JSON 格式返回给前端。例如，前端在用户上传文件时，会调用 API 服务的文件上传接口，API 服务处理上传请求后返回上传结果给前端。
  • 与中间件的交互：API 服务可能会依赖中间件来完成一些功能，如认证、日志记录、缓存等。例如，在处理请求时，API 服务会使用中间件进行身份验证，确保请求来自合法用户；同时，中间件可以记录请求和响应的日志，方便后续的监控和分析。

7.2 Worker服务功能

• Worker 服务通常负责处理一些后台任务和异步操作，以减轻 API 服务的负担，提高系统的性能和响应速度。
• 具体功能包括：
  • 任务调度：负责调度和执行一些定时任务或异步任务，如数据处理、模型训练、日志分析等。例如，Worker 服务可以定时对应用的日志进行分析，生成性能报告。
  • 资源管理：管理系统的资源使用，如分配计算资源、存储资源等。在处理大规模数据或复杂任务时，Worker 服务可以合理分配资源，确保系统的稳定性和高效性。
  • 工作流执行：执行工作流中的具体任务，根据工作流的配置和规则，依次执行各个节点的操作。例如，在一个包含知识检索和模型推理的工作流中，Worker 服务会负责执行知识检索和模型推理的任务。

四、前端Web服务部署

1. 前端环境准备

• 要启动 web 前端服务，需要 Node.js v22 (LTS) 和 PNPM v10。
• 安装 NodeJS，访问 https://nodejs.org/en/download 并选择适合您操作系统的 v18.x 或更高版本的安装包。推荐使用 LTS 版本进行常规使用。
• 安装 PNPM，按照 安装指南 安装 PNPM。或者直接使用 npm 运行以下命令安装 pnpm。

# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash# in lieu of restarting the shell
\. "$HOME/.nvm/nvm.sh"# Download and install Node.js:
nvm install 22# Verify the Node.js version:
node -v # Should print "v22.16.0".
nvm current # Should print "v22.16.0".# Download and install pnpm:
corepack enable pnpm# Verify pnpm version:
pnpm -v

2. 启动Web服务

# 进入 web 目录
cd web# 安装依赖
pnpm install --frozen-lockfile# 配置环境变量，根据需求修改这些环境变量的值
cp .env.example .env.local# 构建Web服务
pnpm build# 启动Web服务
pnpm start

• 一些重要的环境变量及其说明

# 对于生产版本，将此值改为PRODUCTION
NEXT_PUBLIC_DEPLOY_ENV=DEVELOPMENT
# 部署版本，这里为自托管版本
NEXT_PUBLIC_EDITION=SELF_HOSTED
# 控制台应用的基础URL，如果控制台域名与API或Web应用域名不同，则参考WEB服务的控制台基础URL
# 示例: http://cloud.dify.ai/console/api
NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api
# Web应用的URL，如果Web应用域名与API或控制台域名不同，则参考WEB服务的Web应用基础URL

• 预期输出

> cp -r .next/static .next/standalone/.next/static && cp -r public .next/standalone/public && cross-env PORT=$npm_config_port HOSTNAME=$npm_config_host node .next/standalone/server.js▲ Next.js 15.2.3- Local:        http://localhost:3000- Network:      http://0.0.0.0:3000✓ Starting...✓ Ready in 2.5s

• 通过访问http://localhost:3000来配置应用程序

3. 前端部署问题解决

• ERR_PNPM_EACCES  EACCES: permission denied，权限错误通常发生在 Linux/WSL 环境下，表示当前用户对文件系统没有足够的操作权限
• 首先，停止所有正在运行的 Node 进程：pkill -f node
• 方法一：修复目录所有权（推荐）

# 进入项目目录
cd /mnt/e/llm-workspace/dify# 递归修复所有权（将 USER 替换为你的实际用户名）
sudo chown -R $USER:$USER .# 修复执行权限
sudo chmod -R 755 web/node_modules# 清理缓存并重试安装
pnpm store prune
pnpm install --frozen-lockfile

• 方法二：使用 WSL 专用目录（最佳实践），将项目移至 WSL 原生文件系统并重新安装依赖

# 创建 WSL 家目录下的工作区
mkdir -p ~/workspace# 复制项目（避免权限问题）
cp -r /mnt/e/llm-workspace/dify ~/workspace/# 切换到新位置
cd ~/workspace/dify/web# 删除原有 node_modules
rm -rf node_modules# 重新安装
pnpm install --frozen-lockfile

• 对于 WSL 环境，强烈建议将项目放在 Linux 原生文件系统（如 ~/workspace/）而不是 /mnt/ 下

4. 前端服务功能

• Dify 前端服务是整个平台与用户交互的重要界面，为用户提供了直观、便捷的操作体验。前端服务主要提供以下功能特性的展示与操作：

  1. 工作流构建与测试：提供可视化画布，让用户可以在上面构建和测试强大的 AI 工作流。用户可以利用各种功能模块，如知识检索、模型推理等，组合出满足自己需求的工作流。
  2. 模型管理与使用：支持与数百种专有 / 开源 LLMs 以及数十种推理提供商和自托管解决方案无缝集成。用户可以在前端界面选择不同的模型，查看模型的相关信息，并进行模型性能的比较。完整的支持模型提供商列表可在此处找到。
  3. Prompt IDE：提供直观的界面，用于制作提示、比较模型性能以及向基于聊天的应用程序添加其他功能（如文本转语音）。用户可以在该界面中输入和编辑提示信息，实时查看模型的响应结果。
  4. RAG Pipeline 操作：具备广泛的 RAG 功能，涵盖从文档摄入到检索的所有内容。前端支持用户上传 PDF、PPT 和其他常见文档格式的文件，并提供对文本提取功能的操作入口。
  5. Agent 智能体管理：用户可以基于 LLM 函数调用或 ReAct 定义 Agent，并为 Agent 添加预构建或自定义工具。Dify 为 AI Agent 提供了 50 多种内置工具，如谷歌搜索、DALL・E、Stable Diffusion 和 WolframAlpha 等，这些工具在前端界面有相应的展示和配置选项。
  6. LLMOps 监控与分析：允许用户随时间监视和分析应用程序日志和性能。用户可以在前端查看应用的运行状态、错误信息等，并根据生产数据和标注持续改进提示、数据集和模型。
  7. 应用开发与配置：提供创建和配置应用的功能，用户可以设置应用的基本信息、图标、背景颜色等。例如，在 dify/api/constants/recommended_apps.json 中定义的推荐应用，前端会展示这些应用的相关信息，如名称、描述、图标等，用户可以基于这些模板快速创建自己的应用。

• 前端与后端及中间件的交互逻辑

  1. 与后端 API 服务的交互：前端通过发送 HTTP 请求调用后端 API 服务的接口，以获取数据或执行操作。例如，在用户上传文件时，前端会调用 API 服务的文件上传接口；在创建工作流时，前端会将工作流的配置信息发送给 API 服务进行保存和处理。API 服务接收到请求后进行处理，并将处理结果以 JSON 格式返回给前端，前端根据返回结果更新界面显示。
  2. 与中间件的交互：前端与中间件的交互主要通过 API 服务间接完成。中间件可以提供认证、日志记录、缓存等功能，确保前端请求的安全性和高效性。例如，中间件会对前端发送的请求进行身份验证，只有合法用户的请求才会被转发到 API 服务进行处理；同时，中间件可以记录前端请求和响应的日志，方便后续的监控和分析。

五、单独启动Web服务容器

• 当单独开发后端时，可能只需要源码启动后端服务，而不需要本地构建前端代码并启动，因此可以直接通过拉取 docker 镜像并启动容器的方式来启动前端服务。

1. 直接使用镜像启动容器

docker run -it -p 3000:3000 -e CONSOLE_API_URL=http://127.0.0.1:5001 -e APP_API_URL=http://127.0.0.1:5001 langgenius/dify-web:latest
docker run -it -p 3000:3000 -e CONSOLE_API_URL=http://127.0.0.1:5001 -e APP_API_URL=http://127.0.0.1:5001 swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/langgenius/dify-web:1.4.0

2.源码构建Docker镜像

• 构建前端镜像

cd web && docker build . -t dify-web

• 启动前端镜像

docker run -it -p 3000:3000 -e CONSOLE_API_URL=http://127.0.0.1:5001 -e APP_API_URL=http://127.0.0.1:5001 dify-web

• 当控制台域名和 Web APP 域名不一致时，可单独设置 CONSOLE_URL 和 APP_URL
• 本地访问 http://127.0.0.1:3000