alibabacloud-mongodb-instances-manage

Alibaba Cloud MongoDB 实例管理

创建和管理 Alibaba Cloud ApsaraDB for MongoDB 实例：单机版（开发/测试）、副本集（读密集型）、分片集群（高并发）。

安装要求

预检查：Aliyun CLI >= 3.3.3 运行 aliyun version，确认版本 >= 3.3.3。如果尚未安装或版本过低， 请参阅 references/cli-installation-guide.md 查看安装说明。

[MUST] 运行 aliyun configure set --auto-plugin-install true 以启用自动安装插件。 [MUST] 运行 aliyun plugin update，确保所有现有插件始终保持最新状态。

aliyun version
aliyun plugin install --names dds kms resourcemanager bssopenapi

[MUST] CLI 用户代理 — 每次调用 aliyun CLI 命令时，都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

[MUST] 启用 AI-Mode — 执行 Agent Skill 时必须启用 AI-mode。 在调用任何 CLI 命令之前，运行以下命令：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage"

[MUST] 在每个退出点禁用 AI-Mode — 无论出于何种原因，在给出最终回复之前，都必须先禁用 AI-mode。这适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何其他不会再执行 CLI 命令的情形。

aliyun configure ai-mode disable

信息展示规范

[MUST] 向用户展示的所有信息都必须符合以下要求：

1. 不得捏造输出：所有展示的信息都必须来自实际 API 查询结果。严禁猜测、捏造或拼接信息
2. 截断处理：如果 API 响应被截断（例如内容被省略），必须重新完整查询后再展示
3. 数量验证：展示的数量必须与 API 返回的 TotalCount/实际数量一致
4. 不得猜测时间：没有官方文档依据时，不要提供时间估算；只能通过 API 轮询确认状态
5. 写操作响应规范：执行任何写操作（创建、修改规格、云盘重新配置、添加/删除节点等）后，仅展示 RequestId（以及可用时的 DBInstanceId/OrderId），然后询问用户是否要轮询实例状态。未经用户确认，不得自动开始轮询。
6. 实例创建后的自动轮询规则：
   • 新创建的实例通常需要 10-25 分钟才能达到 Running 状态
   • 场景 A：用户只创建实例，没有后续操作 → 询问是否要轮询
   • 场景 B：用户创建实例后还有后续操作（例如修改规格、配置白名单等），且未明确表示会手动检查状态 → 必须自动轮询，每 30 秒查询一次 describe-db-instance-attribute，直到状态变为 Running 或超时（30 分钟）
   • 场景 C：用户明确表示“我会自己检查”“之后再处理”等 → 不要自动轮询，按场景 A 处理
7. 实例创建后的安全配置指引：实例创建完成（状态为 Running）后，必须主动询问是否要进行安全配置（参见“参数确认”部分的安全配置菜单）
8. 包年包月实例展示：必须显示剩余天数；到期时间在 10 天内的实例必须在列表下方显示警告，并引导用户续费

实例状态预检查标准

[必须] 执行非查询操作前必须检查实例状态：

1. 调用 describe-db-instance-attribute 检查 DBInstanceStatus
2. 仅当状态为 Running 时才能发起操作

状态	描述	是否可发起
Running	运行中	✅
DBInstanceClassChanging	规格变更中	❌
NodeCreating / NodeDeleting	节点创建中／删除中	❌
Creating	创建中	❌
Locked	已锁定	❌ 请先调查原因

Locked 状态诊断（检查 LockMode 字段）：

• LockByDiskQuota：磁盘使用量超限；扩容或清理数据后会自动解锁
• 其他值：欠费或已过期；请续费或充值

aliyun dds describe-db-instance-attribute --db-instance-id <id> --region <region> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage 2>&1 | grep '"DBInstanceStatus"'

身份验证

预检查：需要 Alibaba Cloud 凭证

• 绝不可读取／回显／打印 AK/SK 值（不要运行 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 仅可使用 aliyun configure list 检查凭证状态

aliyun configure list

如果没有有效的配置文件，请从 RAM 控制台获取凭证，并在本次会话之外进行配置。

RAM 权限

此技能需要以下 RAM 权限。完整列表请参阅 references/ram-policies.md § 完整权限速查。

**[必须] 权限错误处理：**检测到 Forbidden.RAM/NoPermission/Forbidden/SubAccountNoPermission 时：

