简介这份资源是面向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-VDocker 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 ar /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 组避免每次都要 sudosudo usermod -aG docker $USER # 重新登录 shell 后生效git 的安装更简单Ubuntu 上sudo apt-get install -y gitWindows 上从官网下载安装包安装时注意选择默认编辑器不然后面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 或 milvusSECRET_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_URLhttp://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 --tail50 api | grep -i error df -h /var/lib/docker关于 SSL如果要在公网暴露 Dify建议在 nginx 前面再加一层反向代理配证书而不是直接改 Dify 自带的 nginx 配置。这样升级时不会覆盖你的证书配置。我吃过这个亏升级后自定义的 SSL 配置被冲掉服务直接 502排查了半天才发现是配置文件被覆盖。源码二次开发时我习惯在改代码前先git stash保存当前改动拉取最新代码后再git stash pop避免合并冲突。如果冲突太多就新开分支重做。这个习惯帮我省了很多后悔药。希望帮到你。本文还有配套的精品资源点击获取
Dify 部署实战：Docker 与源码部署避坑指南
简介这份资源是面向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-VDocker 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 ar /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 组避免每次都要 sudosudo usermod -aG docker $USER # 重新登录 shell 后生效git 的安装更简单Ubuntu 上sudo apt-get install -y gitWindows 上从官网下载安装包安装时注意选择默认编辑器不然后面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 或 milvusSECRET_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_URLhttp://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 --tail50 api | grep -i error df -h /var/lib/docker关于 SSL如果要在公网暴露 Dify建议在 nginx 前面再加一层反向代理配证书而不是直接改 Dify 自带的 nginx 配置。这样升级时不会覆盖你的证书配置。我吃过这个亏升级后自定义的 SSL 配置被冲掉服务直接 502排查了半天才发现是配置文件被覆盖。源码二次开发时我习惯在改代码前先git stash保存当前改动拉取最新代码后再git stash pop避免合并冲突。如果冲突太多就新开分支重做。这个习惯帮我省了很多后悔药。希望帮到你。本文还有配套的精品资源点击获取
