企业官网建设流程全解析

导读

本文基于 Context Hub 仓库中维护的 AWS SDK for JavaScript v3 Elasticsearch Service 客户端文档，完整讲解如何用@aws-sdk/client-elasticsearch-service（版本3.1007.0，JavaScript 语言变体）管理 Amazon Elasticsearch Service 的控制平面：包括域的创建、查询、配置更新、升级、软件更新、标签、自定义包、VPC 端点与删除等操作。读完本文后，你将能够：用 12 个典型命令覆盖域生命周期管理；区分控制平面与数据平面（/_search、/_bulk）的边界；并掌握异步变更后的进度轮询与升级预检等实战技巧。

说明：该文档属于 Context Hub 的aws内容仓库，由 maintainer 维护，revision: 1，updated-on: 2026-03-13，可通过chub get aws/elasticsearch-service --lang js方式获取（参见 docs/cli-reference.md 与 docs/content-guide.md）。

包定位：控制平面，而非数据平面

@aws-sdk/client-elasticsearch-service封装的是 AWS 上负责管理 Amazon Elasticsearch Service 域（Domain）的控制平面 API，对应的服务标识是es、API 版本2015-01-01。它覆盖以下能力：

• 创建、删除域；
• 查看域状态、端点或配置；
• 修改实例规格、存储、端点、安全或日志设置；
• 管理标签、自定义包、版本升级与服务软件更新。

它不处理数据平面流量：索引文档、执行搜索、调用/_search、/_bulk或其他 Elasticsearch/OpenSearch REST 端点都不属于本包的职责范围。做数据平面操作时，应先用DescribeElasticsearchDomainCommand拿到域端点，再对DomainStatus.Endpoint（公网）或DomainStatus.Endpoints.vpc（VPC 内）发送签名 HTTP 请求。

由于服务 API 仍叫es，本包保留了传统的Elasticsearch...命名；同时部分操作涉及 Amazon OpenSearch Service 资源（如EngineType: "OpenSearch"、OpenSearch 托管的 VPC 端点），因此出现 Elasticsearch/OpenSearch 混用命名是正常现象。

安装与前置条件

安装：

npm install @aws-sdk/client-elasticsearch-service

配置区域与凭证（目标域必须位于同一区域，域管理是按区域隔离的）：

export AWS_REGION=us-east-1 export AWS_PROFILE=my-aws-profile # 或使用直接凭证代替 AWS_PROFILE export AWS_ACCESS_KEY_ID=... export AWS_SECRET_ACCESS_KEY=... export AWS_SESSION_TOKEN=... # 仅临时凭证需要

客户端初始化

最简初始化（从环境变量读取区域，默认us-east-1）：

import { ElasticsearchServiceClient } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: process.env.AWS_REGION ?? "us-east-1", });

需要显式传入凭证时：

import { ElasticsearchServiceClient } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: process.env.AWS_REGION ?? "us-east-1", credentials: { accessKeyId: process.env.AWS_ACCESS_KEY_ID, secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY, sessionToken: process.env.AWS_SESSION_TOKEN, }, });

所有请求通过await es.send(new XxxCommand({...}))发起；ElasticsearchServiceClient的构造函数自动继承 AWS SDK 标准的凭证链（环境变量、共享凭证文件、IAM 角色等）与区域解析逻辑。

核心工作流：12 个高频命令实战

1. 列出当前账户与区域下的域

