使用 AWS CDK 一键部署高可用 Dify Enterprise 生产环境

1. 项目概述：为什么选择 AWS CDK 部署 Dify Enterprise？

如果你正在寻找一个开箱即用、能快速构建和部署 AI 应用的企业级平台，Dify 绝对是一个绕不开的选择。它把大模型应用开发中那些繁琐的环节——比如工作流编排、知识库管理、API 集成——都封装成了可视化的操作，让开发者能更专注于业务逻辑本身。然而，当你想把 Dify 从本地测试环境搬到生产环境，尤其是在 AWS 这样复杂的云平台上时，挑战就来了：你需要管理 VPC、EKS 集群、RDS、Redis、OpenSearch、S3 等一系列云服务，还要确保它们之间的网络互通、安全合规。手动在 AWS 控制台点点点，不仅容易出错，而且几乎无法复现和版本化管理。

这正是 AWS CDK（Cloud Development Kit）大显身手的地方。这个项目langgenius/aws-cdk-for-dify提供了一套用代码（TypeScript）定义 AWS 基础设施的方案，让你能像管理应用代码一样，通过npm run deploy这样的命令，一键部署一个完整、高可用的 Dify Enterprise 生产环境。它帮你把最佳实践固化成了代码，从资源规格、网络规划到安全策略，都预先定义好了。对于 DevOps 工程师、云架构师或者任何需要在 AWS 上稳定运行 Dify 的团队来说，这个项目能节省大量前期架构设计和手动配置的时间，直接把一个经过验证的、企业级的部署架构交到你手上。

2. 架构设计与核心组件解析

在真正动手部署之前，理解这个 CDK 项目为你构建的整个技术栈至关重要。这能帮助你在后续配置和排查问题时，心里有一张清晰的地图。

2.1 整体架构视图

这个项目构建的是一个典型的、云原生的微服务应用架构。Dify 的核心服务（包括前端控制台、后端 API、工作流引擎等）被打包成容器，运行在 Amazon EKS（弹性 Kubernetes 服务）集群中。EKS 负责服务的调度、扩缩容和生命周期管理。数据层则完全由 AWS 的托管服务支撑：用 RDS PostgreSQL 存储结构化数据（用户、应用配置等），用 ElastiCache for Redis 处理缓存和会话，用 Amazon OpenSearch 作为向量数据库支撑 AI 应用的语义搜索能力，最后用 S3 对象存储来持久化用户上传的文件、生成的图片等静态资源。

所有这些组件都被部署在一个自定义的 VPC（虚拟私有云）内，确保了网络隔离和安全。外部流量通过一个 Application Load Balancer（ALB）接入，ALB 根据域名（如api.yourdomain.com）将请求路由到 EKS 集群内对应的 Kubernetes Service。整个架构的设计遵循了 AWS 的安全最佳实践，比如将数据库、缓存等数据层服务放在私有子网，只有 EKS 工作节点可以访问，而 ALB 则部署在公有子网对外提供服务。

2.2 测试环境与生产环境规格对比

项目贴心地提供了两套预设配置：测试（test）和生产（prod）。它们的核心区别在于资源的规格和冗余度，直接对应了成本与性能、可用性的权衡。

测试环境的核心目标是低成本、快速验证。因此，它采用了最小化的资源组合：

• EKS 工作节点：仅 1 个节点，配置为 4 vCPU 和 16 GB 内存。这意味着所有 Dify 的服务都挤在这一个节点上，一旦节点故障，服务就会中断。存储给了 100 GB，对于试水来说绰绰有余。
• 数据库与缓存：RDS 和 Redis 都采用了较低的规格（2 vCPU，内存分别为 8GB 和 6.38GB）。OpenSearch 也只有一个节点（2 vCPU, 16GB内存）。这种配置能跑起来，但绝对经不起任何像样的负载。
• 设计意图：这套配置就是为了让你能在 AWS 上完整走通一遍部署流程，验证网络连通性、服务启动和基本功能。它不适合承载真实用户或进行压力测试。

生产环境的配置则体现了高可用和可扩展性的设计：

• EKS 工作节点：6 个节点，每个节点 8 vCPU 和 32 GB 内存，并且分散在多个可用区（AZ）。这确保了即使某个可用区发生故障，服务依然可以运行在其他可用区的节点上。Kubernetes 的调度器也能更好地分散 Pod 负载。
• 数据库与缓存：RDS 采用了更高的规格（4 vCPU, 32GB内存）。更重要的是，OpenSearch 配置了 2 个数据节点（8 vCPU, 64GB内存），这提供了数据冗余和查询性能的横向扩展能力。
• 设计意图：这套配置旨在支撑真实的业务流量。多可用区部署是 AWS 上实现高可用性的基石，而充足的资源预留则为业务增长留出了空间。当然，相应的月度费用也会显著高于测试环境。

