#安装 Dify

本文档介绍如何使用 Helm chart 和常见配置将 Dify 部署到 Kubernetes 集群。有关 Dify 及其组件的概览，请参见 简介。该 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. 创建实例时，在 Architecture 中选择 Redis Sentinel。
2. 切换到 YAML 模式，将 spec.arch 设置为 standalone，然后创建。
3. 创建完成后，在 Alauda Container Platform 中找到名为 rfr-<Redis instance name>-read-write 的 Service 作为 Redis 主机。

#准备向量存储（用于 RAG）

此 chart 仅支持 pgvector。请使用启用了 pgvector 扩展的 PostgreSQL 实例（可以与主数据库使用同一主机，但数据库名称不同；也可以使用专用主机）。如果不使用 RAG，请将 vectorStore.type: ""，并省略 pgvector。

#准备存储（可选）

如果你为 API 和插件存储使用 PVC，则集群应具备 CSI 或预先创建的 PersistentVolumes。默认情况下，该 chart 使用 PVC；你可以在 values 中覆盖 storageClass、size 和 accessMode，或者改用兼容 S3 的对象存储（参见 存储（S3 和 PVC））。

#创建应用

1. 在 Alauda Container Platform 中，选择 Dify 将要部署到的 namespace。
2. 进入 Applications / Applications，点击 Create。
3. 选择 Create from Catalog 并进入 Catalog 视图。
4. 找到 3rdparty/chart-dify 并点击 Create。
5. 输入 Name（例如 dify），并按下面的内容配置 Custom values，然后创建。你之后可以通过应用的 Update 进行修改。

#必需配置

你至少必须配置以下内容：

1. URLs – urls.consoleUrl 和 urls.appUrl（用于浏览器访问的基础 URL，不带路径后缀；这是应用正确打开所必需的）
2. Database – PostgreSQL 12+（通过 Secret 提供主机和凭据）
3. Redis – Redis 6.0+ standalone（通过 Secret 提供主机和凭据）
4. Vector store – 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>'

最小 Custom values（填入你的主机和 Secret 名称）：

# Required: base URLs for console and app (no path suffix)
urls:
  consoleUrl: <https://console-domain>   # or http://
  appUrl: <https://app-domain>           # or http://

# Required: main database (PostgreSQL 12+)
database:
  host: <postgres-host-without-port>
  secret:
    name: <dify-db-secret>
  # Optional: enable when PostgreSQL uses SSL
  # ssl:
  #   enabled: true

# Required: Redis 6.0+ (standalone only)
redis:
  host: <redis-host-without-port>
  secret:
    name: <dify-redis-secret>

# Required: vector store (pgvector; or set vectorStore.type: "" to disable)
vectorStore:
  pgvector:
    host: <pgvector-host-without-port>
    secret:
      name: <dify-pgvector-secret>

# If your cluster has no default StorageClass, configure storage.*.pvc.storageClass
# storage:
#   api:
#     pvc:
#       storageClass: <storage-class>
#   plugin:
#     pvc:
#       storageClass: <storage-class>

#可选配置

#Database（SSL）

当 PostgreSQL 需要 SSL 连接时，请启用它：

database:
  ssl:
    enabled: true

#Vector store（禁用）

当不使用 RAG/vector search 时：

vectorStore:
  type: ""

#Ingress（host 和 TLS）

默认情况下 ingress.enabled 为 true，且 ingress.hosts[].host 可以为空（匹配所有域名）。按需设置 hostname 和 TLS：

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

#存储（S3 和 PVC）

PVC（默认）： API 和 plugin daemon 在启用时各自使用一个 PVC。可按需覆盖 storage class 和大小。

如果你的集群没有默认 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 和/或 plugin 使用 Amazon S3 或其他兼容 S3 的对象存储。创建一个包含 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>   # empty for AWS default; for custom endpoints e.g. https://object-storage.example.com:9000
      region: <region>
      bucket: <bucket>
      addressStyle: path   # "path" for many S3-compatible endpoints; "virtual" for AWS
      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 index URL：

pluginDaemon:
  pipMirrorUrl: "<mirror-url>"   # e.g. 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： 通过控制台中的 “Install via Local Package File” 安装插件。参见 Dify：安装插件。

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 且设置了 host，请使用 https://<host>（或已配置的 urls.consoleUrl / urls.appUrl）打开控制台和应用。
• 通过 Service： 否则，请使用 chart 暴露的 API 和 Web Services（例如 NodePort 或 LoadBalancer）；确保 urls.consoleUrl 和 urls.appUrl 与用户访问应用的方式一致，以便前端能够正确加载。

#用户管理

Dify 没有默认管理员密码。请在应用运行后，完成初始设置，并通过登录或注册页面创建用户（例如使用 email/password）。