1. 确定缺少的权限（从错误消息中提取 Action 和 Resource）
2. 引导用户参阅 references/ram-policies.md 申请权限
3. 等待用户确认权限已授予后再重试；权限问题解决前不得继续执行

---

查询地域和实例

[必须] 地域确认标准：

1. 用户未指定地域时，先询问地域；不要直接遍历搜索
2. 仅当用户明确表示不确定时，才按以下顺序遍历：cn-beijing → cn-shanghai → ap-southeast-1 → us-west-1 → us-east-1 → cn-hangzhou → cn-shenzhen → cn-chengdu → cn-hongkong；如果仍未找到，则调用 DescribeRegions 获取剩余地域
3. 查询路由：通过 cn-hangzhou 查询可能会返回其他地域的实例；展示时，RegionId 必须依据 API 返回的 RegionId 字段，而非查询参数
4. 列表展示：必须按实例类型分类；包年包月实例必须显示剩余天数；到期时间在 10 天内的实例必须在列表下方显示警告并引导用户续费

# Query instance list
# If user specifies instance type, query that type only; if not specified, must query both types separately:
aliyun dds describe-db-instances --biz-region-id <region> --db-instance-type replicate --page-size 50 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
aliyun dds describe-db-instances --biz-region-id <region> --db-instance-type sharding --page-size 50 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# ⚠️ Without --db-instance-type, only replicate is returned by default; sharded clusters will be missed

# Query single instance details
aliyun dds describe-db-instance-attribute --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Query all supported regions
aliyun dds describe-regions --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

跨地域查找脚本和全地域扫描脚本：参阅 references/operations.md § 查询地域和实例

参数确认

[必须] 执行任何创建／修改操作前，必须向用户显示完整的参数列表并获得 Y/Yes 确认

**工作流：**收集参数 → 显示参数列表 → 等待 Y 确认 → 执行 → 仅显示 RequestId/DBInstanceId → 询问是否轮询 → 完成后显示安全配置指引

创建实例后必须显示安全配置指引菜单：

[0] Set root password         - Cannot connect without password (priority)
[1] Set IP whitelist          - Configure allowed access IPs
[2] Bind ECS security group   - Control access via security group
[3] Associate global whitelist template - Use unified whitelist template
[4] Modify maintenance window - Set maintenance window
[5] Allocate public address   - Enable public access (dev/test only)
[N] Skip

完整的参数确认格式及必需／可选参数表：参阅 references/operations.md § 参数确认

核心工作流

步骤	名称	类型	描述
0	创建资源组	可选	需要管理资源组时执行
0.5	创建 KMS 实例	可选	需要云盘加密时执行
1	查询 VPC/VSwitch	可选	用户未提供 VPC 时执行
2	验证 VPC/VSwitch	必需	确保 VPC/VSwitch 可用
3	验证可用区	独立实例必需	确认目标可用区支持独立实例
4	确认参数	必需	创建前必须确认
5	创建实例	必需	核心操作
6	验证创建结果	必需	确认实例创建成功

步骤	跳过条件
创建资源组	使用默认资源组
创建 KMS 实例	使用默认密钥或不加密
查询 VPC/VSwitch	用户已提供 VPC/VSwitch ID（但仍需验证）
验证可用区	创建副本集或分片集群实例

[MUST] 用户提供 VPC/VSwitch 时必须进行验证： 即使用户已提供 VPC ID 和 VSwitch ID，也必须先调用以下 API 验证其正确性和可用性：

1. describe-rds-vpcs：验证 VPC ID 是否存在且可用
2. describe-rds-vswitchs：验证 VSwitch ID 是否存在于指定 VPC 中，且与目标可用区匹配
3. 如果任何验证失败，必须告知用户具体错误并引导其修正；不得直接使用未经验证的 VPC/VSwitch 创建实例

[MUST] VPC/VSwitch 验证必须使用 DDS 专用 API；禁止使用通用 VPC API（vpc DescribeVpcs/vpc DescribeVSwitches）：

# Step 1: Query available VPC list for specified zone (DDS-specific)
aliyun dds describe-rds-vpcs --zone-id <zone> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Step 2: Query available VSwitches under specified VPC (DDS-specific)
aliyun dds describe-rds-vswitchs --vpc-id <vpc-id> --zone-id <zone> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

