Dify 部署踩坑指南：常见问题排查与配置文件参考

发布人：慈云数据-客服中心发布时间：12小时前阅读量：1

Dify 常见问题汇总｜附配置文件

Dify 是一款开源的 LLMOps 平台，支持可视化编排 AI 应用、接入多种大模型、构建知识库、发布聊天机器人、工作流应用以及 Agent 应用。对于企业或个人开发者来说，Dify 的优势在于上手快、生态开放、部署方式灵活，并且可以将模型能力、提示词、工具调用、知识库检索、API 服务等能力整合到一个平台中。

不过，在实际部署和使用 Dify 的过程中，很多用户会遇到各种问题，例如：Docker 启动失败、环境变量配置不正确、模型无法调用、知识库无法索引、插件安装异常、API 地址配置错误、Nginx 反向代理不生效、上传文件失败、数据库连接异常等。

本文将围绕 Dify 的常见问题进行系统整理，并附上一份常用配置文件示例，方便大家在部署、排查和优化时参考。

一、Dify 是什么？

Dify 是一个开源的大语言模型应用开发平台，主要面向 AI 应用开发者和企业团队。它提供了从模型接入、提示词编排、知识库管理、工作流构建、API 发布到应用监控的一整套能力。

简单来说，Dify 可以帮助你快速构建以下类型的 AI 应用：

智能客服机器人
企业知识库问答系统
文档总结工具
AI 写作助手
工作流自动化应用
多步骤 Agent 应用
基于 API 的 AI 能力服务

Dify 支持多种模型服务，例如：

OpenAI
Azure OpenAI
Anthropic Claude
Google Gemini
Cohere
Hugging Face
Ollama
通义千问
智谱 AI
百川智能
月之暗面 Kimi
DeepSeek
OpenRouter
本地私有化大模型

由于 Dify 使用 Docker Compose 部署较为方便，因此很多开发者会选择在服务器上通过 Docker 方式部署。但也正因为其涉及多个服务组件，例如 api、web、worker、db、redis、weaviate、sandbox、plugin_daemon 等，所以在部署时容易出现配置遗漏或网络访问问题。

二、Dify 常见部署方式

Dify 常见的部署方式主要有以下几种：

1. Docker Compose 部署

这是官方最推荐、也是最常见的方式。适合个人用户、中小团队以及测试环境使用。

优点：

部署简单
服务组件完整
便于升级和维护
不需要手动安装 PostgreSQL、Redis 等依赖

缺点：

需要理解 Docker 网络、环境变量和数据卷
生产环境需要额外配置反向代理、HTTPS 和备份机制

2. 源码部署

适合有二次开发需求的团队。可以直接修改后端、前端或插件逻辑。

优点：

灵活度高
适合深度定制
便于调试代码

缺点：

部署复杂
需要 Node.js、Python、数据库、Redis 等环境
维护成本更高

3. Kubernetes 部署

适合企业生产环境、大规模团队或云原生场景。

优点：

可扩展性强
便于服务治理
适合高可用部署
可结合企业已有 DevOps 流程

缺点：

部署门槛较高
需要 Kubernetes 运维经验
配置项更多

三、Dify 常见问题汇总

下面按照部署、访问、模型、知识库、插件、文件上传、工作流、性能和安全等维度进行整理。

1. Docker Compose 启动失败怎么办？

问题现象

执行以下命令后启动失败：

docker compose up -d

可能出现类似错误：

port is already allocated

或：

container exited with code 1

或：

failed to solve: network timeout

常见原因

端口被占用
Docker 版本过低
镜像拉取失败
.env 配置错误
数据库、Redis 等依赖服务未正常启动
服务器内存不足

解决方法

首先查看容器状态：

docker compose ps

查看具体日志：

docker compose logs -f api
docker compose logs -f worker
docker compose logs -f web
docker compose logs -f db
docker compose logs -f redis

如果端口被占用，可以使用：

lsof -i:80
lsof -i:443
lsof -i:5001

或者：

netstat -tunlp | grep 80

如果发现端口已经被 Nginx、Apache 或其他服务占用，需要修改 docker-compose.yaml 中的端口映射，或者停止占用端口的服务。

