3 · 部署与操作（Deployment and Operations）

部署与操作

部署与运维

相关源文件

本章引用的主要源码文件：

• api/.env.example
• api/Dockerfile
• api/app.py
• api/app_factory.py
• api/configs/feature/__init__.py
• api/configs/middleware/__init__.py
• api/configs/middleware/cache/redis_config.py
• api/configs/observability/__init__.py
• api/configs/observability/otel/otel_config.py
• api/configs/packaging/__init__.py
• api/controllers/console/datasets/datasets.py
• api/core/rag/datasource/vdb/vector_factory.py
• api/core/rag/datasource/vdb/vector_type.py
• api/extensions/ext_celery.py
• api/extensions/ext_compress.py
• api/extensions/ext_otel.py
• api/extensions/ext_redis.py
• api/extensions/otel/instrumentation.py
• api/pyproject.toml
• api/schedule/queue_monitor_task.py
• api/schedule/workflow_schedule_task.py
• api/tests/test_containers_integration_tests/trigger/__init__.py
• api/tests/test_containers_integration_tests/trigger/conftest.py
• api/tests/test_containers_integration_tests/trigger/test_trigger_e2e.py
• api/tests/unit_tests/configs/test_dify_config.py
• api/tests/unit_tests/core/workflow/graph_engine/test_table_runner.py
• api/tests/unit_tests/extensions/test_celery_ssl.py
• api/tests/unit_tests/extensions/test_redis.py
• api/uv.lock
• docker/.env.example
• docker/README.md
• docker/docker-compose-template.yaml
• docker/docker-compose.middleware.yaml
• docker/docker-compose.yaml
• docker/envs/core-services/shared.env.example
• docker/envs/infrastructure/nginx.env.example
• docker/envs/security.env.example
• docker/nginx/conf.d/default.conf.template
• web/.env.example
• web/Dockerfile
• web/app/layout.tsx
• web/config/index.ts
• web/docker/entrypoint.sh
• web/package.json
• web/types/feature.ts

目的与范围

本文档概述了 Dify 平台的部署策略和运维注意事项，涵盖了在生产环境中部署和运维 Dify 所需的服务架构、部署方法、配置管理和运行时模式。

关于特定主题的详细信息：

• Docker 镜像构建过程：参见 Docker 构建过程与多阶段镜像
• 运行时模式与入口点配置：参见 环境配置与运行时模式
• 存储与向量数据库设置：参见 存储后端与向量数据库配置
• 后台任务处理：参见 使用 Celery 处理后台任务

关于开发环境设置，参见 开发环境设置。关于系统架构详情，参见 系统架构总览。

部署架构

Dify 平台由多个容器化服务组成，通过 Docker Compose 或 Kubernetes 进行编排。架构将关注点分离到不同的服务层：表示层（Web）、应用层（API）、后台处理层（Worker/Beat）、执行隔离层（Sandbox）和数据持久化层（数据库）。

服务拓扑

服务依赖与启动顺序

来源：docker/docker-compose-template.yaml:1-152, docker/docker-compose.yaml:1-115, docker/docker-compose.middleware.yaml:1-128

部署方法

Docker Compose 部署

Docker Compose 是开发、测试和小规模生产部署的推荐方法。平台提供了预配置的 Compose 文件，用于编排所有必要的服务。

关键文件：

• docker/docker-compose.yaml - 自动生成的主 Compose 文件 docker/docker-compose.yaml:1-5
• docker/docker-compose-template.yaml - 用于生成的模板 docker/docker-compose-template.yaml:1-2
• docker/docker-compose.middleware.yaml - 仅中间件服务 docker/docker-compose.middleware.yaml:1-103
• docker/.env.example - 环境配置模板 docker/.env.example:1-150

部署步骤：

1. 配置：复制并自定义环境文件

   cp docker/.env.example docker/.env

1. 数据库选择：通过 Docker Compose 配置文件选择数据库 docker/docker-compose.middleware.yaml:5-7
   • PostgreSQL：--profile postgresql（默认）
   • MySQL：--profile mysql

1. 服务启动：启动服务及其依赖

   docker compose --profile postgresql up -d

服务配置文件：

来源：docker/docker-compose-template.yaml:184-210, docker/docker-compose.middleware.yaml:1-100

服务组件

API 服务（api）

API 服务是主要的应用服务器，处理来自控制台（管理端）和服务（运行时）接口的 HTTP 请求。

容器配置：

• 镜像：langgenius/dify-api:1.14.2 api/pyproject.toml:3
• 运行时模式：MODE: api docker/docker-compose-template.yaml:30
• 端口：5001（可通过 DIFY_PORT 配置）docker/.env.example:54
• 进程管理器：使用 gevent 工作模式的 Gunicorn api/pyproject.toml:14-18
• 工作进程数量：由 SERVER_WORKER_AMOUNT 控制 docker/.env.example:55

