简介这份PDF教程面向希望快速上手开源LLM应用开发平台的开发者与AI应用爱好者围绕Dify的本地化部署展开帮助读者在自有环境中搭建一套可运行的生成式AI应用原型系统无需依赖复杂云服务即可完成技术验证与演示。资源包内仅含1个PDF文件大小约711KB内容以图文结合的命令行操作指导为主覆盖从环境准备到容器启动的完整流程。教程从Docker与Git的前置安装讲起逐步演示新建目录、克隆源码、复制环境变量配置、使用docker compose一键拉起服务并说明如何通过容器状态确认九个服务是否健康运行最后引导访问本地地址完成管理员账号初始化。对于网络受限或克隆失败的情况文中也提供了替代获取方式与排错提示。目前已有1350人学习下载适合初学者对照操作也便于有经验的开发者在此基础上进行定制与扩展。1. 从一份 Dify 部署教程说起为什么 Docker 是绕不开的第一道坎很多人第一次接触 Dify 应用开发平台都是被它「拖拽式编排 LLM 应用」的能力吸引进来的结果真正动手时卡住的地方往往不是工作流怎么画而是环境根本起不来。我见过太多人在 Windows 上装完 Docker Desktop拉完镜像docker compose up -d一敲容器起起落落浏览器打开一片空白日志里全是数据库连接超时或者 SSL 握手失败。这份部署教程要解决的核心问题就是把 Dify 从「看起来能用」变成「本地稳定跑起来」。Dify 本身是一套前后端分离的 LLM 应用开发平台后端依赖 PostgreSQL、Redis、Weaviate 或 Qdrant 这类向量库前端是 Next.js 服务整体用 Docker Compose 编排。它适合想快速验证 RAG、Agent、工作流编排的开发者也适合团队内部搭一套私有化的大模型应用底座。但它的部署门槛不在代码而在环境配置和容器网络。这篇内容会按「先理解架构 → 再动手部署 → 最后排错调优」的顺序把 Docker、Git、SSL、知识库流水线这些热搜里反复出现的问题一次讲透。2. Dify 部署前的架构拆解与选型判断2.1 为什么 Dify 默认用 Docker Compose 而不是裸机安装Dify 官方仓库里提供的docker-compose.yaml不是随便写的它把 API 服务、Worker 异步任务、Web 前端、PostgreSQL、Redis、向量数据库、Nginx 反向代理全部编排在一起。裸机安装意味着你要手动装 Python 3.10、Node 18、PostgreSQL 15、Redis 7还要处理 Python 依赖里psycopg2编译、celery启动参数、前端pnpm build内存溢出这些琐碎问题。Docker Compose 的价值在于把「环境一致性」这件事从开发者手里拿走。我一般会先看docker-compose.yaml里的服务依赖关系再决定用哪种部署模式。社区版默认包含api、worker、web、db、redis、weaviate、nginx七个核心服务。如果你只是本地验证用默认配置就够了如果要上生产至少要把db和redis换成外部托管实例把weaviate换成 Qdrant 或 Milvus并且给api和worker配置独立的资源限制。提示Dify 社区版 1.x 之后对多租户做了支持但默认配置仍然是单租户模式。如果你看到「dify社区版1.10多租户」这类搜索词说明你已经在考虑团队共用场景这时候数据库连接池和 Redis 的maxmemory策略必须提前规划。2.2 部署方式对比Docker Desktop、Linux Docker 与 K8s部署方式适用场景优点主要坑点Docker DesktopWindows/macOS本地开发验证安装简单GUI 管理虚拟化支持检测失败、WSL2 内存占用高、端口映射冲突Linux Docker Compose测试环境、小型生产资源占用低网络可控需要手动配置防火墙、SELinux 可能拦截容器挂载K8s 部署中大型生产、多副本弹性伸缩、滚动更新配置复杂度高需要处理 PVC、Ingress、Secret 管理如果你在 Windows 上遇到virtualization support not detected或者 Docker Desktop 启动失败先别急着重装。进 BIOS 确认 Intel VT-x 或 AMD-V 已开启然后在「启用或关闭 Windows 功能」里勾选「虚拟机平台」和「适用于 Linux 的 Windows 子系统」。这两步做完再重启九成以上的启动问题能解决。2.3 Git 在 Dify 部署里的真实作用很多人以为 Git 只是用来克隆代码的但在 Dify 部署和后续升级里Git 的作用远不止git clone。你需要用 Git 管理.env文件的变更、跟踪docker-compose.yaml的版本差异、在升级时用git diff看配置项有没有新增。我习惯把 Dify 的部署目录做成一个独立的 Git 仓库.env文件用.gitignore排除敏感信息但保留一份.env.example作为模板。# 克隆 Dify 仓库并进入目录 git clone https://github.com/langgenius/dify.git cd dify/docker # 查看当前分支和最近提交确认版本 git log --oneline -5 # 复制环境变量模板 cp .env.example .env # 如果你需要切换到特定版本用 git checkout git checkout 1.0.0上面这段命令里git log --oneline -5是为了确认你拉到的代码是不是最新稳定版避免直接上 main 分支踩到未发布的坑。cp .env.example .env之后你必须手动改几个关键项SECRET_KEY要换成随机字符串DB_PASSWORD不能再用默认的difyai123456CONSOLE_API_URL和CONSOLE_WEB_URL要改成你实际访问的地址。这些参数不改后面要么登录不了要么前端接口 404。3. 用 Docker Compose 把 Dify 跑起来从零到可访问3.1 环境准备Docker、Git 与系统参数在 Linux 上部署 Dify我一般会先确认三件事Docker 版本不低于 20.10Docker Compose 版本不低于 2.0系统vm.max_map_count不低于 262144。前两个决定你能不能跑 Compose 文件第三个决定向量库能不能正常启动。很多「dify 安装教程」里不写这一条结果 Weaviate 容器一直重启日志里报max virtual memory areas vm.max_map_count [65530] is too low。# 查看 Docker 和 Compose 版本 docker --version docker compose version # 临时调整 vm.max_map_count sudo sysctl -w vm.max_map_count262144 # 永久生效写入 /etc/sysctl.conf echo vm.max_map_count262144 | sudo tee -a /etc/sysctl.conf # 启动 Docker 服务并设置开机自启 sudo systemctl enable docker sudo systemctl start dockervm.max_map_count这个参数控制进程可以拥有的内存映射区域数量Elasticsearch、Weaviate 这类基于 Lucene 的向量库对它有硬性要求。临时修改只对当前会话有效写入/etc/sysctl.conf才能重启后保留。如果你用的是 CentOS 7还要注意默认的firewalld可能会拦截 Docker 容器之间的通信建议先systemctl stop firewalld做验证生产环境再按需开放端口。3.2 配置 .env 文件六个必须改的参数.env文件是 Dify 部署的核心配置文件里面有两百多个参数但真正影响启动的只有六个。我按重要性排个序SECRET_KEY、DB_PASSWORD、REDIS_PASSWORD、CONSOLE_API_URL、CONSOLE_WEB_URL、APP_WEB_URL。前三个是安全相关后三个是访问地址相关。# 生成随机 SECRET_KEY openssl rand -base64 42 # 编辑 .env 文件 vim .env# 安全相关必须修改 SECRET_KEY你生成的随机字符串 DB_PASSWORD你的强密码 REDIS_PASSWORD你的Redis密码 # 访问地址按实际 IP 或域名填写 CONSOLE_API_URLhttp://192.168.1.100:5001 CONSOLE_WEB_URLhttp://192.168.1.100:3000 APP_WEB_URLhttp://192.168.1.100:3000 # 向量库选择默认 weaviate可改为 qdrant VECTOR_STOREweaviateSECRET_KEY用于加密会话和敏感数据一旦泄露攻击者可以伪造登录态。DB_PASSWORD和REDIS_PASSWORD如果保持默认值在公网环境等于把数据库直接敞开。CONSOLE_API_URL必须和浏览器访问的地址一致否则前端请求会跨域失败。我见过有人填localhost结果局域网其他机器访问时接口全部 404这就是地址没对齐的典型翻车。3.3 启动服务与验证容器状态配置改完之后启动命令本身很简单但验证环节不能省。docker compose up -d之后你要等至少 30 秒让 PostgreSQL 完成初始化、Redis 加载配置、API 服务执行数据库迁移。直接打开浏览器大概率看到 502不是部署失败是服务还没就绪。# 后台启动所有服务 docker compose up -d # 查看容器状态确认没有 Restarting 或 Exit docker compose ps # 查看 api 服务日志确认数据库迁移完成 docker compose logs -f api # 查看 worker 日志确认 celery 正常启动 docker compose logs -f workerdocker compose ps的输出里STATUS列如果是Up或Up (healthy)才算正常。如果看到Restarting直接看对应服务的日志。api日志里出现Running migrations然后Application startup complete说明后端就绪。worker日志里出现celery... ready说明异步任务队列正常。这两个都 OK 之后浏览器访问http://你的IP:3000应该能看到 Dify 的登录页面。3.4 初始化管理员账号与知识库流水线验证第一次访问 Dify 会引导你设置管理员账号邮箱和密码填完之后进入控制台。这时候别急着建应用先去「知识库」里传一个小的 TXT 或 PDF 文件验证文档处理流水线是否正常。这一步能同时检查 API 服务、Worker 异步任务、向量库写入三个环节。# 查看 worker 日志观察文档处理任务 docker compose logs -f worker | grep -i document # 如果文档一直处于「排队中」检查 redis 连接 docker compose exec redis redis-cli -a 你的Redis密码 ping如果文档上传后一直卡在「排队中」九成是 Worker 没连上 Redis或者 Redis 密码配置不一致。docker compose exec redis redis-cli -a 密码 ping返回PONG说明 Redis 本身正常问题在 Worker 的REDIS_PASSWORD环境变量没同步。另外如果你搜到「dify unstructured api url is not configured for doc file processing」这个报错说明你用了 Unstructured API 做文档解析但没配 URL要么补上UNSTRUCTURED_API_URL要么在知识库设置里切换回默认的本地解析模式。4. Dify 部署避坑SSL 错误、网络不通与升级翻车4.1 SSL 错误an error occurred during credentials validation这个报错在 Dify 配置模型供应商时特别常见尤其是接 OpenAI 或国内兼容接口的时候。现象是填完 API Key 点保存弹窗提示an error occurred during credentials validation。原因通常有三个容器内 DNS 解析不了外部域名、SSL 证书链不完整、或者系统时间偏差太大导致 TLS 握手失败。排查步骤# 进入 api 容器测试域名解析 docker compose exec api ping api.openai.com # 测试 HTTPS 连通性 docker compose exec api curl -v https://api.openai.com/v1/models # 检查容器内系统时间 docker compose exec api date如果ping不通说明 Docker 的 DNS 配置有问题可以在docker-compose.yaml里给api和worker服务加dns: 8.8.8.8。如果curl报SSL certificate problem说明容器内缺少 CA 证书需要在 Dockerfile 里加ca-certificates包或者挂载宿主机的证书目录。如果date显示的时间偏差超过几分钟TLS 握手会直接失败同步宿主机时间即可。4.2 Docker 网络不通容器之间互相访问失败Dify 的api服务要连db、redis、weaviate这些连接走的是 Docker Compose 创建的默认网络。如果你在.env里把DB_HOST改成localhost容器内解析不到宿主机的 PostgreSQL就会报连接拒绝。正确做法是保持DB_HOSTdb、REDIS_HOSTredis让 Compose 的服务名做 DNS 解析。# 查看 Docker 网络列表 docker network ls # 查看 dify 默认网络的详细信息 docker network inspect docker_default # 进入 api 容器测试连接 db docker compose exec api nc -zv db 5432 docker compose exec api nc -zv redis 6379nc -zv返回succeeded说明网络层通。如果db连不上检查db容器是否在运行、POSTGRES_PASSWORD是否和.env里的DB_PASSWORD一致。如果redis连不上检查REDIS_PASSWORD是否一致以及redis容器的启动命令有没有带--requirepass。4.3 升级 Dify 时数据库迁移失败Dify 版本更新频率不低升级时最容易翻车的环节是数据库迁移。现象是api容器启动后不断重启日志里报alembic.util.exc.CommandError或者relation xxx does not exist。原因通常是新版本的迁移脚本依赖旧版本没有的表结构或者你跳过了中间版本直接升级。正确升级流程# 进入部署目录 cd dify/docker # 拉取最新代码 git pull origin main # 查看 .env.example 是否有新增配置项 git diff HEAD~1 .env.example # 备份数据库 docker compose exec db pg_dump -U postgres dify backup_$(date %Y%m%d).sql # 停止服务 docker compose down # 拉取新镜像并启动 docker compose pull docker compose up -d升级前备份数据库是后悔药别省这一步。git diff HEAD~1 .env.example用来发现新版本有没有增加必须配置的环境变量如果有手动同步到你的.env里。启动后如果api还是反复重启看日志里具体是哪条迁移失败必要时回滚到上一个版本等社区修复后再升。4.4 Windows 上 Docker Desktop 启动失败Windows 环境下的部署问题集中在 Docker Desktop 本身。virtualization support not detected和docker desktop failed to start because virtualization support is not enabled这两个报错本质都是 BIOS 虚拟化没开或者 Hyper-V 冲突。解决顺序是先进 BIOS 开 VT-x/AMD-V再确认 Windows 功能里「虚拟机平台」和「WSL2」已启用最后检查有没有装过 VirtualBox 或 VMware 导致 Hyper-V 被占用。# 以管理员身份打开 PowerShell检查 WSL 状态 wsl --status # 如果 WSL 版本过低更新内核 wsl --update # 查看 Hyper-V 相关功能是否启用 Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V如果wsl --status报错先wsl --install重装 WSL2 内核。如果 Hyper-V 被其他虚拟化软件占用要么卸载冲突软件要么在 Docker Desktop 设置里切换到 WSL2 后端。Windows 上跑 Dify 的另一个坑是文件挂载性能建议把代码放在 WSL2 的文件系统里不要放在/mnt/c下否则容器读写速度会慢到影响知识库处理。5. 进阶调优让 Dify 在本地跑得更稳的几个技巧5.1 用外部 PostgreSQL 和 Redis 降低容器耦合默认 Compose 把数据库和 Redis 也放在容器里本地验证没问题但数据持久化和性能调优不方便。我一般会在.env里把DB_HOST和REDIS_HOST指向外部实例然后从docker-compose.yaml里删掉db和redis服务。这样升级 Dify 时不用动数据备份也直接用宿主机的pg_dump。# 使用外部数据库 DB_HOST192.168.1.200 DB_PORT5432 DB_USERpostgres DB_PASSWORD你的密码 DB_DATABASEdify # 使用外部 Redis REDIS_HOST192.168.1.200 REDIS_PORT6379 REDIS_PASSWORD你的密码 REDIS_DB0外部 PostgreSQL 建议开pg_stat_statements扩展方便排查慢查询。Redis 建议设置maxmemory-policy allkeys-lru避免知识库缓存把内存吃满。这两个调整做完Dify 在长时间运行下的稳定性会明显提升。5.2 向量库切换从 Weaviate 到 Qdrant 的注意事项Weaviate 默认配置对内存要求较高如果你机器只有 8GB 内存跑一段时间后可能触发 OOM。Qdrant 在同等数据量下内存占用更低适合本地开发。切换方式是在.env里改VECTOR_STOREqdrant然后在docker-compose.yaml里把weaviate服务换成qdrant。# docker-compose.yaml 中 qdrant 服务示例 qdrant: image: qdrant/qdrant:latest restart: always ports: - 6333:6333 volumes: - ./volumes/qdrant:/qdrant/storage environment: - QDRANT__SERVICE__API_KEY你的APIKey切换向量库之后之前 Weaviate 里的知识库数据不会自动迁移需要重新上传文档。如果你已经有大量知识库数据建议先用 Dify 的导出功能备份再切换。Qdrant 的API_KEY要和.env里的QDRANT_API_KEY一致否则 API 服务连不上向量库。5.3 用 Git 管理部署配置的版本最后分享一个我自己的习惯把整个dify/docker目录做成一个 Git 仓库.env加入.gitignore但保留.env.example和docker-compose.yaml的版本记录。每次升级前先git commit当前状态升级出问题直接git checkout回滚配置。这样即使 Dify 官方仓库的 Compose 文件结构变了你也能快速对比差异而不是从头重配。# 初始化部署配置仓库 cd dify/docker git init git add .env.example docker-compose.yaml git commit -m 初始部署配置 # 升级前提交当前状态 git add -A git commit -m 升级前备份 # 出问题回滚 git checkout HEAD~1 -- docker-compose.yaml这套做法不能替代数据库备份但能让你在配置层面有后悔药。我踩过最深的坑是一次升级时没记录.env的改动结果新版本删掉了某个旧参数服务起不来花了两个小时才定位到。从那以后所有部署配置都进 Git改一行也提交。希望这些经验能帮你少走点弯路。本文还有配套的精品资源点击获取