← 返回文章列表

Dify 本地部署失败的六个症状:每一个都能用一个数判断

摘要:Dify 装不上,重装解决不了——每次重装只是把同一个错再演一遍。这篇把「装不上」拆成六个症状,每个给一条能直接跑的命令和一个数值判据:内存要看 Docker 虚拟机而不是电脑、镜像源看着正常其实已经死了、报错文案会把人带偏。全部基于 Windows 11 + Docker Desktop 29.5.3 + Dify 1.18.0 实测。

相关技能:Dify 本地部署陪跑 下面这六个判断已经做成一个命令,装进 AI 助手就能自己跑一遍,四个平台通用

三个晚上,三次重装

装 Dify 那两天,我把 Docker 卸了装、装了卸,前后三回。

第一回是容器反复重启。第二回是拉镜像卡在 30% 不动。第三回我把系统里跟 Docker 有关的东西全删干净,重装,重新 clone,重新 compose up——然后得到一个跟第一次一模一样的错误。

每回重装四十分钟,不算拉镜像的时间。整整三个晚上,全花在同一件事上。

第三回结束我才反应过来:我一直在做同一件事,而且做得越来越干净,但错误一次都没变。这说明问题根本不在我装得干不干净。

这就是我想说的第一句话:装不上别急着重装。重装是把同一个错再演一遍,它不会告诉你错在哪。

第一步就查错了:内存不是电脑的内存

我最早排查的是内存。

电脑 16G,df -h 看磁盘还有两百多 G,CPU 二十核。按经验,这个配置跑 Dify 绰绰有余,所以我根本没往资源上想。

后来有人让我跑一条命令:

docker info --format "{{.MemTotal}}"

返回 2147483648。

除以 1073741824,得 2。

Docker 能用的内存只有 2 GB。

我当时的第一反应是「这数不对吧」,因为我电脑明明是 16G。查下去才明白:Windows 上 Docker Desktop 不是直接跑在宿主上,它跑在一个虚拟机里,那个虚拟机默认只分到 2G。容器被杀、服务起不来,看的是虚拟机里那个数。

docker info 这条命令我看过很多次,但从来没注意过 MemTotal 这一行——它跟 free -h 显示的宿主内存是两个数,而且差了一个数量级。

这是我这次踩得最深的一个坑:判断的内存和实际的内存不是一个内存。前两次重装,全都是在这个误判上白费的。

三件反直觉的事

把内存调上去之后,我又撞了三次墙。这三次的共同点是:报错信息都在指向错误的方向。

一、Docker Desktop 填 8G,实际只有 7.62 GiB

内存调到 8 GB,重启之后我再去查,得到 8181682176。

除以 1073741824,7.62 GiB。

不是 8。差的那部分是虚拟机的固定开销,填多少都会少一块。

所以判据不能写「8G 够不够」——写 8,会把一个已经配好的机器判成不足,然后你继续往上加,加到 16 还是差一点,永远差一点。

**判据要取 7.5。**低于 4 必挂,7.5 以上才算稳。这个数有来历:把「填 8 得到 7.62」这件事算进去之后,门槛就落在 7.5。

二、镜像源看着完全正常,走完流程才告诉你 403

Dify 的 docker-compose.yaml 要拉十几个镜像,其中一部分在国内直接拉会超时。配镜像加速源是标准动作,我照着网上流传的清单配了四个。

四个里有一个是华为云的 repo.huaweicloud.com。

它 /v2/ 返回的是标准 registry 的 401 加 Bearer 挑战头——看起来完全像一个正常的、需要认证的镜像仓库。你按正常流程去换 token,换到了,再拿 token 去请求 manifest,返回 403。

它拒绝匿名拉取,但拒绝的方式让你以为自己在正常流程里。

配进去不会让拉取变快,只会让下一次排错多绕一圈——因为你会怀疑是 token 过期、是网络、是自己配错了顺序,而真相是这条源根本不对外。

2026 年 11 月我按 OCI 流程重新测了一遍,四个可用、四个失效:

可用 docker.xuanyuan.me    免认证直取

   docker.1panel.live    免认证直取

   docker.m.daocloud.io   Bearer token

   docker.1ms.run      Bearer token



失效 repo.huaweicloud.com  403,拒绝匿名拉取

   docker.mirrors.ustc.edu.cn 域名已不解析

   hub-mirror.c.163.com    域名已不解析

   mirror.baidubce.com    域名已不解析

