安装 Dify

本指南使用 Dify Operator(一个基于 helm 的 OLM operator)在 Alauda Container Platform 上安装 Dify。请按顺序执行这些步骤——每一步都依赖于前一步。

关于 Dify 的用途及其部署的组件,请参见 简介。

概览

你需要原因
Dify operator 包(.tgz)通过 violet 推送,使该 operator 显示在 OperatorHub 中
外部 PostgreSQL 12+Dify 的主数据库(仅支持 PostgreSQL)
外部 Redis 6+(独立模式或 Sentinel)缓存 + Celery broker;不支持 Cluster 模式
外部 pgvector (可选)用于 RAG 的向量存储;如果不使用 RAG,可禁用
RWX PVC 或 S3 兼容存储为 API + Plugin Daemon 提供共享的可写存储
浏览器的一个访问方式任选其一:NodePort/Service、单域名或双域名。域名和 TLS 证书通过 ACP 网络管理进行注册。参见 第 4 步
集群内代理 (仅限受限网络)一个 Marketplace 反向代理 + 一个 PyPI 镜像,以便插件可离线安装

第 1 步 — 发布 Operator 包

从客户支持 / Portal 下载 Dify operator 包(例如 dify-operator.alpha.ALL.v<version>.tgz),然后将其推送到平台仓库,以便它显示在 Marketplace / OperatorHub 中:

violet push \
  --platform-address=<platform-access-address> \
  --platform-username=<platform-admin> \
  --platform-password=<platform-admin-password> \
  dify-operator.alpha.ALL.v<version>.tgz

第 2 步 — 安装 Dify Operator

在 Alauda Container Platform 的 管理员视图中:

  1. 打开 Marketplace / OperatorHub 并选择目标集群。
  2. 搜索 Dify,点击 安装,并保持默认值,除非你需要使用非默认命名空间。
  3. 等待磁贴显示 已安装。

第 3 步 — 准备外部依赖

PostgreSQL(必需)

使用 PostgreSQL 12+。最简单的方式是使用 Data Services 中的 PostgreSQL operator:创建一个集群,然后为 Dify 创建一个空数据库(例如 dify)。记录主机、端口、用户名和密码。

Redis(必需——独立模式或 Sentinel)

使用 Redis 6.0+。通过 Data Services 创建。

  • 独立模式: 使用 Redis Sentinel 架构创建,切换到 YAML,设置 spec.arch: standalone,然后创建。使用 rfr-<instance>-read-write Service 作为 Redis 主机。
  • Sentinel(HA): 保持 Sentinel 架构;在 第 6 步 中使用 Sentinel Service 端点 + 主节点名称。

pgvector — 向量存储 (可选,适用于 RAG)

仅支持 pgvector。请使用安装了 pgvector 扩展的 PostgreSQL 实例。它可以与主数据库共享同一个主机(不同的数据库名),也可以使用独立主机。如果不使用 RAG,请跳过。

存储 — RWX PVC 或 S3

API、Worker、Worker-Beat 和 Plugin Daemon 需要共享的可写存储:

  • 一个在各工作负载之间共享的 ReadWriteMany (RWX) StorageClass,或者
  • 一个 S3 兼容对象存储(MinIO、AWS S3、OBS 等)——在没有 RWX class 可用时推荐使用。

记录 StorageClass 名称,或 S3 endpoint + region + bucket + 访问密钥。

第 4 步 — 选择并设置访问方式

Dify 面向浏览器,并且有两个访问面,因此 Dify 实例有两个 URL 字段:

  • Console URL — 管理员 / 应用创建者使用的构建 UI(构建应用、配置模型、管理知识库)。
  • App URL — 最终用户打开的已发布应用(聊天 / Agent 页面,例如 /chat/<code>)。

这两个 URL 都必须与用户实际访问 Dify 的方式一致,否则前端无法加载。请选择下面三种方案之一——每种方案都说明了需要准备什么,以及这两个 URL 如何填写。

选项适用场景需要准备的内容Console URL / App URL
A. NodePort / Service IP开发 / 内部环境;没有域名无两者都设置为 http://<node-ip>:<nodeport>(两者使用同一个地址)
B. 单域名两个访问面使用同一个主机名1 个 ACP Certificate + 1 个 ACP Domain;Envoy Gateway + 一个 Gateway resource两者都设置为 https://<host>
C. 双域名生产环境——管理员与最终用户分离访问(不同的 DNS / 证书 / 网络暴露)1 个 ACP Certificate(可同时覆盖两个域名,例如泛域名)+ 2 个 ACP Domains;Envoy Gateway + 一个 Gateway resourceConsole URL = https://<console-host>,App URL = https://<app-host>

对于 选项 A,这里无需额外设置——直接转到第 5 步。对于 选项 B 和 C,请按如下方式设置 Gateway。

设置 Gateway(仅限选项 B 或 C)

三个子步骤:在 ACP 中注册域名(含证书)→ 安装 Envoy Gateway → 创建一个引用证书 Secret 的 Gateway resource。

