Dify Enterprise Edition 部署指南（AWS）
本文档介绍如何在 AWS 云环境中部署 Dify 企业版。您可以选择以下任一方式完成部署：- 通过 Terraform（推荐）
- 通过 CDK（已废弃，不再推荐）
- 手动创建基础设施并部署（不推荐）
选项一：通过 Terraform 构建
Terraform 脚本已开源，请访问 langgenius/dify-ee-terraform-aws 获取最新版本与使用说明。
前提条件
- 本地已安装
kubectl、helm和aws cli。 - 拥有具备创建以下资源权限的 AWS 账号。
- AWS EKS（Elastic Kubernetes Service）：用于部署 Dify 核心服务，节点需能访问互联网或配置 NAT Gateway
- AWS S3（Simple Storage Service）：用于持久化存储
- AWS ECR（Elastic Container Registry）：用于 Dify 插件安装，也可用于托管 Dify 镜像与 Helm Chart
- AWS RDS Aurora Postgres：关系数据库，用于存储应用数据和审计记录
- AWS OpenSearch：向量数据库，用于 RAG（检索增强生成）相关功能
- Amazon ElastiCache：托管 Redis 缓存服务，用于加速数据访问
选项二：通过 CDK 构建（已废弃）
⚠️ 已废弃： CDK 部署方式不再推荐使用，新部署请优先选择 Terraform。仓库 aws-cdk-for-dify 仅作为历史参考保留，不再持续更新。
选项三：手动创建基础设施并部署
1. 创建基础设施
请参考下表推荐的配置，根据实际需求创建基础设施。（请将双括号中的内容替换为实际值）版本说明（重要）： 下表中的版本以“可用范围/版本系列”为参考。在实际部署前，请务必在目标 AWS Region 的控制台或通过 AWS CLI 校验对应服务当前支持的版本（EKS Kubernetes、Aurora PostgreSQL、OpenSearch、ElastiCache Redis 等），避免因区域差异或版本下线导致无法创建资源。
测试环境基础设施配置参考
注意： 若在单节点上启用 unstructured 服务，需将磁盘容量提升至 40 GB。
生产环境基础设施配置参考
此外，您还需要创建适当的虚拟私有云（VPC）和安全组（SG）以确保基础设施的安全性。
2. 配置 values.yaml
完成数据库、S3 等基础设施的创建后，请参考以下示例配置values.yaml（将双括号中的内容替换为实际值）。在此之前，您需要先在数据库中创建 dify、enterprise、audit、dify_plugin_daemon 四个数据库，并相应替换 values.yaml 中的 rds_main_database_name 等配置项。
3.9.x 注意事项（按补丁版本区分）：
- ⚠️ 已知问题：AWS S3 的
persistence.s3.endpoint必须留空（3.9.0 / 3.9.1 均受影响）。 3.9.x 在使用useAwsS3: true+useAwsManagedIam: true时，若同时填写了endpoint，插件安装会失败。使用 AWS S3 时请将endpoint置为""，让 SDK 自动推导区域域名。下方示例已置空。使用 S3 兼容的非 AWS 对象存储（MinIO、OSS 等）不受此问题影响。- ⚠️ 已知问题：3.9.0 / 3.9.1 使用 OpenSearch 作为向量库时，无法上传文件到知识库。 请联系 Dify 技术支持团队获取 hotfix 镜像。
- 数据库配置结构变更（3.9.0 起，3.9.1 未回滚）： 旧的
externalPostgres配置块已被externalDatabase取代。新结构支持 Postgres / MySQL / TiDB 三种引擎，并在顶层统一指定user/password；所有逻辑数据库（dify、enterprise、audit、plugin_daemon）默认共享这一组凭证。该重命名在 3.9.1 中没有回滚，3.9.x 全系都使用externalDatabase。- 按数据库覆写凭证
databaseCredentials（3.9.1+ 新增）： 从 3.9.1 起，externalDatabase下新增databaseCredentials子块，可为单个逻辑数据库单独指定user/password，覆盖顶层全局凭证；留空或未配置时回落到全局凭证。3.9.0 不支持databaseCredentials，只能使用顶层全局user/password。下方示例已使用新结构，databaseCredentials部分默认注释，3.9.1+ 按需启用。- 内置 MinIO 子 chart 移除（3.9.0 起）： 外部对象存储（此处使用 S3）现为必需项。
- 首次部署的探针延迟： API Pod 的就绪/存活探针会留出最长约 5 分钟用于 Pod 内数据库迁移完成（
api.readinessProbe.initialDelaySeconds=120、api.livenessProbe.initialDelaySeconds=300）。在helm install后 API Pod 启动较慢属于预期行为。
3. 配置 S3 和 ECR 权限
为确保 Dify 服务正常启动及插件系统正常运行，api、worker、workerBeat、plugin_daemon、plugin_connector Deployment 需要 S3 访问权限；通过 DifyPlugin CR 派生的插件构建 / 运行时 Pod 还需要 ECR 推送 / 拉取权限。关于这些服务需要相关权限的具体原因，将在后文详细说明。
您可以通过以下两种方式配置权限：
- IRSA 模式：IAM Roles for Service Accounts，实现安全、精细的权限控制（推荐）
- Access Key（AK/SK）模式：通过环境变量提供凭证
IRSA 模式配置
Dify 推荐使用 IRSA 配置 ServiceAccount 权限。您可联系 Dify 技术支持团队获取一键部署(one_click) IRSA 脚本。 IRSA 通过 OIDC Provider 建立 EKS 集群与 IAM 之间的信任关系，使 Pod 能够通过 ServiceAccount 安全获取 AWS 权限，无需在 Pod 中配置 Access Key。整体架构如下：注意（3.9.x）： Helm chart 会额外自动创建两个 ServiceAccount ——以下是 Dify 企业版所需的 ServiceAccount 权限说明：dify-plugin-controller-sa（由dify-crd-controllerDeployment 使用）和dify-plugin-manager-sa（由 3.9.x 新增的dify-plugin-managerDeployment 使用）。这两个 SA 均不需要 IRSA 角色绑定 —— 它们只需要集群内 Kubernetes RBAC（命名空间级Role，用于管理 CRD / Deployment / Job / Service / ConfigMap），chart 会一并创建好。请勿为它们添加eks.amazonaws.com/role-arn注解。
💡 关于 CRD 安装的特殊说明 Dify 企业版在安装时仅需 namespace 级别权限。但由于 CRD 本身是集群级别资源，安装时需要相应的集群权限。如果没有集群级别权限，可以先单独安装 CRD，再安装其余组件。CRD 本身只是注册到 Kubernetes 中的 API 结构声明，当其对应的 Controller 为 namespace 级别时，不具备跨 namespace 访问或修改其他资源的能力。
步骤 1：验证 IAM OIDC Provider
在配置 IRSA 之前，请确保集群已启用 IAM OIDC Provider。如果是手动创建的集群，建议通过eksctl 命令行工具来启用或验证。IAM OIDC Provider 建立了信任关系，允许 EKS 集群向 IAM 证明 Pod 的身份，从而让 Pod 能够安全地获取 AWS 权限。
步骤 2：创建 AWS IAM 策略
需要创建以下三个 IAM 策略： 策略 1：S3 访问策略（名称可自定义，如DifyS3Policy）
DifyECRPolicy）
用于插件镜像的推送和管理，包含 ECR 认证、仓库管理、镜像推送以及审计日志权限：
策略 3：ECR 只读拉取策略（名称可自定义，如{your_ecr_repo_prefix}为您的 ECR 仓库名称前缀。例如您在步骤 5 中配置imageRepoPrefix为123456789.dkr.ecr.us-east-1.amazonaws.com/dify-ee，则此处 ECR 仓库前缀为dify-ee，对应 Resource 应填写arn:aws:ecr:us-east-1:123456789:repository/dify-ee*。
DifyECRPullOnlyPolicy）
仅用于拉取插件运行时镜像：
步骤 3：创建 AWS IAM 角色
创建以下三个角色，并将步骤 2 中的策略附加到对应角色上（角色名称可自定义）：
获取对应的角色 ARN：
请将{oidc_id}替换为 EKS 集群的 OIDC Provider ID。可通过以下命令获取：
步骤 4：将角色绑定到 EKS 的 ServiceAccount
ServiceAccount（SA）是一种机制，允许 EKS 中的 Pod 获取特定的 AWS 权限，以访问云资源（如 S3）。创建以下四个 ServiceAccount，并将对应的角色 ARN 添加到
eks.amazonaws.com/role-arn 注解中。只有这四个 SA 需要 IRSA 绑定 —— dify-plugin-controller-sa 与 dify-plugin-manager-sa 由 Helm 自动创建，仅 RBAC，无需任何 role-arn。
创建 ServiceAccount 的示例命令（请将
$DIFY_EE_* 替换为步骤 3 中获取的角色 ARN）：
可选 —— 部分 Terraform 模块提供的替代命名。 较新版本的 Dify Terraform 模块会同时创建dify-plugin-build-sa（S3+ECR 角色）与dify-plugin-build-run-sa（ECR 拉取角色），作为上述两个 IAM 角色语义更清晰的备选名。Helm chart 默认不引用这两个名字 —— 若要启用，请在values.yaml中设置plugin_connector.customServiceAccount: "dify-plugin-build-sa"及plugin_connector.runnerServiceAccount: "dify-plugin-build-run-sa"（chart 会把这两个值写入每个 DifyPlugin CR，进而绑定到构建 / 运行时 Pod 上）。只要values.yaml里配置的名字与实际带正确 role-arn 的 SA 一致，两套命名都可工作。
步骤 5：在 values.yaml 中配置 ServiceAccount
修改 Helm 的values.yaml，添加以下配置（以下仅展示 ServiceAccount 和 ECR 相关配置，其他配置省略）。imageRepoPrefix 可自定义：
‼️dify-plugin-connector-sa由 Helm 为plugin_connectorDeployment 自动创建（安装后为其补上 S3 的 role-arn 注解即可）。dify-plugin-crd-sa与dify-plugin-runner-sa并非由任一 Deployment 直接挂载 —— 它们通过上方plugin_connector.customServiceAccount/runnerServiceAccount被 chart 写入每一个 DifyPlugin CR，真正消费 IRSA 权限的是 CR 派生出的构建 / 运行时 Pod。dify-plugin-controller-sa与dify-plugin-manager-sa（dify-crd-controller和dify-plugin-managerDeployment 自身的 SA）由 Helm 创建且仅用 RBAC —— 请勿为plugin_controller/plugin_manager显式设置serviceAccountName，也请勿为这两个 SA 添加 role-arn。
‼️ 关于additionalWorkers与 IRSA。 Helm chart 的模板不会把worker.serviceAccountName传播到additionalWorkers的各条目里（见templates/additional-worker-deployment.yaml）。如果您确实需要启用某个additionalWorkers[*]条目（例如在大规模部署中做队列隔离），必须：(1) 在主worker块上覆写worker.celeryQueues，去掉已拆分出去的队列，否则两个 Deployment 会争抢同一队列，导致重复消费；以及 (2) 为每个启用的条目显式设置additionalWorkers[i].serviceAccountName: "dify-api-sa"，否则 worker pod 无法通过 IRSA 访问 S3。
Access Key 模式配置
步骤 1：准备凭证
创建一个仅具备 S3 和 ECR 权限的 IAM 用户，并获取其 Access Key 和 Secret Key。步骤 2：创建 Kubernetes Secret
values.yaml 中的 imageRepoSecret 配置给 plugin_connector 服务。
步骤 3：配置 values.yaml
4. 安装 AWS ALB（Application Load Balancer）
为使 Dify 企业版可通过域名访问，您需要安装 AWS ALB（Application Load Balancer）。您也可以选择使用 Nginx Ingress Controller 或其他 Ingress Controller。推荐使用 AWS ALB，因为它能与 Dify 企业版无缝集成，并提供更好的性能和可扩展性。 请访问 https://docs.aws.amazon.com/eks/latest/userguide/lbc-manifest.html 获取 AWS ALB 安装指南。如果无法安装 AWS ALB，可使用 Nginx Ingress Controller 作为备选方案：AWS ALB 安装完成后，可通过以下命令确认服务是否正常运行：
values.yaml 中配置 Ingress：
global 配置中启用 TLS。您可通过 AWS Certificate Manager 验证域名并创建证书。
5. 执行安装
请访问 https://langgenius.github.io/dify-helm/#/ 获取详细的安装说明。
‼️ 不建议将 Dify 安装在 default 命名空间中。
6. 验证服务状态
- 更新 kubectl 访问凭证：
- 验证 EKS 节点已正常启动：
- 验证 Dify 服务运行状态：
- 确认 ALB 是否正常工作：
‼️ 请将上述命令输出的 DNSName 配置为 CNAME 记录，解析到 Dify 所需的各个域名。
7. 初始化服务
至此安装完成。请访问 enterprise.dify.yourdomain.com 登录 Dify 企业版管理后台，进行后续配置和使用。已知问题（3.9.0 / 3.9.1）
以下问题影响 Dify 企业版 3.9.0 和 3.9.1。上文相关配置处已就近标注，这里再次集中列出，便于查阅。1. 使用 AWS S3 时 persistence.s3.endpoint 必须留空
当 useAwsS3: true 且 useAwsManagedIam: true 时，给 persistence.s3.endpoint 填入非空值会导致插件安装失败。请将其设置为 ""，让 AWS SDK 按 Region 自动推导终端节点：
2. 使用 OpenSearch 作为向量数据库时无法上传文件到知识库
当vectorDB.externalType: "opensearch" 时，无法上传文件到知识库。
临时方案： 联系 Dify 技术支持团队获取 hotfix 镜像。