详细命令和参数：请参阅 references/operations.md § Step 2: Query and Validate VPC and VSwitch

创建副本集实例

• --db-instance-class 必须通过 describe-available-resource 查询（规格因地域/可用区/版本/存储类型而异）
• --zone-id 必须与 --vswitch-id 所属可用区匹配，否则会出现 InvalidVpcIdRegion.NotSupported 错误
• 多可用区部署需要 --secondary-zone-id 和 --hidden-zone-id

aliyun dds create-db-instance \
  --biz-region-id <region> --zone-id <zone> --engine-version <ver> \
  --db-instance-class <class> --db-instance-storage <GB> \
  --vpc-id <vpc> --vswitch-id <vsw> --network-type VPC \
  --replication-factor 3 --storage-type cloud_essd1 --charge-type PostPaid \
  --db-instance-description <name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Optional: --secondary-zone-id --hidden-zone-id --readonly-replicas --encryption-key --resource-group-id
# Subscription: --charge-type PrePaid --period 1 --auto-renew true

创建独立实例

• --replication-factor 1 --db-type replicate，存储类型固定为 cloud_essd1
• 必须使用独立实例专用规格（以 .1 结尾，如 dds.sn2.large.1，或包含 .single）；不能使用副本集规格
• 某些地域/可用区不支持；创建前必须查询 describe-available-resource --replication-factor 1
• 出现 InvalidDBInstanceNodeCount 错误时，尝试其他可用区，或建议切换为副本集

aliyun dds create-db-instance ... --db-type replicate --replication-factor 1 \
  --db-instance-class <standalone-specific-spec> --storage-type cloud_essd1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

创建分片集群实例

• 至少需要 2 个 Mongos 和 2 个 Shard（最多 32 个）；每个 Shard 默认是一个三节点副本集
• --mongos / --replica-set 参数需要重复指定（每次指定一个节点）
• 使用 --db-type sharding 查询分片集群规格（--db-type normal 仅用于副本集）

aliyun dds create-sharding-db-instance \
  --biz-region-id <region> --zone-id <zone> --engine MongoDB --engine-version <ver> \
  --vpc-id <vpc> --vswitch-id <vsw> --network-type VPC \
  --mongos Class=<class> --mongos Class=<class> \
  --replica-set Class=<class> ReadonlyReplicas=0 Storage=20 \
  --replica-set Class=<class> ReadonlyReplicas=0 Storage=20 \
  --config-server Class=<class> Storage=20 \
  --storage-type cloud_essd1 --charge-type PostPaid --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

实例创建错误诊断

错误诊断表：请参阅 references/operations.md § Instance Creation Error Diagnosis

修改副本集实例配置

[MUST] 修改前：

1. 查询当前配置（describe-db-instance-attribute），提取 DBInstanceStatus/DBInstanceClass/DBInstanceStorage/ReplicationFactor/ReadonlyReplicas/StorageType
2. 显示“当前值与新值”对比表，并获取用户的 Y 确认
3. 用户确认前不得执行修改命令

**限制：**不支持缩减存储、变更实例类型和变更存储类型（如需转换为 ESSD，请参阅“云盘重新配置”部分） **影响：**修改可能导致 1～2 次约 30 秒的短暂断连；建议在业务低峰期进行

修改命令成功后，仅显示 RequestId/OrderId；不得自动轮询；必须先征得用户确认才能开始

aliyun dds modify-db-instance-spec --db-instance-id <id> \
  [--db-instance-class <class>] [--db-instance-storage <GB>] \
  [--replication-factor 3/5/7] [--readonly-replicas 0-5] \
  [--order-type UPGRADE/DOWNGRADE] [--auto-pay true] \
  --effective-time Immediately/MaintainTime --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

完整参数说明：参见 references/operations.md § 修改副本集实例

删除实例

[MUST] 删除前检查清单：

1. 确认 ChargeType：PostPaid → 可以删除；PrePaid → 不能直接删除（等待到期或通过控制台退款）
2. 仅限云盘实例：查询 describe-backup-policy → 检查 BackupRetentionPolicyOnClusterDeletion（0=释放时删除所有备份 / 1=保留最近一次备份 / 2=保留所有备份）→ 删除前询问用户是否要通过 modify-backup-policy --backup-retention-policy-on-cluster-deletion 修改该设置；参见 operations.md
3. [MUST] 向用户显示确认信息：实例 ID、地域、计费类型、不可逆的数据丢失警告 → **要求用户回复“confirm delete {instance ID}”**后再执行

