Dify 部署避坑指南：这 8 个错误让我多花了 3 天

Dify 部署避坑指南：这 8 个错误让我多花了 3 天

这篇是我自己踩坑的实录。第一次部署 Dify 花了 3 天，其中 2.5 天在排查本可避免的问题。现在把这些坑写下来，希望你能一天内搞定。

---

坑 1：用 latest 标签而不是固定版本

踩坑经过：拉取 langgenius/dify-api:latest，第二天更新后接口格式变了，前端报错。

正确做法：

# docker-compose.yml 使用固定版本
services:
  api:
    image: langgenius/dify-api:0.9.3  # 明确版本号
  web:
    image: langgenius/dify-web:0.9.3

升级前先阅读 GitHub Releases 的迁移说明。

---

坑 2：.env 中 URL 配置不一致

报错现象：登录后跳转到错误域名，或者 API 请求跨域失败。

原因：Dify 有多个 URL 配置项，必须全部保持一致：

# 这四个必须同时修改，且与实际访问地址完全一致
CONSOLE_WEB_URL=https://dify.example.com
CONSOLE_API_URL=https://dify.example.com
APP_WEB_URL=https://dify.example.com
APP_API_URL=https://dify.example.com
SERVICE_API_URL=https://dify.example.com

改完需要完整重启：docker compose down && docker compose up -d

---

坑 3：知识库上传 PDF 乱码

报错现象：上传 PDF 后，知识库中的内容是乱码或空白。

原因：扫描件 PDF 没有文字层，Dify 无法直接提取文字。

解决方案：

# 方案一：使用 OCR 工具预处理
pip install pdf2image pytesseract

# 方案二：在 Dify 设置中开启 OCR
# 需要配置 OCR 服务（如 Azure Computer Vision）
# .env
PDF_PREVIEW=true

或者使用 百度 OCR 等服务预处理后转为可选中的 PDF。

---

坑 4：Nginx 配置没有增加上传文件大小限制

报错现象：上传大文件（PDF > 10MB）时报 413 Request Entity Too Large。

# /etc/nginx/nginx.conf 或站点配置
http {
    client_max_body_size 100M;  # 默认是 1M，必须增大
}

同时修改 Dify 应用层配置：

UPLOAD_FILE_SIZE_LIMIT=50  # 单位 MB
UPLOAD_FILE_BATCH_LIMIT=10

---

坑 5：Weaviate 数据没有持久化

踩坑经过：重启 Docker 后知识库全空了，原来向量数据库数据没有挂载 volume。

# docker-compose.yml 确认 weaviate 有 volume 挂载
weaviate:
  volumes:
    - ./volumes/weaviate:/var/lib/weaviate  # 必须！

# 检查数据是否真的持久化
ls -la ./volumes/weaviate
# 应该能看到数据文件

---

坑 6：忘记配置 SSRF 防护导致安全漏洞

风险：Workflow 中的 HTTP 请求节点如果没有 SSRF 防护，恶意用户可以让服务器发请求到内网地址。

检查配置：

# .env 确认以下配置存在
SSRF_PROXY_HTTP_URL=http://ssrf-proxy:3128
SSRF_PROXY_HTTPS_URL=http://ssrf-proxy:3128

# 确认 ssrf-proxy 容器在运行
docker compose ps ssrf-proxy

---

坑 7：Worker 数量不够导致任务积压

报错现象：用户提交 Workflow 后等待很久，日志里任务在队列里堆积。

原因：默认只有 1 个 Worker 进程。

# docker-compose.yml
worker:
  command: celery -A app.celery worker -P gevent -c 10 --loglevel INFO
  # -c 10 表示 10 个并发 worker，根据 CPU 核数调整

或者：

# 不修改配置，直接扩展 worker 实例数
docker compose up -d --scale worker=3

---

坑 8：生产环境没有做健康监控

踩坑经过：某次 PostgreSQL 容器因为磁盘满了崩溃，过了半天才被反馈，服务中断了 6 小时。

最简监控方案：

#!/bin/bash
# health_check.sh - 加入 crontab 每 5 分钟执行

STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://dify.example.com/api/health)

if [ "$STATUS" != "200" ]; then
    # 发送告警（替换为你的 webhook）
    curl -X POST "YOUR_DINGTALK_WEBHOOK" \
        -H "Content-Type: application/json" \
        -d '{"msgtype":"text","text":{"content":"Dify 服务异常！HTTP 状态码: '$STATUS}}'
fi

# crontab -e
*/5 * * * * /home/ubuntu/health_check.sh

---

总结清单

部署前请核对：

• 使用固定版本号镜像
• 所有 URL 配置项一致
• Nginx 文件上传大小限制已增大
• Weaviate volume 已挂载
• SSRF 防护已配置
• Worker 数量满足并发需求
• 健康监控已上线
• 数据库备份已设置

如果不想独自踩这些坑，LocalClaw（insman.cn） 上有专业 Dify 服务商按最佳实践交付，避免这些问题从一开始发生。