1. 在 ACP 中注册域名

在 管理员视图中,前往 网络管理 → 域名 → 创建域名,并填写表单:

字段值
类型Domain(特定主机名)或 Wildcard Domain(*.example.com)
域名主机名,例如 dify-console.example.com
分配集群目标集群 + 项目(或所有项目)
证书直接将 Public Key(tls.crt)和 Private Key(tls.key)粘贴到表单中——ACP 会自动创建绑定的 TLS Secret

ACP 会创建:

  • global 集群上的一个 Domain custom resource(apiVersion: crd.alauda.io/v2,cluster-scoped,带有 cluster.cpaas.io/name / project.cpaas.io/name 标签);
  • 一个位于 cpaas-system 命名空间中的 kubernetes.io/tls Secret,名称为 <domain>-<random>(例如 dify-console.example.com-xfd8x);Domain 的 cpaas.io/secret-ref 注解会记录这个名称。

你可以在 Domain 详情页中找到 Secret 名称。完整 UI 参考:配置域名。

然后,将该主机名的 DNS 解析到集群的负载均衡地址。

对于选项 C 中的第二个主机名,重复以上步骤。一个覆盖两个主机名的证书(例如泛域名证书)可以重复使用——在两个 Domain 表单中粘贴相同的证书,或者通过 网络管理 → 证书 先导入一次证书,再在创建域名时选择它(参见 创建证书)。

2. 安装 Envoy Gateway

ACP 包含 Alauda Build of Envoy Gateway operator。如果尚未安装,请从 Marketplace / OperatorHub 中安装——参见 安装 Envoy Gateway operator。

3. 创建 Gateway resource

引用子步骤 1 中的证书 Secret。由于这些 Secret 位于 cpaas-system 中,而 Gateway listener 的 certificateRefs 默认只会解析 Gateway 自身命名空间中的 Secret,因此你有两个等价选项:

  • 更简单的方式——将 Gateway 放在 cpaas-system 中,这样可以直接引用这些 Secret。
  • 跨命名空间方式——将 Gateway 保留在自己的命名空间中,并在 cpaas-system 中添加一个 ReferenceGrant,允许你的 Gateway 命名空间引用其中的 Secret。

选项 a — 将 Gateway 放在 cpaas-system 中:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: dify
  namespace: cpaas-system                 # co-located with the cert Secrets
spec:
  gatewayClassName: <envoy-gateway-class> # the GatewayClass exposed by Envoy Gateway
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"           # cover all hostnames registered in sub-step 1
      tls:
        mode: Terminate
        certificateRefs:
          - {name: <secret-name-from-ACP-domain>}   # from the Domain detail page
      allowedRoutes:
        namespaces:
          from: All

选项 b — 将 Gateway 放在其他命名空间中,并使用 ReferenceGrant:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: dify
  namespace: <gateway-namespace>
spec:
  gatewayClassName: <envoy-gateway-class>
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - {namespace: cpaas-system, name: <secret-name-from-ACP-domain>}
      allowedRoutes:
        namespaces:
          from: All
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: dify-tls
  namespace: cpaas-system                 # grant lives in the Secret's namespace
spec:
  from:
    - {group: gateway.networking.k8s.io, kind: Gateway, namespace: <gateway-namespace>}
  to:
    - {group: "", kind: Secret}            # could also restrict by name

对于同一个 Gateway 上的两个不同主机名的选项 C,请添加第二个 listener(每个 listener 都可以指向自己的 hostname 和 certificateRefs)。

第 5 步 — 提供插件安装代理 (仅限受限网络)

