Dify 搭建保姆级教程：从零部署到上线的完整指南

范围与目标

本文面向首次接触 Dify 的技术团队与个人开发者，提供从零开始到对外可用的完整部署流程，覆盖本地验证、服务器上线、反向代理与 HTTPS、模型与向量库接入、性能与安全加固，以及面向生产的监控、备份、伸缩和自动化运维实践。示例以常见的 Linux 服务器与 Docker 生态为主，同时给出在 Kubernetes 集群中的落地思路，确保可平滑演进至更大规模与更高可用的架构。

架构概览

核心组件

• 应用层：Dify Web 控制台、API 服务、后台 Worker。
• 数据层：PostgreSQL（事务与配置数据）、Redis（缓存与任务队列）、对象存储（上传文件与知识库原文）。
• 检索层：向量数据库（pgvector、Milvus、Weaviate、Qdrant 等）。
• 模型层：LLM 与嵌入模型（OpenAI、Azure OpenAI、DeepSeek、Ollama、本地推理服务等）。
• 外围层：反向代理与 HTTPS、日志与监控、告警、备份与恢复。

典型流转

用户通过浏览器访问反向代理，反向代理将请求转发至 Dify API/Web；API 与 Worker 访问 PostgreSQL、Redis 与对象存储；知识检索路径经由向量数据库完成召回与重排序；模型调用走外部 LLM 平台或自建推理服务；日志与指标经由采集器输出至日志系统与监控平台。

部署方式对比

Docker Compose

• 优点：上手快、组件一体化、维护简单、适合单机或小规模。
• 适用：原型验证、中小团队内部部署、资源受限环境。

Kubernetes

• 优点：弹性伸缩、滚动升级、服务治理完善、易于与云原生生态集成。
• 适用：生产级、跨可用区、高可用与高吞吐需求。

云托管与自建

• 云托管：更少运维、快速上线、按需扩缩，成本可控但受平台限制。
• 自建：灵活可控、数据在握，需投入运维与监控体系建设。

前置准备

硬件与系统

• 操作系统：Ubuntu 20.04+ 或 Debian/RHEL 同级；确保时区与 NTP 正确。
• 资源建议：2–4 核 CPU、8–16GB 内存、50GB+ SSD；生产视并发与知识库规模增配。
• 网络：放通 80/443、数据库与 Redis 内网访问；禁止数据库与 Redis 对公网暴露。
• 依赖：Docker 24+、Docker Compose v2+ 或 Kubernetes 1.25+。

域名与证书

• 准备二级域名，如 app.example.com 指向服务器公网 IP。
• 建议使用自动签发证书（Caddy/Traefik/Certbot），或导入现有证书链。

外部服务与凭据

• 模型服务：OpenAI/兼容服务或 Azure OpenAI、DeepSeek、Ollama、本地推理网关。
• 对象存储：S3/MinIO，配置访问键与桶策略。
• 邮件：SMTP 凭据用于账号激活与通知。
• 单点登录：如企业内部 OAuth2/OIDC、SAML（可选）。

Docker Compose 部署

获取项目与目录结构

在部署主机创建工作目录，拉取发布版本镜像或官方示例编排文件，使用专用数据目录持久化 PostgreSQL、Redis 与对象存储数据，避免容器销毁导致数据丢失。建议结构如下：

/opt/dify/
├─ compose.yml
├─ .env
├─ config/
│  ├─ app.env
│  └─ nginx.conf
├─ data/
│  ├─ postgres/
│  ├─ redis/
│  └─ minio/
└─ logs/

环境变量与配置

核心环境项示例（根据实际镜像版本与发布说明调整）：

# .env
DIFY_EXTERNAL_URL=https://app.example.com
DIFY_ENABLE_SIGNUP=false
DIFY_ENABLE_EMAIL_SIGNIN=true
DIFY_SMTP_HOST=smtp.example.com
DIFY_SMTP_PORT=587
DIFY_SMTP_USER=mailer@example.com
DIFY_SMTP_PASS=请替换为强密码
DIFY_SMTP_FROM=mailer@example.com

# 数据库
POSTGRES_USER=dify
POSTGRES_PASSWORD=强密码
POSTGRES_DB=dify

# Redis
REDIS_PASSWORD=强密码