2. Dify 页面打不开怎么办？

问题现象

浏览器访问服务器 IP 或域名时，页面无法打开，常见表现包括：

连接超时
502 Bad Gateway
404 Not Found
页面空白
前端加载失败
API 请求跨域错误

排查步骤

首先确认容器是否正常运行：

docker compose ps

确认 web 和 api 是否启动成功：

docker compose logs -f web
docker compose logs -f api

然后检查防火墙是否放行端口：

ufw status

如果使用的是云服务器，还需要检查云厂商安全组是否开放了对应端口，例如：

80
443
3000
5001

如果通过 Nginx 反向代理访问，需要确认 Nginx 配置中的 proxy_pass 是否指向正确的服务地址。

3. 登录后接口报错怎么办？

问题现象

Dify 前端可以打开，但登录、创建应用或进入控制台时接口报错，例如：

Network Error

或：

Failed to fetch

或浏览器控制台出现跨域错误。

常见原因

通常是 CONSOLE_API_URL、SERVICE_API_URL、APP_API_URL、FILES_URL 等环境变量配置错误。

Dify 前端和后端之间依赖这些地址进行请求。如果地址配置成了 localhost，但用户是通过域名访问，就可能导致浏览器请求本地地址，从而失败。

解决方法

检查 .env 文件中的 URL 配置，例如：

CONSOLE_API_URL=https://dify.example.com
CONSOLE_WEB_URL=https://dify.example.com
SERVICE_API_URL=https://dify.example.com
APP_API_URL=https://dify.example.com
APP_WEB_URL=https://dify.example.com
FILES_URL=https://dify.example.com

如果没有配置 HTTPS，也可以使用：

CONSOLE_API_URL=http://你的服务器IP
CONSOLE_WEB_URL=http://你的服务器IP
SERVICE_API_URL=http://你的服务器IP
APP_API_URL=http://你的服务器IP
APP_WEB_URL=http://你的服务器IP
FILES_URL=http://你的服务器IP

修改后需要重启服务：

docker compose down
docker compose up -d

4. 忘记管理员账号密码怎么办？

问题现象

首次部署后忘记登录邮箱或密码，无法进入 Dify 控制台。

解决思路

Dify 的用户信息通常存储在 PostgreSQL 中。如果忘记密码，可以通过数据库修改用户状态或重置密码。但直接操作数据库存在风险，建议先备份数据。

进入数据库容器：

docker compose exec db psql -U postgres

查看数据库：

\l

连接 Dify 数据库：

\c dify

查看用户表：

select id, email, name, created_at from accounts;

如果需要重置密码，建议优先使用 Dify 官方支持的重置流程。如果环境没有配置邮件服务，就需要通过数据库或后端命令方式处理。由于不同版本表结构和密码加密方式可能变化，不建议随意手动写入密码哈希。

5. 模型供应商配置后无法调用怎么办？

问题现象

在 Dify 中配置 OpenAI、DeepSeek、通义千问、智谱等模型后，测试调用失败，提示：

API key invalid
connection error
request timeout
model not found
insufficient quota
401 Unauthorized
429 Too Many Requests

常见原因

API Key 填写错误
模型名称填写错误
模型服务商接口地址不正确
账户余额不足
服务器无法访问模型服务商
代理配置错误
请求频率超限
模型供应商服务不稳定

解决方法

首先确认服务器能访问模型服务商：

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

如果访问不通，需要检查服务器网络、代理或防火墙。

如果使用兼容 OpenAI API 的服务，例如 DeepSeek、OpenRouter、本地模型服务等，需要确认 Base URL 配置是否正确。

示例：

https://api.deepseek.com/v1

或：

https://openrouter.ai/api/v1

如果是 Ollama，本地部署时要注意 Docker 容器内不能直接访问宿主机的 localhost。可以使用：

http://host.docker.internal:11434

在 Linux 环境中，有时需要在 docker-compose.yaml 中增加：

extra_hosts:
  - "host.docker.internal:host-gateway"

6. Ollama 本地模型无法连接怎么办？

问题现象

Ollama 在宿主机运行正常：

ollama list
ollama run qwen2.5

但 Dify 中配置 Ollama 后连接失败。

