Dify 开源 LLM 应用开发平台企业级 Docker Compose 部署手册

责任边界声明：本文聚焦 Docker Compose 形态下的生产部署实践，不涵盖 Kubernetes / Helm 等大规模集群场景。

Dify 是由 LangGenius 开发的开源 LLM 应用开发平台，可帮助开发者与团队快速构建 AI 应用（如智能聊天机器人、私有知识库问答、自动化业务工作流等）。它支持可视化开发界面、多模型集成（GPT、文心一言、通义千问等），并提供完整的前后端架构；通过自托管部署，能有效保障数据隐私与安全，广泛适用于企业私有环境、定制化 AI 服务场景。

本文为企业级可落地的 Dify 部署指南，包含：环境准备、Docker / Docker Compose 安全安装、轩辕镜像加速、「测试/生产双模式」部署方案、前后端关联配置、生产级安全加固及排错要点。文中所有配置均标注官方/镜像来源，按步骤执行即可稳定运行。

适用场景对照表

🧰 准备工作

若你的系统尚未安装 Docker，请先完成安装。以下提供一键安装脚本（附安全声明），也可选择 Docker 官方安装方式。

Linux Docker & Docker Compose 一键安装

一键安装配置脚本（适配国内环境）：
该脚本支持多种 Linux 发行版，一键安装 Docker、Docker Compose 并自动配置轩辕镜像加速源。

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

⚠️ 安全提示（生产环境强制要求）
该脚本将以root权限执行，涉及系统配置修改、软件安装等操作：

• 企业/生产环境：必须先下载脚本本地审计（wget https://xuanyuan.cloud/docker.sh），确认无风险后再执行；或直接使用 Docker 官方安装文档
• 测试/个人环境：可直接使用，脚本已做国内镜像适配，无需额外配置

一、核心组件说明：dify-api/dify-web及依赖关系

• dify-api：后端核心服务（API 接口、任务调度、模型调用、数据存储等），镜像可从 Docker Hub 或轩辕加速源获取。(hub.docker.com)
• dify-web：前端管理控制台（Next.js 开发），通过环境变量指向后端 API，不直接处理业务逻辑。(hub.docker.com)
• worker/celery：异步任务处理组件（向量计算、文件解析、LLM 异步调用等），与dify-api共享存储和配置，是生产环境不可缺少的组件。
• 依赖关系：前端仅通过 API 调用后端；后端依赖数据库（MySQL）、对象存储（MinIO）、向量数据库；Worker 负责异步任务，与 API 共享存储和配置。(Dify 文档)

二、部署前准备（硬件 & 软件规范）

硬件要求（分场景）

软件要求

• Docker：推荐 Docker Engine 24.0+（Linux Server 环境）；不建议在生产环境使用 Docker Desktop，其主要适用于开发/本地测试场景
• Docker Compose：必须使用 V2 版本（命令为docker compose，而非docker-compose）
• 操作系统：推荐 Ubuntu 22.04 LTS / Rocky Linux 9 / AlmaLinux 9（不再推荐使用已停止维护的 CentOS Linux）

三、镜像来源（安全 & 稳定优先）

镜像标签规范（生产强制要求）

❌ 绝对禁止使用latest标签（会随机拉取新版本，导致 API 兼容、数据库 schema 冲突）
✅ 生产环境必须指定具体版本号（如0.10.3），版本号需与 Dify 官方发布一致（Dify 版本列表）

镜像拉取命令（示例）

## 1. 生产环境（推荐，指定版本） # 从 Docker Hub（外网环境） docker pull langgenius/dify-api:0.10.3 docker pull langgenius/dify-web:0.10.3 # 从轩辕加速源（国内环境，替换为专属域名） docker pull docker.xuanyuan.run/langgenius/dify-api:0.10.3 docker pull docker.xuanyuan.run/langgenius/dify-web:0.10.3 ## 2. 测试环境（仅临时使用，不推荐） docker pull langgenius/dify-api:latest docker pull langgenius/dify-web:latest

轩辕镜像加速说明：国内网络拉取官方镜像慢/失败时，可访问 轩辕镜像 获取专属加速地址，无需登录即可拉取。

四、方法 A —— 官方 Github 仓库 + Docker Compose（生产/推荐）

说明

官方仓库提供完整的docker-compose.yml、.env模板，包含所有核心组件（API、Web、MySQL、MinIO、向量数据库、Worker），适配生产环境的持久化、权限配置，是企业部署的首选方案。(Dify 文档)

步骤（按序执行，生产级规范）

1. 克隆官方仓库（指定版本标签，避免主分支不稳定）：

git clone https://github.com/langgenius/dify.git cd dify # 切换到稳定版本（示例：v0.10.3） git checkout v0.10.3

1. 进入 Docker 部署目录，复制配置模板：

cd docker cp .env.example .env ## 复制配置模板

1. 编辑.env（生产级关键配置）

   • APP_API_URL/CONSOLE_API_URL：前端访问后端的基础 URL（仅写主机+端口，如http://192.168.1.100，禁止加/api子路径），错误配置会导致前端 API 请求 404。(GitHub)
   • SECRET_KEY：核心加密密钥，生产环境必须自定义强随机字符串，且一旦设置禁止修改（修改会导致 JWT 令牌失效、已加密数据无法解密）。
   • 数据库/MinIO 密码：必须替换默认值，使用大小写字母+数字+特殊符号的强密码。
   • 存储配置：/app/api/storage需挂载到宿主机固定目录，且仅需在 dify-api 和 worker 容器间共享，dify-web 无需挂载该目录。(Dify 文档)

2. 启动服务（指定 Compose 文件，后台运行）：

docker compose -f docker-compose.yml up -d

1. 验证启动状态（生产级检查）：

# 1. 查看容器运行状态 docker compose ps # 所有服务应显示 "Up" 状态 # 2. 查看 API 服务日志（容器名以实际 Compose 配置为准） docker compose logs -f dify-api # 3. 访问前端页面（替换为你的服务器 IP） # 浏览器打开 http://<服务器IP>，应显示 Dify 登录界面

五、方法 B —— 最小化 Docker Compose（仅测试/Demo）

⚠️ 重要警告（强制阅读）

• 该配置仅用于本地功能测试，禁止直接用于生产环境
• 存在弱口令、端口暴露、无异步任务处理等安全/功能缺陷
• 生产环境必须使用方法 A，并补充反向代理、TLS 加密、权限隔离等配置

最小化 Compose 示例（docker-compose.min.yml）

version: "3.8" services: mysql: image: docker.xuanyuan.run/mysql:8.0 environment: # 示例占位密码，仅用于本地测试，禁止用于任何生产环境 MYSQL_ROOT_PASSWORD: StrongP@ssw0rd_2026 MYSQL_DATABASE: dify volumes: - db_data:/var/lib/mysql restart: unless-stopped # 生产建议：禁用端口映射，仅内网访问 # ports: # - "3306:3306" minio: image: docker.xuanyuan.run/minio/minio command: server /data environment: # 示例占位密码，仅用于本地测试，禁止用于任何生产环境 MINIO_ROOT_USER: dify_minio_admin MINIO_ROOT_PASSWORD: MinIO@StrongP@ss0rd # ❌ 测试用端口暴露，生产必须删除（仅内网访问） # ports: # - "9000:9000" volumes: - minio_data:/data restart: unless-stopped dify-api: image: docker.xuanyuan.run/langgenius/dify-api:0.10.3 depends_on: - mysql - minio environment: DATABASE_URL: "mysql+pymysql://root:StrongP@ssw0rd_2026@mysql:3306/dify" STORAGE_DRIVER: "local" SECRET_KEY: "your_strong_random_secret_key_here_123456" APP_API_URL: "http://dify-api:5001" volumes: - ./storage:/app/api/storage ## 仅 API 需挂载，Web 无需挂载 ports: - "5001:5001" restart: unless-stopped # 生产建议：添加健康检查 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:5001/health"] interval: 30s timeout: 10s retries: 3 dify-web: image: docker.xuanyuan.run/langgenius/dify-web:0.10.3 depends_on: - dify-api environment: APP_API_URL: "http://dify-api:5001" ports: - "80:3000" restart: unless-stopped # 生产建议：添加健康检查 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:3000"] interval: 30s timeout: 10s retries: 3 volumes: db_data: minio_data:

