快速上手

相关源文件

本页面内容基于以下源文件生成：

• docker/docker-compose.yaml
• docker/.env.example
• docker/README.md
• api/.env.example
• web/.env.example
• api/services/workflow_event_snapshot_service.py
• api/services/init.py
• api/services/app_service.py
• api/services/tag_service.py
• api/services/ops_service.py

Dify 是一个开源的 LLM 应用开发平台，支持通过可视化界面构建 AI 应用。本文档将指导完成从环境准备到服务启动的完整流程。

环境准备与配置

在启动 Dify 之前，需要准备运行环境并正确配置系统参数。Dify 使用 Docker Compose 进行容器编排，将所有依赖服务（数据库、缓存、向量数据库等）打包在一起。

系统要求

必需依赖：

• Docker Engine 20.10+
• Docker Compose v2.0+
• 操作系统：Linux / macOS / Windows (with WSL2)
• 内存：建议 4GB 以上（默认配置包含 PostgreSQL、Redis、Weaviate 等多个服务）

可选依赖：

• NVIDIA Docker Runtime（如需 GPU 加速）

配置环境变量

Dify 使用环境变量文件管理配置。首次部署时，需要从模板创建配置文件：

bash
1cd docker
2cp .env.example .env

环境变量文件包含多个关键配置区块。以下是最重要的配置项：

外部访问地址配置（docker/.env.example:22-53）：

这些地址配置决定了前端界面显示的 API 端点。如果留空，系统将使用当前域名作为默认值。

安全与部署配置（docker/.env.example:101-116）：

重要：生产环境部署时，必须修改 SECRET_KEY 为随机生成的强密钥。可使用以下命令生成：

bash
1openssl rand -base64 42

安装步骤

获取源码

bash
1git clone https://github.com/langgenius/dify.git
2cd dify/docker

配置文件说明

Docker Compose 配置文件是自动生成的，不应直接修改。根据 docker/docker-compose.yaml:1-6 的说明：

WARNING: This file is auto-generated by generate_docker_compose. Do not modify this file directly. Instead, update the .env.example or docker-compose-template.yaml and regenerate this file.

正确的配置修改流程是：

1. 编辑 .env 文件（从 .env.example 复制而来）
2. 如需修改服务架构，编辑 docker-compose-template.yaml
3. 运行生成脚本重新创建 docker-compose.yaml

理解服务架构

Docker Compose 配置使用 YAML 锚点（anchors）实现配置复用。docker/docker-compose.yaml:7-20 定义了共享环境变量块：

yaml
1x-shared-env: &shared-api-worker-env
2  CONSOLE_API_URL: ${CONSOLE_API_URL:-}
3  CONSOLE_WEB_URL: ${CONSOLE_WEB_URL:-}
4  SERVICE_API_URL: ${SERVICE_API_URL:-}
5  # ... 更多配置
6  LOG_LEVEL: ${LOG_LEVEL:-INFO}
7  LOG_OUTPUT_FORMAT: ${LOG_OUTPUT_FORMAT:-text}

这个配置块被 API 服务和 Worker 服务共同引用，确保所有后端组件使用一致的配置。

最短可运行路径

以下是最快启动 Dify 的步骤：

bash
1# 1. 进入 docker 目录
2cd dify/docker
3
4# 2. 创建环境变量文件（使用默认配置）
5cp .env.example .env
6
7# 3. 启动所有服务
8docker compose up -d

启动后，Dify 将运行以下核心服务：

• API 服务：处理所有 API 请求
• Worker 服务：处理异步任务（工作流执行、向量索引等）
• Web 前端：提供用户界面
• PostgreSQL：元数据存储
• Redis：缓存和消息队列
• Weaviate：向量数据库（默认）
• Nginx：反向代理和负载均衡

运行验证

确认服务端口

根据 docker/.env.example:152-156 的配置，API 服务默认绑定到：

检查服务状态

执行以下命令验证服务是否正常运行：

bash
1# 查看所有容器状态
2docker compose ps
3
4# 预期输出：所有服务状态为 "running" 或 "healthy"

访问 Web 界面：

• 默认地址：http://localhost（需要确认：Nginx 默认端口配置未在提供的源文件中明确）
• 首次访问将引导创建管理员账户

API 健康检查（需要确认：健康检查端点未在源文件中明确）：

bash
1curl http://localhost:5001/health
2# 预期输出：需要确认具体响应格式

理解服务运行参数

docker/docker-compose.yaml:42-46 定义了 API 服务的工作进程配置：

生产环境建议根据 CPU 核心数调整 SERVER_WORKER_AMOUNT，参考公式：CPU核心数 × 2 + 1（同步模式）或 1（gevent 模式）。

常见问题与排错

问题 1：端口冲突

症状：启动失败，日志显示端口已被占用。

原因：默认端口（5001、80 等）被其他服务占用。

解决方案：

1. 修改 .env 文件中的 DIFY_PORT 为未被占用的端口
2. 检查 Nginx 配置（需要确认：Nginx 端口配置位置）
3. 重启服务：docker compose down && docker compose up -d

问题 2：数据库连接失败

症状：API 服务日志显示 PostgreSQL 连接错误。

原因：数据库容器未完全启动，或连接配置错误。

解决方案：

1. 检查数据库容器状态：docker compose ps db_postgres
2. 查看数据库日志：docker compose logs db_postgres
3. 验证连接配置（docker/docker-compose.yaml:59-64）：
   • DB_HOST: 默认 db_postgres
   • DB_PORT: 默认 5432
   • DB_USERNAME: 默认 postgres
   • DB_PASSWORD: 默认 difyai123456
   • DB_DATABASE: 默认 dify

问题 3：向量数据库初始化失败

症状：创建知识库或导入文档时报错。

原因：Weaviate 服务未正常启动或配置错误。

解决方案：

1. 检查 Weaviate 容器：docker compose ps weaviate
2. 验证配置（docker/docker-compose.yaml:178-183）：
   • VECTOR_STORE: 默认 weaviate
   • WEAVIATE_ENDPOINT: 默认 http://weaviate:8080
   • WEAVIATE_API_KEY: 默认内置值
3. 查看 Weaviate 日志：docker compose logs weaviate

问题 4：配置修改后未生效

症状：修改 .env 文件后，服务行为未改变。

原因：Docker Compose 缓存了旧的环境变量。

解决方案：

bash
1# 完全重建服务
2docker compose down
3docker compose up -d --build

问题 5：日志查看与调试

启用调试日志（docker/.env.example:72-99）：

修改 .env 文件：

bash
1LOG_LEVEL=DEBUG
2DEBUG=true
3FLASK_DEBUG=true
4ENABLE_REQUEST_LOGGING=True

重启服务后查看日志：

bash
1docker compose logs -f api

下一步建议

完成快速上手后，建议按以下顺序深入学习：

1. 配置模型提供商：在控制台设置页面配置 OpenAI、Anthropic 等 LLM API 密钥
2. 创建第一个应用：通过可视化编排器创建聊天助手或工作流
3. 知识库管理：上传文档并创建向量索引
4. API 集成：使用 Service API 将 AI 能力集成到现有系统

详细使用指南请参考"使用指南"章节，高级配置（如切换向量数据库、配置对象存储、集群部署）请参考"配置参考"章节。