02-Dify平台部署与环境配置
第二章：Dify 平台部署与环境配置
2.1 部署概述
2.1.1 部署方式选择
Dify 提供了多种部署方式以适应不同的使用场景和需求：
| 部署方式 | 适用场景 | 优势 | 劣势 |
|---|---|---|---|
| Dify 云服务 | 快速体验、小规模使用 | 零运维、即开即用 | 数据在云端、功能受限 |
| Docker Compose | 开发测试、中小规模生产 | 部署简单、资源可控 | 需要 Docker 基础 |
| 本地源码 | 二次开发、深度定制 | 完全可控、便于调试 | 环境配置复杂 |
| 云服务商部署 | 企业级生产环境 | 高可用、易扩展 | 成本较高 |
| 宝塔面板 | 国内服务器管理 | 可视化管理 | 功能受限 |
2.1.2 系统要求
无论选择哪种部署方式，都需要满足以下基本系统要求：
最低配置（开发/测试）：
- CPU：2 核心
- 内存：4 GB
- 存储：20 GB SSD
- 操作系统：Linux（推荐 Ubuntu 22.04）、macOS、Windows（WSL2）
推荐配置（生产环境）：
- CPU：4 核心以上
- 内存：8 GB 以上
- 存储：50 GB SSD 以上
- 操作系统：Ubuntu 22.04 LTS
网络要求：
- 能够访问 Docker Hub（或配置镜像加速）
- 能够访问模型 API（如 OpenAI、Anthropic 等）
- 开放必要的端口（默认 80/443）
2.2 Docker Compose 部署（推荐）
2.2.1 前置准备
Docker Compose 是最推荐的部署方式，它将所有服务打包在一起，一键启动。
安装 Docker：
对于 Ubuntu 系统：
# 更新包索引
sudo apt-get update
# 安装必要的包
sudo apt-get install ca-certificates curl gnupg lsb-release
# 添加 Docker 官方 GPG 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
# 设置仓库
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装 Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin
# 验证安装
docker --version
docker compose version
对于 macOS：
# 使用 Homebrew 安装
brew install --cask docker
# 启动 Docker Desktop 应用
# 验证安装
docker --version
对于 Windows：
- 安装 WSL2（Windows Subsystem for Linux）
- 下载并安装 Docker Desktop
- 在设置中启用 WSL2 后端
2.2.2 克隆项目
# 克隆 Dify 仓库
git clone https://github.com/langgenius/dify.git
# 进入 docker 目录
cd dify/docker
如果网络访问 GitHub 较慢，可以使用镜像：
git clone https://gitee.com/mirrors/dify.git
cd dify/docker
2.2.3 配置环境变量
# 复制环境变量示例文件
cp .env.example .env
# 编辑环境变量（可选，使用默认值也可启动）
nano .env
重要的环境变量说明：
# 应用密钥（生产环境必须修改，请生成随机字符串替换）
SECRET_KEY=your-secret-key-replace-with-random-string
# 数据库配置
DB_USERNAME=postgres
DB_PASSWORD=difyai123456
DB_HOST=db
DB_PORT=5432
DB_DATABASE=dify
# Redis 配置
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=difyai123456
# 向量数据库（默认使用 Weaviate）
VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://weaviate:8080
# 存储配置
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=storage
# 日志级别
LOG_LEVEL=INFO
2.2.4 启动服务
# 启动所有服务（后台运行）
docker compose up -d
# 查看服务状态
docker compose ps
# 查看日志
docker compose logs -f
首次启动时，Docker 会拉取所需的镜像，可能需要几分钟时间。
2.2.5 访问 Dify
服务启动成功后：
- 打开浏览器访问
http://localhost（或服务器 IP） - 首次访问会进入初始化设置页面
- 设置管理员邮箱和密码
- 完成初始化后即可开始使用
2.2.6 常用运维命令
# 停止服务
docker compose stop
# 重启服务
docker compose restart
# 停止并删除容器
docker compose down
# 停止并删除容器和数据卷（谨慎使用）
docker compose down -v
# 更新到最新版本
git pull origin main
docker compose down
docker compose pull
docker compose up -d
# 查看资源使用情况
docker stats
2.3 本地源码部署
2.3.1 适用场景
本地源码部署适合以下场景：
- 需要对 Dify 进行二次开发
- 需要调试和分析源码
- 需要更细粒度的配置控制
- 开发环境搭建
2.3.2 环境准备
后端环境：
- Python 3.10+
- Poetry（Python 包管理器）
- PostgreSQL 15+
- Redis 6+
前端环境：
- Node.js 18+
- pnpm 包管理器
2.3.3 后端部署
安装 Python 依赖：
# 克隆仓库
git clone https://github.com/langgenius/dify.git
cd dify
# 进入 api 目录
cd api
# 安装 Poetry
pip install poetry
# 安装依赖
poetry install
# 如果安装过程中遇到问题，可以尝试：
poetry install --no-root
配置数据库：
# 创建 PostgreSQL 数据库
sudo -u postgres psql
CREATE DATABASE dify;
CREATE USER dify WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE dify TO dify;
\q
配置环境变量：
# 复制配置文件
cp .env.example .env
# 编辑配置
nano .env
关键配置项：
# Flask 配置
FLASK_DEBUG=true
FLASK_ENV=development
# 数据库
DB_USERNAME=dify
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=dify
# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
# 密钥
SECRET_KEY=your_secret_key
初始化数据库：
# 运行数据库迁移
poetry run flask db upgrade
启动后端服务：
# 启动 API 服务
poetry run flask run --host=0.0.0.0 --port=5001
# 在另一个终端启动 Worker
poetry run celery -A app.celery worker -l INFO
2.3.4 前端部署
# 进入 web 目录
cd ../web
# 安装 pnpm（如果未安装）
npm install -g pnpm
# 安装依赖
pnpm install
# 配置环境变量
cp .env.example .env.local
nano .env.local
前端环境变量：
# API 地址
NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api
NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api
启动前端开发服务器：
pnpm dev
访问 http://localhost:3000 即可看到 Dify 界面。
2.4 云服务部署选项
2.4.1 Zeabur 部署
Zeabur 是一个现代化的云平台，支持一键部署 Dify。
部署步骤：
- 注册 Zeabur 账号：https://zeabur.com
- 点击 Dify 模板进行部署
- 等待部署完成
- 获取访问地址
优势：
- 一键部署，无需配置
- 自动扩缩容
- 支持自定义域名
- 提供免费额度
2.4.2 阿里云部署
使用阿里云容器服务：
- 创建 Kubernetes 集群
- 配置 kubectl 连接
- 部署 Dify Helm Chart：
# 添加 Helm 仓库
helm repo add dify https://langgenius.github.io/dify-helm
# 安装 Dify
helm install dify dify/dify \
--set ingress.enabled=true \
--set ingress.hostname=your-domain.com
2.4.3 AWS 部署
使用 AWS ECS：
- 创建 ECS 集群
- 配置任务定义
- 设置服务和负载均衡
- 配置 RDS（PostgreSQL）和 ElastiCache（Redis）
使用 AWS EKS：
- 创建 EKS 集群
- 配置 kubectl
- 使用 Helm 部署
2.5 环境变量详解
2.5.1 应用配置
# 基础配置
SECRET_KEY=your-secret-key # 加密密钥，必须修改
CONSOLE_WEB_URL=http://localhost # 控制台地址
SERVICE_API_URL=http://localhost # API 服务地址
# 调试模式
DEBUG=false # 生产环境设为 false
LOG_LEVEL=INFO # 日志级别：DEBUG, INFO, WARNING, ERROR
2.5.2 数据库配置
# PostgreSQL
DB_USERNAME=postgres
DB_PASSWORD=difyai123456
DB_HOST=db
DB_PORT=5432
DB_DATABASE=dify
# 连接池配置
SQLALCHEMY_POOL_SIZE=30
SQLALCHEMY_POOL_RECYCLE=3600
SQLALCHEMY_ECHO=false
2.5.3 Redis 配置
# Redis 连接
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=difyai123456
REDIS_DB=0
# 使用 Sentinel（高可用）
REDIS_USE_SENTINEL=false
REDIS_SENTINEL_MASTER_NAME=mymaster
REDIS_SENTINEL_NODES=sentinel1:26379,sentinel2:26379
2.5.4 向量数据库配置
Dify 支持多种向量数据库，通过 VECTOR_STORE 变量选择：
Weaviate（默认）：
VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://weaviate:8080
WEAVIATE_API_KEY=WVF5YThaHlkYwhGUSmCRgsX3tD5ngdN8pkih
Qdrant：
VECTOR_STORE=qdrant
QDRANT_URL=http://qdrant:6333
QDRANT_API_KEY=your-api-key
Milvus：
VECTOR_STORE=milvus
MILVUS_HOST=milvus
MILVUS_PORT=19530
MILVUS_USER=root
MILVUS_PASSWORD=Milvus
Chroma：
VECTOR_STORE=chroma
CHROMA_HOST=chroma
CHROMA_PORT=8000
2.5.5 存储配置
本地存储：
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=storage
Amazon S3：
STORAGE_TYPE=s3
S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET_NAME=dify-storage
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=us-east-1
阿里云 OSS：
STORAGE_TYPE=aliyun-oss
ALIYUN_OSS_BUCKET_NAME=dify-storage
ALIYUN_OSS_ACCESS_KEY=your-access-key
ALIYUN_OSS_SECRET_KEY=your-secret-key
ALIYUN_OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
2.5.6 邮件配置
MAIL_TYPE=smtp
MAIL_DEFAULT_SEND_FROM=noreply@your-domain.com
SMTP_SERVER=smtp.your-domain.com
SMTP_PORT=587
SMTP_USERNAME=your-username
SMTP_PASSWORD=your-password
SMTP_USE_TLS=true
2.6 高可用部署
2.6.1 架构设计
生产环境的高可用架构通常包括：
┌─────────────┐
│ 负载均衡 │
│ (Nginx/ALB) │
└──────┬──────┘
│
┌────────────────┼────────────────┐
│ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ Web 1 │ │ Web 2 │ │ Web 3 │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
└────────────────┼────────────────┘
│
┌────────────────┼────────────────┐
│ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ API 1 │ │ API 2 │ │ API 3 │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
└────────────────┼────────────────┘
│
┌──────────────────────┼──────────────────────┐
│ │ │
┌───▼───┐ ┌─────▼─────┐ ┌─────▼─────┐
│ Redis │ │PostgreSQL │ │ 向量数据库 │
│ Cluster│ │ 主从复制 │ │ 集群 │
└───────┘ └───────────┘ └───────────┘
2.6.2 负载均衡配置
使用 Nginx 作为反向代理和负载均衡：
upstream dify_web {
least_conn;
server web1:3000 weight=1;
server web2:3000 weight=1;
server web3:3000 weight=1;
}
upstream dify_api {
least_conn;
server api1:5001 weight=1;
server api2:5001 weight=1;
server api3:5001 weight=1;
}
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://dify_web;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location /api {
proxy_pass http://dify_api;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
2.6.3 数据库高可用
PostgreSQL 主从复制配置：
主节点（postgresql.conf）：
wal_level = replica
max_wal_senders = 10
wal_keep_size = 64MB
从节点恢复配置（recovery.conf）：
standby_mode = 'on'
primary_conninfo = 'host=master_ip port=5432 user=replication password=xxx'
2.6.4 Redis 集群配置
# 使用 Redis Sentinel
REDIS_USE_SENTINEL=true
REDIS_SENTINEL_MASTER_NAME=mymaster
REDIS_SENTINEL_NODES=sentinel1:26379,sentinel2:26379,sentinel3:26379
REDIS_SENTINEL_PASSWORD=your-password
2.7 常见问题排查
2.7.1 服务启动失败
问题：Docker 容器无法启动
排查步骤：
# 查看容器状态
docker compose ps
# 查看容器日志
docker compose logs <service_name>
# 常见原因：
# 1. 端口冲突 - 检查端口占用
lsof -i :80
# 2. 内存不足 - 检查系统资源
free -h
# 3. 配置错误 - 检查 .env 文件
2.7.2 数据库连接问题
问题：无法连接到数据库
解决方案：
# 检查数据库服务状态
docker compose logs db
# 测试数据库连接
docker compose exec db psql -U postgres -d dify
# 检查连接配置
# 确认 .env 中的数据库配置正确
2.7.3 向量数据库问题
问题：知识库功能异常
排查步骤：
# 检查向量数据库服务
docker compose logs weaviate
# 测试向量数据库连接
curl http://localhost:8080/v1/.well-known/ready
# 如果使用外部向量数据库，检查网络连通性
2.7.4 模型调用失败
问题：调用模型 API 失败
常见原因：
- API Key 无效或过期
- 网络无法访问模型服务
- 超出速率限制或配额
解决方案：
# 检查网络连通性
curl https://api.openai.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
# 如果在中国大陆，可能需要配置代理
HTTP_PROXY=http://proxy:port
HTTPS_PROXY=http://proxy:port
2.7.5 性能问题
问题：系统响应缓慢
优化建议：
# 1. 增加 Worker 数量
CELERY_WORKER_CONCURRENCY=8
# 2. 优化数据库连接池
SQLALCHEMY_POOL_SIZE=50
# 3. 配置 Redis 缓存
# 确保 Redis 性能正常
# 4. 检查资源使用
docker stats
2.8 安全配置
2.8.1 基础安全
# 1. 修改默认密钥
SECRET_KEY=your-strong-secret-key
# 2. 禁用调试模式
DEBUG=false
# 3. 配置 HTTPS
# 使用 Nginx 配置 SSL 证书
2.8.2 网络安全
# 1. 限制数据库访问
# 只允许应用服务器连接
# 2. 配置防火墙规则
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
# 3. 使用内网通信
# 将数据库和 Redis 放在内网
2.8.3 数据安全
# 1. 定期备份数据库
docker compose exec db pg_dump -U postgres dify > backup.sql
# 2. 加密敏感配置
# 使用环境变量或密钥管理服务
# 3. 日志脱敏
# 确保日志中不包含敏感信息
2.9 本章小结
通过本章的学习，你应该掌握：
- 部署方式选择：根据场景选择合适的部署方式
- Docker Compose 部署：最简单的部署方式，适合大多数场景
- 源码部署：适合二次开发和深度定制
- 环境变量配置：理解各类配置项的作用
- 高可用架构：生产环境的架构设计
- 问题排查：常见问题的解决方法
2.10 思考与练习
-
实践练习：
- 使用 Docker Compose 部署一个完整的 Dify 实例
- 修改环境变量，配置你自己的密钥
- 尝试连接不同的向量数据库
-
思考题：
- 在生产环境中，如何设计 Dify 的高可用架构？
- 如何监控 Dify 服务的运行状态？
-
扩展学习：
- 了解 Kubernetes 部署方案
- 学习 Docker 网络和存储配置
下一章预告：第三章将介绍应用构建基础，包括各种应用类型的创建和配置方法。
浙公网安备 33010602011771号