Dify 本地化部署指南（全平台）

Dify 本地化部署指南（全平台）

目录

一、环境要求
二、依赖安装（按平台）
三、部署 Dify
四、部署验证
五、常用维护命令
六、常见问题排查
七、参考资源

一、环境要求

1.1 硬件要求

💡内存说明：Dify 默认启动 8 个容器（PostgreSQL / Redis / Weaviate / Nginx / API / Worker / Web / Sandbox），合计占用约 2-3GB 内存。8GB 是跑起来的下限，16GB 以上才比较从容。如果同时运行本地模型，建议 32GB+。

未搜索到 Dify 官方发布的最低硬件要求文档。以上数据基于实际部署经验。

1.2 软件要求

1.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

1. 访问 docker.com/products/docker-desktop 下载
2. 运行安装程序，按提示完成安装
3. 关键设置：Settings → General → 勾选“Use WSL 2 based engine”
4. 安装完成后重启电脑

# 验证安装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 Linux（Ubuntu / 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.gpgsudochmoda+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"|\sudotee/etc/apt/sources.list.d/docker.list>/dev/null# 安装 Dockersudoaptupdatesudoaptinstall-ydocker-ce docker-ce-cli containerd.io docker-compose-plugin# 将当前用户加入 docker 组（避免每次 sudo）sudousermod-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-A5"Registry Mirrors"

安装 Git

sudoaptinstall-ygit

2.3 macOS

安装 Docker Desktop

1. 访问 docker.com/products/docker-desktop 下载
2. 选择对应芯片的版本：Apple Silicon（M 芯片）或Intel
3. 安装完成后启动 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”。

三、部署 Dify

3.1 获取源码

# 方案一：GitHub 官方仓库gitclone https://github.com/langgenius/dify.gitcddify# 方案二：国内加速（GitHub 被墙时使用）gitclone https://gitee.com/langgenius/dify.gitcddify

3.2 进入 Docker 目录

cddocker

3.3 配置环境变量

# 复制环境变量模板cp.env.example .env

必须修改的关键配置（用文本编辑器打开.env）：

生成 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 会运行以下容器：

3.5 查看启动日志

# 所有服务日志dockercompose logs-f# 只看后端dockercompose logs-fapi# 只看前端dockercompose logs-fweb

看到类似输出表示启动完成：

api | INFO: Application startup complete. nginx | [notice] 1#1: start worker processes

3.6 停止 Dify

dockercompose 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

1. 打开浏览器
2. 访问http://localhost（默认 80 端口）
3. 应看到 Dify 登录页面
4. 使用.env中配置的管理员账户和INIT_PASSWORD登录

4.3 验证 API 健康检查

# Nginx 前端代理curl-shttp://localhost/health# 后端 API 直接访问curl-shttp://localhost:5001/health

正常响应示例：

{"status":"ok"}

4.4 创建首个应用

登录后建议：

1. 进入“工作室” → “创建应用”
2. 选择一个模板（如"对话型应用"）
3. 在“模型供应商”中配置你的 API Key（如 DeepSeek 或通义千问）
4. 发送一条测试消息验证正常工作

💡 首次登录后第一件事通常是配置模型供应商，否则应用无法调模型。

4.5 配置模型供应商（DeepSeek / 通义千问）

登录 Dify 后，点击左下角“设置”→“模型供应商”，按以下步骤接入大模型 API。

4.5.1 配置 DeepSeek

DeepSeek 常用模型：

DeepSeek API 端点（自动填充，无需手动配置）：

https://api.deepseek.com/v1

4.5.2 配置通义千问 / Qwen

通义千问常用模型：

通义千问 API 端点（Dify 自动配置，无需手动修改）：

https://dashscope.aliyuncs.com/compatible-mode/v1

4.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 dify>dify_backup_$(date+%Y%m%d).sql# Windows PowerShelldockercomposeexecdb pg_dump-Upostgres dify>dify_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 dify

5.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: "3"

5.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

解决方法：

1. 确认已配置镜像源（见 2.1-2.3 节）
2. 检查网络是否能正常访问镜像源
3. 尝试手动拉取测试：docker pull docker.1ms.run/library/nginx:latest

6.2 端口 80 被占用

症状：docker compose up -d后 nginx 一直重启
检查：

# Windowsnetstat-ano|findstr :80# Linux / macOSsudolsof-i:80

解决：修改docker-compose.yaml中 nginx 的端口映射，如"8080:80"。

6.3 内存不足

症状：容器频繁重启，或 Dify 运行缓慢
解决：

1. 调低.env中的WORKER_CONCURRENCY（工作器并发数）
2. 关闭不需要的服务（如 weaviate，如果不用知识库）
3. 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

七、参考资源

Version 0.0.0
2026-07-03