实操心得：环境选择策略我强烈建议，即使你最终目标是生产部署，也先从测试环境开始。用测试环境来熟悉整个 CDK 的部署流程、验证你的 AWS 权限和网络配置，整个过程大约1小时，即使出错，销毁重来的成本和心理压力也小得多。等测试环境的所有服务都运行起来，你再修改.env文件中的ENVIRONMENT=prod，重新部署生产环境。这样能有效避免在复杂的生产配置中踩坑。

3. 部署前关键准备与配置详解

现在，我们进入实操环节。按照 README 的步骤一步步来，但我会补充大量原文档中省略的“为什么”和“避坑点”。

3.1 基础工具与 AWS 权限准备

首先，确保你的本地开发机已经安装了必要的工具：

1. AWS CLI：这是与 AWS 交互的基石。安装后，运行aws configure，输入你的AWS Access Key ID,Secret Access Key，默认区域（例如us-east-1）和输出格式（通常json）。这里使用的 IAM 用户或角色，必须拥有非常广泛的权限，因为 CDK 需要创建 VPC、EKS、RDS 等大量资源。最省事的办法是附加一个AdministratorAccess策略，但在严格的生产环境中，你应该根据 CDK 生成的 CloudFormation 模板来定制最小权限策略。
2. Node.js 与 npm：CDK 本身是一个 Node.js 应用。确保安装了 LTS 版本（如 18.x）。
3. Git：用于拉取代码仓库。

3.2 环境变量 (.env) 配置的深层解读

克隆项目后，cp .env.example .env创建你的配置文件。这个文件是整套部署的“总开关”，每一个变量都至关重要。

• ENVIRONMENT：必须设为test或prod。CDK 会根据这个值去读取configs/目录下对应的test.ts或prod.ts配置文件。
• CDK_DEFAULT_REGION和CDK_DEFAULT_ACCOUNT：这两个值通常不需要手动修改，AWS CLI 的配置会自动提供。但如果你需要在非默认区域或跨账号部署，这里就是覆盖点。
• DEPLOY_VPC_ID（强烈建议设置）：这是第一个关键决策点。你可以留空，让 CDK 创建一个全新的 VPC。但我强烈建议你提供一个已有的 VPC ID。原因有三：1) 你公司可能已有标准的网络架构（如 IP 段规划、对等连接、VPN 等），新 VPC 需要额外配置才能接入；2) 如果你后续需要从公司内网或其他 VPC 访问这个 Dify 环境，使用已有 VPC 更方便；3) 避免产生多余的 NAT 网关费用（每个新 VPC 的公有子网都会默认创建 NAT 网关）。

如果你使用已有 VPC，必须完成以下子网 tagging，否则部署会失败：这是原文档强调但很多人会忽略的一步。AWS Load Balancer Controller（负责在 EKS 中创建 ALB）需要根据子网标签来识别应该将 ALB 部署在哪些子网。

• 为你计划使用的公有子网添加标签：kubernetes.io/role/elb = 1

• 为你计划使用的私有子网添加标签：kubernetes.io/role/internal-elb = 1你可以通过 AWS 控制台（VPC 服务 -> 子网）或使用 AWS CLI 命令（如aws ec2 create-tags）来添加这些标签。

• EKS_CLUSTER_SUBNETS等子网变量：如果你填写了DEPLOY_VPC_ID，就必须手动指定这些子网 ID。这里有一个最佳实践：确保EKS_NODES_SUBNETS（工作节点子网）是私有子网。让计算节点在私有子网，通过 NAT 网关访问外网拉取镜像，是更安全的方式。同时，确保你为每个组件（如 RDS、OpenSearch）指定的子网，在路由表、网络 ACL 上是允许与 EKS 节点子网通信的。

• OPENSEARCH_ADMINNAME和OPENSEARCH_PASSWORD：为你的 OpenSearch 域设置主用户名和密码。请使用强密码并妥善保存。

• RDS_PUBLIC_ACCESSIBLE：务必设置为false。让数据库暴露在公网是极大的安全风险。所有访问都应通过 VPC 内部网络进行。

3.3 CDK Bootstrap 与首次部署

运行npm run init（对应cdk bootstrap）。这个命令会在你的 AWS 账户和区域中初始化一个“引导栈”，主要为 CDK 本身存储部署所需的资源和模板。通常只需执行一次。