aliyun dds delete-db-instance --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

分片集群节点管理

[MUST] 主要限制：

• 至少保留 2 个 Mongos 和 2 个 Shard，最多 32 个
• 新 Shard 配置（规格 + 存储）必须 ≥ 现有 Shard 中配置最高的规格
• modify-node-spec 必须严格串行执行：必须等待上一次修改完成（Running）后，才能发起下一次修改
• 批量修改 modify-node-spec-batch 不支持更改 Shard 只读副本数；请改用单独修改
• 修改多个 Shard 时，必须与用户确认规格映射关系和执行顺序
• NodesInfo 中的 Storage 必须为数值类型（不能是字符串），否则会报 InvalidParameter 错误

# Query sharded cluster node details (ShardList/MongosList contain NodeId)
aliyun dds describe-db-instance-attribute --db-instance-id <id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Add single node
aliyun dds create-node --db-instance-id <id> --node-type mongos/shard --node-class <class> [--node-storage <GB>] --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Batch add nodes (JSON format)
aliyun dds create-node-batch --db-instance-id <id> --nodes-info '{"Shards":[{"DBInstanceClass":"spec","Storage":40}],"Mongos":[{"DBInstanceClass":"spec"}]}' --auto-pay true --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Single node modification (strictly serial)
aliyun dds modify-node-spec --db-instance-id <id> --node-id <node-id> --node-class <class> [--node-storage <GB>] [--readonly-replicas 0-5] --effective-time Immediately/MaintainTime --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Batch modification (does not support readonly replica changes, requires DBInstanceName)
aliyun dds modify-node-spec-batch --db-instance-id <id> --nodes-info '{"Shards":[{"DBInstanceClass":"spec","DBInstanceName":"d-xxx","Storage":40}]}' --auto-pay true --effective-time Immediately --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Release node
aliyun dds delete-node --db-instance-id <id> --node-id <node-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

详细命令示例和 NodesInfo 格式：参见 references/operations.md § 分片集群节点管理

云盘重新配置（磁盘类型升级）

[MUST] 与实例规格修改相互独立；用于更改磁盘类型或调整预配置 IOPS：

• 仅支持 ESSD PL1/PL2/PL3 → ESSD AutoPL（cloud_auto），单向且不可逆
• 前提条件：副本集存储 > 40GB；分片集群的 Shard 存储 > 40GB
• 预配置 IOPS 范围：0～50000；两次修改的间隔必须 > 1 小时
• 执行前，必须查询并显示 MaxIOPS/MaxMBPS/StorageType，并获取用户的 Y 确认
• 用户确认前不得执行

aliyun dds modify-db-instance-disk-type --db-instance-id <id> \
  --db-instance-storage-type cloud_auto [--provisioned-iops <0~50000>] \
  --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

完整参数说明：参见 references/operations.md § 云盘重新配置

IOPS 和吞吐量计算规则

[MUST] 仅适用于云盘实例（不适用于本地盘）：

• 显示基准 IOPS/吞吐量时，必须使用 API 返回的 MaxIOPS/MaxMBPS 字段，不得使用公式计算值（实际值 ≥ 公式计算值）
• 公式（供参考）：IOPS = min{1800+50×StorageGB, spec limit, disk type limit}
• 提升 IOPS 的优先级：扩容存储 > 升级规格 > 更改磁盘类型

完整的规格限制表和计算示例：参见 references/operations.md § IOPS 和吞吐量计算规则

重置根密码

[MUST] 对于分片集群，重置密码前必须询问用户：

你想重置哪种节点类型的密码？
[1] db 节点（mongod，存储业务数据）
[2] cs 节点（configServer，存储集群元数据）
[3] 重置两者（分别执行两次）

根据用户的回答确定执行次数；未经用户确认，不得自动执行两次

密码规则： 8-32 个字符，且必须包含以下至少三种字符：大写字母、小写字母、数字、特殊字符（!@#$%^&*()_+-=）

# Replica set / Standalone
aliyun dds reset-account-password --db-instance-id <id> --account-name root \
  --account-password <pwd> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Sharded cluster (--character-type db or cs, required)
