Dify常见报错与排查手册一、前言二、第一大类Docker 部署/启动失败最常见问题1执行 docker compose up -d 后容器没启动/状态 Exited报错现象常见原因修复步骤验证问题2git clone 拉不到源码官方源超时报错现象常见原因修复换国内Gitee镜像验证问题3docker compose pull 拉镜像超时/失败报错现象常见原因修复一键配置国内加速验证三、第二大类模型调用失败聊天没反应/报错问题4模型添加后测试连接失败报错现象常见原因修复步骤验证问题5聊天发送后一直转圈/空白无回答报错现象常见原因修复步骤验证四、第三大类知识库上传/解析失败PDF/Word传不上去/乱码问题6上传PDF/Word一直处理中/失败报错现象常见原因修复步骤验证问题7知识库问答回答乱码/看不懂报错现象常见原因修复步骤验证五、第四大类工作流执行失败问题8工作流调试节点报错/执行中断报错现象常见原因修复步骤验证六、第五大类网页打不开/访问异常问题9浏览器输入地址打不开/连接超时报错现象通俗原因小白修复步骤验证七、第六大类备份/恢复失败问题10恢复数据库报错恢复后登录不上报错现象通俗原因小白修复步骤验证八、总结一、前言这里整理了Dify使用过程中常见的一些问题及排查解决方式部署启动失败模型调用失败知识库上传失败/解析乱码聊天无响应/回答空白工作流执行失败网页打不开/端口冲突备份恢复失败二、第一大类Docker 部署/启动失败最常见问题1执行docker compose up -d后容器没启动/状态 Exited报错现象docker compose ps看到容器状态是Exited退出浏览器打不开页面常见原因内存不够最常见服务器内存4G容器启动直接崩端口被占用80端口被Nginx/Apache占用配置文件错误.env写错参数镜像没拉全docker compose pull没执行成功修复步骤先看日志找到具体错因cd/usr/local/dify/dockerdockercompose logs-f看到out of memory→ 内存不够看到port 80 already in use→ 端口占用看到.env报错 → 配置文件错修复内存不足最常见Windows/macOSDocker Desktop → 设置 → 资源 → 内存调到8G重启DockerLinux增加swap分区# 一键增加2G swapsudoddif/dev/zeroofswapfilebs1Mcount2048sudomkswapswapfilesudoswaponswapfile修复端口占用80端口被占# 停止占用80端口的服务sudosystemctl stop nginxsudosystemctl stop apache2# 或直接改Dify端口推荐vi/usr/local/dify/docker/.env# 把 EXPOSE_NGINX_PORT80 改成 8080EXPOSE_NGINX_PORT8080# 重启Difydockercompose downdockercompose up-d重新拉镜像启动cd/usr/local/dify/dockerdockercompose pulldockercompose up-d验证docker compose ps所有容器状态Up浏览器打开http://IP:8080正常访问。问题2git clone拉不到源码官方源超时报错现象执行git clone https://github.com/langgenius/dify.git卡住、超时、失败常见原因GitHub国内访问慢、网络不稳定。修复换国内Gitee镜像cd/usr/local# 用Gitee镜像拉取国内秒下gitclone https://gitee.com/mirrors/dify.git验证进入目录cd /usr/local/dify/docker后续部署步骤不变。问题3docker compose pull拉镜像超时/失败报错现象拉镜像时卡住、报错timeout、拉不下来常见原因Docker官方源国内慢没配置国内镜像加速。修复一键配置国内加速创建加速配置文件sudovi/etc/docker/daemon.json粘贴下面内容直接复制{registry-mirrors:[https://docker.mirrors.ustc.edu.cn,https://hub-mirror.c.163.com,https://mirror.baidubce.com]}重启Docker生效sudosystemctl daemon-reloadsudosystemctl restartdocker重新拉镜像cd/usr/local/dify/dockerdockercompose pull验证镜像快速拉取完成无报错。三、第二大类模型调用失败聊天没反应/报错问题4模型添加后测试连接失败报错现象模型供应商 → 测试连接测试失败聊天时提示模型调用失败常见原因API Key 填错/有空格最常见账号没实名认证国内模型必须实名免费额度用完服务器外网不通服务器连不上模型厂商接口修复步骤检查API Key必做复制Key时前后不要有空格、不要换行、不要漏字符重新粘贴到输入框删除首尾空格检查账号实名通义千问/文心一言/DeepSeek登录厂商后台完成实名认证检查额度登录厂商控制台查看免费额度/余额用完就充值或换免费模型测试服务器外网连通性# 测试能否连通通义千问curlhttps://dashscope.aliyun.com# 测试能否连通DeepSeekcurlhttps://api.deepseek.com有返回 → 网络正常超时 → 服务器网络限制放行443端口验证重新点击测试连接提示测试成功。问题5聊天发送后一直转圈/空白无回答报错现象输入问题发送后一直加载最后空白或提示生成失败常见原因模型没选/没启用提示词太长/格式错误上下文记忆轮数太多服务器内存不够模型推理卡死修复步骤检查应用配置应用 → 模型选择已启用的模型提示词删除特殊符号、换行不要太多用简洁提示词你是AI助手简洁回答问题。减少上下文轮数应用 → 上下文设置 → 记忆轮数改成3~5重启Dify释放内存cd/usr/local/dify/dockerdockercompose restart验证重新发送问题正常返回回答。四、第三大类知识库上传/解析失败PDF/Word传不上去/乱码问题6上传PDF/Word一直处理中/失败报错现象上传文件后状态一直处理中最后提示解析失败常见原因文件太大超过20M文件加密/损坏格式不支持如WPS特殊格式服务器内存不够解析卡死修复步骤文件处理必做拆分大文件单个文件≤10M解密/修复文件用WPS/Office打开另存为标准PDF/Worddocx格式转换WPS文件转docx扫描版PDF转文字版重启Dify释放内存cd/usr/local/dify/dockerdockercompose restart重新上传上传后等待1~3分钟状态变为处理完成验证文件解析成功可在知识库中查看内容。问题7知识库问答回答乱码/看不懂报错现象提问后回答全是乱码、问号、看不懂的字符常见原因文件编码不兼容GBK/UTF-8冲突解析时字符编码错误修复步骤重新保存文件用记事本打开TXT另存为UTF-8编码Word/PDF用Office打开另存为标准格式删除旧知识库重新上传验证问答正常无乱码。五、第四大类工作流执行失败问题8工作流调试节点报错/执行中断报错现象点击调试流程执行到某节点报错中断停止常见原因节点连接错误没连好、连错线变量引用错误{{xxx.xxx}}写错模型/知识库没选条件判断逻辑错误修复步骤检查节点连接确保开始→知识库→大模型→结束线连紧、没连错检查变量引用知识库节点检索内容填{{start.query}}大模型节点文档内容填{{retrieval.context}}变量名不要写错字母、大小写一致检查节点配置知识库节点选择已创建的知识库大模型节点选择已启用的模型简化流程测试先只做开始→大模型→结束测试通了再加知识库验证调试流程所有节点执行成功返回正确结果。六、第五大类网页打不开/访问异常问题9浏览器输入地址打不开/连接超时报错现象输入http://IP:端口打不开、显示无法访问此网站通俗原因端口没放行服务器防火墙/安全组拦截容器没启动IP地址写错小白修复步骤放行端口必做Linux服务器放行8080端口sudofirewall-cmd --add-port8080/tcp--permanentsudofirewall-cmd--reload云服务器阿里云/腾讯云进入安全组放行80/8080端口检查容器状态cd/usr/local/dify/dockerdockercomposeps所有容器Up有Exited按问题1修复核对IP和端口输入http://服务器公网IP:端口如8080验证浏览器正常打开Dify登录页。七、第六大类备份/恢复失败问题10恢复数据库报错恢复后登录不上报错现象执行恢复命令报错恢复后用旧账号密码登录失败通俗原因恢复命令顺序错数据库没启动备份文件损坏小白修复步骤按顺序执行恢复命令必做# 1. 进入目录cd/usr/local/dify/docker# 2. 启动数据库dockercompose up-dpostgres# 3. 等待10秒sleep10# 4. 恢复数据库dockerexec-idocker-postgres-1 psql-Upostgres-dpostgres/usr/local/dify_backup.sql用旧账号密码登录恢复后不要新建账号用旧服务器的账号密码验证登录成功数据全部恢复。八、总结启动失败 → 看日志、查内存、改端口模型报错 → 查Key、查实名、查额度、查网络知识库失败 → 拆文件、转格式、重启服务工作流报错 → 查连线、查变量、查节点配置网页打不开 → 放行端口、查容器、核对IP备份恢复 → 按顺序、用旧账号