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 :8080 或 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。
这篇有用吗