import { ElasticsearchServiceClient, ListDomainNamesCommand, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const response = await es.send( new ListDomainNamesCommand({ EngineType: "Elasticsearch", }), ); for (const domain of response.DomainNames ?? []) { console.log(domain.DomainName); }

EngineType为可选参数，在混合资产（mixed estates）场景下可传Elasticsearch或OpenSearch做过滤。

2. 描述域并读取端点

import { DescribeElasticsearchDomainCommand, ElasticsearchServiceClient, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const response = await es.send( new DescribeElasticsearchDomainCommand({ DomainName: "search-prod", }), ); const domain = response.DomainStatus; console.log(domain?.ARN); console.log(domain?.Endpoint ?? domain?.Endpoints?.vpc); console.log(domain?.Created); console.log(domain?.Processing); console.log(domain?.DomainProcessingStatus);

该调用适合：打标签前取 ARN、做数据平面访问前取端点、以及查看当前域处理状态。

3. 查看当前配置模型

import { DescribeElasticsearchDomainConfigCommand, ElasticsearchServiceClient, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const response = await es.send( new DescribeElasticsearchDomainConfigCommand({ DomainName: "search-prod", }), ); console.log(response.DomainConfig?.ElasticsearchClusterConfig); console.log(response.DomainConfig?.EBSOptions); console.log(response.DomainConfig?.DomainEndpointOptions);

与上一条的高层状态摘要不同，这条命令返回受管配置模型（managed configuration model），最适合查看集群、存储、端点的具体配置项。

4. 创建域（含访问策略、安全与标签）

import { CreateElasticsearchDomainCommand, ElasticsearchServiceClient, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const accessPolicy = { Version: "2012-10-17", Statement: [ { Effect: "Allow", Principal: { AWS: "arn:aws:iam::123456789012:role/search-admin" }, Action: "es:*", Resource: "arn:aws:es:us-east-1:123456789012:domain/search-prod/*", }, ], }; const response = await es.send( new CreateElasticsearchDomainCommand({ DomainName: "search-prod", ElasticsearchVersion: "7.10", ElasticsearchClusterConfig: { InstanceType: "m5.large.elasticsearch", InstanceCount: 2, DedicatedMasterEnabled: true, DedicatedMasterType: "m5.large.elasticsearch", DedicatedMasterCount: 3, ZoneAwarenessEnabled: true, ZoneAwarenessConfig: { AvailabilityZoneCount: 2, }, }, EBSOptions: { EBSEnabled: true, VolumeType: "gp3", VolumeSize: 100, }, VPCOptions: { SubnetIds: ["subnet-0123456789abcdef0", "subnet-0fedcba9876543210"], SecurityGroupIds: ["sg-0123456789abcdef0"], }, EncryptionAtRestOptions: { Enabled: true, }, NodeToNodeEncryptionOptions: { Enabled: true, }, DomainEndpointOptions: { EnforceHTTPS: true, TLSSecurityPolicy: "Policy-Min-TLS-1-2-2019-07", }, AccessPolicies: JSON.stringify(accessPolicy), TagList: [ { Key: "Environment", Value: "prod" }, { Key: "Service", Value: "search" }, ], }), ); console.log(response.DomainStatus?.ARN); console.log(response.DomainStatus?.Created); console.log(response.DomainStatus?.Processing);

要点：

• AccessPolicies是字符串化的 JSON资源策略（示例中授权指定 IAM 角色对域执行es:*）；
• ElasticsearchClusterConfig支持专用主节点（DedicatedMasterEnabled/Type/Count，推荐生产环境 3 节点）与多可用区（ZoneAwarenessEnabled+ZoneAwarenessConfig.AvailabilityZoneCount）；
• EBSOptions使用 gp3 卷 100 GiB；
• EncryptionAtRestOptions（静态加密）与NodeToNodeEncryptionOptions（节点间加密）在生产域上应开启；
• DomainEndpointOptions强制 HTTPS 并锁定 TLS 1.2 策略；
• 创建、更新、升级、删除均为异步操作，提交后需轮询DescribeElasticsearchDomain或DescribeDomainChangeProgress直至域稳定。

5. 用DryRun预演配置变更

import { ElasticsearchServiceClient, UpdateElasticsearchDomainConfigCommand, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const dryRun = await es.send( new UpdateElasticsearchDomainConfigCommand({ DomainName: "search-prod", DryRun: true, ElasticsearchClusterConfig: { InstanceType: "m5.xlarge.elasticsearch", InstanceCount: 3, }, EBSOptions: { EBSEnabled: true, VolumeType: "gp3", VolumeSize: 200, }, }), ); console.log(dryRun.DryRunResults?.DeploymentType); console.log(dryRun.DryRunResults?.Message);

DryRun: true让你在实际提交前就能预知该更新走**动态更新路径（无需停机）**还是blue/green 式部署（会重建集群），从而评估变更风险。

6. 应用配置更新

import { ElasticsearchServiceClient, UpdateElasticsearchDomainConfigCommand, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const response = await es.send( new UpdateElasticsearchDomainConfigCommand({ DomainName: "search-prod", ElasticsearchClusterConfig: { InstanceType: "m5.xlarge.elasticsearch", InstanceCount: 3, }, EBSOptions: { EBSEnabled: true, VolumeType: "gp3", VolumeSize: 200, }, DomainEndpointOptions: { EnforceHTTPS: true, TLSSecurityPolicy: "Policy-Min-TLS-1-2-2019-07", }, }), ); console.log(response.DomainConfig?.ElasticsearchClusterConfig?.Options); console.log(response.DomainConfig?.EBSOptions?.Options);

响应中的DomainConfig.*.Options反映更新后（目标）配置。

7. 跟踪变更进度

import { DescribeDomainChangeProgressCommand, ElasticsearchServiceClient, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const response = await es.send( new DescribeDomainChangeProgressCommand({ DomainName: "search-prod", }), ); console.log(response.ChangeProgressStatus?.ChangeId); console.log(response.ChangeProgressStatus?.Status); console.log(response.ChangeProgressStatus?.ConfigChangeStatus); console.log(response.ChangeProgressStatus?.PendingProperties);

当一次变更长时间停留在Processing时，DescribeDomainChangeProgress是最有用的进度 API：Status反映整体进度，ConfigChangeStatus反映配置变更阶段，PendingProperties列出待生效的属性。

8. 打标签 / 取消标签（注意：用 ARN）

AddTags与RemoveTags接收的是域 ARN，而不是DomainName：

import { AddTagsCommand, ElasticsearchServiceClient, ListTagsCommand, RemoveTagsCommand, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const arn = "arn:aws:es:us-east-1:123456789012:domain/search-prod"; await es.send( new AddTagsCommand({ ARN: arn, TagList: [ { Key: "Team", Value: "platform" }, { Key: "Environment", Value: "prod" }, ], }), ); const listed = await es.send(new ListTagsCommand({ ARN: arn })); console.log(listed.TagList); await es.send( new RemoveTagsCommand({ ARN: arn, TagKeys: ["Team"], }), );

9. 列出并关联自定义包

包 API 面向 Amazon ES 自定义包（如TXT-DICTIONARY词典包）：

import { AssociatePackageCommand, DescribePackagesCommand, ElasticsearchServiceClient, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const packages = await es.send( new DescribePackagesCommand({ Filters: [ { Name: "PackageStatus", Value: ["AVAILABLE"], }, ], MaxResults: 25, }), ); const packageId = packages.PackageDetailsList?.[0]?.PackageID; if (packageId) { await es.send( new AssociatePackageCommand({ DomainName: "search-prod", PackageID: packageId, }), ); }

注意：过滤器的成员名是Value（数组），不是Values，这是容易踩坑的点。

10. 列出域关联的 VPC 端点

import { ElasticsearchServiceClient, ListVpcEndpointsForDomainCommand, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const response = await es.send( new ListVpcEndpointsForDomainCommand({ DomainName: "search-prod", }), ); for (const endpoint of response.VpcEndpointSummaryList ?? []) { console.log(endpoint.VpcEndpointId, endpoint.Status, endpoint.DomainArn); }

尽管包名仍叫 Elasticsearch Service，该操作描述的是OpenSearch Service 托管的 VPC 端点——这是命名混用的又一实例。

11. 查询升级目标版本与可用实例类型

import { ElasticsearchServiceClient, ListElasticsearchInstanceTypesCommand, ListElasticsearchVersionsCommand, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); let nextToken; do { const versions = await es.send( new ListElasticsearchVersionsCommand({ MaxResults: 100, NextToken: nextToken, }), ); console.log(versions.ElasticsearchVersions ?? []); nextToken = versions.NextToken; } while (nextToken); const instanceTypes = await es.send( new ListElasticsearchInstanceTypesCommand({ ElasticsearchVersion: "7.10", DomainName: "search-prod", MaxResults: 100, }), ); console.log(instanceTypes.ElasticsearchInstanceTypes ?? []);

版本列表的分页通过NextToken循环完成。ListElasticsearchInstanceTypes传入DomainName时，返回的是对修改现有域有效的实例类型列表，而不仅是版本级的通用清单。

12. 升级前资格预检（PerformCheckOnly）

import { ElasticsearchServiceClient, UpgradeElasticsearchDomainCommand, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const check = await es.send( new UpgradeElasticsearchDomainCommand({ DomainName: "search-prod", TargetVersion: "7.10", PerformCheckOnly: true, }), ); console.log(check.PerformCheckOnly); console.log(check.ChangeProgressDetails?.ConfigChangeStatus);

预检通过后，去掉PerformCheckOnly再提交一次相同的命令即可真正开始升级。

扩展操作：软件更新与删除

启动服务软件更新：

import { ElasticsearchServiceClient, StartElasticsearchServiceSoftwareUpdateCommand, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const response = await es.send( new StartElasticsearchServiceSoftwareUpdateCommand({ DomainName: "search-prod", }), ); console.log(response.ServiceSoftwareOptions?.CurrentVersion); console.log(response.ServiceSoftwareOptions?.NewVersion); console.log(response.ServiceSoftwareOptions?.UpdateStatus);

删除域（永久删除，数据不可恢复）：

import { DeleteElasticsearchDomainCommand, ElasticsearchServiceClient, } from "@aws-sdk/client-elasticsearch-service"; const es = new ElasticsearchServiceClient({ region: "us-east-1" }); const response = await es.send( new DeleteElasticsearchDomainCommand({ DomainName: "search-prod", }), ); console.log(response.DomainStatus?.Deleted); console.log(response.DomainStatus?.Processing);

实战避坑清单（Practical Pitfalls）

1. 只用于服务管理：本包不能替代签名 HTTP 客户端处理搜索与索引流量。
2. 区域对齐：客户端 region 必须与目标域所在区域一致，域列举与管理均按区域隔离。
3. 异步操作要轮询：create/update/upgrade/software-update/delete 提交后，轮询DescribeElasticsearchDomain与DescribeDomainChangeProgress。
4. 标签操作用 ARN：AddTags、ListTags、RemoveTags只接受ARN，不接受DomainName。
5. 命名混用属正常：命令仍是Elasticsearch...前缀，但部分操作暴露 OpenSearch 字段（如EngineType: "OpenSearch"、OpenSearch 托管 VPC 端点）。
6. 最小化请求体：控制平面 API 有大量可选的嵌套设置，建议从最小请求开始，只添加实际需要的选项。

在 Context Hub 中获取与使用本文档

本文内容对应仓库中的 content/aws/docs/elasticsearch-service/javascript/DOC.md，是按 Context Hub 内容规范组织的多语言文档的 JavaScript 变体（目录结构约定参见 docs/content-guide.md）。编码 Agent 可以在编写调用 Elasticsearch Service 控制平面 API 的代码前，通过chubCLI 拉取该文档作为权威依据：

chub search "elasticsearch service" --json # 查找文档 ID chub get aws/elasticsearch-service --lang js # 获取 JavaScript 变体

CLI 的用法与--lang参数行为（多语言文档未指定语言时会提示选择，单语言文档自动推断）可参考 docs/cli-reference.md。该文档的 frontmatter 声明versions: 3.1007.0、source: maintainer、tags包含aws,elasticsearch-service,opensearch,javascript,nodejs,search,managed-service,control-plane，便于在检索与过滤时精准命中。

总结

@aws-sdk/client-elasticsearch-service是管理 Amazon Elasticsearch Service 域生命周期的唯一正确入口：它覆盖从创建、查询、更新、预演、打标签、包关联、VPC 端点、升级预检到删除的完整控制平面能力，但明确不承载索引与搜索流量。牢记「控制平面 vs 数据平面」的边界、异步变更的轮询模式、标签操作的 ARN 要求，以及 DryRun / PerformCheckOnly 两类预演手段，即可在生产环境中安全、高效地管理搜索域。