# 对象存储（S3/MinIO）
S3_ENDPOINT=http://minio:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET=dify-objects
S3_REGION=us-east-1
S3_FORCE_PATH_STYLE=true

# 向量库（pgvector 或外部 Milvus/Weaviate）
VECTOR_DB=pgvector

应用容器读取上述变量以连接数据库、缓存、存储与外部服务。对外地址用于构建回调与资源链接，务必与反向代理暴露的域名一致。

示例 compose 文件

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      retries: 5

  redis:
    image: redis:7
    command: ["redis-server", "--requirepass", "${REDIS_PASSWORD}"]
    volumes:
      - ./data/redis:/data

  minio:
    image: minio/minio:latest
    environment:
      MINIO_ROOT_USER: ${S3_ACCESS_KEY}
      MINIO_ROOT_PASSWORD: ${S3_SECRET_KEY}
    command: server /data --console-address ":9001"
    volumes:
      - ./data/minio:/data

  dify-api:
    image: langgenius/dify-api:latest
    env_file: .env
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      REDIS_URL: redis://default:${REDIS_PASSWORD}@redis:6379/0
      STORAGE_ENDPOINT: ${S3_ENDPOINT}
      STORAGE_ACCESS_KEY: ${S3_ACCESS_KEY}
      STORAGE_SECRET_KEY: ${S3_SECRET_KEY}
      STORAGE_BUCKET: ${S3_BUCKET}
    depends_on:
      - postgres
      - redis
      - minio

  dify-web:
    image: langgenius/dify-web:latest
    environment:
      DIFY_API_BASE_URL: http://dify-api:5001
    depends_on:
      - dify-api

  dify-worker:
    image: langgenius/dify-worker:latest
    env_file: .env
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      REDIS_URL: redis://default:${REDIS_PASSWORD}@redis:6379/0
    depends_on:
      - dify-api
      - redis

  gateway:
    image: caddy:2
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - dify-web
      - dify-api

volumes:
  caddy_data:
  caddy_config:

反向代理与 HTTPS

使用 Caddy 自动签发证书示例：