后三条在很多「2024 镜像源清单」里还挂着,域名早就不解析了。配了等于没配,而且它们不会报错——Docker 只是默默地用不了,然后你以为自己配了。

配一两个就够。配太多,拉取时轮询反而慢。

三、报错说「no HTTPS proxy」,其实跟代理一点关系没有

拉镜像失败的时候,Docker Desktop 会吐一句:

Docker Desktop has no HTTPS proxy

看到 proxy,人的第一反应是去查代理设置——我看过系统代理、看过 Docker 的代理配置、重启过 Docker Desktop。

全都没有用,因为我根本没开代理。

这句话的意思是「我没有配 HTTPS 代理」,它正是在告诉你:别去找代理了,问题不在这。真正的原因藏在 pull.log 里:

docker compose pull 2>&1 | tee pull.log

grep -oE "https?://[a-z0-9.-]+" pull.log | sort -u

跑完你会发现失败的那些镜像根本不在 docker.io 上——它们来自 ghcr.io、cr.weaviate.io 这类 registry。**镜像加速源只管 docker.io,管不了别的 registry。**配得再对也没用。

处理办法是从 Docker Hub 拉同名镜像重新打 tag,或者换掉那个组件。

六个症状,每个都能用一个数判断

下面六个是我在自己机器上真实撞到的。每一条都写了「先确认」——先跑命令验证判断,判断成立再动手。判断没验证就动手,容易修错地方。

症状一:容器反复重启,状态 Restarting,exit code 137

docker inspect --format '{{.State.ExitCode}} {{.State.OOMKilled}}' <容器名>

docker info --format "{{.MemTotal}}"

137 且 OOMKilled 是 true,就是内存不足被杀。第二个数是判据:除以 1073741824,低于 4 必挂。

Docker Desktop → Settings → Resources → Memory 调到 8 GB 以上,Apply & restart。Linux 上改宿主 swap 或者加内存。调完再查一次,应到 7.5 GiB 以上。

一个例外:137 也可能是 docker stop 超时之后被 SIGKILL 掉的,那种情况 OOMKilled 是 false。所以两个值要一起看,只看到 137 就断定内存不足,会误判。

症状二:拉镜像卡住、超时

docker info --format '{{json .RegistryConfig.Mirrors}}'

docker compose pull 2>&1 | tee pull.log && grep -i "error\|timeout" pull.log

第一条看镜像源配没配、配了哪几个。第二条拿到真正失败的那个 registry。

判断分叉很简单:失败的镜像在 docker.io 上 → 换镜像源。在 ghcr.io 或别的 registry 上 → 镜像源救不了,走拉取加打 tag,或者换组件。

如果是 Docker Desktop 本身下载不动,还有一个坑:curl 默认优先走 IPv6,国内到 CloudFront 的 IPv6 经常直接卡死。加 -4 强制 IPv4。

实测:不加 -4 是 HTTP 000,超时,0 字节;加了立刻 200,速度 1.1 MB/s,500 MB 大概七八分钟。

症状三:bind: address already in use

# Windows

netstat -ano | findstr ":80 "

# Linux / macOS

lsof -i :80

80 或 443 被别的服务占了:IIS、宝塔、另一个 nginx、旧版 Dify 留下的容器。

关掉占用者最干净。关不掉就改端口——docker/.env 里 EXPOSE_NGINX_PORT=8080,docker compose up -d,访问改成 http://localhost:8080。

这条有时候不报错,而是表现为「页面能打开,但不是 Dify」。那也是同一个原因:80 端口上是别人。

症状四:init_permissions 显示 Exited (0)

不是故障。

这个容器只跑一次,作用是改文件权限,跑完自己退出,退出码 0 是设计行为。

判断标准:api、worker、web、nginx、db_postgres、redis、sandbox、plugin_daemon 这几个是 Up 或 healthy,就正常。

我第一回重装就是被这个骗的——看到 Exited 以为容器挂了,其实一切正常。

症状五:http://localhost/ 返回 307

不是故障。

未登录状态的重定向。

正确的验证地址是 http://localhost/install,应该返回 200,标题是设置管理员账号。

这条也是纯误判来源。307 不是错误码,它在说「你还没初始化,先去 /install」。

症状六:WSL 里 docker 用不了

wsl -l -v

