耿雨飞的个人博客

[[ slide_text ]]

[[ item.c ]]

Dify 系列教程 | 第 2 篇：10 分钟搞定！Dify 本地部署完全指南

发布时间：2026-04-08 作者：gengyufei 来源：gengyufei个人博客

dify 教程

> **Dify 系列教程** | 模块一：认识 Dify -- 从零开始 | 第 2 篇 / 共 30 篇
>
> **适合读者**：所有技术水平
>
> **学习目标**：掌握 Docker Compose 一键部署 Dify 的方法；理解 Dify 的服务架构组成；完成初始化配置和管理员账户创建

---

## 开篇：部署 Dify 究竟有多简单？

上一篇我们全面了解了 Dify 平台的核心能力。相信你已经跃跃欲试了 -- 但在动手创建 AI 应用之前，我们需要先把 Dify 跑起来。

很多开源项目的部署过程让人头疼：依赖冲突、环境配置、版本不兼容......但 Dify 在部署体验上做得非常出色。借助 Docker Compose，整个过程只需要 **4 条命令**，真正做到"10 分钟部署完成"。

本篇教程将在 **Linux 服务器**上完成 Dify 的本地部署，带你从零跑通整个流程。

---

## 一、部署前的准备

### 1.1 系统最低要求

| 资源     | 最低配置                                      | 推荐配置                             |
| -------- | --------------------------------------------- | ------------------------------------ |
| CPU      | 2 核                                          | 4 核及以上                           |
| 内存     | 4 GB                                          | 8 GB 及以上                          |
| 磁盘     | 20 GB                                         | 50 GB 及以上（含模型缓存和文档存储） |
| 操作系统 | Linux（Ubuntu 20.04+、CentOS 7+、Debian 11+） | Ubuntu 22.04 LTS                     |

### 1.2 安装 Docker 和 Docker Compose

Dify 依赖 Docker 运行所有服务。如果你的服务器尚未安装 Docker，按以下步骤操作：

**安装 Docker Engine**：

```bash
# 更新包索引
sudo apt-get update

# 安装必要依赖
sudo apt-get install -y ca-certificates curl gnupg

# 添加 Docker 官方 GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 添加 Docker 仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
```

**验证安装**：

```bash
docker --version
# Docker version 27.x.x

docker compose version
# Docker Compose version v2.x.x
```

> **提示**：如果需要非 root 用户运行 Docker，执行 `sudo usermod -aG docker $USER` 后重新登录。

---

## 二、理解 Dify 的服务架构

在部署之前，先了解 Dify 由哪些服务组成，这有助于后续的配置调优和问题排查。

### 2.1 整体架构图

```
                     用户浏览器
                        │
                        ▼
              ┌──────────────────┐
              │   Nginx (:80)    │  反向代理 + 静态资源
              └───┬──────────┬───┘
                  │          │
          ┌───────▼──┐  ┌────▼───────┐
          │ Web      │  │ API        │
          │ Next.js  │  │ Flask      │
          │ (:3000)  │  │ (:5001)    │
          └──────────┘  └──┬─────┬───┘
                           │     │
                    ┌──────▼┐  ┌─▼──────────┐
                    │Worker │  │Worker Beat  │
                    │Celery │  │定时任务调度   │
                    └───┬───┘  └─────────────┘
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
   ┌────────────┐ ┌──────────┐ ┌──────────────┐
   │ PostgreSQL │ │  Redis   │ │  Weaviate    │
   │ 主数据库    │ │ 缓存+队列 │ │ 向量数据库   │
   └────────────┘ └──────────┘ └──────────────┘

┌─────────────┐  ┌──────────────────┐
      │  Sandbox     │  │  Plugin Daemon   │
      │ 代码执行沙箱  │  │  插件运行时       │
      └─────────────┘  └──────────────────┘
              │
        ┌─────▼──────┐
        │ SSRF Proxy │
        │ 安全代理    │
        └────────────┘
```

