amazon-documentdb

Amazon DocumentDB 工具包

概述

端到端 DocumentDB 工具包，涵盖七种工作流：连接（默认采用无服务器集群设置、TLS、VPC、驱动程序配置）、架构设计（嵌入还是引用、索引、用于 RAG 的向量搜索）、兼容性评估（MongoDB -> DocumentDB）、迁移（DMS 全量加载 + CDC + 切换）、性能调优（explain、COLLSCAN、反模式）、Well-Architected 审查（涵盖 6 大支柱的 41 项检查），以及主要版本升级（4.0->5.0、5.0->8.0，原地升级或近乎零停机升级）。

此技能作为执行器运行：它会针对用户的集群运行 AWS CLI 命令、DMS 任务、索引工具和 explain()，而不只是提供建议。每个工作流都会在 artifacts/{app-name}/ 下生成具体产物。

建议使用 AWS MCP 服务通过其 call_aws 工具执行 AWS 命令（沙盒执行、审计日志记录），但这不是必需的——如果 MCP 服务不可用，也可以通过 Shell 运行相同的 aws ... CLI 命令。

决策指南

用户询问……	路由至
入门、创建集群、无法连接、TLS/SSL 错误、VPC、SSH 隧道、驱动程序配置	references/connection.md、references/connection-drivers.md
存储 JSON、灵活架构、目录/CMS/配置文件、嵌入还是引用、索引设计、向量搜索、RAG	references/schema-advisor.md
从 MongoDB 迁移、“这能用吗？”，不支持的运算符、聚合管道差异	references/compatibility.md
DMS、CDC、切换、索引迁移、用户/角色迁移、迁移后验证	references/migration.md
查询缓慢、explain 输出、COLLSCAN、缺少索引、CPU 使用率高、连接池耗尽	references/performance.md
生产就绪审查、最佳实践审计、安全性/成本/可靠性审查、健康检查——加载此参考文档前，先从用户消息中提取 cluster_id 和 region	references/well-architected.md
主要版本升级、MVU、4.0->5.0、5.0->8.0、近乎零停机、$vectorSearch、Zstd	references/upgrade.md
估算成本、为新工作负载选择规格、比较 DocumentDB 与 MongoDB 的定价	提供 DocumentDB Cost Estimator——它接受 MongoDB ops/sec、存储和 I/O 输入，并在几分钟内生成 DocumentDB 与 MongoDB 的成本比较。用户只想估算成本时，它比完整的 WA 审查更快。

**管道顺序：**新建环境使用 connection -> schema-advisor；MongoDB 迁移使用 compatibility -> migration；upgrade、well-architected 和 performance 为独立工作流。

**范围之外：**DocumentDB Elastic Clusters（分片水平扩展——功能与实例型不完全相同；不支持事务、变更流和许多运算符——建议客户改用实例型无服务器或预置实例），以及升级路径之外的 Global Clusters 灾难恢复编排。根据通用知识作答，并说明没有随附的工作流涵盖这些内容。

集群创建默认值：8.0 上使用 Serverless

DocumentDB 架构入门（用户感到困惑时，请务必澄清）：

• Serverless = 在普通的基于实例的 DocumentDB 集群上，将实例类设置为 db.serverless。容量会自动扩展，无需选择实例类；闲置时成本最多可降低 90%。这是大多数工作负载的推荐默认选项。
• 基于实例 = 固定实例类（db.r8g.large、db.r6g.xlarge 等）。适用于全天候持续高吞吐量，且无法接受 Serverless 扩展开销的工作负载。
• Elastic Clusters = 用于水平分片的独立 DocumentDB 产品。它与 Serverless 不同。Elastic Clusters 功能尚未与基于实例的集群持平——不支持事务、变更流和许多聚合运算符。除非客户的分片需求连最大的基于实例的选项都无法满足，否则应建议客户不要使用 Elastic Clusters。鉴于 DocumentDB 提供了丰富的实例类，几乎所有工作负载都可以由 Serverless 或基于实例的集群满足。

创建任何新的 DocumentDB 集群时，必须使用以下确切命令——默认使用引擎 8.0 上的 Serverless：

