Dify 常见问题解答：私有化部署的 18 个高频问题

Dify 常见问题解答：私有化部署的 18 个高频问题

---

安装启动类

Q1：docker compose up 后 Web 页面打不开，显示 502

排查步骤：

# 1. 检查 web 容器是否正常
docker compose logs web --tail=30

# 2. 检查 api 容器
docker compose logs api --tail=30

# 3. 直接访问 API（跳过 Nginx）
curl http://localhost:5001/health

最常见原因：api 容器启动慢，web 容器先起来但后端未就绪。等待 1-2 分钟再刷新通常解决。

Q2：初始化页面一直转圈，控制台报 Failed to fetch

原因：前端静态资源加载失败，通常是 CORS 配置问题。

# .env 确保这些 URL 与实际访问地址一致
CONSOLE_WEB_URL=https://your-domain.com
CONSOLE_API_URL=https://your-domain.com
APP_WEB_URL=https://your-domain.com
APP_API_URL=https://your-domain.com

修改后需要重新 docker compose up -d 才能生效。

Q3：Weaviate 容器无法启动，日志显示 bind: address already in use

# 检查端口占用
ss -tlnp | grep 8080

# 修改 Weaviate 端口
# docker-compose.yml 中修改 weaviate 的端口映射
ports:
  - "18080:8080"  # 改用其他端口

---

知识库与向量数据库类

Q4：上传文档后，知识库搜索结果不准确

原因：默认的文本切分策略可能不适合你的文档格式。

调整方案：

• 技术文档：减小 chunk_size（推荐 256-512）
• 长文叙述：增大 chunk_size（推荐 1024）
• 表格/结构化数据：使用「父子切片」模式

知识库 → 设置 → 索引方式 → 高质量（推荐）
分段设置 → 分段标识符：\n\n → 最大长度：512

Q5：文档上传时报 Unsupported file type

Dify 支持的格式：TXT, MARKDOWN, PDF, HTML, XLSX, XLS, DOCX, CSV, EML, MSG, PPTX, PPT, XML, EPUB

不支持：.doc（旧格式，需转为 .docx）、图片（需 OCR 预处理）

# 批量转换 .doc 到 .docx
libreoffice --headless --convert-to docx *.doc

Q6：向量数据库占用磁盘过大

# 查看 Weaviate 数据目录大小
du -sh ./volumes/weaviate

# 清理无用知识库（在 UI 中删除后，数据可能未立即释放）
# Weaviate 需要手动触发 vacuum
curl -X POST http://localhost:8080/v1/schema/COLLECTION_NAME/backups

---

工作流（Workflow）类

Q7：Workflow 执行卡在某个节点不动

# 查看 Worker 日志
docker compose logs worker -f --tail=50

# 常见原因：
# 1. Worker 进程挂了（重启 worker）
# 2. LLM API 超时（检查模型节点的 timeout 设置）
# 3. 代码执行节点有死循环

Q8：Workflow 中的「代码执行」节点报 Sandbox execution timeout

# .env 中增加沙箱超时时间
CODE_EXECUTION_ENDPOINT=http://sandbox:8194
CODE_MAX_NUMBER=10000
CODE_MAX_STRING_LENGTH=80000
# 超时时间（秒）
CODE_EXECUTION_CONNECT_TIMEOUT=10
CODE_EXECUTION_READ_TIMEOUT=60
CODE_EXECUTION_WRITE_TIMEOUT=10

Q9：Workflow 的 HTTP 请求节点无法访问内网地址

原因：Sandbox 容器默认限制了出站请求，防止 SSRF 攻击。

# .env 中配置内网白名单（谨慎开放）
SSRF_PROXY_HTTP_URL=http://ssrf-proxy:3128
SSRF_PROXY_HTTPS_URL=http://ssrf-proxy:3128

---

模型与 API 类

Q10：添加 Ollama 模型后，请求时报 Connection refused

# Ollama 运行在宿主机时，容器内不能用 localhost
# 应使用宿主机 IP 或特殊地址
OLLAMA_HOST=http://host.docker.internal:11434  # Mac/Windows
OLLAMA_HOST=http://172.17.0.1:11434  # Linux

Q11：API 调用频繁报 429 Too Many Requests

Dify 自身不限流，这是下游 LLM 提供商的限制。解决方案：

1. 升级 LLM API 套餐
2. 在 Dify 中配置多个同类型模型，启用负载均衡
3. 在 Workflow 中添加限速节点

Q12：如何使用自己的 Embedding 模型？

设置 → 模型供应商 → 添加模型
→ 选择提供商 → 选择 Embedding 类型
→ 填入 API 端点（兼容 OpenAI 格式的均可）

---

权限与多租户类

Q13：普通成员看不到某个应用

原因：应用默认对工作空间内所有成员可见，但可能被设置为私有。

应用 → 设置 → 可见性 → 工作空间内所有成员

Q14：如何禁止成员创建新的 LLM 模型配置？

目前 Dify 不支持细粒度的模型权限控制，成员角色只能控制应用的创建/编辑权限。如需更细粒度控制，需要修改源码。

---

升级与维护类

Q15：升级 Dify 后知识库内容消失

原因：通常是向量数据库 volume 未正确挂载或升级时被误删。

# 升级前务必确认数据卷存在
docker volume ls | grep dify

# 备份
docker compose down
tar -czf dify_volumes_backup.tar.gz ./volumes
docker compose pull
docker compose up -d

Q16：如何迁移 Dify 到新服务器？

# 源服务器：打包数据
docker compose down
tar -czf dify_full_backup.tar.gz ./volumes ./docker/.env

# 目标服务器：恢复
tar -xzf dify_full_backup.tar.gz
docker compose up -d

Q17 - Q18 快速解答

问题	答案
如何开启注册邀请制？	设置 → 成员 → 关闭「允许所有人注册」
日志保留多久？	默认无限期，可在数据库中手动清理

---

专业支持

如果你在部署或使用中遇到上述之外的问题，LocalClaw（insman.cn） 上有 Dify 专业服务商提供有偿技术支持，通常比在社区等待回复更快。