### 2.2 核心服务说明

以下是 `docker-compose.yaml` 中定义的核心服务，每个服务都是一个独立的 Docker 容器：

| 服务名            | 镜像                                        | 端口    | 作用                                                    |
| ----------------- | ------------------------------------------- | ------- | ------------------------------------------------------- |
| **nginx**         | `nginx:latest`                              | 80, 443 | 反向代理，统一入口，将请求分发到 API 和 Web 服务        |
| **api**           | `langgenius/dify-api:1.13.3`                | 5001    | Flask 后端 API 服务，处理所有业务逻辑                   |
| **worker**        | `langgenius/dify-api:1.13.3`                | -       | Celery 异步工作进程，处理文档索引、工作流执行等后台任务 |
| **worker_beat**   | `langgenius/dify-api:1.13.3`                | -       | Celery Beat 定时任务调度器，负责周期性任务              |
| **web**           | `langgenius/dify-web:1.13.3`                | 3000    | Next.js 前端应用，提供控制台界面                        |
| **db_postgres**   | `postgres:15-alpine`                        | 5432    | PostgreSQL 主数据库，存储用户、应用、工作流等业务数据   |
| **redis**         | `redis:6-alpine`                            | 6379    | Redis 缓存服务 + Celery 消息队列                        |
| **weaviate**      | `semitechnologies/weaviate:1.27.0`          | 8080    | 默认向量数据库，存储知识库的文档向量                    |
| **sandbox**       | `langgenius/dify-sandbox:0.2.14`            | 8194    | 代码执行沙箱，安全隔离运行用户代码                      |
| **plugin_daemon** | `langgenius/dify-plugin-daemon:0.5.3-local` | 5002    | 插件运行时守护进程                                      |
| **ssrf_proxy**    | `ubuntu/squid:latest`                       | 3128    | SSRF 防护代理，防止服务端请求伪造攻击                   |

> **关键点**：`api` 和 `worker` 使用的是**同一个镜像**（`dify-api`），通过环境变量 `MODE` 区分启动模式。`MODE=api` 启动 API 服务，`MODE=worker` 启动 Celery Worker，`MODE=beat` 启动定时调度器。

### 2.3 网络隔离

Dify 定义了两个 Docker 网络来实现安全隔离：

- **default**：所有服务间的常规通信网络
- **ssrf_proxy_network**（internal: true）：仅 `api`、`worker` 和 `ssrf_proxy` 之间的隔离网络，外部请求必须通过 SSRF 代理，防止恶意请求

---

## 三、一键部署：4 条命令搞定

### 3.1 克隆项目

```bash
git clone https://github.com/langgenius/dify.git
cd dify
```

> 如果你不使用 Git，也可以直接在 GitHub Releases 页面下载对应版本的压缩包。

### 3.2 进入 Docker 目录并创建环境配置

```bash
cd docker
cp .env.example .env
```

这一步从模板文件复制出实际的环境配置文件。`.env` 文件包含了 Dify 运行所需的全部配置项（700+ 行），大多数配置使用默认值即可正常运行。

### 3.3 启动全部服务

```bash
docker compose up -d
```

Docker 会自动拉取所有镜像并启动服务。首次拉取镜像可能需要几分钟，取决于你的网络速度。

> **国内用户加速提示**：如果镜像拉取速度慢，可以配置 Docker 镜像加速器。编辑 `/etc/docker/daemon.json`，添加国内镜像源后重启 Docker 服务。

### 3.4 验证服务状态

```bash
docker compose ps
```

正常情况下，你应该看到所有核心服务的状态为 `running` 或 `healthy`：

```
NAME                 STATUS
dify-api-1           Up (healthy)
dify-worker-1        Up
dify-worker_beat-1   Up
dify-web-1           Up
dify-db_postgres-1   Up (healthy)
dify-redis-1         Up (healthy)
dify-weaviate-1      Up
dify-nginx-1         Up
dify-sandbox-1       Up (healthy)
dify-plugin_daemon-1 Up
dify-ssrf_proxy-1    Up
```