aliyun dds reset-account-password --db-instance-id <id> --account-name root \
  --account-password <pwd> --character-type db --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

---

实例安全配置

管理 IP 白名单

[MUST] 修改白名单前：

1. 先查询当前白名单（describe-security-ips）并展示给用户
2. 询问修改模式：覆盖（覆盖现有内容，⚠️ 会删除现有 IP）/ 追加（添加，遇到重复 IP 会报错）/ 扩展（扩展，推荐）
3. 未经询问，不得使用覆盖模式

aliyun dds describe-security-ips --db-instance-id <id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
aliyun dds modify-security-ips --db-instance-id <id> --security-ips <IPs> --modify-mode Extend --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Specify group: add --security-ip-group-name <name>

管理 ECS 安全组

注意： 绑定到分片集群的 ECS 安全组仅适用于 Mongos 节点。

aliyun dds modify-security-group-configuration --db-instance-id <id> --security-group-id <sg-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
aliyun dds describe-security-group-configuration --db-instance-id <id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

管理全局白名单模板

[MUST] 所有全局白名单命令都必须同时指定 --region 和 --biz-region-id（值相同） 与实例关联时使用 --db-cluster-id（而非 --db-instance-id）

# Create
aliyun dds create-global-security-ip-group --biz-region-id <region> --region <region> --global-ig-name <name> --gip-list <IPs> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Query
aliyun dds describe-global-security-ip-group --biz-region-id <region> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Associate with instance
aliyun dds modify-global-security-ip-group-relation --db-cluster-id <id> --global-security-group-id <gid> --biz-region-id <region> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

---

管理公网地址

[MUST] SRV 地址的前提条件：（1）仅限云盘；（2）公网 SRV：先分配公网地址；（3）分片集群：先在 Mongos 节点上分配公网地址（--node-id <s-xxx>）；（4）每个步骤之间都要等待状态变为 Running

分片集群公网 SRV 检查流程： describe-sharding-network-address → 如果没有公网地址 → allocate-public-network-address --node-id <mongos-s-xxx> → 等待状态变为 Running → allocate-db-instance-srv-network-address --srv-connection-type public → 等待状态变为 Running → 确认 NodeType=logic 且带有 srv

[MUST] 网络地址查询 API 选择规则：

• 副本集：必须使用 describe-replica-set-role
• 分片集群：必须使用 describe-sharding-network-address
• 禁止：不得使用 describe-db-instance-attribute 查询网络地址——它不会返回分片集群的完整网络信息。在结果中：NetworkType=Public=公网；NodeType=logic+ConnectionType=SRV=SRV 地址

# Allocate public address (add --node-id <s-xxx> for sharded clusters)
aliyun dds allocate-public-network-address --db-instance-id <id> [--node-id <s-xxx>] --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Release non-SRV public address
aliyun dds release-public-network-address --db-instance-id <id> [--node-id <s-xxx>] --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Release SRV public address (sharded cluster MUST use --node-id <mongos-id> + --connection-type SRV; omitting either causes InvalidParameters.Format)
aliyun dds release-public-network-address --db-instance-id <id> --node-id <s-xxx> --connection-type SRV --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Allocate SRV address (vpc=private, public=public; public SRV requires public network address first)
aliyun dds allocate-db-instance-srv-network-address --db-instance-id <id> --srv-connection-type vpc/public --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Query (replica set)
aliyun dds describe-replica-set-role --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Query (sharded cluster)
aliyun dds describe-sharding-network-address --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

---

管理实例续费

续费仅适用于包年包月实例；自动续费次日生效；激活当天不会立即扣费。扣费重试计划请参阅 references/operations.md。

# Manual renewal (--period: 1~9, 12, 24, 36 months)
aliyun dds renew-db-instance --db-instance-id <id> --period <months> --auto-pay true --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Enable auto-renewal (--duration required, in months)
aliyun dds modify-instance-auto-renewal-attribute --db-instance-id <id> --auto-renew true --duration 1 --biz-region-id <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Disable auto-renewal
aliyun dds modify-instance-auto-renewal-attribute --db-instance-id <id> --auto-renew false --biz-region-id <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

转换实例计费类型

前提条件：实例状态为 Running，且不是旧版规格 [MUST] 使用 transform-instance-charge-type（不得使用 TransformToPrePaid，该 API 已禁止）