healthcheck 版本说明：/health接口以当前 Dify 版本为准，如升级后接口路径变更，请以官方 API 文档或容器启动日志为准调整检查路径。

启动与验证（测试用）

# 启动 docker compose -f docker-compose.min.yml up -d # 验证（容器名以实际 Compose 配置为准） docker compose -f docker-compose.min.yml logs -f # 浏览器访问 http://localhost 即可进入测试界面

六、前端（dify-web）与后端（dify-api）关联配置（核心）

前端通过环境变量获取后端 API 地址，生产环境需严格遵循以下规范：

核心环境变量

配置示例（.env文件）

# 生产环境（域名访问，带 HTTPS） APP_API_URL=https://dify-api.example.com CONSOLE_API_URL=https://dify-api.example.com # 测试环境（IP 访问） APP_API_URL=http://192.168.1.100 CONSOLE_API_URL=http://192.168.1.100

关键提醒：Dify 前端基于 Next.js 开发，部分变量需带NEXT_PUBLIC_前缀，优先参考官方.env.example模板，避免变量名错误导致前端无法调用 API。(Dify 文档)

七、生产环境 Docker 通用加固建议

1. 容器运行规范

• 所有服务必须设置restart: unless-stopped（避免服务器重启后容器未启动）
• 核心服务（API、MySQL、MinIO）添加healthcheck（自动检测服务状态，异常时重启）
• 高安全要求环境：使用 Rootless Docker 运行容器，或自建非 root 镜像（官方镜像默认以 root 运行，存在权限风险）

2. 网络与端口规范

• 禁止直接暴露数据库、MinIO、向量数据库端口到公网（仅内网访问）
• 使用 Nginx/Traefik 做反向代理，统一暴露 80/443 端口，并配置 TLS 加密（Let's Encrypt 免费证书）
• 配置防火墙（如 iptables/ufw），仅开放必要端口

3. 存储与备份规范

• 数据库、MinIO、storage 目录挂载到独立数据盘（避免系统盘满导致服务崩溃）
• 配置定时备份：每日备份 MySQL 数据库、MinIO 数据、storage 目录
• 生产环境优先使用外部托管数据库/对象存储（如阿里云 RDS、OSS），简化运维

八、高级定制与升级规范

1. 本地构建镜像（定制化需求）

若需修改前端代码或自定义配置，可在web/目录构建镜像：

cd dify/web docker build -t your-registry/dify-web:0.10.3 .

参考：GitHub 构建示例

2. 切换向量数据库

Dify 支持 Weaviate、Milvus、Qdrant 等向量数据库，修改.env中VECTOR_STORE变量即可切换，需确保 API 和 Worker 配置一致。(Dify 文档)

3. 版本升级（生产级流程）

升级前必须执行以下步骤，避免数据丢失或兼容问题：

1. 备份 MySQL 数据库（mysqldump -u root -p dify > dify_backup.sql）
2. 备份/app/api/storage目录（cp -r /path/to/storage /path/to/storage_backup）
3. 备份 MinIO 数据（cp -r /path/to/minio_data /path/to/minio_backup）
4. 记录当前部署的 Dify 版本号与 Git Tag（便于异常时快速回滚）
5. 确认新版本与当前版本的兼容性（参考官方升级文档）
6. 修改docker-compose.yml中的镜像版本号，执行docker compose up -d

九、常见问题 & 排查步骤（快速清单）

1. 网页打不开/502 错误

• 检查防火墙是否开放端口，容器是否全部Up状态（docker compose ps）
• 查看 Nginx/反向代理日志，确认前端是否能访问后端 API
• 检查服务器网络（是否能 ping 通，是否有网络策略限制）

2. 前端 API 请求 404/报错

• 检查.env中APP_API_URL是否正确（仅主机+端口，无/api）
• 查看 API 服务日志（docker compose logs -f dify-api），确认 API 服务是否正常监听