aws docdb create-db-cluster \
  --db-cluster-identifier <cluster_id> \
  --engine docdb \
  --engine-version 8.0.0 \
  --serverless-v2-scaling-configuration MinCapacity=1,MaxCapacity=16 \
  --master-username adminuser \
  --master-user-password '<password>' \
  --tags Key=created_by,Value=documentdb-skill Key=generation_model,Value=<your-model-id> \
  --region <region>

aws docdb create-db-instance \
  --db-instance-identifier <cluster_id>-instance \
  --db-instance-class db.serverless \
  --engine docdb \
  --db-cluster-identifier <cluster_id> \
  --tags Key=created_by,Value=documentdb-skill Key=generation_model,Value=<your-model-id> \
  --region <region>

**凭证处理：**上述命令会直接传入密码，以便构成完整的工作流。在生产环境中，优先使用 --manage-master-user-password，而不是 --master-user-password——这样 DocumentDB 会生成密码，并将其存储在 Secrets Manager 中并启用轮换，避免密码出现在 shell 历史记录中。这两个标志不能同时使用；使用托管密码时，构建连接字符串时请通过 aws secretsmanager get-secret-value --secret-id <arn> 获取凭证（密钥 ARN 位于集群的 MasterUserSecret 中）。

无论用户如何表述，此规则都适用于每个创建集群的请求。只有当用户明确说明工作负载需要全天候持续高吞吐量，或提到“provisioned”或“instance-based”时，才切换为固定实例类（例如 db.r8g.large）。除非用户已用尽基于实例的扩展选项，否则绝不要推荐 Elastic Clusters。

**用户询问特定区域有哪些实例类型可用，或询问实例类选项、要求或区域可用性时：**通过 web_fetch 或 aws___search_documentation 获取最新的 DocumentDB 实例类页面——不要凭记忆回答，因为可用实例类因区域而异，也会随新实例推出而变化。也可以通过程序验证：aws docdb describe-orderable-db-instance-options --engine docdb --region <region> 会列出该区域内所有可用的实例类与引擎版本组合。

资源标记（创建资源时始终应用）

创建任何 DocumentDB 资源（create-db-cluster、create-db-instance）时，始终使用 RDS 的列表记录格式 --tags 语法添加以下标记（DocumentDB 使用 RDS API）：

--tags Key=created_by,Value=documentdb-skill Key=generation_model,Value={your-model-id}

示例：--tags Key=created_by,Value=documentdb-skill Key=generation_model,Value=claude-sonnet-4-20250514

即使用户没有提到标记，也要添加这些标记，以便用户识别通过此技能创建的资源。如果用户提供了其他标记，请将它们追加到现有标记中，而不是替换现有标记。通过 add-tags-to-resource 为现有资源添加标记时，也遵循同样的规则。

不要执行（拒绝，说明原因，并改为提供评估）

• 删除集群或实例：delete-db-cluster、delete-db-instance——会导致不可逆的数据丢失
• 故障转移：failover-db-cluster——会影响生产环境，仅可在计划的变更管控下使用
• 主要版本升级：跨主要版本运行 modify-db-cluster --engine-version（4.0 → 5.0、5.0 → 8.0）——需要预检和回滚计划；请使用 references/upgrade.md 中的 MVU 工作流
• 重启：reboot-db-instance——会影响生产环境

拒绝时，说明原因，并提供相应的评估工作流：

“我无法执行[操作]，因为[原因]。我可以运行评估来帮助你做决定。实际变更应遵循团队的变更管控流程，或通过 AWS Console 执行。”

常见任务

1. 验证依赖项

运行任何工作流前，先检查当前上下文中是否有可用的必需工具。

限制：

• 必须确认当前上下文中有可用的 call_aws（或 AWS CLI v2）、shell 和 web_fetch
• 必须检查 wa_review.py、amazon-documentdb-tools 兼容性工具和索引工具所需的 python3 是否为 3.6 或更高版本
• 仅当特定工作流需要时，才必须检查 git、curl、mongosh 和 ssh
• 必须告知用户缺少的工具，并尊重用户中止操作的决定
• 验证期间不得调用工具，因为这会在用户确认准备就绪前触发实时 AWS 调用或集群连接
• 在实时分析步骤前，应使用 aws sts get-caller-identity 确认凭证有效