如果集群可访问公网,可跳过此步骤。否则,请准备两个可通过 HTTP 访问的代理(部署方式不限——Nginx、现有 API gateway、devpi 等均可):

  • Marketplace 反向代理 — 代理到 https://marketplace.dify.ai,并保留 Host: marketplace.dify.ai header。记录其 Service URL。
  • PyPI 镜像 — 提供一个 PyPI simple index(例如代理 https://mirrors.aliyun.com/pypi/simple/,或任意 PyPI cache)。记录其 Service URL。
WARNING

Marketplace 代理 URL 必须是 FQDN(例如 http://dify-marketplace-proxy.<ns>.svc.cluster.local)——Dify 的内部 SSRF 代理(squid)无法解析集群内的短名称。

第 6 步 — 创建 Dify 实例

创建连接 Secret

# DB / Redis / pgvector passwords are read from key `password`
kubectl create secret generic dify-db       --from-literal=password='<db-password>'
kubectl create secret generic dify-redis    --from-literal=password='<redis-password>'    # omit if Redis has no auth
kubectl create secret generic dify-pgvector --from-literal=password='<pgvector-password>'
# S3 only — keys must be `accessKey` / `secretKey`
kubectl create secret generic dify-s3 --from-literal=accessKey='<ak>' --from-literal=secretKey='<sk>'

填写表单

在 OperatorHub → 已安装的 operator 中,选择 Dify,点击 创建 Dify,然后填写表单。字段分为以下几组:

  • Access — 根据第 4 步中选择的方案设置 Console URL 和 App URL(方案 A 和 B 中两者使用相同值;方案 C 中使用两个不同的主机名)。包含 scheme(NodePort 使用 http://,Gateway 使用 https://)。
  • Database — 主机、端口、用户名(默认 postgres)、数据库名,以及 DB Secret(dify-db)。如果你的 PostgreSQL 需要 SSL,请切换 SSL。
  • Redis — 选择 Standalone 或 Sentinel。
    • Standalone: 主机、端口、Redis Secret(如果没有认证则留空)。
    • Sentinel: 以逗号分隔的 host:port 列表、Master name、Redis Secret,以及如果 Sentinel 本身需要认证时的 Sentinel Secret。
  • Vector store (pgvector) — 切换 Enable。启用后:主机、端口、用户名、数据库名、Vector Secret。
  • Storage — 选择 PVC 或 S3。
    • PVC: RWX StorageClass 和大小。
    • S3: endpoint、region、API bucket、Plugin bucket、S3 Secret(dify-s3),以及 Path-style addressing(对 MinIO 和大多数 S3-compatible endpoint 设为 ON;对 AWS 设为 OFF)。
  • HTTP Route — 仅在使用 Gateway(选项 B 或 C)时需要。 设置 Gateway name、Gateway namespace、可选的 Section name(listener)以及 Hostnames(必须被 Gateway listener 覆盖)。
  • Advanced → Plugin proxy — 仅适用于受限网络集群。 将 Marketplace 设为 ON,并使用第 5 步中的代理填写 Marketplace URL(必须是 FQDN)。填写 PIP Mirror URL。打开 Ignore uv lock(否则 uv sync --frozen 会绕过镜像)。对于较慢的镜像,可将 Plugin init timeout 调大(例如 1200s)。如果你提供的是重新打包的插件,则将 Verify plugin signature 设为 OFF。

以下是与表单 YAML 视图对应的相同配置示例:

consoleUrl: https://dify-console.example.com
appUrl:     https://dify-app.example.com

database:
  host: <postgres-host>
  port: 5432
  username: postgres
  name: dify
  secret: dify-db
  sslEnabled: false

redis:
  mode: standalone               # standalone | sentinel
  host: <redis-host>
  port: 6379
  secret: dify-redis             # omit if no auth
  cacheDB: 0
  brokerDB: 1

vectorStore:
  enabled: true                  # set false to disable RAG
  host: <pgvector-host>
  port: 5432
  username: postgres
  name: dify_vector
  secret: dify-pgvector

storage:
  type: PVC                      # PVC | S3
  storageClass: <rwx-storage-class>
  size: 20Gi

httpRoute:                       # Option B / C only
  gatewayName: dify
  gatewayNamespace: <gateway-namespace>
  hostnames:
    - dify-console.example.com
    - dify-app.example.com

proxy:                           # restricted network only
  marketplace: true
  marketplaceURL: http://dify-marketplace-proxy.<ns>.svc.cluster.local
  pipMirrorUrl:   http://dify-pip-proxy.<ns>.svc.cluster.local/pypi/simple/
  ignoreUvLock: true
  pluginInitTimeout: 1200
  verifyPluginSignature: false

第 7 步 — 登录

  1. 等待 Dify 实例报告其工作负载为 Ready。
  2. 在浏览器中打开 Console URL;Dify 在首次登录时会提示进行初始管理员设置(邮箱 + 密码)。
  3. 登录后,可在控制台中创建其他用户。
  4. 访问 App URL 以确认已发布应用的访问是否正常(可先从控制台发布一个快速测试应用进行验证)。

参考:Dify 实例字段

字段表单分组作用
consoleUrlAccess构建 UI 的浏览器 URL
appUrlAccess已发布应用的浏览器 URL
database.{host, port, username, name, secret, sslEnabled}Database外部 PostgreSQL 连接。secret 保存键 password。
redis.{mode, host, port, sentinels, masterName, secret, sentinelSecret, cacheDB, brokerDB, sslEnabled}Redismode = standalone 或 sentinel
vectorStore.{enabled, host, port, username, name, secret}Vector storepgvector
storage.{type, storageClass, size, endpoint, apiBucket, pluginBucket, s3Secret, region, s3PathStyle}Storagetype = PVC 或 S3
httpRoute.{gatewayName, gatewayNamespace, sectionName, hostnames}HTTP RouteGateway API 暴露;NodePort 时省略
proxy.{marketplace, marketplaceURL, pipMirrorUrl, ignoreUvLock, pluginInitTimeout, verifyPluginSignature}Advanced — Plugin proxy受限网络下的插件安装

Secret 键约定:

Secret 字段Secret 必须包含的 key
database.secret / redis.secret / redis.sentinelSecret / vectorStore.secretpassword
storage.s3SecretaccessKey, secretKey