启动流程（从入口点开始）：

关键环境变量：

来源：api/Dockerfile:113-122, docker/docker-compose-template.yaml:22-68, docker/.env.example:1-70

Worker 服务（worker）

Worker 服务使用 Celery 处理异步后台任务，从多个专用队列中消费消息。

容器配置：

• 镜像：langgenius/dify-api:1.14.2 api/pyproject.toml:3
• 运行时模式：MODE: worker docker/docker-compose-template.yaml:78
• 工作进程类：由 CELERY_WORKER_CLASS 控制 docker/.env.example:62

队列架构：

Worker 扩缩容配置：

来源：docker/docker-compose-template.yaml:69-114, docker/.env.example:62-70, api/pyproject.toml:10

Worker Beat 服务（worker_beat）

Beat 服务使用 Celery Beat 提供定时任务执行功能，用于周期性后台作业。

容器配置：

• 镜像：langgenius/dify-api:1.14.2 api/pyproject.toml:3
• 运行时模式：MODE: beat docker/docker-compose-template.yaml:124

Beat 服务只需要 Redis 连接，不处理请求。每个部署应只运行一个 Beat 实例，以避免重复的任务调度。

来源：docker/docker-compose-template.yaml:115-152

Web 服务（web）

Web 服务提供 Next.js 前端应用，用于控制台和最终用户界面。

容器配置：

• 镜像：langgenius/dify-web:1.14.2 web/package.json:4
• 框架：Next.js（通过 next build 构建）web/package.json:27
• 端口：3000（默认）
• Node 版本：22.x api/Dockerfile:55

环境变量映射： Web 容器在运行时将后端环境变量映射到 Next.js 变量，包括 CONSOLE_API_URL 和 APP_API_URL docker/docker-compose-template.yaml:158-159。

来源：web/package.json:1-50, docker/docker-compose-template.yaml:153-182

Sandbox 服务（sandbox）

Sandbox 服务为工作流代码节点和工具操作提供隔离的代码执行环境。

容器配置：

• 镜像：langgenius/dify-sandbox:0.2.15 docker/docker-compose.middleware.yaml:106
• 端口：8194 docker/docker-compose.middleware.yaml:120
• API 认证：API_KEY docker/docker-compose.middleware.yaml:114

关键安全参数：

来源：docker/docker-compose.middleware.yaml:105-128, api/configs/feature/__init__.py:103-116

插件守护进程服务（plugin_daemon）

插件守护进程在隔离环境中管理插件的生命周期、安装和执行。

容器配置：

• 镜像：langgenius/dify-plugin-daemon:0.6.1-local docker/docker-compose.middleware.yaml:132
• 端口：5002 docker/docker-compose.middleware.yaml:145
• 数据库：DB_DATABASE docker/docker-compose.middleware.yaml:141

来源：docker/docker-compose.middleware.yaml:131-180, docker/.env.example:209-213

配置管理

配置层级

Dify 平台使用基于 Pydantic 校验的分层配置系统 api/configs/feature/__init__.py:15-17。

配置类：

关键配置变量

安全：

SECRET_KEY=<openssl rand -base64 42>  # 会话签名、加密 [api/configs/feature/__init__.py:25-30]

数据库：

DB_TYPE=postgresql                     # [docker/.env.example:72]
DB_USERNAME=postgres                   # [docker/.env.example:73]
DB_PASSWORD=difyai123456               # [docker/.env.example:74]
DB_HOST=db_postgres                    # [docker/.env.example:75]
DB_PORT=5432                           # [docker/.env.example:76]

Redis：

REDIS_HOST=redis                       # [docker/.env.example:96]
REDIS_PORT=6379                        # [docker/.env.example:97]
REDIS_PASSWORD=difyai123456            # [docker/.env.example:99]

来源：docker/.env.example:1-110, api/configs/feature/__init__.py:1-210

卷管理

持久化数据卷

Docker Compose 部署使用宿主机挂载卷来实现数据持久化。

卷映射：

权限初始化： init_permissions 服务确保在应用启动前，挂载卷具有正确的所有权（1001:1001）docker/docker-compose-template.yaml:202-218。

来源：docker/docker-compose-template.yaml:3-220, api/Dockerfile:54-60

日志与可观测性

日志配置

OpenTelemetry 集成

Dify 支持通过多个检测包使用 OpenTelemetry 进行分布式追踪和指标收集 api/pyproject.toml:35-41。

来源：docker/.env.example:43-49, api/pyproject.toml:35-41