常见原因

Dify 运行在 Docker 容器中，容器内的 localhost 指向的是容器自身，而不是宿主机。因此，如果在 Dify 中填写：

http://localhost:11434

大概率无法访问宿主机上的 Ollama。

解决方法

推荐使用：

http://host.docker.internal:11434

如果 Linux 下无法解析该域名，可以在 docker-compose.yaml 中为相关服务添加：

extra_hosts:
  - "host.docker.internal:host-gateway"

同时确保 Ollama 监听地址不是仅限本机回环地址。可以设置环境变量：

export OLLAMA_HOST=0.0.0.0:11434
ollama serve

或者通过 systemd 配置 Ollama 服务的监听地址。

7. 知识库上传文档后无法索引怎么办？

问题现象

上传 PDF、Word、TXT、Markdown 等文档后，知识库一直处于：

排队中
索引中
处理失败
文档解析失败
向量化失败

常见原因

Worker 服务异常
向量数据库异常
Embedding 模型未配置
文档过大
文件格式解析失败
Celery 队列堵塞
Redis 异常
模型供应商限流

排查方法

查看 worker 日志：

docker compose logs -f worker

查看 api 日志：

docker compose logs -f api

查看向量数据库日志，例如 Weaviate：

docker compose logs -f weaviate

确认是否配置了可用的 Embedding 模型。知识库检索依赖文本向量化，如果只配置了聊天模型，而没有配置 Embedding 模型，知识库通常无法正常索引。

解决方法

在 Dify 控制台中进入模型供应商配置，确保至少配置一个可用的 Embedding 模型。例如：

OpenAI：text-embedding-3-small
通义千问：text-embedding-v2
智谱：embedding-2
BGE 系列本地 Embedding 模型

如果文档较大，建议先拆分上传，或者调整文档处理参数。对于扫描版 PDF，需要先进行 OCR，否则解析出的文本可能为空。

8. 知识库检索效果差怎么办？

问题现象

知识库可以正常索引，但问答效果不好，例如：

答非所问
找不到相关内容
引用片段不准确
回答过于泛化
明明文档里有答案却检索不到

可能原因

文档切分策略不合理
Embedding 模型效果较差
检索召回数量过少
相似度阈值设置过高
文档本身结构混乱
提示词没有约束模型基于知识库回答
没有启用重排序模型
查询问题和文档语言不一致

优化建议

可以从以下几个方面优化：

1. 优化文档结构

上传前尽量保证文档结构清晰，例如：

使用明确的标题层级
删除无关页眉页脚
避免大量表格嵌套
将过长文档按主题拆分
Markdown 文档优先于扫描 PDF

2. 调整分段策略

知识库切分太短，可能丢失上下文；切分太长，可能影响检索精度。一般建议：

普通知识问答：每段 500～1000 字左右
技术文档：按标题层级切分
FAQ 文档：一问一答作为一个片段
合同和制度文档：按章节切分

3. 使用更好的 Embedding 模型

如果预算允许，可以选择效果更好的 Embedding 模型。中文场景下，建议选择中文表现较好的模型或多语言 Embedding 模型。

4. 启用 Rerank

重排序模型可以对召回结果重新排序，提升命中率。尤其是在知识库较大、内容相似度较高的情况下，Rerank 效果明显。

5. 优化提示词

可以在应用提示词中加入类似约束：

请严格基于知识库内容回答问题。
如果知识库中没有相关信息，请回答“根据已知资料无法确定”，不要编造答案。
回答时请尽量引用知识库中的关键事实。

9. 文件上传失败怎么办？

问题现象

上传文档、图片或其他附件时报错：

file too large
upload failed
413 Request Entity Too Large
unsupported file type
文件上传后无法访问

常见原因

Nginx 限制上传大小
Dify 环境变量限制上传大小
对象存储配置错误
FILES_URL 配置错误
后端服务无法写入存储目录
文件类型不支持

Nginx 解决方法

如果使用 Nginx 反向代理，需要增加：

client_max_body_size 100M;

示例：