# Pay-As-You-Go → Subscription
aliyun dds transform-instance-charge-type --instance-id <id> --charge-type PrePaid --period 1 --pricing-cycle Month --auto-pay true --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Subscription → Pay-As-You-Go (no period needed, may involve refund)
aliyun dds transform-instance-charge-type --instance-id <id> --charge-type PostPaid --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

管理实例维护窗口

aliyun dds modify-db-instance-maintain-time --db-instance-id <id> --maintain-start-time "01:00Z" --maintain-end-time "02:00Z" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

---

其他操作

[MUST] 以下所有操作都要求实例状态为 Running。写操作响应请遵循标准（§ 信息展示规范，第 5 项）。 详细 CLI 命令和参数：请参阅 references/operations.md § 其他操作

操作	CLI 命令	主要限制
重启实例	restart-db-instance	[MUST] 执行前请向用户确认：实例 ID，以及预计会断连约 30 秒；建议在业务低峰期执行
重启节点	restart-node --node-id --role-id	[MUST] 执行前请向用户确认：实例 ID 和目标节点（RoleType/RoleId）；仅适用于云盘（StorageType=cloud_*），本地盘会返回 InsType.NotSupport；通过 describe-role-zone-info 查询 RoleId（包含 Hidden）；describe-replica-set-role 不包含 Hidden；分片集群要求同时指定 --node-id（例如 d-xxx）和 --role-id
手动备份	create-backup --backup-method	云盘：必须传入 --backup-method Snapshot；本地盘：Physical/Logical；云盘副本集/分片集群：--backup-retention-period（7-730 或 -1 表示永久）；响应中使用 BackupJobId（不要使用已弃用的 BackupId）；通过 describe-backup-tasks 轮询，然后查询 describe-backups --backup-job-id；请参阅 operations.md
查询备份	describe-backups --start-time --end-time	时间格式：yyyy-MM-ddTHH:mmZ（UTC）；响应：Backups.Backup[]；按任务筛选：--backup-job-id
查询备份策略	describe-backup-policy	查看保留天数和备份时间窗口
修改备份策略	modify-backup-policy	[MUST] 始终传入 --preferred-backup-time 和 --preferred-backup-period（即使只修改其他字段，这两个参数也是必需的）；先通过 describe-backup-policy 查询当前值；分片集群无法禁用日志备份
升级主版本	upgrade-db-instance-engine-version	不可逆的单向操作；请先查询可用版本
升级内核版本	upgrade-db-instance-kernel-version	仅适用于副本集和分片集群（不适用于单节点实例）
高可用切换	switch-db-instance-ha	[MUST] 先通过 describe-role-zone-info 查询节点；询问用户要交换哪两个节点的角色（例如 Primary↔Secondary、Secondary↔Hidden 等）；分片集群：必须指定 --node-id
创建账号	create-account	仅适用于云盘分片集群；名称：3-16 个小写字符
查询账号	describe-accounts	列出数据库账号
绑定标签	tag-resources --resource-type INSTANCE	--resource-id 使用空格分隔的列表；--tag Key=<k> Value=<v> 可重复使用；每个实例最多 20 个标签；使用 --biz-region-id；请参阅 operations.md
解绑标签	untag-resources --resource-type INSTANCE	移除指定的标签键
查询标签	list-tag-resources --resource-type INSTANCE	[MUST] 查询标签时只能使用 list-tag-resources API；禁止：不得使用 DescribeDBInstances 的 Tags 字段或 describe-tags 代替

CLI 不支持的功能

功能	说明
KMS 实例激活	创建 KMS 实例后，必须在 KMS 控制台中激活，并配置 VPC/VSwitch
免费试用申请	必须通过 阿里云免费试用页面申请

验证方法

详情请参阅 references/verification-method.md。

最佳实践

详情请参阅 references/operations.md § 最佳实践。

参考资料

参考资料	说明
references/operations.md	详细的 CLI 命令示例、参数表和 IOPS 计算规范表
references/related-apis.md	完整的 API 和 CLI 命令列表及外部文档链接
references/ram-policies.md	RAM 权限策略
references/verification-method.md	验证方法
references/cli-installation-guide.md	CLI 安装指南
references/acceptance-criteria.md	测试验收标准