### 3.5 访问 Dify 控制台

打开浏览器，访问 `http://localhost`（或者你的服务器 IP 地址），你将看到 Dify 的初始化设置页面。

**初始化步骤**：

1. 设置管理员邮箱和密码
2. 填写你的名称
3. 点击"设置"完成初始化

> **提示**：你也可以通过 `.env` 中的 `INIT_PASSWORD` 预设管理员密码，密码长度不超过 30 个字符。

完成后即可登录 Dify 控制台，开始创建你的第一个 AI 应用。

---

## 四、关键环境变量配置详解

`.env` 文件中有数百个配置项，绝大多数使用默认值即可。以下是**最需要关注的配置项**：

### 4.1 安全相关（生产环境必改）

```bash
# 加密密钥 —— 用于签名 Session Cookie 和加密数据库中的敏感信息
# 务必替换为你自己生成的强密钥！
# 生成方法: openssl rand -base64 42
SECRET_KEY=sk-9f73s3ljTXVcMT3Blb3ljTqtsKiGHXVcMT3BlbkFJLK7U

# 管理员初始密码（可选，不设则在界面上手动创建）
INIT_PASSWORD=

# 数据库密码
DB_PASSWORD=difyai123456

# Redis 密码
REDIS_PASSWORD=difyai123456
```

**重要**：在生产环境中，`SECRET_KEY`、`DB_PASSWORD`、`REDIS_PASSWORD` 必须替换为强随机字符串，不要使用默认值。

### 4.2 数据库配置

```bash
# 数据库类型：postgresql（默认） 或 mysql
DB_TYPE=postgresql
DB_USERNAME=postgres
DB_PASSWORD=difyai123456
DB_HOST=db_postgres
DB_PORT=5432
DB_DATABASE=dify

# 连接池大小（默认 30，高并发可适当增大）
SQLALCHEMY_POOL_SIZE=30
SQLALCHEMY_MAX_OVERFLOW=10
```

### 4.3 Redis 配置

```bash
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=difyai123456
REDIS_DB=0

# Celery 消息队列使用 Redis 的 DB 1
CELERY_BROKER_URL=redis://:difyai123456@redis:6379/1
```

### 4.4 向量数据库配置

```bash
# 向量数据库类型，默认 weaviate
# 可选值：weaviate、qdrant、milvus、pgvector、opensearch 等 30+ 种
VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://weaviate:8080
WEAVIATE_API_KEY=WVF5YThaHlkYwhGUSmCRgsX3tD5ngdN8pkih
```

### 4.5 文件存储配置

```bash
# 存储类型，默认使用 OpenDAL 本地文件系统
STORAGE_TYPE=opendal
OPENDAL_SCHEME=fs
OPENDAL_FS_ROOT=storage

# 也可以切换为 S3、Azure Blob、阿里云 OSS 等
# 示例：使用 S3
# S3_ENDPOINT=https://s3.amazonaws.com
# S3_REGION=us-east-1
# S3_BUCKET_NAME=difyai
# S3_ACCESS_KEY=your-access-key
# S3_SECRET_KEY=your-secret-key
```

### 4.6 Nginx 与端口配置

```bash
# Nginx 对外暴露端口（默认 80）
EXPOSE_NGINX_PORT=80
EXPOSE_NGINX_SSL_PORT=443

# 是否开启 HTTPS
NGINX_HTTPS_ENABLED=false

# 上传文件大小限制（默认 100MB）
NGINX_CLIENT_MAX_BODY_SIZE=100M

# 代理超时时间（默认 3600 秒，支持长连接 SSE 流式响应）
NGINX_PROXY_READ_TIMEOUT=3600s
```

### 4.7 Worker 配置

```bash
# Celery Worker 数量（默认 4，根据 CPU 核心数调整）
CELERY_WORKER_AMOUNT=4

# API 服务 Gunicorn 超时（默认 360 秒）
GUNICORN_TIMEOUT=360

# 是否启用 Worker 自动伸缩
CELERY_AUTO_SCALE=false
```

