Dify 本地化部署指南全平台目录一、环境要求二、依赖安装按平台三、部署 Dify四、部署验证五、常用维护命令六、常见问题排查七、参考资源一、环境要求1.1 硬件要求项目最低要求推荐配置CPUx86_64 双核4 核及以上内存8GB 可用16GB磁盘10GB 可用50GB网络可拉取 Docker 镜像 访问模型 API宽带连接内存说明Dify 默认启动 8 个容器PostgreSQL / Redis / Weaviate / Nginx / API / Worker / Web / Sandbox合计占用约 2-3GB 内存。8GB 是跑起来的下限16GB 以上才比较从容。如果同时运行本地模型建议 32GB。未搜索到 Dify 官方发布的最低硬件要求文档。以上数据基于实际部署经验。1.2 软件要求软件版本要求说明Docker Engine24.0本机使用29.5.3Docker Composev2.0本机使用v5.1.4Docker Desktop 已内置Git可选用于克隆 Dify 仓库浏览器Chrome / Edge 最新版访问 Dify Web UI1.3 环境检查# 操作系统uname-a# Linux / macOSwinver# Windows运行对话框运行# Dockerdocker--version# 需要 24.0dockercompose version# 需要 v2# 内存free-h# Linux / macOSsysteminfo|findstr物理内存# Windows# 磁盘df-h/# Linux / macOSwmic logicaldisk get size,freespace,caption# Windows二、依赖安装按平台2.1 Windows安装 Docker Desktop访问 docker.com/products/docker-desktop 下载运行安装程序按提示完成安装关键设置Settings → General → 勾选“Use WSL 2 based engine”安装完成后重启电脑# 验证安装docker--version docker compose version安装 Git可选winget install Git.Git配置 Docker 镜像源国内环境必配打开 Docker Desktop → Settings → Docker Engine修改daemon.json{registry-mirrors:[https://docker.1ms.run,https://docker.xuanyuan.me]}点击“Apply Restart”。⚠️ Docker Hub 官方 registry 在中国大陆已被屏蔽不配置镜像源将无法拉取镜像。以上镜像源于 2026 年 7 月验证可用。2.2 LinuxUbuntu / Debian安装 Docker# 卸载旧版本sudoaptremovedockerdocker-engine docker.io containerd runc# 安装依赖sudoaptupdatesudoaptinstall-yca-certificatescurlgnupg# 添加 Docker 官方 GPG 密钥sudoinstall-m0755-d/etc/apt/keyringscurl-fsSLhttps://download.docker.com/linux/ubuntu/gpg|sudogpg--dearmor-o/etc/apt/keyrings/docker.gpgsudochmodar /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-releaseecho$VERSION_CODENAME)stable|\sudotee/etc/apt/sources.list.d/docker.list/dev/null# 安装 Dockersudoaptupdatesudoaptinstall-ydocker-ce docker-ce-cli containerd.io docker-compose-plugin# 将当前用户加入 docker 组避免每次 sudosudousermod-aGdocker$USER# 退出并重新登录或执行newgrpdocker# 验证docker--versiondockercompose version配置 Docker 镜像源国内环境sudomkdir-p/etc/dockersudotee/etc/docker/daemon.json-EOF { registry-mirrors: [ https://docker.1ms.run, https://docker.xuanyuan.me ] } EOFsudosystemctl daemon-reloadsudosystemctl restartdocker# 验证镜像源是否生效dockerinfo|grep-A5Registry Mirrors安装 Gitsudoaptinstall-ygit2.3 macOS安装 Docker Desktop访问 docker.com/products/docker-desktop 下载选择对应芯片的版本Apple SiliconM 芯片或Intel安装完成后启动 Docker Desktop# 验证安装docker--versiondockercompose version安装 Git# 使用 Homebrewbrewinstallgit配置 Docker 镜像源国内环境Docker Desktop → Settings → Docker Engine修改daemon.json{registry-mirrors:[https://docker.1ms.run,https://docker.xuanyuan.me]}点击“Apply Restart”。三、部署 Dify3.1 获取源码# 方案一GitHub 官方仓库gitclone https://github.com/langgenius/dify.gitcddify# 方案二国内加速GitHub 被墙时使用gitclone https://gitee.com/langgenius/dify.gitcddify3.2 进入 Docker 目录cddocker3.3 配置环境变量# 复制环境变量模板cp.env.example .env必须修改的关键配置用文本编辑器打开.env变量说明建议值SECRET_KEY应用密钥需随机生成见下方生成命令INIT_PASSWORD管理员初始密码修改为强密码生成 SECRET_KEY# Linux / macOSopenssl rand-base6442# Windows PowerShell[Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))⚠️ 生产环境必须设置SECRET_KEY否则重启后所有会话和 Token 将失效。3.4 启动 Dify# 启动所有服务dockercompose up-d首次启动需要拉取镜像根据网络状况耗时5-30 分钟。启动成功后Dify 会运行以下容器服务镜像端口说明nginxnginx:latest80Web 反向代理通过http://localhost访问apilanggenius/dify-api5001后端 API 服务workerlanggenius/dify-api—异步任务处理知识库索引、模型调用等weblanggenius/dify-web3000前端 SPA 应用Nginx 反代dbpostgres:15-alpine5432PostgreSQL 数据库redisredis:7-alpine6379缓存 / 消息队列weaviatesemitechnologies/weaviate8080向量数据库知识库 RAGsandboxlanggenius/dify-sandbox—代码沙箱安全执行用户代码3.5 查看启动日志# 所有服务日志dockercompose logs-f# 只看后端dockercompose logs-fapi# 只看前端dockercompose logs-fweb看到类似输出表示启动完成api | INFO: Application startup complete. nginx | [notice] 1#1: start worker processes3.6 停止 Difydockercompose down# 停止容器保留数据dockercompose down-v# ⚠️ 停止并删除数据卷清空数据库3.7 更新 Dify# 1. 拉取最新源码gitpull origin main# 2. 拉取最新 Docker 镜像dockercompose pull# 3. 重新启动dockercompose up-d四、部署验证4.1 检查容器状态dockercomposeps所有服务的Status应为“Up”正常或“running”。如果某服务显示 “restarting” 或 “exited”说明有问题。4.2 访问 Web UI打开浏览器访问http://localhost默认 80 端口应看到 Dify 登录页面使用.env中配置的管理员账户和INIT_PASSWORD登录4.3 验证 API 健康检查# Nginx 前端代理curl-shttp://localhost/health# 后端 API 直接访问curl-shttp://localhost:5001/health正常响应示例{status:ok}4.4 创建首个应用登录后建议进入“工作室” → “创建应用”选择一个模板如对话型应用在“模型供应商”中配置你的 API Key如 DeepSeek 或通义千问发送一条测试消息验证正常工作 首次登录后第一件事通常是配置模型供应商否则应用无法调模型。4.5 配置模型供应商DeepSeek / 通义千问登录 Dify 后点击左下角“设置”→“模型供应商”按以下步骤接入大模型 API。4.5.1 配置 DeepSeek步骤操作① 获取 API Key登录 DeepSeek 开放平台 → “API Keys” → 创建新密钥② 在 Dify 中添加设置 → 模型供应商 → 搜索 “DeepSeek” → 点击 “添加”③ 输入 API Key将复制的密钥粘贴到 API Key 输入框④ 验证连接点击“保存并验证”成功后可看到可用模型列表⑤ 设置默认模型在应用中选择已添加的 DeepSeek 模型即可使用DeepSeek 常用模型模型 ID说明特点deepseek-chatDeepSeek V3 对话模型通用对话性价比高deepseek-reasonerDeepSeek R1 推理模型支持深度推理适合复杂任务deepseek-coderDeepSeek 代码模型编程专用代码生成质量高DeepSeek API 端点自动填充无需手动配置https://api.deepseek.com/v14.5.2 配置通义千问 / Qwen步骤操作① 获取 API Key登录 百炼控制台 → “API-KEY 管理” → 创建密钥② 在 Dify 中添加设置 → 模型供应商 → 搜索 “Qwen” 或 “通义千问” → 点击 “添加”③ 输入 API Key粘贴获取到的 API Key④ 验证连接点击“保存并验证”⑤ 设置默认模型选择 Qwen 模型即可使用通义千问常用模型模型 ID说明特点qwen-plus通义千问 Plus均衡型适合通用场景qwen-max通义千问 Max最强性能适合复杂任务qwen-turbo通义千问 Turbo速度快、成本低适合简单任务qwen-vl-plus通义千问 VL Plus支持图像理解qwen-coder-plus通义千问 Coder Plus编程专用通义千问 API 端点Dify 自动配置无需手动修改https://dashscope.aliyuncs.com/compatible-mode/v14.5.3 注意事项API Key 安全API Key 存储在 Dify 数据库中请勿泄露。生产环境建议定期轮换密钥。模型额度部分模型特别是通义千问 Max有调用频率限制注意查看控制台用量。国内网络DeepSeek 和百炼的 API 均可直接访问无需代理。首次使用添加模型供应商后回到工作室创建应用时即可在模型选择下拉中看到已添加的模型。验证方法创建一个新的对话应用 → 选择刚添加的模型 → 输入 “你好你是谁” → 如收到正常回复即配置成功。五、常用维护命令5.1 容器生命周期dockercomposeps# 查看所有容器状态dockercompose logs-f-n100# 查看最近的 100 行日志dockercompose restart api# 重启后端服务dockercompose restart web# 重启前端dockercompose up-d# 启动/重建dockercompose down# 停止保留数据5.2 数据库备份与恢复备份# Linux / macOSdockercomposeexecdb pg_dump-Upostgres difydify_backup_$(date%Y%m%d).sql# Windows PowerShelldockercomposeexecdb pg_dump-Upostgres difydify_backup_$(Get-Date-FormatyyyyMMdd).sql恢复# Linux / macOScatdify_backup_20260703.sql|dockercomposeexec-Tdb psql-Upostgres dify# Windows PowerShellGet-Content dify_backup_20260703.sql|dockercomposeexec-Tdb psql-Upostgres dify5.3 资源监控# 容器级资源占用dockerstats# Docker 磁盘占用dockersystemdf# 清理无用的镜像、容器、卷dockersystem prune-f# 连构建缓存一起清理dockersystem prune-a-f--volumes# ⚠️ 会清除构建缓存和未使用卷5.4 日志管理# 查看各服务日志位置dockerinspect--format{{.Name}} {{.LogPath}}$(dockerps-q)# 日志默认大小Docker 默认无限制日志文件可能很大# 建议在 docker-compose.yaml 中限制日志大小## logging:# driver: json-file# options:# max-size: 10m# max-file: 35.5 修改端口映射如果 80 端口被其他服务占用需修改端口映射# 编辑 docker/docker-compose.yaml找到 nginx 服务的 ports 部分services:nginx:ports:-8080:80# 将 80 改为其他端口如 8080改完后重启dockercompose up-d六、常见问题排查6.1 镜像拉取失败Error response from daemon: pull access denied for langgenius/dify-api 或 manifest for langgenius/dify-api:latest not found解决方法确认已配置镜像源见 2.1-2.3 节检查网络是否能正常访问镜像源尝试手动拉取测试docker pull docker.1ms.run/library/nginx:latest6.2 端口 80 被占用症状docker compose up -d后 nginx 一直重启检查# Windowsnetstat-ano|findstr :80# Linux / macOSsudolsof-i:80解决修改docker-compose.yaml中 nginx 的端口映射如8080:80。6.3 内存不足症状容器频繁重启或 Dify 运行缓慢解决调低.env中的WORKER_CONCURRENCY工作器并发数关闭不需要的服务如 weaviate如果不用知识库docker compose down停掉不必要的容器6.4 WSL2 Docker Desktop 引擎崩溃症状Docker Desktop 启动后报 WSL 相关错误解决# Windows PowerShell管理员wsl--shutdown然后重启 Docker Desktop再启动 Dify。6.5 SECRET_KEY 未设置症状Dify 重启后需要重新登录之前创建的 API Key 失效解决在.env中设置SECRET_KEY见 3.3 节然后dockercompose downdockercompose up-d七、参考资源资源地址Dify 官方文档自托管部署https://docs.dify.ai/getting-started/install-self-hostedDify GitHub 仓库https://github.com/langgenius/difyDify Gitee 镜像国内https://gitee.com/langgenius/difyDocker Desktop 下载https://www.docker.com/products/docker-desktop/Docker 文档https://docs.docker.comVersion 0.0.02026-07-03