安装 Dify
本指南使用 Dify Operator(一个基于 helm 的 OLM operator)在 Alauda Container Platform 上安装 Dify。请按顺序执行这些步骤——每一步都依赖于前一步。
关于 Dify 的用途及其部署的组件,请参见 简介。
目录
概览第 1 步 — 发布 Operator 包第 2 步 — 安装 Dify Operator第 3 步 — 准备外部依赖PostgreSQL(必需)Redis(必需——独立模式或 Sentinel)pgvector — 向量存储 (可选,适用于 RAG)存储 — RWX PVC 或 S3第 4 步 — 选择并设置访问方式设置 Gateway(仅限选项 B 或 C)1. 在 ACP 中注册域名2. 安装 Envoy Gateway3. 创建Gateway resource第 5 步 — 提供插件安装代理 (仅限受限网络)第 6 步 — 创建 Dify 实例创建连接 Secret填写表单第 7 步 — 登录参考:Dify 实例字段概览
第 1 步 — 发布 Operator 包
从客户支持 / Portal 下载 Dify operator 包(例如 dify-operator.alpha.ALL.v<version>.tgz),然后将其推送到平台仓库,以便它显示在 Marketplace / OperatorHub 中:
第 2 步 — 安装 Dify Operator
在 Alauda Container Platform 的 管理员视图中:
- 打开 Marketplace / OperatorHub 并选择目标集群。
- 搜索 Dify,点击 安装,并保持默认值,除非你需要使用非默认命名空间。
- 等待磁贴显示 已安装。
第 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-writeService 作为 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 如何填写。
对于 选项 A,这里无需额外设置——直接转到第 5 步。对于 选项 B 和 C,请按如下方式设置 Gateway。
设置 Gateway(仅限选项 B 或 C)
三个子步骤:在 ACP 中注册域名(含证书)→ 安装 Envoy Gateway → 创建一个引用证书 Secret 的 Gateway resource。
1. 在 ACP 中注册域名
在 管理员视图中,前往 网络管理 → 域名 → 创建域名,并填写表单:
ACP 会创建:
- global 集群上的一个
Domaincustom resource(apiVersion: crd.alauda.io/v2,cluster-scoped,带有cluster.cpaas.io/name/project.cpaas.io/name标签); - 一个位于
cpaas-system命名空间中的kubernetes.io/tlsSecret,名称为<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 中:
选项 b — 将 Gateway 放在其他命名空间中,并使用 ReferenceGrant:
对于同一个 Gateway 上的两个不同主机名的选项 C,请添加第二个 listener(每个 listener 都可以指向自己的 hostname 和 certificateRefs)。
第 5 步 — 提供插件安装代理 (仅限受限网络)
如果集群可访问公网,可跳过此步骤。否则,请准备两个可通过 HTTP 访问的代理(部署方式不限——Nginx、现有 API gateway、devpi 等均可):
- Marketplace 反向代理 — 代理到
https://marketplace.dify.ai,并保留Host: marketplace.dify.aiheader。记录其 Service URL。 - PyPI 镜像 — 提供一个 PyPI simple index(例如代理
https://mirrors.aliyun.com/pypi/simple/,或任意 PyPI cache)。记录其 Service URL。
Marketplace 代理 URL 必须是 FQDN(例如 http://dify-marketplace-proxy.<ns>.svc.cluster.local)——Dify 的内部 SSRF 代理(squid)无法解析集群内的短名称。
第 6 步 — 创建 Dify 实例
创建连接 Secret
填写表单
在 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 视图对应的相同配置示例:
第 7 步 — 登录
- 等待 Dify 实例报告其工作负载为
Ready。 - 在浏览器中打开 Console URL;Dify 在首次登录时会提示进行初始管理员设置(邮箱 + 密码)。
- 登录后,可在控制台中创建其他用户。
- 访问 App URL 以确认已发布应用的访问是否正常(可先从控制台发布一个快速测试应用进行验证)。
参考:Dify 实例字段
Secret 键约定: