← 返回文章列表

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

  1. 访问 docker.com/products/docker-desktop 下载安装包
  2. 运行安装程序,按提示完成安装
  3. 关键设置:Settings → General → 勾选 Use WSL 2 based engine(不勾后面会各种卡)
  4. 安装完成后重启电脑
# 验证

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

  1. 访问 docker.com/products/docker-desktop 下载
  2. 按芯片选版本:Apple Silicon(M 系列)或 Intel
  3. 安装完成后启动 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 docker

3.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 dify

Windows 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
  1. 确认镜像加速器已配置且生效(docker info | grep -A5 "Registry Mirrors")
  2. 手动试拉一个公共镜像:docker pull nginx
  3. 还不行就换一个加速器地址

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

装完只是开始

能对话了,下一步会撞上的是另外几类问题:知识库里的文档格式乱七八糟、检索明明有答案却答不准、文档更新之后库还是旧的。这些不在部署这一步,在部署之后。

我把这些单独写成了文:

如果卡在部署这一步本身——机器跑不起来、容器反复重启、装了三遍还是同一个错——那就不必再对着文档试了,把环境报给我:Dify 本地部署陪跑。这活我干过多次,多数问题在报环境那一步就能判断出根因。

这篇有用吗

联系我

邮箱contact@fishsun.cn

点击邮箱直接写信 · 扫码加微信沟通

微信

微信二维码

扫码加微信 · 备注「门户」更快通过