server {
    listen 80;
    server_name dify.example.com;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

修改后测试并重载：

nginx -t
systemctl reload nginx

10. 插件安装失败怎么办？

问题现象

Dify 安装插件时失败，可能出现：

Plugin daemon connection failed
plugin install timeout
signature verification failed
marketplace unavailable
插件列表加载失败

常见原因

plugin_daemon 容器未启动
网络无法访问插件市场
插件版本与 Dify 版本不兼容
代理配置错误
插件服务端口未配置
沙箱服务异常

排查方法

查看插件服务状态：

docker compose ps plugin_daemon

查看日志：

docker compose logs -f plugin_daemon

如果插件市场访问异常，需要检查服务器外网连接。如果是内网环境，可以考虑离线安装插件，或者配置可访问的镜像源。

11. 工作流节点执行失败怎么办？

问题现象

在 Dify 工作流中添加 HTTP 请求、代码执行、知识库检索、模型调用等节点后，执行失败。

常见原因

节点输入变量为空
上游节点输出字段名称错误
HTTP 节点请求地址不可达
代码执行沙箱异常
模型超时或限流
JSON 格式不合法
条件分支判断逻辑错误

排查建议

工作流调试时建议逐个节点验证：

先运行开始节点
再检查变量输出
单独测试 HTTP 节点
检查 JSON 结构是否正确
查看节点错误堆栈
查看 api、worker、sandbox 日志

常用日志命令：

docker compose logs -f api
docker compose logs -f worker
docker compose logs -f sandbox

如果是 HTTP 请求节点访问内网服务，也需要注意 Docker 网络问题。容器内访问宿主机服务不能直接使用 localhost，通常需要使用宿主机网关地址或将服务加入同一 Docker 网络。

12. API 调用 Dify 应用失败怎么办？

问题现象

通过外部程序调用 Dify 应用 API 时失败，例如：

401 Unauthorized

或：

404 Not Found

或：

Invalid Authorization header

正确调用示例

以聊天应用为例：

curl -X POST 'https://dify.example.com/v1/chat-messages' \
  -H 'Authorization: Bearer app-xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "你好，请介绍一下 Dify",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "user-001"
  }'

注意事项：

API Key 必须是应用 API Key，不是模型供应商 Key
请求头格式必须是 Authorization: Bearer xxx
接口路径通常为 /v1/chat-messages、/v1/completion-messages 或 /v1/workflows/run
如果使用流式输出，response_mode 设置为 streaming
反向代理必须正确转发请求体和响应流

13. 流式输出不生效怎么办？

问题现象

应用设置了流式输出，但前端或 API 调用时仍然一次性返回，或者一直等待。

常见原因

Nginx 缓冲未关闭
客户端不支持 SSE
模型供应商不支持流式返回
代理层超时
response_mode 设置错误

Nginx 配置建议

location / {
    proxy_pass http://127.0.0.1:80;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding on;
    proxy_read_timeout 3600s;
}

API 调用时需要设置：

{
  "response_mode": "streaming"
}

14. 数据库连接失败怎么办？

问题现象

api 或 worker 日志中出现：

could not connect to server
connection refused
password authentication failed
database does not exist

常见原因

PostgreSQL 容器未启动
数据库密码配置不一致
数据库初始化失败
数据卷损坏
数据库连接数耗尽

排查方法

查看数据库容器：

docker compose ps db
docker compose logs -f db

进入数据库测试：

docker compose exec db psql -U postgres -d dify

检查 .env 中数据库配置：

DB_USERNAME=postgres
DB_PASSWORD=your-password
DB_HOST=db
DB_PORT=5432
DB_DATABASE=dify

在 Docker Compose 内部网络中，DB_HOST 通常应填写服务名 db，而不是 localhost。

15. Redis 连接失败怎么办？

问题现象

日志中出现：

Redis connection refused
Error connecting to Redis

常见原因

Redis 容器未启动
Redis 密码配置错误
Redis 地址配置错误
Docker 网络异常

解决方法

查看 Redis 日志：

docker compose logs -f redis

检查配置：

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password

同样，在 Compose 内部应使用服务名 redis，不要使用 localhost。

16. 升级 Dify 后异常怎么办？

问题现象

升级后出现：

页面打不开
数据库迁移失败
插件异常
应用无法运行
知识库检索异常
环境变量不兼容