注意这个命令的输出是 UTF-16LE,在 Git Bash 里直接看是一堆空格和 \x00。转一下:

wsl -l -v | iconv -f utf-16le -t utf-8

然后在目标发行版里试跑:

wsl -d Ubuntu-24.04 docker --version

根因按概率排三条:

① WSL Integration 开关没开(最常见)。Settings → Resources → WSL Integration → 选中发行版 → Apply & restart。开关是灰色点不动的,说明 Docker Desktop 版本太旧,升级再看。

② 发行版是 WSL1。wsl -l -v 的 VERSION 列显示 1。Docker 集成只支持 WSL2,wsl --set-version <发行版> 2。

③ 发行版没启动。状态 Stopped 时跑 docker 一定失败,这不是故障。wsl -d <发行版> 进去一次再退出,让它变成 Running。

一个容易误判的地方:docker-desktop 这个发行版是 Docker Desktop 自己建的,它没有「集成开关」这回事。检测时要跳过,否则会误报。

判断顺序比解法重要

六个症状拆完,我发现真正省时间的地方在顺序。解法记不住没关系,顺序对了就少走弯路。

docker compose logs --tail=50 <服务>

50 行日志里通常已经写了根因,比翻文档快。先看日志,再猜。

然后三条纪律:

一次只改一个变量。 同时改端口和镜像源,好了不知道是哪个起的作用,坏了也不知道是哪个弄坏的。

同一个方案失败两次就换方向。 第二次失败通常说明判断错了,不是操作没做到位。我三次重装就是没执行这条。

改之前备份 .env 和数据库。 尤其是 docker compose down -v 之前——那个 -v 会删卷,知识库数据一起没。

这套判断我做成了一个命令

上面这些查法散在六处,每次排查都要重新想起来跑哪条。我把它收进了一个脚本,一条命令出完八项:Docker 装没装、daemon 起没起、虚拟机内存多大、CPU 和磁盘、端口占用、已有部署、WSL 集成、镜像源。

输出是一份能直接看懂的清单,每条带「为什么」和「怎么办」。

后来这个脚本被整理成了一个技能包,装进 AI 助手之后,你说一句「Dify 装不上」,它自己判断能不能代你跑——能跑就直接查,改系统的动作先说清做什么、怎么撤回,得到同意再动。四个平台通用:Hermes Agent、WorkBuddy、千问办公、豆包工作。

11 月 9 日四个平台逐一装通那天,豆包工作当场在我机器上查出两个我自己没注意的问题:C 盘只剩 17.3 GB,docker 不在 PATH 里。

这套东西我放在这里,需要的话自己取:Dify 本地部署陪跑 · 29.9

不买也能用上面六个判断,判断方法全在文章里,我没有藏。买的是那条命令、那份报告格式,还有每次装不上时不用再从头想一遍。

它做不到什么

不替你填模型配置和 API Key——那部分要你自己决定用哪家模型。

不承诺一键装完。环境千差万别,查出来的问题还是要人判断。这篇文章里的六个症状是真的,但第七个可能就在你机器上,我没见过。

不碰你的数据库。要动生产数据之前,它一定会先让你备份。

装不上的时候,先问自己一句:我查的这个数,是它真正在用的那个数吗。

常见问题

为什么 docker info 显示的内存和我电脑的内存差这么多?

因为 Docker Desktop 在 Windows 上跑在一个虚拟机里,容器用的是虚拟机的内存配额,不是宿主的物理内存。虚拟机默认只分 2 GB,所以 16 GB 的电脑上容器照样会被杀。判据看 docker info --format "{{.MemTotal}}" 除以 1073741824 的结果。

镜像源配了四五个,为什么还是拉不动?

先看失败的镜像是哪个 registry。镜像加速源只对 docker.io 生效,ghcr.io、cr.weaviate.io 这些它管不着。用 docker compose pull 2>&1 | tee pull.log 拿到失败地址,再用 grep -oE "https?://[a-z0-9.-]+" pull.log | sort -u 看域名,不在 docker.io 上的换源没用。

容器状态 Exited 一定是出问题了吗?

不一定。init_permissions 这类初始化容器跑完就退出,退出码 0 是设计行为。判断要看的是一组核心容器是不是 Up 或 healthy:api、worker、web、nginx、db_postgres、redis、sandbox、plugin_daemon。


这篇有用吗

联系我

邮箱contact@fishsun.cn

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

微信

微信二维码

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