1. 项目概述Dify作为一款新兴的大模型应用开发平台正在技术社区快速走红。它让开发者能够像搭积木一样快速构建基于大语言模型的智能应用而无需从零开始处理复杂的模型部署和API对接。最近我在Windows和Linux双环境下完整走通了Dify的部署流程过程中踩过的坑、验证过的方案都值得记录下来分享。对于需要同时支持Windows开发环境和Linux生产环境的团队来说跨平台部署能力尤为重要。Dify官方虽然提供了Docker这一理论上跨平台的部署方式但在不同操作系统下的具体表现差异很大。比如Windows下的Hyper-V与WSL2的兼容性问题或是Linux环境下对NVIDIA驱动的特殊要求都需要有针对性的解决方案。2. 环境准备2.1 硬件与系统要求在开始部署前需要确保你的设备满足以下基本要求CPU至少4核推荐8核以上内存最低8GB16GB以上更佳存储50GB可用空间用于存放Docker镜像和模型文件GPU非必须项但运行大模型时推荐NVIDIA显卡CUDA 11.7操作系统版本要求Windows 10/11 Pro/Enterprise家庭版无法使用Hyper-VLinux发行版Ubuntu 20.04/CentOS 7/Debian 10特别注意Windows系统需要确认BIOS中已开启虚拟化支持Intel VT-x/AMD-V可通过任务管理器→性能选项卡查看虚拟化是否已启用2.2 基础软件安装Windows环境准备安装WSL2wsl --install执行后重启系统默认会安装Ubuntu发行版安装Docker Desktop从官网下载最新稳定版安装包安装时勾选Use WSL 2 instead of Hyper-V选项安装完成后在设置→Resources→WSL Integration中启用Ubuntu集成验证安装docker --version docker-compose --versionLinux环境准备更新系统sudo apt update sudo apt upgrade -y # Ubuntu/Debian sudo yum update -y # CentOS/RHEL安装Docker引擎curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER newgrp docker安装Docker Composesudo curl -L https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose sudo chmod x /usr/local/bin/docker-compose3. Dify核心组件解析3.1 架构组成Dify采用微服务架构主要包含以下组件前端服务基于Vue.js的Web界面API服务处理业务逻辑的Python后端工作节点实际执行模型推理的WorkerPostgreSQL存储应用数据和配置Redis处理缓存和消息队列MinIO对象存储服务用于文件上传3.2 配置文件详解部署前需要重点关注的配置项位于.env文件# 数据库配置 POSTGRES_HOSTpostgres POSTGRES_PORT5432 POSTGRES_DBdify POSTGRES_USERpostgres POSTGRES_PASSWORDyour_strong_password # Redis配置 REDIS_HOSTredis REDIS_PORT6379 REDIS_PASSWORDyour_redis_password # 模型服务配置 MODEL_PROVIDERopenai # 可选openai/azure_openai/anthropic... OPENAI_API_KEYsk-xxx # 使用自有API key时需要4. 完整部署流程4.1 Windows环境部署克隆仓库git clone https://github.com/langgenius/dify.git cd dify/docker修改.env配置将COMPOSE_PROJECT_NAMEdify取消注释设置强密码替换默认的数据库凭证启动服务docker-compose up -d访问应用浏览器打开http://localhost首次访问会进入初始化页面Windows常见问题处理若遇到端口冲突修改docker-compose.yml中的端口映射WSL2内存不足时在%UserProfile%\.wslconfig中添加[wsl2] memory8GB swap4GB4.2 Linux环境部署获取部署脚本curl -O https://raw.githubusercontent.com/langgenius/dify/main/docker/install.sh chmod x install.sh执行安装./install.sh --channelstable管理服务# 查看状态 docker-compose ps # 停止服务 docker-compose down # 更新版本 docker-compose pull docker-compose up -d配置Nginx反向代理可选server { listen 80; server_name your_domain.com; location / { proxy_pass http://localhost:80; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }5. 模型接入与配置5.1 接入OpenAI模型登录Dify控制台进入模型供应商设置选择OpenAI填入API Key测试连接成功后保存5.2 本地模型部署对于希望完全本地运行的用户可接入以下开源模型LLaMA 27B/13B版本ChatGLM36B版本Baichuan27B/13B版本部署示例以ChatGLM3-6B为例# 下载模型权重 git lfs install git clone https://huggingface.co/THUDM/chatglm3-6b # 启动API服务 docker run -d --name chatglm \ -p 8000:8000 \ -v /path/to/chatglm3-6b:/app/model \ registry.hf.space/chatglm3-6b-api:latest然后在Dify的模型配置中添加自定义端点API Base URL: http://localhost:8000 Model Name: chatglm3-6b6. 性能优化指南6.1 Windows环境优化调整WSL2资源限制# .wslconfig [wsl2] memory12GB processors6 swap8GB禁用不必要的Windows服务停止Connected User Experiences and Telemetry服务关闭Windows Search索引使用SSD存储Docker镜像wsl --shutdown wsl --export docker-desktop-data D:\wsl\docker-data.tar wsl --import docker-desktop-data D:\wsl\data D:\wsl\docker-data.tar --version 26.2 Linux环境优化内核参数调整echo vm.max_map_count262144 /etc/sysctl.conf sysctl -pDocker存储驱动优化// /etc/docker/daemon.json { storage-driver: overlay2, log-driver: json-file, log-opts: { max-size: 100m, max-file: 3 } }NVIDIA GPU加速如有distribution$(. /etc/os-release;echo $ID$VERSION_ID) \ curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add - \ curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list sudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo systemctl restart docker7. 常见问题排查7.1 Docker启动失败症状Virtualization support not detected错误解决方案确认BIOS中已启用虚拟化Windows功能中开启Hyper-V和Windows Hypervisor Platform执行bcdedit /set hypervisorlaunchtype auto7.2 端口冲突处理修改docker-compose.yml中的端口映射services: api: ports: - 8080:80 # 原80端口改为8080然后重启服务docker-compose down docker-compose up -d7.3 数据库连接问题检查PostgreSQL日志docker logs dify-postgres-1常见修复步骤确认.env中的密码与docker-compose.yml一致检查PostgreSQL容器是否正常运行重置数据库docker-compose down -v docker-compose up -d8. 生产环境建议8.1 安全加固措施修改默认凭证PostgreSQL密码Redis密码MinIO访问密钥启用HTTPSserver { listen 443 ssl; server_name your_domain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://localhost:80; } }定期备份# 备份数据库 docker exec dify-postgres-1 pg_dump -U postgres dify dify_backup.sql # 备份上传文件 rsync -av /var/lib/docker/volumes/dify_minio_data/_data /backup/minio8.2 监控方案推荐使用PrometheusGrafana监控栈在docker-compose.yml中添加services: prometheus: image: prom/prometheus ports: - 9090:9090 volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml grafana: image: grafana/grafana ports: - 3000:3000配置prometheus.yml采集Dify指标scrape_configs: - job_name: dify static_configs: - targets: [api:80]导入Grafana仪表板模板ID131799. 版本升级策略小版本升级如0.5.0 → 0.5.1docker-compose pull docker-compose up -d大版本升级如0.5 → 0.6docker-compose down mv .env .env.bak git pull origin main cp .env.bak .env docker-compose up -d数据库迁移docker exec -it dify-api-1 python manage.py migrate升级前务必备份数据库查看Release Notes中的破坏性变更在测试环境验证升级流程
)
