#安装 Dify

本文档介绍如何使用 Helm Chart 和常见配置将 Dify 部署到 Kubernetes 集群。有关 Dify 及其组件的概述，请参见 Introduction。该 Chart 仅部署 Dify 组件；PostgreSQL、Redis 和向量存储需外部提供并在 values 中配置。

#概述

该 Chart 以独立工作负载的形式运行以下组件：

• API – 后端 API 和业务逻辑
• Worker – 用于异步任务的 Celery worker
• Worker Beat – 用于定时任务的 Celery beat
• Web – 前端 UI
• Plugin Daemon – 插件运行时
• Sandbox – 隔离代码执行环境
• SSRF Proxy – 基于 Squid 的出站请求代理

#前提条件

• Kubernetes 1.19+
• 暴露 Ingress 时需 Ingress controller（如 nginx-ingress-controller）
• 外部 PostgreSQL 12+（该 Chart 仅支持 PostgreSQL）
• 外部 Redis 6.0+（仅支持 standalone，不支持 Sentinel 和 Cluster）
• RAG 场景：需带 pgvector 扩展的 PostgreSQL，或设置 vectorStore.type: "" 禁用

#下载

下载 Dify 安装包：dify.ALL.xxxx.tgz

使用 violet 命令推送到平台仓库：

violet push --platform-address=platform-access-address --platform-username=platform-admin --platform-password=platform-admin-password dify.ALL.xxxx.tgz

#部署

#准备数据库

使用 PostgreSQL 12+。该 Chart 仅支持 PostgreSQL。可以通过 Data Services 中的 PostgreSQL operator 创建 PostgreSQL 集群，并从实例详情中获取主机和凭据。

#准备 Redis

仅支持 Redis 6.0+ 的 standalone 模式（不支持 Sentinel 和 Cluster）。可以通过 Data Services 创建 Redis 实例。使用 standalone 模式步骤：

1. 创建实例时，架构选择 Redis Sentinel。
2. 切换到 YAML 模式，将 spec.arch 设置为 standalone，然后创建。
3. 创建完成后，在 Alauda Container Platform 中找到名为 rfr-<Redis 实例名>-read-write 的 Service，作为 Redis 主机。

#准备向量存储（RAG 场景）

该 Chart 仅支持 pgvector。使用带 pgvector 扩展的 PostgreSQL 实例（可与主数据库同主机但不同数据库名，或独立主机）。不使用 RAG 时，设置 vectorStore.type: "" 并省略 pgvector。

#准备存储（可选）

如果 API 和插件存储使用 PVC，集群应具备 CSI 或预创建 PersistentVolumes。默认 Chart 使用 PVC，可在 values 中覆盖 storageClass、size 和 accessMode，或改用 S3/MinIO（详见 Storage (S3 and PVC)）。

#创建原生应用

1. 在 Alauda Container Platform 中选择部署 Dify 的命名空间。
2. 进入 Applications / Applications，点击 Create。
3. 选择 Create from Catalog，进入 Catalog 视图。
4. 找到 3rdparty/chart-dify 并点击 Create。
5. 输入 Name（如 dify），并按下述配置 Custom 值后创建。后续可通过应用的 Update 修改配置。

#必填配置

必须配置至少：

1. URLs – urls.consoleUrl 和 urls.appUrl（浏览器访问的基础 URL，无路径后缀；应用正确打开所必需）
2. 数据库 – PostgreSQL 12+（主机和凭据通过 Secret）
3. Redis – Redis 6.0+ standalone（主机和凭据通过 Secret）
4. 向量存储 – pgvector（主机和凭据通过 Secret），或设置 vectorStore.type: "" 禁用

#最小必填值

创建 Secret（替换占位符为实际值）：

kubectl create secret generic dify-db-secret --from-literal=password='<db-password>'
kubectl create secret generic dify-redis-secret --from-literal=password='<redis-password>'
kubectl create secret generic dify-pgvector-secret --from-literal=password='<pgvector-password>'

最小自定义值（填写你的主机和 Secret 名称）：

# 必填：控制台和应用的基础 URL（无路径后缀）
urls:
  consoleUrl: <https://console-domain>   # 或 http://
  appUrl: <https://app-domain>           # 或 http://

# 必填：主数据库（PostgreSQL 12+）
database:
  host: <postgres-host-without-port>
  secret:
    name: <dify-db-secret>
  # 可选：PostgreSQL 使用 SSL 时启用
  # ssl:
  #   enabled: true

