1. 概述什么是 DifyDify 是一个开源的 LLM 应用开发平台旨在帮助开发者快速构建、部署和管理基于大语言模型的 AI 应用。它提供了可视化的编排工具、丰富的模型集成、知识库管理、工作流设计等功能让开发者无需深入底层代码即可创建复杂的 AI 应用。核心优势可视化编排通过拖拽式界面构建复杂的 AI 工作流。多模型支持无缝集成 OpenAI、Anthropic、国内主流大模型以及开源模型如 Llama、Qwen 等。知识库增强支持上传多种格式文档构建私有知识库实现基于文档的精准问答。应用托管一键部署为 Web 应用、API 或集成到其他系统。开源可私有化代码完全开源支持本地部署保障数据隐私和安全。下面是 Dify 本地部署的整体流程图否是准备系统环境安装 Docker 与 Docker Compose下载部署文件配置 .env 环境变量启动服务 docker compose up -d服务是否正常启动?查看日志排查问题访问控制台并初始化管理员配置模型供应商创建并发布 AI 应用2. 部署前准备2.1 系统要求操作系统Linux (Ubuntu 20.04/CentOS 7)、macOS 或 Windows (WSL2 推荐)。Docker Docker Compose这是最推荐的部署方式需提前安装。硬件资源CPU4 核以上。内存8 GB 以上运行大模型或知识库检索需要更多内存。磁盘空间至少 20 GB 可用空间。网络能够访问 Docker Hub 和所需的模型仓库如 Hugging Face。2.2 安装 Docker 和 Docker Compose如果你的系统尚未安装请参考以下命令以 Ubuntu 为例# 1. 更新软件包索引并安装必要依赖sudoapt-getupdatesudoapt-getinstallca-certificatescurl# 2. 添加 Docker 官方 GPG 密钥sudoinstall-m0755-d/etc/apt/keyringssudocurl-fsSLhttps://download.docker.com/linux/ubuntu/gpg-o/etc/apt/keyrings/docker.ascsudochmodar /etc/apt/keyrings/docker.asc# 3. 添加 Docker APT 仓库echo\deb [arch$(dpkg --print-architecture)signed-by/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \$(./etc/os-releaseecho$VERSION_CODENAME)stable|\sudotee/etc/apt/sources.list.d/docker.list/dev/null# 4. 更新并安装 Docker 引擎sudoapt-getupdatesudoapt-getinstalldocker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin# 5. 验证安装sudodockerrun hello-world3. 使用 Docker Compose 快速部署这是最简单、最主流的部署方式。3.1 下载部署文件# 创建项目目录并进入mkdirdify-localcddify-local# 下载 docker-compose.yml 配置文件curl-odocker-compose.yml https://raw.githubusercontent.com/langgenius/dify/main/docker/docker-compose.yaml# 下载环境变量配置文件curl-o.env https://raw.githubusercontent.com/langgenius/dify/main/docker/.env.example3.2 配置环境变量编辑.env文件关键配置项如下# 数据库配置使用内置 PostgreSQLDB_PASSWORDyour_secure_password_here# 外部访问地址根据你的网络环境修改CONSOLE_API_URLhttp://localhost:5001CONSOLE_WEB_URLhttp://localhost:3000APP_API_URLhttp://localhost:5001APP_WEB_URLhttp://localhost:3000# 可选邮件服务配置用于用户注册/密码重置# MAIL_TYPEsmtp# MAIL_HOSTsmtp.gmail.com# MAIL_PORT587# MAIL_USERyour_emailgmail.com# MAIL_PASSWORDyour_app_password3.3 启动 Dify 服务# 在项目目录 (dify-local) 下执行sudodockercompose up-d此命令会拉取镜像并启动所有必需的服务包括 Web 前端、API 后端、数据库等。3.4 访问与初始化等待服务启动首次启动可能需要几分钟拉取镜像和初始化数据库。访问控制台在浏览器中打开http://localhost:3000。初始化管理员账户首次访问会引导你创建第一个管理员账号。登录并开始使用使用创建的管理员账号登录即可进入 Dify 控制台。4. 配置与调优4.1 配置模型供应商进入控制台后首要任务是配置模型供应商否则无法创建 AI 应用。点击左下角“设置”-“模型供应商”。选择你需要的模型提供商如 OpenAI、Azure OpenAI、通义千问、DeepSeek 等。填入对应的 API Key 和 Base URL如果需要。点击“保存”并“校验”。4.2 配置知识库向量数据库可选Dify 默认使用内置的向量数据库Weaviate。对于生产环境或大量文档建议使用外部向量库。修改.env文件# 例如使用 QdrantVECTOR_STOREqdrantQDRANT_URLhttp://qdrant:6333然后重启服务sudo docker compose down sudo docker compose up -d4.3 数据持久化与备份Dify 的 Docker 部署默认将数据数据库、上传文件、向量数据存储在命名卷中。建议映射到宿主机目录以便备份。修改docker-compose.yml为相关服务添加volumes映射例如services:db:volumes:-./data/pg_data:/var/lib/postgresql/datastorage:volumes:-./data/storage:/app/storage5. 常见问题与故障排除5.1 端口冲突如果 3000 或 5001 端口被占用可以在.env文件中修改CONSOLE_WEB_URLhttp://localhost:3001APP_WEB_URLhttp://localhost:3001并在docker-compose.yml中修改对应服务的端口映射。5.2 服务启动失败检查日志sudo docker compose logs [service_name]例如sudo docker compose logs api。常见原因内存不足尝试增加系统 Swap 空间或关闭其他占用内存的应用。网络问题确保能正常访问 Docker Hub 和 GitHub。数据库初始化失败尝试删除数据卷重新启动 (sudo docker compose down -v然后重新up -d)。5.3 更新 Dify 版本# 进入项目目录cddify-local# 拉取最新的镜像sudodockercompose pull# 重启服务sudodockercompose up-d# 执行数据库迁移如果需要通常会自动进行sudodockercomposeexec-Tapi flask db upgrade5.4 常见故障排查速查表故障现象可能原因排查命令 / 方法解决方案服务启动后无法访问控制台端口未映射或防火墙拦截sudo docker compose ps检查端口映射放行 3000/5001 端口API 返回 502 Bad GatewayAPI 服务未就绪或崩溃sudo docker compose logs api等待初始化完成或重启 api 服务数据库连接失败PostgreSQL 未启动或密码错误sudo docker compose logs db核对.env中DB_PASSWORD重建数据卷模型调用报错API Key 无效或网络不通控制台「模型供应商」页校验重新填写 Key检查网络代理设置上传文档后知识库检索无结果向量数据库未正确配置sudo docker compose logs worker检查VECTOR_STORE配置并重启磁盘空间不足镜像或日志堆积sudo docker system df清理无用镜像与日志docker system prune6. 进阶部署方式6.1 使用 Kubernetes 部署对于生产级高可用部署推荐使用 Kubernetes。Dify 官方提供了 Helm Chart。# 添加 Helm 仓库helm repoadddify https://langgenius.github.io/dify-helm# 安装 Difyhelminstalldify dify/dify-ndify --create-namespace-fvalues.yaml你需要准备一个自定义的values.yaml文件来配置数据库、存储、模型等。6.2 从源码构建适合开发者进行二次开发或深度定制。# 克隆仓库gitclone https://github.com/langgenius/dify.gitcddify# 后端启动cdapipipinstall-rrequirements.txt flask run--host0.0.0.0--port5001# 前端启动另一个终端cdwebnpminstallnpmrun dev6.3 部署方式对比部署方式难度适用场景优点缺点Docker Compose⭐ 低个人开发、中小团队、快速试用部署快、一键升级、资源占用适中单机部署高可用性有限Kubernetes (Helm)⭐⭐⭐ 高生产环境、大规模集群、高可用要求弹性伸缩、自动容灾、滚动更新运维复杂需要 K8s 集群源码构建⭐⭐ 中二次开发、深度定制、研究源码完全可控、便于调试与修改升级需手动合并维护成本高选型建议追求快速上手与低成本 → 选择Docker Compose。面向生产且已有 K8s 基础设施 → 选择Kubernetes。需要修改源码或深度集成 → 选择源码构建。7. 总结通过 Docker Compose你可以在几分钟内完成 Dify 的本地部署快速拥有一个功能强大的私有 AI 应用开发平台。部署完成后重点在于配置好模型供应商和知识库然后就可以开始可视化地构建你的第一个 AI 智能体、聊天应用或工作流了。对于寻求更高可控性和定制化的用户可以考虑源码部署或 Kubernetes 部署方案。记得定期关注 Dify GitHub 仓库 的更新以获取新功能和安全补丁。