# Caddyfile
app.example.com {
  encode zstd gzip
  tls {
    issuers acme
  }
  @web path_regexp ^/(?!api/).*
  handle @web {
    reverse_proxy dify-web:3000
  }
  handle_path /api/* {
    reverse_proxy dify-api:5001
  }
}

如使用 Nginx/Certbot，保持相同的路由与超时策略，建议为长链接与大文件上传适当提升超时与缓冲区。

首次启动与初始化

• 执行启动：在工作目录运行 docker compose up -d。
• 健康检查：确认各容器状态正常，日志无报错，能通过域名访问界面。
• 管理员：通过邮件或命令行初始化管理员账号，关闭公开注册。
• 存储桶：在 MinIO 控制台创建指定桶名称，设置私有访问与生命周期。

常见问题

• 502/超时：检查反向代理转发与 API 服务端口，增大 proxy_read_timeout。
• 对象存储失败：校验 S3_ENDPOINT、访问键与桶存在性，启用路径样式。
• 知识库检索为空：确认向量库配置与嵌入模型可用，检查 Worker 日志。
• 邮件收发异常：核对发件人域、端口与 TLS/STARTTLS 设置。

Kubernetes 部署

镜像与拉取

• 选用官方镜像并配置镜像源凭据（如私有仓库）。
• 使用 ImagePullSecrets 管理拉取凭据，统一镜像标签策略。

配置与密钥

• ConfigMap：非机密配置如外部 URL、特性开关。
• Secret：数据库、Redis、S3、SMTP 等机密凭据，分命名空间隔离。

工作负载与服务

# 示例片段（省略非关键字段）
apiVersion: apps/v1
kind: Deployment
metadata:
  name: dify-api
spec:
  replicas: 2
  strategy:
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 1
  template:
    spec:
      containers:
        - name: api
          image: langgenius/dify-api:latest
          envFrom:
            - configMapRef: {name: dify-config}
            - secretRef: {name: dify-secrets}
          readinessProbe:
            httpGet: {path: /healthz, port: 5001}
          livenessProbe:
            httpGet: {path: /healthz, port: 5001}
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: dify
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
spec:
  tls:
    - hosts: [app.example.com]
      secretName: dify-tls
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend: {service: {name: dify-web, port: {number: 3000}}}
          - path: /api
            pathType: Prefix
            backend: {service: {name: dify-api, port: {number: 5001}}}

有状态与持久化

• PostgreSQL、Redis、MinIO 使用 StatefulSet+PVC 或托管云服务。
• 设置存储类、读写模式与备份快照策略；关键数据多副本或跨可用区。

伸缩与升级

• 开启 HPA，基于 CPU/内存/自定义指标进行弹性伸缩。
• 使用滚动升级与金丝雀发布；对 Worker 高峰任务可临时扩容。

监控与日志

• Prometheus 收集容器与自定义指标，Grafana 展示看板。
• Loki/Elastic 收集应用日志，配置按服务与环境分流。
• 告警：延迟、错误率、队列堆积、磁盘空间、证书到期。

外部能力接入

LLM 与嵌入模型

• OpenAI/兼容：配置 API Key、Base URL、模型名称、超时与重试。
• Azure OpenAI：指定资源名、部署名与 API 版本。
• DeepSeek 等：对齐兼容协议与鉴权头，留意并发限流与账单。
• Ollama/本地推理：将推理网关内网服务化，限制公网访问。
• 嵌入模型：区分中文与多语场景，评估向量维度与召回效果。

向量数据库

• pgvector：适合中小规模，维护简单，与 PostgreSQL 同源备份。
• Milvus/Weaviate/Qdrant：更高吞吐与扩展性，需专门运维与监控。
• 参数建议：合适的索引类型、分片与副本数、压缩与落盘策略。

对象存储

• S3/MinIO：启用私有桶与预签名访问，设置生命周期与版本管理。
• 网络：应用与存储位于同一私有网络或 VPC，减少延迟与外泄。

身份与权限

• SMTP：统一发信域，启用 SPF、DKIM、DMARC 以提高送达率。
• SSO：OIDC/SAML 对接企业 IdP，映射角色与租户边界。
• 审计：记录关键变更、模型调用与数据导出操作。

安全加固

网络与访问控制

• 仅暴露 80/443；数据库、Redis、对象存储保持内网访问。
• 细粒度防火墙策略与安全组，最小权限放通。
• 反爬与限流：由网关或 WAF 实施速率限制与 IP 封禁。

机密管理

• 分级管理 API Key 与凭据，定期轮换，启用审计与告警。
• Kubernetes 使用 Secret 与加密存储；Docker 环境避免将密钥写入镜像。

数据与合规

• 隐私：敏感字段脱敏存储与展示，访问日志留痕。
• 加密：传输层全站 HTTPS，静态数据采用磁盘与对象存储加密。

性能调优

应用与并发

• API 与 Worker 分离伸缩，异步任务充分利用队列并发。
• 连接池：数据库与向量库连接池大小依据核心数与延迟调整。
• 超时与重试：模型调用设置上限，区分幂等与非幂等操作策略。

数据库与索引

• PostgreSQL：合理 shared_buffers、work_mem、wal 相关参数；热点表与索引监控膨胀。
• 向量库：批量写入、分段构建索引，查询时控制 topK 与过滤条件。

缓存与队列

• Redis：划分独立 DB 与键前缀，设置过期与淘汰策略。
• 热点缓存：对模型配置、应用清单等短TTL缓存，减少数据库压力。

高可用与灾备

多副本与隔离

• API/Web 多副本部署，前置负载均衡健康检查。
• 数据库主从或云托管高可用版，读写分离与自动故障转移。
• 对象存储与向量库跨可用区副本与版本管理。

备份与演练

• 备份项：PostgreSQL 冷热备份、对象存储桶版本化、向量库快照、配置与密钥。
• 频率：日常增量、每周全量；保留周期与合规对齐。
• 演练：定期在隔离环境完成恢复验证，测量 RTO/RPO。

多环境与发布

环境分层

• dev/staging/prod 分离命名空间或独立集群，使用差异化配置。
• 外部依赖分环境隔离，避免测试流量进入生产账单。

灰度与回滚

• 基于权重或标签的流量分配，观测错误率与延迟后逐步扩大。
• 保留上一版本镜像与数据快照，触发自动回滚策略。

监控与可观测性

指标体系

• 服务健康：请求量、响应时间、错误率、队列堆积、并发数。
• 模型调用：成功率、重试率、单位成本、各模型配额与限流。
• 数据库：连接、慢查询、缓存命中、复制延迟。

日志与追踪

• 结构化日志：包含请求 ID、租户、用户、模块、耗时与错误码。
• 分布式追踪：接入标准追踪头，定位跨服务瓶颈。

成本与配额

资源与用量

• 按需扩缩：模型侧并发与 token 上限、向量库存储增长曲线。
• 分环境预算：开发与测试使用低成本模型与较小副本数。
• 缓存与复用：复用嵌入，减少重复向量化与调用次数。

自动化与运维脚本

CI/CD

• 构建：按分支生成镜像标签，扫描依赖漏洞与许可证。
• 部署：阶段化发布，集成数据库迁移脚本与健康检查。

定时与巡检

• 定时任务：日志归档、冷数据迁移、索引重建、备份校验。
• 巡检清单：证书有效期、磁盘与 inode、任务队列延迟、失败重试率。

上线校验与验收

功能验证

• 账号体系：注册、登录、密码重置、角色权限与租户隔离。
• 知识库：上传、切分、向量化、检索与召回结果可解释性。
• 应用编排：流程配置、变量注入、模型切换与 A/B 对照。

非功能验证

• 负载测试：典型并发与峰值压力，定位瓶颈并调优。
• 故障演练：断开外部模型、向量库与数据库，验证降级策略。
• 安全扫描：镜像、依赖、公开端口、弱口令与暴露面检查。

实用排错策略

定位路径

• 从网关到应用：先看 4xx/5xx，再查上游与下游服务。
• 分流量与数据：请求是否进入目标副本、是否命中缓存、是否触发限流。
• 最小化复现场景：用相同输入在测试环境重放，捕捉精确堆栈。

高频问题

• 模型限流：实现指数退避与熔断，必要时切换备用模型。
• 长文本超时：启用流式响应或分块处理，调整超时阈值。
• 检索不稳定：优化分词与切分粒度，提升向量化质量与召回阈值。

最佳实践清单

• 环境隔离：配置、凭据、网络、存储分环境分域管理。
• 最小权限：服务账号与访问策略仅授予必须的操作。
• 观测先行：没有可观测性就不要贸然扩容或改造。
• 自动化优先：构建、发布、备份、验证、回滚尽量流水线化。
• 经常演练：备份恢复、故障切换、证书与密钥轮换。
• 成本透明：模型与向量库账单可视化与告警。

示例操作步骤

单机到生产的迁移路径

• 步骤一：本地或单机 Docker Compose 启动，完成管理员初始化。
• 步骤二：接入外部模型与对象存储，验证知识库与应用流程。
• 步骤三：引入反向代理与正式域名，启用 HTTPS 与限流策略。
• 步骤四：分离数据层到托管服务或独立节点，设置备份与监控。
• 步骤五：将 API/Web/Worker 拆分多副本，设置水平伸缩。
• 步骤六：迁移至 Kubernetes（如需），引入 HPA、Ingress 与集中日志。
• 步骤七：完善 CI/CD、灰度发布、回滚与演练流程。

日常维护要点

• 变更管理：每次配置或模型策略变更需记录与回溯。
• 配额监控：API Key 用量、速率与账单阈值达标告警。
• 数据健康：数据库膨胀、索引重建、向量库碎片与再索引窗口。
• 安全基线：定期扫描镜像与依赖，修复高危 CVE。
• 用户支持：错误码与日志一致性，构建内部知识库便于自助排障。

参考参数建议

超时与重试

• 网关层：读超时 120–300s，上传适度放宽。
• 模型调用：重试 2–3 次，指数退避与抖动，区分可重试错误。

连接与队列

• 数据库连接池：每副本 20–50 起步，视延迟与并发调整。
• Redis 队列并发：Worker 实例并发乘以队列数，按 CPU 与 I/O 平衡。

安全与合规补充

数据生命周期

• 保留策略：原文与向量定期归档或清理，遵循最小保存期限。
• 访问边界：按租户、项目与角色隔离数据视图与操作权限。

第三方依赖

• 供应商评估：SLA、隐私条款、数据驻留、加密与安全认证。
• 密钥托管：集中化密钥管理，最小暴露，日志审计可查询。

实践范式

团队协作

• 配置即代码：所有环境变量、路由、资源配额写入版本库。
• 知识沉淀：将排错经验与运行手册放入内部文档与自动化脚本。
• 反馈闭环：从监控与工单回流到配置优化与容量规划。