# 必填：Redis 6.0+（仅 standalone）
redis:
  host: <redis-host-without-port>
  secret:
    name: <dify-redis-secret>

# 必填：向量存储（pgvector；或设置 vectorStore.type: "" 禁用）
vectorStore:
  pgvector:
    host: <pgvector-host-without-port>
    secret:
      name: <dify-pgvector-secret>

# 如果集群无默认 StorageClass，需配置 storage.*.pvc.storageClass
# storage:
#   api:
#     pvc:
#       storageClass: <storage-class>
#   plugin:
#     pvc:
#       storageClass: <storage-class>

#可选配置

#数据库（SSL）

PostgreSQL 需要 SSL 连接时启用：

database:
  ssl:
    enabled: true

#向量存储（禁用）

不使用 RAG/向量搜索时：

vectorStore:
  type: ""

#Ingress（主机和 TLS）

默认 ingress.enabled 为 true，ingress.hosts[].host 可为空（匹配所有域）。需要时设置主机名和 TLS：

ingress:
  className: <ingress-class>
  hosts:
    - host: <dify.example.com>
  tls:
    - secretName: <dify-tls>
      hosts:
        - <dify.example.com>

#存储（S3 和 PVC）

PVC（默认）： API 和插件守护进程启用时各使用一个 PVC。根据需要覆盖存储类和大小。

无默认 StorageClass 时，每个 PVC 需配置 storageClass：

storage:
  api:
    type: opendal
    pvc:
      enabled: true
      size: 10Gi
      storageClass: <storage-class>
      accessMode: ReadWriteOnce
  plugin:
    type: local
    pvc:
      enabled: true
      size: 10Gi
      storageClass: <storage-class>
      accessMode: ReadWriteOnce

S3（对象存储）： API 和/或插件可使用 S3 或兼容 MinIO 的存储。创建包含 ACCESS_KEY 和 SECRET_KEY 的 Secret（或在 values 中配置自定义密钥）：

kubectl create secret generic <dify-s3-secret> --from-literal=ACCESS_KEY='<access-key>' --from-literal=SECRET_KEY='<secret-key>'

storage:
  api:
    type: s3
    s3:
      endpoint: <s3-endpoint>   # AWS 默认为空；MinIO 例如 http://minio:9000
      region: <region>
      bucket: <bucket>
      addressStyle: path   # MinIO 用 "path"；AWS 用 "virtual"
      secret:
        name: <dify-s3-secret>
  plugin:
    type: s3
    s3:
      endpoint: <s3-endpoint>
      region: <region>
      bucket: <bucket>
      secret:
        name: <dify-s3-secret>

#PIP 安装镜像（代理）

集群无法访问 PyPI（如离线或网络受限）时，为 Plugin Daemon（插件依赖）和/或 Sandbox（代码执行）设置 PIP 索引 URL：

pluginDaemon:
  pipMirrorUrl: "<mirror-url>"   # 例如 https://mirrors.aliyun.com/pypi/simple/

sandbox:
  pipMirrorUrl: "<mirror-url>"

简单自建 PyPI 代理可用 devpi；然后将 pipMirrorUrl 设置为该代理 URL（如 http://<host>:3141/root/pypi/+simple/）。

#Marketplace（内网）

集群无法访问公共 marketplace (https://marketplace.dify.ai) 时：

方案 1 – 禁用 marketplace： 在控制台通过“通过本地包文件安装”安装插件。详见 Dify: Installing the Plugin。

api:
  marketplace:
    enabled: false

方案 2 – 内部 marketplace 代理： 部署反向代理到 https://marketplace.dify.ai（上游需 Host: marketplace.dify.ai），并设置：

api:
  marketplace:
    enabled: true
    url: <https://internal-marketplace.example.com>

#访问

• 通过 Ingress： 启用 Ingress 且设置了主机时，使用 https://<host>（或配置的 urls.consoleUrl / urls.appUrl）打开控制台和应用。
• 通过 Service： 否则使用 Chart 暴露的 API 和 Web 服务（如 NodePort 或 LoadBalancer）；确保 urls.consoleUrl 和 urls.appUrl 与用户访问方式匹配，保证前端正确加载。

#用户管理

Dify 无默认管理员密码。应用运行后，完成初始设置并在登录或注册页面创建用户（如邮箱/密码）。