接下来是重头戏：npm run deploy。这个命令会启动一个可能长达 30-60 分钟的资源创建过程。CDK 会调用 CloudFormation，依次创建 VPC（如果未指定）、安全组、EKS 集群、节点组、RDS、Redis、OpenSearch、S3 桶等所有资源。

注意事项：部署过程中的监控与常见卡点

1. 耐心等待：创建 EKS 集群和 OpenSearch 域尤其耗时。不要在中途中断命令。
2. 查看 CloudFormation 控制台：如果部署失败，第一时间去 AWS 控制台的 CloudFormation 服务，查看对应栈（Stack）的“事件”（Events）选项卡。错误信息通常会在这里清晰显示，例如 IAM 权限不足、子网配置错误、服务配额（Quota）超限等。
3. 配额检查：确保你的 AWS 账户在目标区域有足够的 vCPU、EIP 等配额。特别是生产环境配置，可能会触发 vCPU 限额。
4. 网络配置错误：这是最常见的失败原因。请反复核对.env中的子网 ID 是否属于你指定的 VPC，以及这些子网是否具有正确的路由（私有子网有到 NAT 网关的路由，公有子网有到互联网网关的路由）。

4. 部署后配置：打通 K8s 与外部服务

当cdk deploy成功运行完毕，基础设施已经就绪，但 Dify 应用本身还未安装。我们需要进入 Kubernetes 的世界进行配置。

4.1 配置 kubectl 访问 EKS 集群

CDK 创建的 EKS 集群，默认情况下，创建者（即执行 CDK 命令的 IAM 实体）并没有被自动添加到集群的aws-authConfigMap 中，因此无法用kubectl操作。这就是为什么需要 README 中第 7 步的“更新 AWS EKS 访问权限”。

更高效的做法：你可以跳过控制台操作，直接使用 AWS CLI 完成授权。首先，获取你的 IAM 用户或角色的 ARN：

# 如果是IAM用户 aws sts get-caller-identity --query Arn --output text # 输出类似：arn:aws:iam::123456789012:user/your-username

然后，使用eksctl工具（需单独安装）或通过编辑aws-authConfigMap 来添加权限。但原文档提供的控制台步骤是清晰且可靠的。

完成授权后，运行：

aws eks update-kubeconfig --region <你的区域> --name <你的集群名>

集群名通常是类似Dify-Testing-DifyStackTest-EKS的格式。执行成功后，运行kubectl get nodes，你应该能看到健康的 EKS 工作节点。

4.2 配置 Helm Values：连接外部服务

Dify 通过 Helm Chart 部署。我们需要修改values.yaml文件，告诉 Dify 如何使用 CDK 创建的那些托管服务（RDS, Redis, OpenSearch, S3）。

1. 数据持久化 (S3)：找到persistence部分，启用 S3 并配置useAwsManagedIam: true。这是关键：这允许 EKS 节点上的 Pod 通过其附加的 IAM Role 来访问 S3，无需配置 Access Key。CDK 已经创建了 S3 桶并配置了正确的 IAM 策略。你只需要从 AWS 控制台（S3 服务）或 CDK 输出中获取桶名和区域，替换{your-s3-bucket-name}和{your-region-name}。

2. 数据库 (RDS)：禁用内置的 PostgreSQL（postgre.enabled: false），启用外部数据库。{your-postgres-endpoint}和{your-postgres-password}在哪里？CDK 将数据库密码安全地存放在了AWS Secrets Manager服务中。你需要：

• 打开 AWS Secrets Manager 控制台。
• 找到一个名称包含DifyStack、RDS、Secret的密钥。
• 查看密钥内容，找到host（即端点，形如dify-xxxx.cluster-xxx.rds.amazonaws.com）和password字段。注意，username通常是clusteradmin。

3. 缓存 (Redis)：同理，禁用内置 Redis，启用外部 Redis。主机地址{your-redis-host}需要去ElastiCache控制台，找到创建的 Redis 集群，在“主终端节点”处获取。切记去掉端口号（6379），只保留主机名。

4. 向量数据库 (OpenSearch)：配置externalOpenSearch。端点{openSearch_endpont}在OpenSearch 服务控制台的“域”详情页中，是“终端节点”下的那个 URL（例如vpc-dify-xxx-xxx.us-east-1.es.amazonaws.com）。同样，去掉https://前缀。用户名和密码就是你之前在.env文件里设置的OPENSEARCH_ADMINNAME和OPENSEARCH_PASSWORD。

4.3 配置 Ingress 与 TLS（生产环境必看）