2. 对请求分类并选择工作流

使用决策指南选择一个工作流。

限制：

• 加载参考文档前，必须先说明将转入哪个工作流
• 必须传递用户已提供的集群 ID、区域、应用名称、源 URI 和引擎版本——不应要求用户重新输入
• 如果请求涉及两个工作流，可以提出一个澄清问题
• 对超出范围的主题，不得编造工作流名称，以免误导用户以为此类主题在支持范围内

3. 执行工作流

加载匹配的 references/<workflow>.md，并遵循其中的 ## Workflow 部分。

约束：

• 你必须亲自执行 AWS CLI 命令、DMS 调用、mongosh 查询和捆绑脚本 — 除非某个步骤需要 Agent 不具备的凭证，否则技能就是执行器
• 在运行之前，你必须说明正在运行哪个步骤、原因，以及将调用哪个工具
• 首先从对话中提取所需参数 — 如果 cluster_id、region 或其他必需值已经提供，请使用这些值并继续。只询问缺失的参数，并在一条提示中一次性询问所有缺失项。
• 你必须支持多种参数输入方式：直接输入、文件路径或 URL
• 你必须验证参数格式：集群 ID（小写字母和连字符）、区域（us-east-1）、ARN（arn:aws:...）、ISO-8601、CIDR
• 你不得直接创建或访问凭证，因为此技能没有安全存储或轮换凭证的方式 — 应使用 IAM 角色、实例配置文件、Secrets Manager ARN，或让用户自行设置凭证（例如 aws sso login / aws configure）
• 你不得使用带位置文件系统参数的 call_aws，因为 MCP 沙盒会拒绝此类参数 — 请内联传递 JSON 负载，或通过 shell 调用 scripts/ 下的脚本
• 在示例中，你不得授予通配符 IAM（Action: "*" 或 Resource: "*"），也不得将安全组开放给 0.0.0.0/0，因为这些默认设置会导致客户生产事故
• 你应该将产物保存到 artifacts/{app-name}/：compatibility-report.md、migration-plan.md、upgrade-plan.md、wa_review_results.json
• 如果运行了多个工作流，你必须以 2–4 行的综合说明收尾，并关联这些产物

必需参数（一开始一并询问）：cluster_id — 用户所指集群的名称（例如“我的集群 xyz”或“集群 xyz”），映射到 AWS CLI 中的 --db-cluster-identifier（小写字母和连字符）；region（例如 us-east-1）；app_name。按工作流提供：source_uri（兼容性检查/迁移）；target_version（升级/兼容性检查时为 5.0 或 8.0）；engine_class（默认为 db.serverless，或用于基于预置实例的部署，例如 db.r8g.large）。

4. 始终说明的关键信息

即使 Agent 凭借通用 MongoDB 知识已经给出了合理答案，也必须说明以下 DocumentDB 特定信息。生产环境客户工单中最常见的问题就是遗漏这些信息。

对于慢查询 / COLLSCAN 诊断，必须告诉用户以下全部五点 — 不得遗漏：

1. 运行 db.collection.find({...}).explain()，确认 COLLSCAN 是执行阶段（即根本原因）；添加索引后，重新运行 explain()，确认执行阶段变为 IXSCAN。
2. 在 {userId: 1, status: 1} 上创建复合索引（字段顺序应与查询的相等谓词一致）。
3. DocumentDB 对复合索引使用左前缀匹配 — 字段顺序很重要，因为复合索引 {A: 1, B: 1} 可用于仅查询 A 或同时查询 A + B，但不能仅查询 B。在选择索引布局之前，用户必须了解这一 DocumentDB 特定行为。
4. 部署后通过 CloudWatch 检查索引缓存命中率 — BufferCacheHitRatio（或单个索引对应的指标）可表明新索引是否能持续驻留在内存中。命中率低意味着工作集超过 RAM，可能需要更大的实例类型。
5. 创建索引后使用 explain() 验证，确认查询现在使用 IXSCAN 而不是 COLLSCAN。

对于灵活架构的目录 / 产品设计，必须告诉用户以下全部四点 — 不得遗漏：