3. 文件上传/读取失败

• 确认/app/api/storage仅在 dify-api 和 worker 容器间共享，Web 无需挂载
• 检查 storage 目录权限（推荐chmod 755，避免权限不足）

4. 镜像拉取失败

• 切换到轩辕加速镜像源，或检查网络是否能访问 Docker Hub
• 确认镜像版本号正确（避免使用不存在的版本）

十、Dify 部署架构图

1. 生产级架构（方法 A）

┌──────────────┐ │ Client │ │ Browser/API │ └──────┬───────┘ │ HTTPS ▼ ┌──────────────┐ │ Nginx / LB │ ← 反向代理+TLS+端口转发 └──────┬───────┘ │ ┌─────▼──────────────┐ │ dify-web │ ← 前端（仅API调用，无本地存储） │ 管理台 / Console │ └─────┬──────────────┘ │ REST API ┌─────▼──────────────┐ │ dify-api │ ← 核心服务（Auth/LLM/File） └─────┬───────┬──────┘ │ │ │ ├──────────┐ │ │ │ ┌──────▼───┐ ┌─▼────────┐ ┌────────────┐ │ MySQL │ │ Vector │ │ MinIO │ │ Metadata │ │ DB │ │ Object │ └──────────┘ └───────────┘ └────────────┘ ▲ │ ┌──────┴────────┐ │ Worker/Celery│ ← 异步任务（向量计算/文件解析） └───────────────┘

核心特征：API/Worker 共享 storage；所有后端服务内网隔离；反向代理统一暴露端口；全组件持久化存储。

2. 测试级架构（方法 B）

┌──────────────┐ │ Client │ │ Browser/API │ └──────┬───────┘ │ HTTP ▼ ┌──────────────┐ │ dify-web │ └──────┬───────┘ │ REST API ▼ ┌──────────────┐ │ dify-api │ └──────┬───────┘ │ ├──┬──────────┐ │ │ │ ┌──────▼──┐│ ▼ │ MySQL ││ MinIO（端口暴露） └────────┘│ │

核心特征：无反向代理；端口直接暴露；无 Worker 组件；仅核心功能可用，无生产级保障。

十一、实践小结

1. 安装 Docker/Compose：测试环境可使用一键脚本（需审计），生产环境优先官方安装方式。
2. 选择部署方式：测试用方法 B（最小化 Compose），生产用方法 A（官方 Compose）。
3. 配置核心参数：指定镜像版本号、自定义强密码、正确配置APP_API_URL、共享 API/Worker 的 storage 目录。
4. 启动并验证：检查容器状态和日志，确认前端可正常访问后端 API。
5. 生产加固：添加反向代理/TLS、健康检查、定时备份，禁止暴露敏感端口。
6. 版本记录：升级前后务必记录 Dify 版本号与 Git Tag，确保可回滚。

生产部署前 Checklist

参考与延伸阅读

• Dify 官方 Docker Compose 部署文档
• Dify API 镜像（Docker Hub）
• Dify Web 镜像（Docker Hub）
• 轩辕镜像加速（dify-api）
• Dify 环境变量配置文档
• Dify 版本发布列表

总结

1. 版本与标签：生产环境必须指定具体镜像版本号，禁止使用latest标签，避免版本兼容问题；升级前后需记录版本号与 Git Tag，便于回滚。
2. 安全规范：一键安装脚本需审计后执行，最小化 Compose 仅用于测试，生产需替换弱口令、关闭敏感端口、配置反向代理/TLS；密码配置行需标注“示例占位，禁止生产使用”。
3. 存储与配置：/app/api/storage仅需在 API 和 Worker 容器间共享，Web 无需挂载；SECRET_KEY一旦设置禁止修改，升级前必须备份数据。
4. 架构区分：测试环境用最小化 Compose 快速验证功能，生产环境用官方 Compose 并补充健康检查、备份、权限隔离等加固措施；测试架构图移除无关的 SQLite 标识，与示例配置保持一致。
5. 日志命令：优先使用docker compose logs -f <服务名>查看日志，规避容器名不一致的问题。