Dify-6: 部署

部署

本文档提供了在不同环境中部署 Dify 的完整指南，涵盖推荐的部署方法、系统要求、配置选项和部署后步骤，聚焦整体部署架构和流程。

部署架构

在深入部署步骤前，先了解 Dify 部署的整体架构。

部署架构图

Dify 部署架构  
├─ 数据存储  
│  ├─ PostgreSQL（端口 5432）  
│  ├─ Redis（端口 6379）  
│  ├─ 向量数据库（Weaviate、Qdrant 等）  
│  └─ 文件存储（S3、本地存储等）  
├─ 核心服务  
│  ├─ API 服务（Flask/Gunicorn，端口 5001）  
│  ├─ Web 前端（Next.js，端口 3000）  
│  ├─ 工作进程服务（Celery，队列：dataset, generation, mail, ops_trace, app_deletion）  
│  ├─ 插件守护进程（端口 5002）  
│  ├─ 代码执行沙箱（端口 8194）  
│  ├─ SSRF 代理（端口 3128）  
│  └─ Nginx 反向代理（端口 80/443）  
└─ 插件系统  

组件关系图

用户  
└─ Nginx 反向代理  ├─ Web 服务（Next.js）  ├─ API 服务（Flask）  │  ├─ 工作进程（Celery）  │  ├─ 插件守护进程  │  └─ 沙箱（代码执行）  ├─ 数据层  │  ├─ PostgreSQL  │  ├─ Redis  │  ├─ 向量数据库  │  └─ 文件存储  

系统要求

Dify 由多个服务组成，系统要求取决于预期使用场景。以下是最低推荐配置：

组件	最低配置
CPU	4 核
内存	8 GB
存储	20 GB（不含数据集存储）
操作系统	Linux（Ubuntu 20.04+）、macOS 或支持 Docker 的 Windows
Docker	Docker Engine 20.10+ 和 Docker Compose V2
端口	80/443（HTTP/HTTPS）、5001（API）、3000（Web）

对于包含更大数据集或更高并发的生产环境，建议相应扩展资源。

部署方法

Docker Compose 部署（推荐）

Docker Compose 是推荐的部署方式，可编排所有所需服务并处理互联。

前置条件

1. 在服务器安装 Docker 和 Docker Compose V2。
2. 确保端口 80 和 443（用于 HTTP/HTTPS）可用。
3. 克隆 Dify 仓库或获取 Docker Compose 配置。

部署步骤

1. 准备环境配置

   cd docker  
   cp .env.example .env  
   

   编辑 .env 文件，配置关键参数：

   • SECRET_KEY：使用 openssl rand -base64 42 生成强密钥
   • 数据库、Redis 和存储配置
   • 外部 URL（如 CONSOLE_API_URL、CONSOLE_WEB_URL）

2. 启动 Dify 服务

   docker compose up -d  
   

   -d 标志使服务在后台运行。

3. 验证部署

   docker compose ps  
   

   所有服务应显示 “running” 状态。访问 Dify 网页界面：http://你的服务器地址。

手动部署（从源码）

适用于开发或自定义部署，直接从源码运行服务：

API 服务

1. 配置 Python 环境（Python 3.11+）：

   cd api  
   cp .env.example .env  
   pip install uv  
   uv sync  
   

2. 初始化数据库：

   uv run flask db upgrade  
   

3. 启动 API 服务

uv run flask run --host 0.0.0.0 --port=5001  

4.启动worker API服务（另一个终端启动工作进程）：

uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,generation,mail,ops_trace,app_deletion  

Web 服务

1. 配置 Node.js 环境（Node.js 18+）：

   cd web  
   cp .env.example .env.local  
   npm install -g pnpm  
   pnpm install  
   

2. 启动 Web 服务：

   pnpm run dev  
   

配置

Dify 通过环境变量高度可配置，关键配置分类如下：

核心配置

变量名	描述	默认值
SECRET_KEY	安全会话签名密钥	随机生成
CONSOLE_API_URL	控制台 API 后端 URL	http://localhost:5001
CONSOLE_WEB_URL	控制台前端 URL	http://localhost:3000
DEBUG	启用调试模式	false
DEPLOY_ENV	部署环境	PRODUCTION

数据库配置

变量名	描述	默认值
DB_USERNAME	数据库用户名	postgres
DB_PASSWORD	数据库密码	difyai123456
DB_HOST	数据库主机	db
DB_PORT	数据库端口	5432

存储配置

Dify 支持多种文件存储后端：

• 本地文件系统：

  STORAGE_TYPE=opendal, OPENDAL_SCHEME=fs, OPENDAL_FS_ROOT=storage  
  

• AWS S3：

  STORAGE_TYPE=s3, S3_ENDPOINT, S3_BUCKET_NAME, S3_ACCESS_KEY, S3_SECRET_KEY, S3_REGION  
  

向量数据库配置

支持的向量数据库及配置示例：