---

## 五、服务健康检查与问题排查

### 5.1 内置健康检查机制

Dify 为核心服务配置了健康检查（healthcheck），Docker 会定期探测服务状态：

| 服务        | 检查方式                               | 间隔 | 超时 | 重试  |
| ----------- | -------------------------------------- | ---- | ---- | ----- |
| api         | `curl -f http://localhost:5001/health` | 30s  | 5s   | 3 次  |
| worker      | `celery inspect ping`                  | 30s  | 30s  | 3 次  |
| db_postgres | `pg_isready`                           | 1s   | 3s   | 60 次 |
| redis       | `redis-cli ping`                       | 默认 | 默认 | 默认  |
| sandbox     | `curl -f http://localhost:8194/health` | 默认 | 默认 | 默认  |

查看各服务健康状态：

```bash
docker compose ps
```

### 5.2 查看服务日志

```bash
# 查看所有服务日志
docker compose logs

# 查看特定服务日志（实时跟踪）
docker compose logs -f api

# 查看最近 100 行日志
docker compose logs --tail 100 api
```

### 5.3 常见问题排查

**问题 1：端口冲突**

```
Error: bind: address already in use
```

解决方法：修改 `.env` 中的端口映射：

```bash
# 将 Nginx 端口改为 8080
EXPOSE_NGINX_PORT=8080
```

**问题 2：数据库连接失败**

```bash
# 检查 PostgreSQL 容器状态
docker compose logs db_postgres

# 进入容器验证连接
docker compose exec db_postgres pg_isready -U postgres -d dify
```

**问题 3：API 服务持续重启**

```bash
# 查看 API 容器详细日志
docker compose logs --tail 200 api

# 常见原因：
# 1. SECRET_KEY 格式不正确
# 2. 数据库未就绪（依赖启动顺序问题）
# 3. Redis 连接失败
```

**问题 4：页面可以访问但功能异常**

```bash
# 检查 Worker 服务是否正常运行
docker compose logs worker

# 检查 Plugin Daemon 是否正常
docker compose logs plugin_daemon
```

**问题 5：镜像拉取超时**

```bash
# 单独拉取超时的镜像
docker pull langgenius/dify-api:1.13.3

# 或使用代理
export HTTPS_PROXY=http://your-proxy:port
docker compose pull
```

---

## 六、升级与数据备份策略

### 6.1 数据持久化目录

Dify 的所有持久化数据都存储在 `docker/volumes/` 目录下：

```
docker/volumes/
├── app/storage/        # 用户上传的文件、知识库文档
├── db/data/            # PostgreSQL 数据库数据
├── redis/data/         # Redis 持久化数据
├── weaviate/           # 向量数据库数据
├── sandbox/            # 沙箱配置和依赖
└── certbot/            # SSL 证书（如启用）
```

### 6.2 数据备份

在升级前或定期执行数据备份：

```bash
# 停止服务（确保数据一致性）
docker compose stop

# 备份整个 volumes 目录
tar -czf dify-backup-$(date +%Y%m%d).tar.gz volumes/

# 单独备份数据库（不停服务也可执行）
docker compose exec db_postgres pg_dump -U postgres dify > dify-db-backup-$(date +%Y%m%d).sql

# 重新启动服务
docker compose start
```

### 6.3 版本升级流程

Dify 提供了环境变量同步工具 `dify-env-sync.sh`，简化升级流程：

```bash
# 1. 停止当前服务
docker compose down

# 2. 备份当前环境配置
cp .env .env.backup

# 3. 拉取最新代码
cd .. && git pull origin main && cd docker

# 4. 同步环境变量（自动保留已有配置，添加新增变量）
bash dify-env-sync.sh

# 5. 拉取新版镜像
docker compose pull

# 6. 启动新版本
docker compose up -d

# 7. 验证服务状态
docker compose ps
```

