掘金 人工智能 03月28日 13:55
Dify 本地源码部署指南
index_new5.html
../../../zaker_core/zaker_tpl_static/wap/tpl_guoji1.html

 

本文提供了一份详尽的 Dify 本地源码部署指南，从环境准备到启动服务，再到常见问题解答，全方位指导用户在本地搭建 Dify 应用。文章详细介绍了 Dify 的架构、所需中间件、API 服务、Worker 服务和 Web 服务，并提供了启动命令和环境变量的说明，帮助用户快速上手并解决部署过程中可能遇到的问题。此外，还包括性能优化建议，助力用户提升 Dify 的运行效率。

⚙️ **架构总览**: Dify 架构由前端（基于 Next.js）、后端（基于 Flask）、Worker（基于 Celery）和多种中间件组成，包括数据库、缓存和向量数据库。

🐳 **环境准备**: 部署 Dify 需要 Docker、Python 3.12、Poetry、Node.js v18+、pnpm 以及 libmagic。文章详细介绍了安装步骤和常见问题解决方案。

🔌 **中间件服务**: Dify 依赖 PostgreSQL、Redis、Weaviate、Plugin Daemon、Sandbox 和 SSRF Proxy 等中间件。文档说明了各中间件的功能、配置和启动方式。

💻 **API、Worker 和 Web 服务**: 文章详细介绍了 API 服务的模块组成、启动方式，以及 Worker 服务的任务类型和启动命令。同时，也提供了 Web 服务的配置和启动指南，确保前端能够正确连接后端。

💡 **功能模块与访问**: 介绍了 Dify 的应用管理、知识库、对话管理、提示词管理、工作流和 AI 提供商管理等功能模块，以及如何通过浏览器访问 Dify 并配置 AI 提供商。

Dify 本地源码部署指南

本指南将帮助您从零开始在本地部署 Dify，包括所有必要的软件安装、中间件和模块的详细介绍，以及常见问题处理。

参考资料：

dify本地源码启动文档

docs.dify.ai/zh-hans/get…

1. Dify 架构概述

Dify 是一个 LLM 应用开发平台，其架构由以下几个主要部分组成：

    前端 (Web) ：基于 Next.js 构建的用户界面，提供应用管理、对话界面等功能后端 (API) ：基于 Flask 构建的 API 服务，处理业务逻辑和数据管理Worker：基于 Celery 的异步任务处理服务，负责处理耗时操作中间件：包括数据库、缓存、向量数据库等支持服务

2. 环境准备

2.1 安装 Docker

Docker 是运行 Dify 中间件服务（数据库、Redis 等）的必要工具。

MacOS 安装步骤：

brew install --cask docker​open /Applications/Docker.app

常见问题：

    问题：安装时提示 Error: It seems there is already a Binary at '/usr/local/bin/docker'

    解决方案：使用 --force 选项强制安装

    brew install --cask --force docker

    问题：安装后 docker 命令找不到

    解决方案：确保 Docker Desktop 应用已启动，或重启终端

2.2 安装 Python 环境

Dify 后端需要 Python 3.12 和 Poetry 包管理工具。

brew install python@3.12​curl -sSL https://install.python-poetry.org | python3 -​echo 'export PATH="/Users/$USER/.local/bin:$PATH"' >> ~/.zshrcsource ~/.zshrc​poetry --version

2.3 安装 Node.js 环境

Dify 前端需要 Node.js v18+ 和 pnpm。

brew install node@18​npm install -g pnpm​node --versionpnpm --version

2.4 安装其他依赖

brew install libmagic

3. 获取 Dify 源码

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

4. 中间件服务详解

Dify 依赖多个中间件服务，每个服务都有特定的功能：

4.1 PostgreSQL

作用：主数据库，存储用户、应用、对话等核心数据。

配置：默认运行在端口 5432 上，用户名 postgres，密码在 middleware.env 中配置。

4.2 Redis

作用：

    缓存服务，提高系统响应速度消息队列代理，支持 Celery 异步任务存储临时数据，如用户会话

配置：默认运行在端口 6379 上，无密码（如果设置了密码，需要在 .env 文件中配置）。

4.3 Weaviate

作用：向量数据库，用于存储和检索向量嵌入，支持知识库的语义搜索功能。

配置：默认运行在端口 8080 上。

4.4 Plugin Daemon

作用：插件守护进程，负责管理和执行 Dify 的插件。

配置：默认运行在端口 5002-5003 上。

4.5 Sandbox

作用：提供安全的代码执行环境，用于运行用户定义的代码。

4.6 SSRF Proxy