升级建议

升级前务必备份：

docker compose down
tar -czvf dify-backup-$(date +%F).tar.gz ./volumes ./.env ./docker-compose.yaml

拉取最新代码和镜像：

git pull
docker compose pull
docker compose up -d

查看迁移日志：

docker compose logs -f api
docker compose logs -f worker

如果跨多个大版本升级，建议先阅读官方 Release Notes，确认是否有环境变量变更、插件系统变化或数据库迁移说明。

四、Dify 常用配置文件示例

下面给出一份较常见的部署配置示例。不同版本 Dify 的配置项可能略有变化，请以你当前版本官方 .env.example 为准。

1. `.env` 示例配置

# =========================
# Dify 基础配置
# =========================

# 控制台地址
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

# 文件访问地址
FILES_URL=https://dify.example.com

# 时区
TZ=Asia/Shanghai

# =========================
# 安全配置
# =========================

# 用于加密敏感信息，生产环境务必修改
SECRET_KEY=please-change-this-secret-key

# 初始化密码，可根据版本支持情况配置
INIT_PASSWORD=please-change-init-password

# =========================
# 数据库配置
# =========================

DB_USERNAME=postgres
DB_PASSWORD=please-change-db-password
DB_HOST=db
DB_PORT=5432
DB_DATABASE=dify

# PostgreSQL 容器内部配置
POSTGRES_USER=postgres
POSTGRES_PASSWORD=please-change-db-password
POSTGRES_DB=dify

# =========================
# Redis 配置
# =========================

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_USERNAME=
REDIS_PASSWORD=please-change-redis-password
REDIS_DB=0
REDIS_USE_SSL=false

# =========================
# Celery 配置
# =========================

CELERY_BROKER_URL=redis://:please-change-redis-password@redis:6379/1

# =========================
# 存储配置
# =========================

# 本地存储
STORAGE_TYPE=opendal
OPENDAL_SCHEME=fs
OPENDAL_FS_ROOT=storage

# 如果使用 S3，可参考：
# STORAGE_TYPE=s3
# S3_ENDPOINT=https://s3.example.com
# S3_BUCKET_NAME=dify
# S3_ACCESS_KEY=your-access-key
# S3_SECRET_KEY=your-secret-key
# S3_REGION=us-east-1

# =========================
# 向量数据库配置
# =========================

VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://weaviate:8080
WEAVIATE_API_KEY=

# =========================
# 上传限制
# =========================

UPLOAD_FILE_SIZE_LIMIT=100
UPLOAD_FILE_BATCH_LIMIT=10

# =========================
# Web 服务
# =========================

WEB_API_CORS_ALLOW_ORIGINS=*
CONSOLE_CORS_ALLOW_ORIGINS=*

# =========================
# 日志
# =========================

LOG_LEVEL=INFO

2. `docker-compose.override.yaml` 示例

如果需要让容器访问宿主机服务，例如 Ollama、本地 Embedding 服务、本地 API 服务，可以增加如下配置：

services:
  api:
    extra_hosts:
      - "host.docker.internal:host-gateway"

  worker:
    extra_hosts:
      - "host.docker.internal:host-gateway"

  plugin_daemon:
    extra_hosts:
      - "host.docker.internal:host-gateway"

使用方式：

docker compose -f docker-compose.yaml -f docker-compose.override.yaml up -d

如果你使用默认的 docker compose up -d，Docker Compose 也会自动识别当前目录下的 docker-compose.override.yaml。

3. Nginx 反向代理配置示例

适用于 Dify 通过域名访问的场景。