`dify-env-sync.sh` 脚本会：

- 自动创建 `.env` 的时间戳备份
- 将 `.env.example` 中新增的变量添加到你的 `.env`
- 保留你已修改的配置值
- 提示已移除的变量

### 6.4 回滚方案

如果升级后出现问题：

```bash
# 停止服务
docker compose down

# 恢复环境配置
cp .env.backup .env

# 恢复数据（如有需要）
tar -xzf dify-backup-YYYYMMDD.tar.gz

# 使用旧版镜像启动
docker compose up -d
```

---

## 七、实践环节：完整部署演练

现在，让我们从头到尾完整走一遍部署流程。

### Step 1：准备服务器

确认 Docker 已安装并正常运行：

```bash
docker --version && docker compose version
```

### Step 2：克隆并配置

```bash
git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
```

### Step 3：（推荐）修改安全配置

```bash
# 生成强密钥
openssl rand -base64 42
# 输出类似：aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW3xY5zA7bC9dE5fG7hI9jK1lM3n

# 编辑 .env 文件，替换以下值：
# SECRET_KEY=<上面生成的密钥>
# DB_PASSWORD=<你的强密码>
# REDIS_PASSWORD=<你的强密码>
# 注意：REDIS_PASSWORD 修改后，还需同步修改 CELERY_BROKER_URL 中的密码部分
```

### Step 4：启动服务

```bash
docker compose up -d
```

观察启动过程（首次需拉取镜像）：

```bash
docker compose logs -f
# 按 Ctrl+C 退出日志跟踪
```

### Step 5：检查服务状态

```bash
docker compose ps
```

等待所有服务状态显示为 `Up` 或 `healthy`。API 服务通常需要 30-60 秒完成初始化（包括数据库迁移）。

### Step 6：访问并初始化

1. 打开浏览器访问 `http://<你的服务器IP>`
2. 在初始化页面设置管理员邮箱和密码
3. 登录进入 Dify 控制台
4. 你应该能看到一个干净的工作区，准备好创建应用

### 验证清单

完成部署后，逐项确认：

- [ ] 能够正常访问 `http://<服务器IP>` 并看到 Dify 界面
- [ ] 能够注册管理员账号并登录
- [ ] 控制台页面加载正常，无报错
- [ ] 点击「创建应用」能看到应用类型选择界面

---

## 小结

本篇教程我们完成了 Dify 的本地部署全流程：

- **服务架构**：Dify 由 11 个 Docker 容器协同工作，核心是 Nginx + Flask API + Next.js Web + PostgreSQL + Redis + Weaviate 的组合
- **部署流程**：只需 `git clone` -> `cp .env.example .env` -> `docker compose up -d`，4 条命令即可完成
- **关键配置**：生产环境必须修改 `SECRET_KEY`、数据库密码和 Redis 密码
- **运维要点**：了解健康检查机制、日志查看方法和常见问题排查
- **升级策略**：使用 `dify-env-sync.sh` 工具安全升级，升级前务必备份 `volumes/` 目录

**下一篇预告**：Dify 已经跑起来了，但还不能用 -- 因为我们还没有配置 AI 模型。下一篇《配置你的第一个 AI 模型供应商》将带你对接 OpenAI、DeepSeek、Ollama 等模型供应商，让 Dify 真正拥有"智能"。

---

**你在部署过程中遇到了什么问题？或者你的服务器环境有什么特殊情况需要处理？欢迎在评论区留言，我们一起解决！**

---

> 本文基于 Dify v1.13.3 源码编写，所有配置项均来自实际的 `docker-compose.yaml` 和 `.env.example` 文件。如有更新请以官方文档为准。

上一篇：Dify 系列教程 | 第 1 篇：Dify 是什么？一文读懂开源 LLM 应用开发平台下一篇：Dify 系列教程 | 第 3 篇：配置你的第一个 AI 模型供应商

你觉得文章怎么样