dify部署常见五类错误及修复：postgresql连接被拒绝需配置healthcheck与service_healthy依赖；插件导入失败应精简protobuf等冲突依赖；端口冲突须修改映射或终止占用进程；内存不足触发oom需扩容swap并重启docker；pg_hba.conf拒绝连接需追加对应网段信任规则。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
部署Dify时遇到服务启动失败、数据库连不上、插件加载异常等报错，是绝大多数新手在首次安装过程中必然经历的阶段。这些错误看似随机，实则集中在五个可复现、可定位、可修复的典型路径上。
PostgreSQL连接被拒绝（psycopg2.OperationalError）
这是Dify启动时最常卡住的第一道关卡，表现为dify-api容器反复重启，日志里反复出现“Connection refused”或“could not connect to server”。根本原因不是密码错或端口错，而是API服务启动太快，PostgreSQL容器还没初始化完就去连——就像人还没坐稳，椅子就被抽走了。
第一步：打开docker-compose.yml，找到postgres服务块，在environment下方插入healthcheck配置：
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-dify}"]
interval: 10s
timeout: 5s
retries: 12
第二步：找到api-server服务块，在depends_on字段下补充健康依赖声明：
depends_on:
postgres:
condition: service_healthy
注意：不加condition只写service_started会导致同样问题，必须显式声明service_healthy，否则Docker默认只等容器进程起来就放行。
插件安装失败（ModuleNotFoundError / ImportError）
当Nano Banana等第三方插件无法在Dify后台启用，且日志中出现“ModuleNotFoundError: No module named 'protobuf'”或类似导入报错，说明Python依赖树存在冲突。这类错误在Ubuntu 22.04 + Python 3.12组合下发生率超四成。
方法一：进入Dify API容器执行依赖树精简检查
docker exec -it dify-api-1 pipdeptree --reverse --packages protobuf,grpcio,numpy
若输出中显示多个版本共存（如protobuf==4.25.1和protobuf==5.27.0同时存在），立即卸载高版本：
pip uninstall protobuf==5.27.0 -y
方法二：强制重建API服务并跳过缓存
docker compose down && docker compose build --no-cache api-server && docker compose up -d api-server
【关键前提】操作前确保已设置PYTHON_BUILD_MIRROR_URL环境变量，否则国内网络下重装将超时中断。
端口冲突导致nginx或api-server启动失败
执行docker compose up -d后发现nginx或api-server状态为“Restarting”，用docker logs -f dify-nginx查看日志，若含“bind: address already in use”，说明宿主机已有进程占用了80、443或3000端口。
Windows用户优先执行：
net stop http /y
Linux/macOS用户执行：
sudo lsof -i :80 | grep LISTEN
sudo kill -9
更稳妥的做法是直接改映射端口：打开docker-compose.yml，将nginx的ports从"80:80"改为"8080:80"，再执行docker compose up -d。访问地址同步变为http://localhost:8080。
内存不足触发OOM Killer（Killed process）
在2GB内存的轻量云服务器上运行docker compose up -d，部分容器（尤其是worker或celery）日志中突然消失，docker stats显示内存使用率瞬间冲到100%，系统日志（dmesg）里出现“Killed process”——这是Linux内核主动杀掉进程保命的信号。
立即执行SWAP扩容（仅限SSD服务器）：
sudo fallocate -l 4G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
永久生效需追加记录：
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
这一步做完后，必须重启docker daemon才能让容器感知新内存边界：
sudo systemctl restart docker
pg_hba.conf拒绝客户端连接（FATAL: no pg_hba.conf entry）
当Dify能启动但始终提示“database connection failed”，且db容器日志明确报出类似“no pg_hba.conf entry for host ‘172.19.0.7’…”时，说明PostgreSQL拒绝了来自Dify API容器的连接请求。这不是密码问题，是白名单没开。
执行命令向pg_hba.conf追加信任规则：
docker exec -it docker-db-1 sh -c "echo 'host all all 172.19.0.0/16 trust' >> /var/lib/postgresql/data/pg_hba.conf"
然后重启数据库服务：
docker restart docker-db-1
