Dify 本地部署完整指南:Windows / Linux / macOS 每一步都能复制
摘要:这是一份命令手册,不讲道理,只给命令和预期输出。从检查机器够不够,到第一个应用能对话,三个平台的安装差异、国内镜像加速、13 个容器各占多少内存、七个最常见故障的判断与修法,全部按部署顺序排好。卡在哪一步,翻到那一节抄命令就行。
相关技能:Dify 本地部署陪跑 这份清单能自己走通就不用往下看。走不通的那些——WSL 版本、端口占用、镜像源半夜失效、内存差那一点——不在文档里,在你那台机器上,陪跑做的就是这一步:报环境、出适配方案、装不通我接手。
为什么写成手册而不是教程
装 Dify 这件事,文档看十遍不如把命令抄错一次。
道理都懂:装 Docker、clone 仓库、改 .env、compose up。真到机器上,卡住你的是某一条命令的输出跟你想的不一样——拉镜像卡在 30%、nginx 一直重启、容器全是 Up 但页面打不开、登录之后一直转圈。
这篇文章按部署顺序排,每一步都写清三件事:敲什么、该看到什么、看到别的怎么办。用法很简单:卡住了来查。
实测环境:Dify 1.17.0,Docker Desktop / Docker Engine,2026-09
更新。文中的内存和容器数据都是我在本机跑起来之后用
docker stats
读的,版本升级后会变,不保证在你机器上完全一致。
这份手册不适合所有场景。 它覆盖的是标准安装路径——内网离线环境(要自己做镜像包)、已有 K8s 集群走 Helm、需要接企业 SSO 或多租户、ARM 机器(部分镜像没有 arm64 版本),这几种情况它有局限,官方文档更合适。
一、环境要求
1.1 硬件要求
| 项目 | 最低要求 | 推荐配置 |
|---|---|---|
| CPU | x86_64 双核 | 4 核及以上 |
| 内存 | 8 GB 可用 | 16 GB+ |
| 磁盘 | 20 GB 可用 | 50 GB+ |
| 网络 | 能拉取 Docker 镜像 + 能访问模型 API | 宽带连接 |
表里的推荐值是照实测算的:13 个容器实占 3.9 GB(见 5.4),加上系统与模型调用的余量,8 GB 够启动、16 GB 才不紧张。磁盘同理——镜像与数据卷加起来 20 GB 起步,跑一段时间会涨。
关于内存:Dify 1.17.0 默认启动 13 个容器(PostgreSQL / Redis / Weaviate / Nginx / API / Worker / Web / Sandbox / 插件守护进程 / Agent 后端等),实测合计占用约 3.9 GB。8 GB 是跑起来的下限(还要留给系统和模型调用),16 GB 以上才比较从容;如果同时跑本地模型,建议 32 GB 以上。
1.2 软件要求
| 软件 | 版本要求 | 说明 |
|---|---|---|
| Docker Engine | 24.0+ | 本机实测 29.5.3 |
| Docker Compose | v2.0+ | Docker Desktop 已内置 |
| Git | 可选 | 用于克隆 Dify 仓库;没有 git 也可以下载 zip |
| 浏览器 | Chrome / Edge 最新版 | 访问 Dify Web UI |
1.3 动手前的环境检查
# 操作系统
uname -a # Linux / macOS
winver # Windows(运行对话框执行)
# Docker
docker --version # 需要 >= 24.0
docker compose version # 需要 v2+
# 内存
free -h # Linux / macOS
systeminfo | findstr "物理内存" # Windows
# 磁盘
df -h / # Linux / macOS
wmic logicaldisk get size,freespace,caption # Windows内存这一项别看错:Windows 的 systeminfo
显示的是物理内存总量,要减掉系统已经占掉的。任务管理器里「可用」那个数才是能分给
Docker 的。
二、安装 Docker(按平台)
2.1 Windows
- 访问
docker.com/products/docker-desktop下载安装包 - 运行安装程序,按提示完成安装
- 关键设置:Settings → General → 勾选 Use WSL 2 based engine(不勾后面会各种卡)
- 安装完成后重启电脑
# 验证
docker --version
docker compose version配置镜像加速器(国内必做)
Docker Hub 在国内基本拉不动,不配这一步,后面
docker compose up 会一直卡在拉镜像。
打开 Docker Desktop → Settings → Docker Engine,把下面内容贴进配置框:
{
"registry-mirrors": [
"https://docker.1ms.run",
"https://docker.xuanyuan.me"
]
}点击 Apply & Restart。
加速器地址会失效(本文记录的地址于 2026-07 验证可用)。用之前先
docker pull nginx试一下,拉不动就换一个可用的地址。
2.2 Linux(Ubuntu / Debian)
安装 Docker
# 方式一:官方脚本一行装完(推荐新手)
curl -fsSL https://get.docker.com | sh
# 把自己加进 docker 组,免得每条命令都带 sudo
sudo usermod -aG docker $USER
newgrp docker # 或者退出登录再进来,用户组变更才生效方式二:用 apt 官方源安装(需要指定版本时用)
sudo apt update
sudo apt install -y ca-certificates curl gnupg
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
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin# 验证
docker --version
docker compose version配置镜像加速器(国内必做)
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
"registry-mirrors": [
"https://docker.1ms.run",
"https://docker.xuanyuan.me"
]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker
# 验证是否生效
docker info | grep -A 5 "Registry Mirrors"2.3 macOS
- 访问
docker.com/products/docker-desktop下载 - 按芯片选版本:Apple Silicon(M 系列)或 Intel
- 安装完成后启动 Docker Desktop
# 验证
docker --version
docker compose version镜像加速器配置同 2.1(Docker Desktop → Settings → Docker Engine)。
三、获取源码并部署 Dify
3.1 获取源码
# GitHub 官方仓库
git clone https://github.com/langgenius/dify.git
cd dify
# GitHub 打不开时用国内镜像
git clone https://gitee.com/langgenius/dify.git没有 git 也可以直接在网页上下载 zip 包解压,效果一样。
3.2 进入 Docker 目录
cd docker3.3 生成并修改配置文件
cp .env.example .env必须修改的关键配置(用文本编辑器打开
.env):
| 变量 | 说明 | 建议 |
|---|---|---|
SECRET_KEY |
登录凭证的加密密钥 | 必须填,见下方生成命令 |
EXPOSE_NGINX_PORT |
Dify 对外端口 | 默认 80;同机有其他站点时改成 8081 |
CONSOLE_API_URL / APP_API_URL |
界面调用后端的地址 | 留空,填完整域名会导致登录页无限跳转 |
NEXT_PUBLIC_SOCKET_URL |
实时通信地址 | 用 HTTPS
时必须有值(wss://你的域名),否则界面卡"同步数据中" |
生成 SECRET_KEY:
# Linux / macOS
openssl rand -base64 42
# Windows PowerShell
[Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))这四个变量是最容易出事的地方。SECRET_KEY
留空的后果特别隐蔽——Dify 每次启动自己生成一个新密钥,你的登录状态和 API
Key 全部作废,看起来像"重启就要重新登录"的怪毛病。
3.4 启动
docker compose up -d首次启动需要拉取镜像,根据网络状况耗时 5-40 分钟。本机实测走公共加速器约 40 分钟,云厂商内网加速器几分钟就下完。
启动后运行的容器(1.17.0,共 13 个):
| 服务 | 镜像 | 端口 | 说明 |
|---|---|---|---|
nginx |
nginx | 80 | Web 入口,http://localhost 访问 |
api |
langgenius/dify-api | 5001 | 后端 API |
worker |
langgenius/dify-api | — | 异步任务(知识库索引、模型调用) |
web |
langgenius/dify-web | 3000 | 前端 SPA |
db |
postgres | 5432 | 业务数据库 |
redis |
redis | 6379 | 缓存 / 消息队列 |
weaviate |
semitechnologies/weaviate | 8080 | 向量数据库(知识库用) |
sandbox |
langgenius/dify-sandbox | — | 代码沙箱 |
plugin_daemon |
langgenius/dify-plugin-daemon | 5002 | 插件守护进程(1.17 新增) |
agent_backend |
langgenius/dify-agent-backend | — | Agent 后端(1.17 新增) |
3.5 查看启动日志
docker compose logs -f # 所有服务
docker compose logs -f api # 只看后端
docker compose logs --tail 50 web # 只看前端最近 50 行看到类似输出表示启动完成:
api | INFO: Application startup complete.
nginx | [notice] 1#1: start worker processes
3.6 停止与更新
docker compose down # 停止容器,保留数据
docker compose down -v # 停止并删除数据卷(会清空数据库,慎用)
# 更新
git pull origin main
docker compose pull
docker compose up -d更新后如果访问出现 502,执行一次
docker exec docker-nginx-1 nginx -s reload——容器重建后 IP 会变,而 Dify 内部 nginx 缓存了旧 IP。
四、部署验证
4.1 检查容器状态
docker compose ps所有服务状态应为 Up。显示 Restarting 或
Exited 说明有问题,先看日志:
docker compose logs --tail 50 <容器名>最常见的两个原因:80 端口被占用(改
.env 里的
EXPOSE_NGINX_PORT)、内存不足(容器被系统杀掉重启)。
4.2 访问 Web UI
浏览器打开
http://localhost(云服务器上换成公网地址),应看到
Dify 登录页。第一次访问会让你创建管理员账号。
4.3 接口健康检查
# 前端(经 nginx)
curl -s -o /dev/null -w "%{http_code}\n" http://localhost/
# 初始化状态(Dify 没有 /health 端点,用这个代替)
curl -s http://localhost/console/api/setup
# 正常返回:{"step":"finished", ...}4.4 配置模型供应商
Dify 本身不带模型,你得给它一个——这是必须由你自己准备的东西。
入口:左侧菜单「集成」→「模型供应商」(旧版本在右上角头像 →「设置」里)。页面底部是供应商列表,已安装的直接显示,没装的要点「安装」。
以 DeepSeek 为例:
| 步骤 | 操作 |
|---|---|
| 1 | 登录 DeepSeek 开放平台(platform.deepseek.com)→ API
Keys → 创建密钥 |
| 2 | Dify 里:左侧菜单「集成」→「模型供应商」→ 找到「深度求索」→ 点「安装」 |
| 3 | 弹出框里粘贴 API Key,保存 |
| 4 | 按钮变成「配置」后点进去,能看到可用模型列表即成功(以后换密钥也走这里) |
常用模型:deepseek-chat(通用对话,性价比高)、deepseek-reasoner(深度推理)。
以通义千问为例:
入口同上。先去百炼控制台(bailian.console.aliyun.com)→
API-KEY 管理 → 创建密钥;其余步骤同上,供应商搜索
"Qwen"。常用模型:qwen-plus(均衡)、qwen-max(能力上限最高的一档,也最贵)、qwen-turbo(快而省)。
4.5 创建第一个应用
登录后:工作室 → 创建应用 → 选一个类型(入门建议"对话助手")→ 选择刚配置的模型 → 发一条"你好"验证能正常回复。
五、常用维护命令
5.1 容器生命周期
docker compose ps # 查看所有容器状态
docker compose logs -f -n 100 # 查看最近 100 行日志
docker compose restart api # 重启后端
docker compose up -d # 启动 / 重建
docker compose down # 停止(保留数据)
docker exec docker-nginx-1 nginx -s reload # 重建容器后重载 nginx(防 502)5.2 数据库备份与恢复
# 备份
docker compose exec db pg_dump -U postgres dify > dify_backup_$(date +%Y%m%d).sql
# 恢复
cat dify_backup_20260703.sql | docker compose exec -T db psql -U postgres difyWindows PowerShell 下把 $(date +%Y%m%d) 换成
$(Get-Date -Format yyyyMMdd),cat 换成
Get-Content。
这件事建议在配好第一个应用之后就做一次,别等有了真数据才想起来。备份文件放在容器外面——docker compose down -v
会连数据卷一起删。
5.3 资源监控
docker stats # 各容器实时资源占用
docker system df # Docker 磁盘占用总览
docker system prune -f # 清理无用镜像/容器/卷5.4 资源占用参考(1.17.0 实测)
| 容器 | 内存占用 |
|---|---|
| plugin_daemon | 905 MB |
| api | 729 MB |
| worker | 551 MB |
| 其余 10 个合计 | 约 1.7 GB |
| 总计 | 约 3.9 GB |
插件守护进程是最吃内存的那一个,比 API 还高。如果机器只有 8 GB,装完先跑起来看看真实占用,别急着开知识库。
六、常见问题排查
6.1 镜像拉取失败
Error response from daemon: pull access denied
或 manifest for langgenius/dify-api not found
- 确认镜像加速器已配置且生效(
docker info | grep -A5 "Registry Mirrors") - 手动试拉一个公共镜像:
docker pull nginx - 还不行就换一个加速器地址
6.2 80 端口被占用
症状:docker compose up -d 后 nginx
一直重启。
# Windows
netstat -ano | findstr :80
# Linux / macOS
sudo lsof -i :80解决:改 .env 里的
EXPOSE_NGINX_PORT=8081,然后
docker compose up -d nginx。
6.3 内存不足
症状:容器频繁重启,或界面响应很慢。
解决:调低 .env 里的
WORKER_CONCURRENCY;不用知识库可以停掉 weaviate
容器;或者直接加内存——Dify 这套按 8 GB 起算。
6.4 登录后一直在转圈 / 提示重定向过多
查 .env 里
CONSOLE_API_URL、APP_API_URL
是否留空。填了完整域名就会这样。改完执行
docker compose up -d web(restart 不生效)。
6.5 界面卡在"同步数据中"
查 .env 里 NEXT_PUBLIC_SOCKET_URL。用 HTTPS
访问时必须显式设成 wss://你的域名,留空会退化成
ws://localhost,被浏览器拦掉。改完
docker compose up -d web。
6.6 重启后要重新登录、API Key 失效
.env 里的 SECRET_KEY 为空。留空时 Dify
每次启动自己生成一个新密钥,导致旧令牌全部作废。填上并重启。
6.7 重建容器后访问 502
docker exec docker-nginx-1 nginx -s reload原因:Dify 内部 nginx 的反代写的是服务名,启动时解析一次并缓存 IP;容器重建后 IP 变了,nginx 还连旧地址。
七、参考资源
| 资源 | 地址 |
|---|---|
| Dify 官方文档(自托管部署) | docs.dify.ai/getting-started/install-self-hosted |
| Dify GitHub 仓库 | github.com/langgenius/dify |
| Dify Gitee 镜像(国内) | gitee.com/langgenius/dify |
| Docker Desktop 下载 | docker.com/products/docker-desktop |
| Docker 文档 | docs.docker.com |
装完只是开始
能对话了,下一步会撞上的是另外几类问题:知识库里的文档格式乱七八糟、检索明明有答案却答不准、文档更新之后库还是旧的。这些不在部署这一步,在部署之后。
我把这些单独写成了文:
- 部署失败的六个症状怎么用数字判断:/blog/Dify本地部署失败的六个症状-每一个都能用一个数判断.html
- 知识库答不准,先查语料不是先换模型:/blog/知识库答不准先别换模型-五个能测出来的语料问题.html
- 有答案却答不准,十种失败模式判型:/blog/知识库有答案却答不准-十种失败模式先判型再调参.html
如果卡在部署这一步本身——机器跑不起来、容器反复重启、装了三遍还是同一个错——那就不必再对着文档试了,把环境报给我:Dify 本地部署陪跑。这活我干过多次,多数问题在报环境那一步就能判断出根因。
这篇有用吗