#安装 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. 创建实例时，在 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 和 plugin 存储使用 PVC，集群应具备 CSI 或预先创建好的 PersistentVolumes。默认情况下该 chart 使用 PVC；您可以在 values 中覆盖 storageClass、size 和 accessMode，或者改用兼容 S3 的对象存储（参见 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 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>'

最小自定义 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>

#可选配置

#数据库（SSL）

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

database:
  ssl:
    enabled: true

#向量存储（禁用）

当不使用 RAG/vector search 时：

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 和 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 中配置自定义 key）：

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 install mirror（代理）

当集群无法访问 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: 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 Services（例如 NodePort 或 LoadBalancer）；并确保 urls.consoleUrl 和 urls.appUrl 与用户访问应用的方式一致，以便前端能够正确加载。

#用户管理

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