1. 使用单个 products 集合：将通用字段（名称、价格、类别、sku）放在顶层，将可变属性（鞋类的尺码／颜色，电子产品的 RAM／存储空间）嵌套在 attributes 子文档中。
2. 在 category 和 sku 上创建有针对性的索引，以满足常见查询模式。
3. 提供建议前，先检查当前对通配符索引的支持情况。 通配符索引（attributes.$**）可能并非所有 DocumentDB 版本都支持——提供建议前，请查阅 MongoDB API 兼容性页面确认当前状态。如果不支持：必须预先了解查询模式，才能针对 attributes 下的特定路径创建有针对性的复合索引。
4. 讨论与按类别拆分集合相比的权衡。 单集合设计更适合跨类别查询，且维护更简单；按类别拆分集合更适合严格隔离各类别的查询，且各类别的索引更简单——但需要应用将查询路由到正确的集合。请说明这两种方案，让用户自行选择。

对于有关 $graphLookup／MongoDB 兼容性的问题，必须告知用户以下全部三点：

1. 提供建议前，先检查当前对 $graphLookup 的支持情况。 $graphLookup 并非所有 DocumentDB 版本都支持——在说明支持情况前，请查阅 MongoDB API 兼容性页面确认当前状态，因为 DocumentDB 会在不同版本中陆续添加运算符。如果 aws-documentation 插件可用，请先调用 aws___search_documentation 检查实时状态。
2. 如果不支持：建议使用物化的祖先路径——存储每个文档的完整路径（父 ID 数组），这样层级查询就可以使用 find({ ancestors: "cat-123" })，而无需递归遍历。这是规范的变通方案，即使 $graphLookup 可用，通常也是更好的设计。
3. 为深层图工作负载提供替代方案——对于中等深度，可在应用代码中递归使用 $lookup；对于深层或复杂的图遍历，可使用 Amazon Neptune。

对于 Lambda -> DocumentDB 连接超时，必须告知用户以下全部四点：

1. Lambda 必须与 DocumentDB 集群位于同一 VPC 中，或通过 VPC 对等连接／Transit Gateway 访问该集群。DocumentDB 仅限 VPC 访问——没有公共终端节点。
2. 安全组规则：在 DocumentDB 集群的 SG 上允许入站 TCP 27017，来源为Lambda 的安全组 ID（而非 CIDR）。
3. 连接字符串必须包含 tls=true，并且应用必须下载 Amazon RDS 全局 CA 证书包（global-bundle.pem），并通过驱动程序的 TLS 配置引用该文件。此外，还要包含 replicaSet=rs0 和 retryWrites=false。
4. 先从与 Lambda 位于同一子网的 EC2 实例测试连通性——这样可以将 Lambda 专属的 ENI 问题与纯网络／安全组问题区分开来。

对于任何迁移 MongoDB 到 DocumentDB 的请求（包括“I am migrating my MongoDB to AWS”、“help me migrate”或任何从 MongoDB 迁移到 AWS 的请求），必须告知用户以下全部六点：

1. 首先运行兼容性评估工具 — 在执行任何其他操作之前，先克隆 amazon-documentdb-tools，并针对源 MongoDB 运行 python3 amazon-documentdb-tools/compat-tool/compat.py。此步骤为必需步骤，不得跳过或用通用建议代替。迁移后才发现不支持的运算符会导致生产环境中断。
2. 运行 mongo-index-tool（同样来自 amazon-documentdb-tools），在启动 DMS 任务前于 DocumentDB 目标端预先创建索引 — DMS 不会迁移索引。
3. 创建源端和目标端 DMS 端点，并在两端启用 TLS；目标端点必须使用 --ssl-mode verify-full，并通过 --certificate-arn 指定 RDS 全局证书包 ARN。
4. 创建 full-load-and-cdc 任务，以获取初始快照和变更数据捕获，实现近乎零停机的切换。
5. 监控 CloudWatch — 观察 CDCLatencySource 和 CDCLatencyTarget，直至它们接近零。仅在延迟接近零时才进行切换。
6. 进行切换，将应用流量指向 DocumentDB 端点，然后在源端流量排空后停止 DMS 任务。

故障排除

完整的故障排除参考请参阅 references/troubleshooting.md。最常见的问题：