对于测试，你可以暂时跳过 TLS 证书，使用 HTTP 和修改本地 hosts 文件的方式来访问。但生产环境必须配置 HTTPS。

证书申请与验证：

1. 在 AWSACM（证书管理器）中申请一个公有证书。你可以申请一个通配符证书（如*.yourdomain.com）来覆盖所有子域名，或者为console.yourdomain.com,api.yourdomain.com等分别申请。
2. ACM 会要求你验证域名所有权。你需要到你的域名注册商（如 Route 53, Cloudflare）处，按照 ACM 的提示添加一条 CNAME 记录。
3. 证书验证成功后，记下其 ARN。

配置 Helm Values：

• 在values.yaml中，将global.useTLS设置为true。
• 在ingress.annotations中，你需要添加一个关键注解来告诉 AWS Load Balancer Controller 使用哪个 ACM 证书：

  alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:region:account:certificate/cert-id

• 同时，将alb.ingress.kubernetes.io/listen-ports设置为'[{"HTTPS":443}]'，让 ALB 只监听 HTTPS 端口。

DNS 配置：最后，将你的域名（api.yourdomain.com等）通过 CNAME 记录指向 ALB 的 DNS 名称（在 EC2 -> 负载均衡器 控制台中可以找到）。

4.4 安装 Dify 并完成初始化

在配置好所有values.yaml后，执行 Helm 安装命令：

helm repo add dify https://langgenius.github.io/dify-helm helm repo update helm upgrade -i dify -f values.yaml dify/dify -n dify --create-namespace

我加上了-n dify --create-namespace，建议将 Dify 安装到一个独立的命名空间，便于管理。

安装完成后，使用kubectl get pods -n dify和kubectl get ingress -n dify查看状态。所有 Pod 应变为Running，Ingress 应获得一个 ALB 的地址。

关键的初始化顺序：

1. 首先访问Dify Console(如https://console.yourdomain.com)。这是一个引导页面，用于初始化 Dify 的核心数据库和创建第一个管理员账号。按照页面提示完成设置。
2. 只有在 Console 初始化完成后，你才能登录Dify Enterprise Dashboard(如https://enterprise.yourdomain.com)，使用默认凭证 (dashboard@dify.ai/difyai123456) 登录并立即修改密码。

实操心得：镜像拉取与网络问题如果你在拉取 Dify 的企业版 Docker 镜像时遇到权限错误，需要按文档联系 LangGenius 获取凭证，并通过kubectl create secret docker-registry命令在 Kubernetes 中创建镜像拉取密钥。此外，确保 EKS 节点所在的私有子网能够通过 NAT 网关访问互联网。如果部署在纯私有网络且无 NAT，你需要配置 VPC 端点（如 S3, ECR, API Gateway）或通过代理服务器来拉取镜像。

5. 高级配置、问题排查与销毁

5.1 自定义配置 (Advanced Configuration)

项目根目录下的configs/test.ts和configs/prod.ts是 CDK 应用的配置入口。你可以在这里深度定制：

• 资源规格：修改rdsInstanceType,redisCacheNodeType,openSearchInstanceType等，使用更符合你需求的 AWS 实例类型。
• 存储大小：调整rdsAllocatedStorage,openSearchEbsVolumeSize。
• EKS 节点组：修改eksNodeDesiredSize,eksNodeMaxSize,eksNodeInstanceType来定义自动伸缩组。
• 网络细节：调整安全组规则、子网 CIDR 等。

修改后，必须重新运行npm run deploy来更新 CloudFormation 栈。

5.2 常见问题排查实录

即使按照指南操作，也可能会遇到问题。以下是我在多次部署中总结的排查清单：

5.3 环境销毁

完成测试或需要清理资源时，运行npm run destroy。这个命令会触发 CDK 清理所有通过它创建的资源。

重要警告：销毁过程是异步的，并且有时可能会因为资源依赖关系而卡住。命令执行完毕后，务必登录 AWS 控制台进行二次确认：

1. 进入CloudFormation服务，查看名为DifyStack-的栈是否已成功删除。如果状态是DELETE_FAILED，需要手动检查失败原因（常见原因是 S3 桶不为空、快照依赖等），清理后手动删除栈。
2. 进入VPC服务，检查是否还有残留的 VPC、子网、NAT 网关、互联网网关等。CDK 创建的 VPC 通常会被自动删除，但手动确认是避免产生意外费用的好习惯。
3. 检查S3控制台，确认创建的桶已被删除。如果桶内有对象，需要先清空才能删除桶。

整个销毁过程大约需要 20-30 分钟。请确保在确认所有资源都已清除后再关闭控制台，以免留下“僵尸资源”持续计费。