作用：防止服务器端请求伪造（SSRF）攻击的代理服务。

配置：默认运行在端口 3128 和 8194 上。

5. 启动中间件服务

注意：启动前先检查端口号是否被占用

cd docker​cp middleware.env.example middleware.env​docker compose -f docker-compose.middleware.yaml --env-file middleware.env up -d

常见问题：

    问题：Redis 连接错误 AUTH <password> called without any password configured

    解决方案：修改 API 的 .env 文件，移除 Redis 密码

    sed -i '' 's/CELERY_BROKER_URL=redis://:difyai123456@localhost:6379/1/CELERY_BROKER_URL=redis://localhost:6379/1/' .envsed -i '' 's/REDIS_PASSWORD=difyai123456/REDIS_PASSWORD=/' .env

6. Dify API 服务详解

API 服务是 Dify 的核心后端，负责处理所有业务逻辑和数据操作。

6.1 主要模块

    app：应用主模块，包含 Flask 应用实例和配置controllers：控制器，处理 HTTP 请求和响应models：数据模型，定义数据库结构services：业务服务，实现核心功能extensions：扩展模块，如数据库、缓存等tasks：异步任务定义libs：通用库和工具函数

6.2 配置并启动 API 服务

cd ../api​poetry env use 3.12poetry install​cp .env.example .env​source .venv/bin/activate​flask db upgrade​flask run --host 0.0.0.0 --port=5001 --debug

常见问题：

    问题：端口 5001 被占用解决方案：使用不同的端口，例如 --port=5002，并相应更新 Web 服务的配置问题：poetry: command not found解决方案：确保已将 Poetry 添加到 PATH，或使用完整路径 /Users/$USER/.local/bin/poetry

7. Worker 服务详解

Worker 服务基于 Celery 构建，用于处理异步任务，避免阻塞主 API 服务。

7.1 主要任务类型

    dataset：知识库相关任务，如文档导入、索引创建generation：生成内容相关任务，如长文本生成mail：邮件发送任务ops_trace：操作跟踪和监控任务

7.2 启动 Worker 服务

cd api​source .venv/bin/activate​celery -A app.celery worker -P gevent -c 1 -Q dataset,generation,mail,ops_trace --loglevel INFO

常见问题：

    问题：source: no such file or directory: .venv/bin/activate解决方案：确保当前目录是 api 目录，而不是项目根目录问题：Redis 连接错误解决方案：确保 Redis 配置正确，密码设置与 Docker 中的 Redis 实例一致

8. Web 服务详解

Web 服务是 Dify 的前端界面，基于 Next.js 构建，提供用户交互界面。

8.1 主要模块

    app：Next.js 应用主目录，包含页面和路由components：UI 组件context：React 上下文，管理全局状态hooks：自定义 React Hooksmodels：数据模型和类型定义service：API 服务调用utils：工具函数

8.2 配置并启动 Web 服务

# 进入 web 目录cd ../web​# 安装依赖pnpm install​# 创建环境配置文件cp .env.example .env.local​# 修改环境配置，确保 API 端点指向正确的端口# 编辑 .env.local 文件，设置以下内容：# NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api# NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api​# 启动 Web 服务pnpm run dev

常见问题：

    问题：API 端点配置错误，导致前端无法连接后端解决方案：确保 .env.local 中的 API 端点与实际运行的 API 服务端口一致

9. Dify 功能模块详解

9.1 应用管理

功能：创建和管理不同类型的 AI 应用，如聊天助手、文本生成等。

相关模块：

    API: controllers/console/appWeb: app/apps

9.2 知识库

功能：创建和管理知识库，支持文档导入、分段和检索。

相关模块：

    API: controllers/console/datasetsWeb: app/datasets

9.3 对话管理

功能：管理用户与 AI 的对话历史。

相关模块：

    API: controllers/console/conversationWeb: app/conversations

9.4 提示词管理

功能：创建和管理提示词模板。

相关模块：

    API: controllers/console/promptWeb: app/prompts

9.5 工作流

功能：创建复杂的 AI 工作流，组合多个步骤和条件。

相关模块：

    API: controllers/console/workflowWeb: app/workflows

9.6 AI 提供商管理

功能：配置和管理 AI 模型提供商，如 OpenAI、Anthropic 等。

相关模块：

    API: controllers/console/providersWeb: app/providers

10. 访问 Dify

现在，您可以通过浏览器访问 Dify：

    打开浏览器，访问 http://localhost:3000首次访问时，您需要注册一个管理员账户注册完成后，您将自动登录到 Dify 控制台

11. 配置 AI 提供商