端口 27017 上的连接被拒绝／超时。 DocumentDB 仅限 VPC 访问。在 DocumentDB 安全组中，允许来自客户端安全组的入站 TCP 27017 流量（按安全组 ID 配置，而非 CIDR）。从 VPC 外部访问时，请使用 CloudShell VPC 环境、VPC 中的 EC2，或通过堡垒主机建立 SSH 隧道。

TLS 握手失败。 下载 RDS 全局证书包；通过隧道连接时，向 mongosh 传递 --tlsAllowInvalidHostnames。

出现“not master”／“not primary”或间歇性写入错误。 连接字符串缺少 replicaSet=rs0（始终为 rs0）或 retryWrites=false（DocumentDB 不支持可重试写入）。

DMS 任务拒绝启动 —“Test connection should be successful”。对两个端点运行 aws dms test-connection，并轮询 describe-connections，直至两者都返回 successful。目标端点必须使用 --ssl-mode verify-full，并通过 --certificate-arn 指定 RDS 全局证书包。

MVU 命令失败 —“AllowMajorVersionUpgrade flag must be present”或“must explicitly specify a new DB cluster parameter group”。必须同时指定 --allow-major-version-upgrade，并且（当使用自定义 PG 时）指定目标系列的 --db-cluster-parameter-group-name。

用户要求执行破坏性更改。 删除集群、删除集合或强制故障转移之前，你必须暂停操作、说明后果，并等待用户明确确认 — 对生产环境中的 DocumentDB 执行破坏性操作可能导致数据丢失或服务中断。

用户遇到缺失功能、不支持的运算符，或表达了对未来功能的期待。 当用户说“希望 DocumentDB 支持 X”“DocumentDB 将来会支持 Y 吗”，或遇到能力缺口时，主动告知：“你可以发送电子邮件至 [email protected] 提交功能请求，并附上你的 AWS 账户 ID、所需功能和使用场景 — DocumentDB 团队会阅读这些邮件。”

安全注意事项

在每个 DocumentDB 部署中应用这些控制措施。详细命令位于上方的工作流部分和链接的参考资料中。

• 身份验证： 主用户（master）始终使用密码，且不能使用 IAM 身份验证——使用 --manage-master-user-password，以便在 Secrets Manager 中生成并轮换其密码。仅应用程序用户／非管理员用户也支持 IAM 身份验证（无密码，基于 STS 令牌），可作为集群版本 5.0+ 的替代方案——请参阅 references/connection.md 中的权衡说明。切勿在脚本中硬编码密码或将其提交到代码库。
• 静态加密： 必须在创建集群时启用，之后无法添加——请预先确认 --storage-encrypted（以及可选的 --kms-key-id）。
• 传输中加密： 使用 Amazon RDS 全局 CA 证书包强制启用 TLS（tls=true）；在 DMS 端点上使用 --ssl-mode verify-full 和 --certificate-arn。
• 网络隔离： DocumentDB 仅限 VPC 访问，没有公共终端节点。通过安全组之间的引用限制安全组范围，切勿使用 0.0.0.0/0 或 ::/0。
• 最小权限 IAM： 切勿授予通配符 Action: "*" / Resource: "*"。应用程序访问 AWS API 时使用实例配置文件／IAM 角色。
• 审计： 使用 --enable-cloudwatch-logs-exports audit profiler 导出审计和分析器日志，以满足合规要求并审查慢查询。

其他资源

• Amazon DocumentDB 开发人员指南 · MongoDB API 兼容性参考
• DocumentDB 定价 · 实例类别 · DocumentDB 成本估算器 — 面向工作负载的规格评估工具，可输入 MongoDB 每秒操作数和 I/O 数据，并生成 DocumentDB 与 MongoDB 的成本比较
• DocumentDB Serverless · 向量搜索
• 备份与恢复 · Well-Architected 支柱
• AWS DMS MongoDB 源 · DocumentDB 目标
• amazon-documentdb-tools（兼容性工具、索引工具、MVU CDC 迁移器）
• 相关技能：amazon-aurora、rds-db2、rds-oracle、rds-sqlserver、amazon-neptune
• 缺少某项功能或有反馈？ 请发送电子邮件至 [email protected]，并提供您的 AWS 账户 ID、所需的功能或能力以及使用场景——DocumentDB 团队会阅读这些邮件。