简介：这份资源是面向AI应用开发初学者与技术爱好者的Dify平台本地部署教程文档，Dify作为融合后端即服务与LLMOps理念的开源大语言模型应用开发平台，能帮助缺乏深厚技术背景的用户快速搭建生产级生成式AI应用。文档围绕Docker与Git环境准备、代码仓库克隆、环境变量配置、Docker Compose服务启动及安装验证等环节展开，并附有官方安装链接与常见问题提示，便于读者按步骤完成本地部署。资源包内含1个docx文档，大小约266KB，内容紧凑、结构清晰，适合作为部署时的对照手册。目前已有517人学习，对于希望降低AI项目入门门槛、加速创意落地的个人或团队而言，可借助该教程快速完成环境搭建与初始化设置，同时为后续维护管理保留关键配置参考。
1. Dify 应用开发平台部署：从 docker 到 git 拉源码，一次跑通不返工
很多人第一次接触 Dify 应用开发平台，卡住的地方不是编排工作流，而是部署这一步。官方文档给的是标准路径，但真实环境里你会遇到 docker 网络不通、git 拉取报fatal: not a git repository、Windows 上 Docker Desktop 提示virtualization support not detected、CentOS 7 上镜像拉取超时、SSL 证书校验失败导致an error occurred during credentials validation。这些问题不解决，后面知识库流水线、智能体编排、多租户配置全都无从谈起。
这篇内容面向三类人：一是在本地 Windows 或 macOS 上想快速跑通 Dify 社区版的开发者；二是在 Linux 服务器上做生产级部署、需要配 SSL 和反向代理的运维；三是准备做 Dify 二次开发、需要从 git 拉源码改代码的工程师。我会把 docker 部署和源码部署两条路径都拆开讲，参数怎么设、坑在哪、失败时看什么日志，全部落到可复现的命令和配置上。读完你应该能独立完成一次干净的部署，而不是反复重装。
2. 部署前的环境选型：docker 一键起还是 git 拉源码
2.1 两种部署方式的适用边界
Dify 官方主推 docker compose 部署，仓库里自带docker-compose.yaml和.env.example，改完配置直接docker compose up -d就能起。这种方式适合绝大多数场景：本地开发验证、测试环境、中小规模生产。它的优势是依赖隔离干净，PostgreSQL、Redis、Weaviate、Nginx 全部由 compose 编排，你不用手动装一堆中间件。
源码部署适合两类人：一是要做 Dify 二次开发，必须改后端 Python 代码或前端 React 代码；二是公司安全策略不允许直接拉取外部镜像，需要自己构建。源码部署的代价是你得自己管 Python 3.11 环境、Node.js 18+ 环境、PostgreSQL 和 Redis 的连接配置，出问题时排查链路更长。
我一般的建议是：先用 docker 跑通，确认功能符合预期，再决定要不要转源码。不要一上来就源码部署，那会让你在环境问题上耗掉大量时间，还没看到 Dify 的界面就放弃了。
2.2 硬件与系统的最低要求
Dify 本身不重，但它依赖的向量库和模型调用会吃资源。最低配置我建议 2 核 4G 内存起步，磁盘 20G 以上。如果要用本地模型或者知识库索引大量文档，内存至少 8G。CPU 架构上，x86_64 和 arm64 都支持，但 arm64 下部分镜像需要确认是否有对应架构版本，Apple Silicon 的 Mac 上跑 Docker Desktop 一般没问题。
操作系统方面，Linux 推荐 Ubuntu 22.04 或 CentOS 7 以上。CentOS 7 的坑在于默认的 docker 版本较老，需要先升级 docker 到 20.10 以上，否则 compose v2 语法不识别。Windows 用户需要 Docker Desktop，并且必须在 BIOS 里开启虚拟化支持，否则会报virtualization support not detected。macOS 用户相对省心，装好 Docker Desktop 即可。
提示：Windows 家庭版不支持 Hyper-V，Docker Desktop 需要 WSL2 后端，安装前先确认系统版本。
2.3 docker 与 git 的安装确认
在动手部署 Dify 之前，先把 docker 和 git 装好并验证版本。这一步看起来简单，但很多后续报错都源于版本不匹配。
# 检查 docker 版本，要求 20.10 以上 docker --version # 检查 docker compose 版本，要求 v2 以上 docker compose version # 检查 git 版本 git --version如果 docker 没装，Ubuntu 上用官方脚本安装：
# 卸载旧版本 sudo apt-get remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg # 添加 docker 官方 GPG key sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg # 添加仓库 echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 docker 和 compose 插件 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin安装完成后把当前用户加入 docker 组，避免每次都要 sudo：
sudo usermod -aG docker $USER # 重新登录 shell 后生效git 的安装更简单，Ubuntu 上sudo apt-get install -y git，Windows 上从官网下载安装包，安装时注意选择默认编辑器，不然后面git commit --amend时会弹出一个你不会用的编辑器。
3. docker compose 部署 Dify：从拉取到访问的完整命令
3.1 获取 Dify 源码与配置环境变量
docker 部署也需要先拿到 compose 文件，所以第一步还是 git clone。这里就是很多人翻车的地方：在错误的目录下执行 git 命令，会报fatal: not a git repository (or any of the parent directories): .git。这个报错的意思是当前目录不是 git 仓库，不是 git 没装好。
# 进入你准备存放项目的目录 cd /opt # 克隆 Dify 仓库，--depth 1 只拉最新一次提交，加快速度 git clone --depth 1 https://github.com/langgenius/dify.git # 进入 docker 部署目录 cd dify/docker # 复制环境变量模板 cp .env.example .env克隆完成后，dify/docker目录下会有docker-compose.yaml和.env。.env是核心配置文件，里面控制数据库密码、Redis 密码、端口映射、向量库类型等。默认配置可以直接用，但生产环境必须改几个关键项。
# 查看 .env 中需要关注的配置项 grep -E "^(EXPOSE_NGINX_PORT|DB_PASSWORD|REDIS_PASSWORD|VECTOR_STORE|SECRET_KEY)" .env参数说明：EXPOSE_NGINX_PORT是 Dify 对外暴露的端口，默认 80，如果 80 被占用改成 8080 之类；DB_PASSWORD和REDIS_PASSWORD是内部中间件密码，生产环境必须改强密码；VECTOR_STORE默认是 weaviate，可以改成 qdrant 或 milvus；SECRET_KEY用于加密会话，必须改成一串随机字符串。
3.2 启动容器并确认服务健康状态
配置改完后，一条命令拉起所有服务：
# 在 dify/docker 目录下执行 docker compose up -d # 查看容器状态 docker compose ps正常情况下你会看到 api、worker、web、db、redis、weaviate、nginx 等容器都是 running 或 healthy。第一次启动需要拉取镜像，时间取决于网络。如果卡在拉取镜像，可以配置国内镜像加速器，在/etc/docker/daemon.json里加registry-mirrors。
# 查看 api 容器日志，确认没有报错 docker compose logs -f api # 查看 nginx 日志 docker compose logs -f nginx如果 api 容器反复重启，大概率是数据库连接失败。检查.env里的DB_PASSWORD和docker-compose.yaml里 db 服务的POSTGRES_PASSWORD是否一致。这两个地方不一致是新手最常见的翻车点，因为.env里的变量会被 compose 文件引用，但如果你手动改过 compose 文件，就可能对不上。
3.3 初始化管理员账号与首次登录
容器全部健康后，浏览器访问http://你的服务器IP:EXPOSE_NGINX_PORT，默认是 80 端口。第一次访问会跳转到初始化页面，让你设置管理员邮箱和密码。这里如果报an error occurred during credentials validation，通常是前端无法连接后端 API，检查 nginx 容器是否正常，以及浏览器控制台的网络请求返回什么状态码。
初始化完成后进入 Dify 主界面，你可以先创建一个简单的聊天助手应用验证功能。如果模型供应商还没配，会提示你先去设置里添加模型。Dify 本身不提供模型，需要你填入 OpenAI、DeepSeek 或其他兼容 OpenAI 接口的模型服务的 API Key。
注意：如果多次输错管理员密码，会触发
too many incorrect password attempts. please try again later.，等几分钟再试，或者直接改数据库重置。
4. 源码部署与二次开发：Python 后端和前端分别怎么起
4.1 后端 Python 环境与依赖安装
源码部署的第一步是确认 Python 版本。Dify 后端要求 Python 3.11，低于这个版本会有依赖装不上。
# 检查 Python 版本 python3 --version # 如果低于 3.11，用 pyenv 或 deadsnakes PPA 安装 sudo apt-get install -y python3.11 python3.11-venv # 进入后端目录 cd dify/api # 创建虚拟环境 python3.11 -m venv venv source venv/bin/activate # 安装依赖 pip install -r requirements.txt依赖安装过程中如果遇到编译错误，通常是缺少系统库，比如libpq-dev、gcc、python3.11-dev。Ubuntu 上先sudo apt-get install -y build-essential libpq-dev python3.11-dev再重试。
后端启动前需要配置环境变量，复制.env.example为.env，重点改数据库和 Redis 连接地址。如果你用 docker 起了中间件，地址填localhost对应的映射端口；如果中间件也在 docker 网络里，填容器名。
# 初始化数据库 flask db upgrade # 启动 API 服务 flask run --host 0.0.0.0 --port 50014.2 前端 Node.js 环境与构建
前端在dify/web目录，需要 Node.js 18 以上。
cd dify/web # 检查 node 版本 node --version # 安装依赖，推荐用 pnpm npm install -g pnpm pnpm install # 开发模式启动 pnpm dev开发模式下前端默认跑在 3000 端口，需要配置代理指向后端 5001。生产构建用pnpm build，产物在.next目录，可以用pnpm start启动。
源码部署的坑在于前后端版本要匹配。如果你只更新了后端代码没更新前端，或者反过来，可能会出现接口不兼容。做二次开发时，建议用 git 分支管理，每次改动前先git checkout -b feature/xxx，改完再合并。git commit --amend用来修改最近一次提交，但注意如果已经推送到远程，amend 后需要强制推送，团队协作时要谨慎。
4.3 源码模式下知识库流水线的配置差异
源码部署时，知识库的文档处理依赖unstructured服务。docker 部署时这个服务已经包含在 compose 里，源码部署需要你自己起。如果没配，上传文档时会报unstructured api url is not configured for doc file processing.。
解决办法是在.env里设置UNSTRUCTURED_API_URL，指向你部署的 unstructured 服务地址。如果不想额外部署，可以改用 Dify 内置的简单解析器，但支持的格式会少一些，PDF 和 Word 的解析效果也会打折扣。
# 在 api/.env 中添加 UNSTRUCTURED_API_URL=http://localhost:8000 # 然后重启 api 服务这个配置在 docker 部署里通常不需要手动改，因为 compose 文件已经处理好了。源码部署时容易漏掉，导致知识库功能不可用。
5. 部署避坑：SSL 报错、网络不通、版本冲突的排查记录
5.1 SSL 证书校验失败导致凭据验证报错
现象：配置模型供应商时，填入 API Key 后报an error occurred during credentials validation，但同样的 Key 在别的工具里能用。
原因：Dify 后端容器内的 CA 证书不完整，或者系统时间不对导致证书校验失败。CentOS 7 上这个问题尤其常见，因为默认的 ca-certificates 包版本太老。
解决：进入 api 容器更新证书，或者挂载宿主机的证书目录。
# 进入 api 容器 docker compose exec api bash # 更新证书 apt-get update && apt-get install -y ca-certificates # 如果容器里没有 apt，用宿主机挂载宿主机是 CentOS 7 的话，先yum update ca-certificates，然后在 compose 文件里把/etc/ssl/certs挂载到容器内。
5.2 docker 网络不通导致容器间无法通信
现象：docker compose up -d后容器都起来了，但 api 连不上 db，日志报 connection refused。
原因：docker 默认的 bridge 网络在某些环境下会有 iptables 规则冲突，或者 docker 服务没正常启动网络组件。
解决：先检查 docker 网络列表，然后重启 docker 服务。
# 查看网络 docker network ls # 查看 dify 默认网络详情 docker network inspect docker_default # 重启 docker sudo systemctl restart docker # 重新拉起 compose docker compose down && docker compose up -d如果还是不通，检查防火墙是否拦截了 docker 的虚拟网卡。sudo iptables -L看有没有 DROP 规则影响docker0或br-开头的网桥。
5.3 Windows 上 Docker Desktop 启动失败
现象：安装完 Docker Desktop 后启动报virtualization support not detected或docker desktop failed to start。
原因：BIOS 里虚拟化没开，或者 WSL2 没装好，或者 Hyper-V 和 WSL2 冲突。
解决：重启进 BIOS 开启 Intel VT-x 或 AMD-V，然后在 Windows 功能里确认「虚拟机平台」和「适用于 Linux 的 Windows 子系统」都勾选。如果用的是 WSL2 后端，执行wsl --update更新内核。
# 以管理员身份运行 PowerShell wsl --install wsl --set-default-version 2 # 然后重启 Docker Desktop5.4 git 拉取代码时的仓库识别错误
现象：执行git clone或git pull时报fatal: not a git repository (or any of the parent directories): .git。
原因：当前目录不是 git 仓库，或者.git目录被误删。常见于在错误的层级执行命令，比如在dify目录而不是dify/docker目录下执行 git 操作。
解决：用pwd确认当前目录，ls -la看有没有.git目录。如果没有，回到正确的仓库目录，或者重新 clone。
# 确认当前目录 pwd # 查看是否有 .git ls -la | grep .git # 如果确实不在仓库里，重新克隆 cd /opt && git clone --depth 1 https://github.com/langgenius/dify.git5.5 升级 Dify 时的版本冲突与数据迁移
现象：从旧版本升级到新版本后，容器起不来，或者数据库迁移报错。
原因：.env配置格式在新版本有变化，或者数据库 schema 不兼容。
解决：升级前先备份数据库，然后拉取新代码，对比.env.example和你的.env，把新增的配置项补上。
# 备份数据库 docker compose exec db pg_dump -U postgres dify > backup.sql # 拉取新代码 git pull # 对比配置 diff .env .env.example # 重新构建并启动 docker compose down docker compose pull docker compose up -d如果数据库迁移失败，看 api 容器日志里的 alembic 报错，必要时回滚到旧版本镜像，先恢复数据再排查。
6. 部署后的验证与日常维护：几个我常用的检查习惯
部署完成只是开始，日常维护里我习惯做几件事来确认系统健康。第一是每天看一眼docker compose ps，确认没有容器反复重启。第二是定期检查磁盘，PostgreSQL 和向量库的数据增长比想象中快，尤其是知识库文档多的时候。第三是关注 api 日志里的错误关键词，比如timeout、connection refused、credentials validation，这些往往是问题的早期信号。
验证部署是否真正可用，我会跑一个最小闭环：创建一个聊天助手，配一个模型，发一条消息，确认能返回。然后上传一个 PDF 到知识库，等索引完成，再问一个只有该 PDF 里才有的问题，确认检索增强生效。这两步过了，说明部署是完整的。
# 我常用的健康检查命令组合 docker compose ps --format "table {{.Name}}\t{{.Status}}" docker compose logs --tail=50 api | grep -i error df -h /var/lib/docker关于 SSL，如果要在公网暴露 Dify，建议在 nginx 前面再加一层反向代理配证书，而不是直接改 Dify 自带的 nginx 配置。这样升级时不会覆盖你的证书配置。我吃过这个亏，升级后自定义的 SSL 配置被冲掉，服务直接 502，排查了半天才发现是配置文件被覆盖。
源码二次开发时，我习惯在改代码前先git stash保存当前改动，拉取最新代码后再git stash pop，避免合并冲突。如果冲突太多，就新开分支重做。这个习惯帮我省了很多后悔药。
希望帮到你。
本文还有配套的精品资源，点击获取