要使用 Dify 的功能，您需要配置至少一个 AI 提供商：

    登录后，点击左侧菜单中的"设置"选择"AI 提供商"选项卡点击"添加"按钮，选择您想要添加的 AI 提供商（如 OpenAI、Anthropic 等）输入相应的 API 密钥和其他必要信息点击"保存"按钮

12. 完整启动命令汇总

每次启动 Dify，您需要按顺序执行以下命令：

cd dockerdocker compose -f docker-compose.middleware.yaml --env-file middleware.env up -d​cd ../apisource .venv/bin/activateflask run --host 0.0.0.0 --port=5001 --debug​cd apisource .venv/bin/activatecelery -A app.celery worker -P gevent -c 1 -Q dataset,generation,mail,ops_trace --loglevel INFO​cd webpnpm run dev

13. 环境变量详解

13.1 API 服务环境变量

    FLASK_APP：Flask 应用入口FLASK_DEBUG：是否启用调试模式SECRET_KEY：应用密钥，用于会话加密SQLALCHEMY_DATABASE_URI：数据库连接 URIREDIS_HOST/PORT/PASSWORD：Redis 连接信息CELERY_BROKER_URL：Celery 消息队列代理 URLUPLOAD_DIR：文件上传目录VECTOR_STORE_TYPE：向量存储类型（如 weaviate）

13.2 Web 服务环境变量

    NEXT_PUBLIC_API_PREFIX：API 服务的控制台 API 端点NEXT_PUBLIC_PUBLIC_API_PREFIX：API 服务的公共 API 端点NEXT_PUBLIC_DEPLOY_ENV：部署环境（DEVELOPMENT/PRODUCTION）NEXT_PUBLIC_EDITION：部署版本（SELF_HOSTED/CLOUD）

14. 常见问题总结

    Docker 安装问题

      使用 --force 选项解决冲突确保 Docker Desktop 应用已启动

    Poetry 安装问题

      确保 Poetry 已添加到 PATH使用完整路径执行命令

    端口冲突

    Redis 连接问题

      确保 Redis 密码配置与实际一致如果 Docker 中的 Redis 没有设置密码，则在配置中移除密码

    虚拟环境激活问题

    API 和 Web 服务连接问题

      确保 Web 服务的环境配置中 API 端点与实际运行的 API 服务端口一致

    文件类型检测问题

      安装 libmagic：brew install libmagic

    数据库迁移问题

    Worker 无法启动问题

      检查 Celery 版本兼容性确保 gevent 已正确安装

    知识库导入失败

      检查 Worker 服务是否正常运行检查文件格式是否支持

15. 性能优化建议

    增加 Worker 数量：对于大规模部署，可以增加 Worker 数量提高并发处理能力

    celery -A app.celery worker -P gevent -c 4 -Q dataset,generation,mail,ops_trace --loglevel INFO

    使用生产级 Web 服务器：在生产环境中，使用 Gunicorn 或 uWSGI 替代 Flask 开发服务器

    gunicorn -w 4 -b 0.0.0.0:5001 app:app

    启用 Redis 持久化：防止数据丢失

    REDIS_APPENDONLY=yes

    配置 PostgreSQL 优化：调整连接池大小和查询缓存

    使用 CDN：对于公开部署的实例，使用 CDN 加速静态资源

按照本指南操作，应该能够成功在本地部署 Dify。

Fish AI Reader

Fish AI Reader

AI辅助创作，多种专业模板，深度分析，高质量内容生成。从观点提取到深度思考，FishAI为您提供全方位的创作支持。新版本引入自定义参数，让您的创作更加个性化和精准。

FishAI

FishAI

鱼阅，AI 时代的下一个智能信息助手，助你摆脱信息焦虑

联系邮箱 441953276@qq.com

相关标签

Dify 本地部署 LLM 源码
相关文章
Import AI 368: 500% faster local LLMs; 38X more efficient red teaming; AI21’s Frankenmodel
Learn AI Together — Towards AI Community Newsletter #23
This AI newsletter is all you need #98
Patterns and Middleware for LLM Applications with Kyle Roche - #659
Building LLM-Based Applications with Azure OpenAI with Jay Emery - #657
Mental Models for Advanced ChatGPT Prompting with Riley Goodside - #652
FastGen: Cutting GPU Memory Costs Without Compromising on LLM Quality
Intel Releases a Low-bit Quantized Open LLM Leaderboard for Evaluating Language Model Performance through 10 Key Benchmarks
Vidur: A Large-Scale Simulation Framework Revolutionizing LLM Deployment Through Cost Cuts and Increased Efficiency
Llama 3 + Llama.cpp is the local AI Heaven