• Weaviate：

  VECTOR_STORE=weaviate, WEAVIATE_ENDPOINT, WEAVIATE_API_KEY  
  

• Qdrant：

  VECTOR_STORE=qdrant, QDRANT_URL, QDRANT_API_KEY  
  

Docker Compose 架构

Docker Compose 部署包含多个互联服务：

主要服务

服务详情

服务	用途	容器镜像	健康检查
api	运行 Flask 的主 API 服务器	langgenius/dify-api:1.2.0	依赖 db 和 redis
worker	使用 Celery 处理后台任务	langgenius/dify-api:1.2.0	依赖 db 和 redis
web	基于 Next.js 的前端应用	langgenius/dify-web:1.2.0	无（N/A）
db	PostgreSQL 数据库	postgres:15-alpine	pg_isready 命令检测
redis	Redis 缓存	redis:6-alpine	redis-cli ping 命令检测
sandbox	代码执行沙箱	langgenius/dify-sandbox:0.2.11	访问 http://localhost:8194/health 检测
plugin_daemon	插件管理守护进程	langgenius/dify-plugin-daemon:0.0.7-local	依赖 db
ssrf_proxy	SSRF 保护代理	ubuntu/squid:latest	无（N/A）
nginx	为 Web 和 API 服务提供反向代理	nginx:latest	无（N/A）

数据卷和持久化

Docker Compose 定义了多个数据卷以确保数据持久化：

服务	卷路径	用途
api/worker	./volumes/app/storage	用户文件存储
db	./volumes/db/data	PostgreSQL 数据文件
redis	./volumes/redis/data	Redis 数据
plugin_daemon	./volumes/plugin_daemon	插件存储
sandbox	./volumes/sandbox/dependencies, ./volumes/sandbox/conf	沙箱配置
向量数据库	./volumes/[vector-db-name]	向量数据库存储

网络配置

Docker Compose 部署会创建多个网络用于服务间通信：

• 默认网络：大多数服务通过此网络进行通信
• SSRF 代理网络：用于 API 服务、沙箱和 SSRF 代理之间安全通信的专用内部网络

高级部署选项

HTTPS 配置

使用 Certbot（推荐）

1. 在.env中配置域名和邮箱：

   CERTBOT_EMAIL=your_email@example.com
   CERTBOT_DOMAIN=your_domain.com
   NGINX_HTTPS_ENABLED=true
   

2. 启动 Certbot 生成证书：

   docker compose --profile certbot up -d  
   

手动配置 SSL

1. 将证书放在nginx/ssl/

   cp your-cert.crt ./nginx/ssl/dify.crt
   cp your-key.key ./nginx/ssl/dify.key
   

2. 在.env中配置证书文件名：

   NGINX_HTTPS_ENABLED=true  
   NGINX_SSL_CERT_FILENAME=dify.crt  
   NGINX_SSL_CERT_KEY_FILENAME=dify.key  
   

性能调优

• 工作进程扩展（在.env中配置）：

  CELERY_AUTO_SCALE=true  
  CELERY_MAX_WORKERS=8  # 基于 CPU 核心数调整  
  

• 数据库优化：

  POSTGRES_MAX_CONNECTIONS=200
  POSTGRES_SHARED_BUFFERS=2GB
  POSTGRES_WORK_MEM=16MB
  SQLALCHEMY_POOL_SIZE=50
  

• API服务扩展：

  SERVER_WORKER_AMOUNT=4   # Typically (CPU cores × 2) + 1
  SERVER_WORKER_CLASS=gevent
  SERVER_WORKER_CONNECTIONS=1000
  

部署后步骤

1. 访问网页界面：导航至 http://你的服务器地址（HTTPS 配置后为 https://）。
2. 创建管理员账户：首次访问时按提示创建。
3. 配置模型提供商：在管理设置中连接 OpenAI、Anthropic 等大语言模型提供商。
4. 设置向量数据库：若部署时未配置，在后台完成设置。
5. 创建首个应用：通过网页界面创建 AI 应用。

故障排除

常见问题

• 服务无法启动：查看日志

  docker compose logs [服务名]  
  

• 数据库连接问题：检查.env中的数据库凭证，确保db服务运行：

  docker compose ps db  
  

• 向量数据库错误：验证向量数据库配置和连接性：

  # Example for testing Weaviate connection
  curl http://localhost:8080/v1/.well-known/ready
  

• 文件存储问题：检查存储配置和权限：

  # For local storage
  ls -la ./volumes/app/storage
  

• 重置加密密钥：

  docker compose exec api flask reset-encrypt-key-pair  
  

升级流程

1. 备份数据：备份数据库、向量数据库和文件存储。

2. 拉取最新代码 / 镜像：

   git pull  # 源码部署  
   docker compose pull  # Docker 部署  
   

3. 运行数据库迁移：

   docker compose exec api flask db upgrade  
   

4. 重启服务：

   docker compose down  
   docker compose up -d  
   

5. 验证升级：在 web 界面设置中检查系统版本。