简介这份PDF教程面向希望快速上手开源LLM应用开发平台的开发者与AI应用爱好者围绕Dify的本地化部署展开帮助读者在自有环境中搭建一套可运行的生成式AI应用原型系统无需依赖复杂云服务即可完成技术验证与演示。资源包内仅含1个PDF文件大小约711KB内容以图文结合的命令行操作指导为主覆盖从环境准备到容器启动的完整流程。教程从Docker与Git的前置安装讲起逐步演示新建目录、克隆源码、复制环境变量配置、使用docker compose一键拉起服务并说明如何通过容器状态确认九个组件是否健康运行最后引导访问本地地址完成管理员账号初始化。对于网络受限或克隆失败的情况文中也提供了替代获取方式与注意事项并提醒妥善保存超级管理员凭证。目前已有1350人学习适合具备基础命令行经验、想深入定制或拓展Dify功能的开发者参考。1. 从一份 Dify 部署教程说起为什么有人 20 分钟跑通有人卡三天Dify 应用开发平台这两年被大量团队拿来搭智能体、知识库问答和内部工作流社区版一条docker compose up -d理论上就能起服务但现实里翻车的人不少。我见过最典型的场景一台刚装好的 CentOS 7 或 Windows 机器照着某份《Dify 应用开发平台部署教程.pdf》一步步敲结果卡在镜像拉取、端口冲突、SSL 报错、an error occurred during credentials validation这类问题上三天都没进到登录页。这篇不是把那份 PDF 复述一遍而是把 Dify 本地部署这条链路拆开讲清楚Docker 和 Git 这两个前置到底怎么配、.env里哪些参数必须改、知识库依赖的向量库和文档解析怎么接、升级和排错怎么做。适合两类人一类是第一次在本地或内网服务器上跑 Dify 的开发者照着命令能复现另一类是已经跑起来但被 SSL、多租户、文档处理报错折腾过的运维能看到参数边界和踩坑点。核心结论先放这Dify 部署的难点从来不在 Dify 本身而在它依赖的那一圈基础设施——Docker 网络、Git 拉取、向量数据库、反向代理任何一个没对齐都会让你以为是自己装错了。2. Dify 部署前的基础设施Docker、Git 与目录规划2.1 为什么 Dify 强依赖 Docker 而不是裸装Dify 社区版官方推荐的部署方式就是 Docker Compose原因很直接它一次性要拉起 api、worker、web、dbPostgreSQL、redis、向量库默认 Weaviate也可换 Qdrant/Milvus六七个容器裸装 Python 环境光是依赖版本冲突就够你调一天。Docker 把这些运行时隔离掉你只需要保证宿主机 Docker 能正常跑、网络能拉镜像、磁盘够用。选型上个人开发机用 Docker DesktopWindows/macOS最省事内网服务器用 Docker Engine Compose 插件。这里有个高频坑Windows 上装 Docker Desktop 报virtualization support not detected本质是 BIOS 里虚拟化没开或和 Hyper-V/WSL2 冲突不是 Docker 的问题。CentOS 7 上则是内核版本偏老建议至少 3.10 以上并升级到较新的 Docker 版本否则 Compose 语法可能不认。Git 的作用是拉取 Dify 源码仓库因为.env.example、docker-compose.yaml、volumes目录结构都在仓库里直接下压缩包容易漏掉隐藏文件。Git 安装后建议顺手配好用户名邮箱避免后续git commit --amend之类操作报身份错误。2.2 环境准备的可复现命令先确认 Docker 和 Git 都可用这一步别跳过很多“部署失败”其实是环境没装好。# 检查 Docker 版本与 Compose 插件 docker --version docker compose version # 检查 Git git --version # 查看磁盘空间Dify 镜像加数据建议预留 20G 以上 df -h逻辑说明docker compose version输出的是 v2 插件版本如果你只有docker-compose带横杠说明是老的 v1部分新语法会报错建议升级。df -h是血泪经验镜像拉一半磁盘满导致容器起不来排查时很容易忽略。参数说明Docker Engine 建议 20.10 以上Compose 建议 v2.20 以上Git 2.x 即可。Windows 用户如果用的是 Docker Desktop确认设置里 WSL2 后端已启用。2.3 目录规划与源码拉取不要随便找个目录就 cloneDify 运行时会挂载volumes目录存数据库和上传文件路径最好固定且空间充足。# 建一个专门的工作目录 mkdir -p /opt/dify cd /opt/dify # 拉取 Dify 源码社区版 git clone https://github.com/langgenius/dify.git # 进入 docker 部署目录 cd dify/docker # 复制环境变量模板 cp .env.example .env逻辑说明git clone拿到的是完整仓库docker子目录里才是 Compose 部署需要的文件。.env.example是模板必须复制成.env才会被 Compose 读取直接改模板文件在升级时会被覆盖。参数说明/opt/dify可换成你习惯的路径但别放在/tmp下重启会丢。如果内网无法直连 GitHub常见做法是配置 Git 的代理或使用内网镜像源这一步按你所在网络环境处理。提示.env里默认端口是 80 和 443如果宿主机已被 Nginx 占用先改EXPOSE_NGINX_PORT再启动否则会报端口绑定失败。3. 用 Docker Compose 把 Dify 跑起来参数、启动与验证3.1 .env 里必须改的几个参数.env文件几百行但真正影响能否跑通的就那么几个。下面这张表是我每次部署都会过一遍的。参数默认值作用建议EXPOSE_NGINX_PORT80Web 访问端口被占用就改 8080EXPOSE_NGINX_SSL_PORT443HTTPS 端口不配 SSL 可忽略SECRET_KEY随机串会话加密必须改成自己的强随机值DB_PASSWORDdifyai数据库密码内网也建议改VECTOR_STOREweaviate向量库类型按需换 qdrant/milvusCONSOLE_API_URL空控制台 API 地址配域名时必填SECRET_KEY不改的后果是多人共用默认值时会话互相干扰属于玄学问题的常见来源。生成方式# 生成一个随机 SECRET_KEY openssl rand -base64 42逻辑说明把输出粘贴到.env的SECRET_KEY后面。openssl在 Linux/macOS 自带Windows 可用 Git Bash 执行。参数说明-base64 42输出长度足够别用简单字符串Dify 对密钥强度有校验太弱会在启动日志里警告。3.2 启动命令与容器状态检查# 在 dify/docker 目录下启动全部服务 docker compose up -d # 查看容器状态 docker compose ps # 跟踪 api 容器日志确认没有报错 docker compose logs -f api逻辑说明up -d后台拉起所有容器第一次会拉镜像耗时取决于网速。ps看的是容器是否 Up但 Up 不代表服务健康必须看api日志里有没有Application startup complete之类的成功标志。参数说明如果只想先起数据库和向量库可以docker compose up -d db redis weaviate再单独起 api便于定位问题。日志里出现credentials validation相关报错多半是数据库密码或连接串不一致回头核对.env里的DB_PASSWORD和DATABASE_URL。3.3 访问验证与初始化浏览器打开http://你的IP:端口第一次会进初始化页面让你设置管理员账号。如果页面打不开按这个顺序排查容器是否 Up → 端口是否被防火墙拦 → Nginx 容器日志有没有 502。# 看 nginx 容器日志 docker compose logs nginx # 从宿主机本地测试端口 curl -I http://127.0.0.1:80逻辑说明curl -I返回 200 或 302 说明 Nginx 在正常响应返回连接拒绝就是端口没通。云服务器还要检查安全组是否放行对应端口。参数说明初始化管理员账号后这个账号就是超级管理员密码别用弱口令。多租户场景下社区版 1.10 之后对租户隔离有调整如果要做多团队共用建议先确认版本再规划。4. 知识库与模型接入让 Dify 真正能干活4.1 向量库选型Weaviate、Qdrant 还是 MilvusDify 默认用 Weaviate够用但资源占用偏高。如果你只是本地测试默认即可如果要上生产或数据量大Qdrant 更轻Milvus 更适合大规模。切换方式是在.env里改VECTOR_STORE然后按对应配置填连接信息。# 切换到 Qdrant 的示例配置 VECTOR_STOREqdrant QDRANT_URLhttp://qdrant:6333 QDRANT_API_KEYyour_api_key逻辑说明改完VECTOR_STORE后Compose 文件里对应的服务才会被启用别只改.env不改 Compose profile。切换向量库后已有知识库数据不会自动迁移需要重新索引。参数说明QDRANT_URL用容器名qdrant而不是localhost因为容器间通过 Docker 网络通信。QDRANT_API_KEY如果没设就留空但生产环境建议设。4.2 文档处理报错的常见原因热词里出现的dify unstructured api url is not configured for doc file processing是高频报错。原因是 Dify 处理 PDF、Word 这类非纯文本文件时依赖 Unstructured API 做解析而默认配置里没启用。# 在 .env 中启用 Unstructured ETL_TYPEUnstructured UNSTRUCTURED_API_URLhttp://unstructured:8000 UNSTRUCTURED_API_KEY逻辑说明ETL_TYPE决定用哪套文档抽取管线设成Unstructured后需要额外起 unstructured 容器。如果不想多起服务也可以设成Dify用内置解析但复杂 PDF 效果会差一些。参数说明UNSTRUCTURED_API_URL指向容器内地址不是公网。启用后记得docker compose up -d重新拉起只重启 api 不够。4.3 接入本地大模型以 Qwen2.5-7B 为例Dify 本身不含模型需要接外部推理服务。本地部署常见做法是用 vLLM 或 Ollama 起一个 OpenAI 兼容接口再在 Dify 的模型供应商里配置。# 用 vLLM 起一个 OpenAI 兼容服务示例 python -m vllm.entrypoints.openai.api_server \ --model Qwen/Qwen2.5-7B-Instruct \ --port 8000 \ --host 0.0.0.0逻辑说明vLLM 暴露的/v1接口和 OpenAI 格式一致Dify 里选“OpenAI-API-compatible”供应商填http://你的IP:8000/v1即可。模型名填Qwen/Qwen2.5-7B-Instruct。参数说明--host 0.0.0.0让容器外可访问否则 Dify 容器连不上。显存不够时加--gpu-memory-utilization 0.9或量化。如果 Dify 和 vLLM 不在同一台机器注意防火墙和 Docker 网络。注意Dify 容器访问宿主机服务时localhost指向容器自己要用宿主机内网 IP 或host.docker.internalDocker Desktop 支持。5. 部署避坑与常见问题排查5.1 SSL 报错与反向代理配置现象配了域名和证书后页面报 SSL 错误或dify ssl错误。原因Dify 自带 Nginx 容器如果你外层又套了一层 Nginx 或云负载均衡证书和转发规则容易冲突。解决要么让 Dify 的 Nginx 直接管证书要么把 Dify 的 443 映射到内层外层只做转发并确保CONSOLE_API_URL、APP_API_URL填的是 https 域名。5.2 credentials validation 报错现象启动后 api 日志反复报an error occurred during credentials validation。原因数据库连接串和实际密码不一致或 PostgreSQL 容器还没初始化完 api 就启动了。解决核对.env里DB_PASSWORD与DATABASE_URL中的密码是否一致如果是首次启动等 db 容器健康检查通过再起 api或直接docker compose restart api。5.3 端口冲突导致容器起不来现象docker compose up -d后 nginx 容器不断重启。原因宿主机 80 或 443 已被占用。解决netstat -tlnp | grep 80找到占用进程或直接改.env里EXPOSE_NGINX_PORT8080重新 up。5.4 升级后数据丢失或页面异常现象git pull更新代码后重新 up知识库数据没了或页面报错。原因升级时如果动了volumes目录或改了数据库密码数据就对不上了。解决升级前备份volumes目录和数据库升级只git pulldocker compose up -d不要删 volumes。热词里的dify 在线升级 windows场景建议先在测试环境验证。5.5 Docker 网络不通导致容器互相访问失败现象api 连不上 redis 或向量库日志报连接超时。原因容器不在同一 Docker 网络或自定义网络配置错误。解决docker network ls确认 Compose 创建的网络存在docker compose down后重新up让网络重建别手动改网络配置。6. 进阶多租户、内网离线部署与验证清单多租户这块Dify 社区版 1.10 之后对租户模型做了调整如果你要给多个团队共用一套实例建议先确认版本行为默认情况下每个注册用户会创建自己的租户空间管理员可以在设置里管理成员和权限。内网离线部署是另一个高频需求核心思路是提前在有网机器上docker pull所有镜像docker save成 tar 包拷到内网docker load再把 Git 仓库打包带过去.env里所有外部 URL 改成内网地址。验证清单我一般这么过容器全部 Up → api 日志无 ERROR → 登录页能打开 → 能创建应用 → 能上传文档并成功索引 → 能对话返回结果。这六步全过才算真正部署完成而不是“容器起来了”就完事。# 一键检查容器健康状态 docker compose ps --format table {{.Name}}\t{{.Status}} # 导出所有镜像用于离线迁移 docker save $(docker compose config --images) -o dify-images.tar逻辑说明config --images列出 Compose 用到的所有镜像名docker save打包成一个 tar内网机器docker load -i dify-images.tar即可。参数说明tar 包可能好几个 G传输前确认磁盘空间。我自己踩过最深的一个坑是以为容器 Up 就是部署成功结果知识库上传文档一直失败查了两小时才发现是 Unstructured 没启用。后来我养成的习惯是每次部署完先跑一遍上面那六步验证不跳步。希望帮到你。本文还有配套的精品资源点击获取
)