server {
    listen 80;
    server_name dify.example.com;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:80;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

如果使用 HTTPS，可以使用 Certbot 申请证书：

apt install certbot python3-certbot-nginx -y
certbot --nginx -d dify.example.com

生成证书后，Nginx 会自动添加 HTTPS 配置。也可以手动配置：

server {
    listen 443 ssl http2;
    server_name dify.example.com;

    ssl_certificate /etc/letsencrypt/live/dify.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/dify.example.com/privkey.pem;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:80;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

server {
    listen 80;
    server_name dify.example.com;
    return 301 https://$host$request_uri;
}

4. Ollama 与 Dify 配置示例

宿主机启动 Ollama：

export OLLAMA_HOST=0.0.0.0:11434
ollama serve

拉取模型：

ollama pull qwen2.5:7b
ollama pull bge-m3

Dify 中模型供应商配置：

Provider: Ollama
Base URL: http://host.docker.internal:11434
Chat Model: qwen2.5:7b
Embedding Model: bge-m3

如果容器无法解析 host.docker.internal，添加：

services:
  api:
    extra_hosts:
      - "host.docker.internal:host-gateway"
  worker:
    extra_hosts:
      - "host.docker.internal:host-gateway"

五、Dify 生产环境部署建议

如果只是个人测试，默认 Docker Compose 基本够用。但如果要用于生产环境，建议重点关注以下内容。

1. 使用 HTTPS

生产环境不要直接使用 HTTP 暴露后台。建议使用 Nginx、Caddy、Traefik 等反向代理，并配置 HTTPS。

HTTPS 可以避免：

Token 明文传输
登录信息泄露
浏览器安全限制
第三方集成失败

2. 修改默认密钥和密码

生产环境必须修改：

SECRET_KEY
DB_PASSWORD
REDIS_PASSWORD
INIT_PASSWORD
对象存储密钥
插件相关密钥

不要使用示例密码，也不要将 .env 文件提交到 Git 仓库。

3. 定期备份数据

至少备份以下内容：

PostgreSQL 数据
Redis 持久化数据
上传文件
向量数据库数据
.env
docker-compose.yaml
插件数据

简单备份示例：

mkdir -p /backup/dify

docker compose exec db pg_dump -U postgres dify > /backup/dify/dify-$(date +%F).sql

tar -czvf /backup/dify/dify-volumes-$(date +%F).tar.gz ./volumes
cp .env /backup/dify/.env-$(date +%F)

建议将备份同步到另一台服务器或对象存储中。

4. 限制后台访问

如果 Dify 部署在公网，建议通过以下方式增强安全性：

使用复杂管理员密码
限制控制台访问 IP
开启 HTTPS
配置防火墙
定期更新版本
不暴露数据库、Redis、向量数据库端口到公网
对应用 API Key 做权限和额度管理

Nginx 限制 IP 示例：

location /console {
    allow 你的办公IP;
    deny all;

    proxy_pass http://127.0.0.1:80;
}

具体路径需根据实际版本和访问路由调整。

5. 监控资源使用

Dify 在使用知识库、工作流、Agent 和插件时，会消耗较多 CPU、内存和网络资源。建议监控：

CPU 使用率
内存使用率
磁盘空间
Docker 容器状态
PostgreSQL 连接数
Redis 内存
Worker 队列堆积
模型调用耗时
向量数据库响应时间

查看容器资源：

docker stats

查看磁盘：

df -h
du -sh ./volumes/*

六、常用排障命令速查

查看所有容器状态

docker compose ps

查看所有服务日志

docker compose logs -f

查看 API 日志

docker compose logs -f api

查看 Worker 日志

docker compose logs -f worker

查看数据库日志

docker compose logs -f db

重启服务

docker compose restart

重启单个服务

docker compose restart api
docker compose restart worker
docker compose restart web

停止服务

docker compose down

启动服务

docker compose up -d

拉取新镜像

docker compose pull

清理无用镜像

docker image prune -f

进入容器

docker compose exec api bash
docker compose exec worker bash
docker compose exec db bash

七、Dify 故障排查思路总结

遇到 Dify 问题时，不建议一上来就删除容器或清空数据卷。更稳妥的排查顺序如下：

确认问题范围
是前端打不开、接口报错、模型失败，还是知识库失败？
查看容器状态
使用 docker compose ps 判断哪些服务异常。
查看关键日志
优先看 api、worker、web、db、redis、weaviate、plugin_daemon。
检查环境变量
特别是 URL、数据库、Redis、存储、向量库、密钥配置。
检查网络连通性
包括服务器到模型服务商、容器到宿主机、容器到数据库等。
检查反向代理
重点关注请求体大小、SSE 流式输出、HTTPS、Header 转发。
确认版本兼容性
插件、配置文件、数据库迁移都可能和版本有关。
备份后再修改
涉及数据库、数据卷、升级和降级时，一定先备份。

八、结语

Dify 的优势在于易用和开放，但它本质上仍然是一个由多个服务组成的完整 AI 应用平台。因此，在部署和维护时，需要同时关注 Web 服务、API 服务、异步任务、数据库、Redis、向量数据库、文件存储、插件系统以及模型供应商等多个环节。

大多数 Dify 问题都可以通过以下方式定位：

查看 Docker 容器状态
查看 API 和 Worker 日志
检查 .env 中的 URL 和连接配置
确认模型供应商 Key、Base URL 和模型名称
检查知识库 Embedding 配置
检查 Nginx 反向代理和上传大小限制
确认 Docker 容器与宿主机、外网服务之间的网络连通性

如果是个人测试环境，建议先使用最小配置跑通：公网域名或服务器 IP、一个可用聊天模型、一个可用 Embedding 模型、本地存储和默认向量数据库。等基础流程稳定后，再逐步引入 HTTPS、对象存储、本地模型、插件、监控和备份。

对于生产环境，则务必重视安全、备份、版本管理和资源监控。尤其是 .env 文件中的密钥、数据库密码、Redis 密码和模型 API Key，必须妥善保管，避免泄露。

希望本文整理的 Dify 常见问题和配置示例，能帮助你更快完成部署、排查故障，并稳定运行自己的 AI 应用平台。

文章标签： Dify DockerCompose 知识库 Nginx

上一篇：Dify 部署踩坑指南：常见报错、排查思路和命令一次讲清 Dify 安装运行出问题？这份排查命令清单建议收藏 Dify 从安装到故障排查：常见问题与实用命令整理 Dify 部署打不开、启动失败、知识库报错？常见问题全汇总 Dify 运维手册：部署、升级、备份、排错命令大全 Dify 常见故障处理指南：Docker 部署必备命令合集 Dify 部署避坑笔记：从容器日志到模型配置的完整排查方案 Dify 使用出错怎么办？20 个高频问题和对应命令整理

下一篇：Dify 新手避坑指南：从搭建应用到知识库配置，一篇讲清楚

更多栏目

新闻动态

文档中心

下载中心

目录结构

全文

产品与服务

新闻帮助

生态合作

了解我们

Dify 部署踩坑指南：常见问题排查与配置文件参考

Dify 常见问题汇总｜附配置文件

一、Dify 是什么？

二、Dify 常见部署方式

1. Docker Compose 部署

2. 源码部署

3. Kubernetes 部署

三、Dify 常见问题汇总

1. Docker Compose 启动失败怎么办？

问题现象

常见原因

解决方法

2. Dify 页面打不开怎么办？

问题现象

排查步骤

3. 登录后接口报错怎么办？

问题现象

常见原因

解决方法

4. 忘记管理员账号密码怎么办？

问题现象

解决思路

5. 模型供应商配置后无法调用怎么办？

问题现象

常见原因

解决方法

6. Ollama 本地模型无法连接怎么办？

问题现象

常见原因

解决方法

7. 知识库上传文档后无法索引怎么办？

问题现象

常见原因

排查方法

解决方法

8. 知识库检索效果差怎么办？

问题现象

可能原因

优化建议

1. 优化文档结构

2. 调整分段策略

3. 使用更好的 Embedding 模型

4. 启用 Rerank

5. 优化提示词

9. 文件上传失败怎么办？

问题现象

常见原因

Nginx 解决方法

10. 插件安装失败怎么办？

问题现象

常见原因

排查方法

11. 工作流节点执行失败怎么办？

问题现象

常见原因

排查建议

12. API 调用 Dify 应用失败怎么办？

问题现象

正确调用示例

13. 流式输出不生效怎么办？

问题现象

常见原因

Nginx 配置建议

14. 数据库连接失败怎么办？

问题现象

常见原因

排查方法

15. Redis 连接失败怎么办？

问题现象

常见原因

解决方法

16. 升级 Dify 后异常怎么办？

问题现象

升级建议

四、Dify 常用配置文件示例

1. .env 示例配置

1. `.env` 示例配置

2. `docker-compose.override.yaml` 示例