alibabacloud-solution-deploy

Alibaba Cloud 解决方案部署

根据用户的场景选择最佳执行路径（Terraform 或 CLI），然后端到端地完成任务。

核心原则

最大程度自动化

如果需要 10 个步骤，其中 9 个可以自动化，就自动化这 9 个。只有确实需要人工操作时才暂停。凡是有 CLI 路径的云操作都应使用 CLI——用户找你正是为了不用在控制台中逐步点击。

CLI 优先，控制台兜底

将每项云操作都写成可运行的 aliyun CLI 命令。只有在没有 CLI 时才使用控制台——如果必须使用控制台，请提供直达的深层链接 URL（而不是产品主页）。https://vision.aliyun.com/facebody 和 https://console.aliyun.com/ 的区别，就是有帮助和毫无用处的区别。

绝不猜测——先验证

• CLI 语法：构造命令前，先运行 aliyun <product> <command> --help。不同产品的参数命名并不一致，可能是 --RegionId、--region-id 或 --region。
• 错误：发生故障时，立即运行 diagnose_cli_command.py。Alibaba Cloud API 的错误消息往往晦涩难懂——诊断脚本会调用专用端点，将错误代码映射为修复方法。

---

工作流

步骤 0：验证环境

在任何新会话中，首先运行：

预检查：需要 Aliyun CLI >= 3.3.1

运行 aliyun version，确认版本 >= 3.3.1。如果尚未安装或版本过低，请参阅安装指南了解操作说明。

然后运行以下命令，启用自动安装插件并设置 Agent 的 user-agent：

aliyun configure set --auto-plugin-install true --user-agent AlibabaCloud-Agent-Skills

这样可确保首次使用时自动下载特定产品的 CLI 插件（无需手动安装），并标识请求来自此技能。

然后运行完整的环境检查：

bash {{SKILL_PATH}}/scripts/verify_env.sh

此检查会验证：CLI 版本、凭证是否有效、是否启用自动安装插件，以及 Python3 和 SDK。如果任何检查未通过，请告知用户需要修复的内容并停止——环境异常意味着之后的每条命令都会失败。

RAM 权限预检查

执行任何命令前，先验证当前用户是否拥有所需权限：

1. 将用户的权限与 references/ram-policies.md 进行比对
2. 如果缺少任何权限，立即停止并提示用户附加所需策略

所需的最低权限列于 references/ram-policies.md。

步骤 1：了解场景

从用户的请求中提取：

• 要构建或配置的内容
• 涉及的 Alibaba Cloud 产品（或可推断出的产品）
• 关键要求：地域、实例规格、预算、高可用需求、环境（开发/预发布/生产）

整理出用于步骤 2 的搜索关键词（中文 + 英文）。例如，“我要搭个 RAG 知识库” → 关键词：RAG、知识库、AnalyticDB、百炼。

步骤 2：选择合适的路径

查看 references/alicloud-tech-solutions-all.md——这是包含 187 个 Alibaba Cloud 技术解决方案的主目录。根据解决方案名称和描述进行关键词匹配搜索。

每一行都有一个 Terraform Module 名称列：

• 列中有值（例如 analyticdb-rag、deepseek-personal-website）→ 路径 A：Terraform
• 列为空或未找到匹配的解决方案 → 路径 B：CLI 优先

还要使用 intent-mapping.md 进行模糊关键词到解决方案的匹配（例如，“小程序” → develop-your-wechat-mini-program-in-10-minutes）。

继续之前，先告诉用户你选择了哪条路径，以及原因。

---

路径 A：Terraform 解决方案

当有匹配的 Terraform 模块时，通过 IaCService 远程运行时进行部署——无需本地 terraform 二进制文件。

A.1: 定位模块

在 references/tf-plan/tf-solutions.md 中查找模块名称和模块地址。匹配顺序如下：

1. 与主目录中的模块名称完全匹配
2. 根据描述列进行关键词匹配
3. 意图映射

A.2: 获取示例参数

每个模块都有一个包含经过测试的示例的 GitHub 仓库。按以下方式推导 URL：

Module 地址: https://registry.terraform.io/modules/alibabacloud-automation/<name>/alicloud/latest
GitHub repo: https://github.com/alibabacloud-automation/terraform-alicloud-<name>
Example:     https://raw.githubusercontent.com/alibabacloud-automation/terraform-alicloud-<name>/main/examples/complete/main.tf

使用 WebFetch 获取示例 main.tf。这些值来自经过实际测试的部署，比通用默认值可靠得多。

参数优先级：

1. 用户明确指定的值 → 始终使用
2. examples/complete/ 中的示例 main.tf → 用作默认值
3. 备用默认值（仅在获取失败时）：参见 terraform-defaults.md

A.3: 与用户确认

展示参数并请求确认。切勿在未告知用户的情况下直接应用——云资源会产生实际费用。

以下是基于官方示例的部署参数，请确认或修改：
• Region: cn-hangzhou
• Instance type: ecs.c7.large
• VPC CIDR: 172.16.0.0/12
• Password: (请提供)

密码和 API 密钥等敏感值：切勿自行生成，应由用户提供。

A.4: 编写 main.tf 并部署

# Based on: https://github.com/alibabacloud-automation/terraform-alicloud-<name>/blob/main/examples/complete/main.tf
module "<module_name>" {
  source  = "alibabacloud-automation/<module_name>/alicloud"
  version = "~> 1.0"
  # Parameters adjusted per user confirmation
}

使用远程运行时进行部署——完整用法请参见 terraform-online-runtime.md：

SKILL_DIR="{{SKILL_PATH}}"
TF="${SKILL_DIR}/scripts/terraform_runtime_online.sh"
STATE_ID=$($TF apply main.tf | grep '^STATE_ID=' | cut -d= -f2)
echo "STATE_ID=$STATE_ID" >> terraform_state_ids.env

任何后续更新或销毁操作都需要 STATE_ID。丢失它就意味着失去对资源的控制。

A.5: 验证并报告

确认资源已创建。提供用于清理的销毁命令。

---

路径 B：CLI 优先执行

此路径无需 Terraform 模板即可完成所有操作。方法是：了解架构 → 拆解步骤 → 为每个步骤找到 CLI 命令 → 执行。

B.1: 了解架构

编写任何命令之前，先了解要构建的内容：

• 如果主目录中有匹配的解决方案（只是没有 TF 模块），它仍然包含教程链接（部署教程列）。获取该页面，了解目标架构、所需产品和部署顺序。这会提供蓝图——然后你可以将每个步骤转换为 CLI 命令。
• 如果没有匹配的解决方案，则根据用户的描述进行判断：需要哪些产品、它们之间有什么依赖关系，以及最终状态是什么。

B.2: 拆解步骤

将目标拆分为按依赖顺序排列的原子步骤。考虑以下事项：

• 资源创建顺序：VPC → VSwitch → 安全组 → ECS 几乎总是基础步骤
• ID 传递：哪些步骤会输出后续步骤所需的 ID（VpcId → CreateVSwitch，VSwitchId → RunInstances）
• 异步操作：某些创建调用会立即返回，但资源需要等待一段时间才能就绪——你需要轮询
• 可能没有 CLI 的操作：某些产品开通、某些仅限控制台的功能

B.3: 调研 CLI 命令

对每个步骤，使用脚本查找正确的 API 名称和参数。这一点至关重要——不要依赖记忆。Alibaba Cloud 有数千个 API，而且不同产品的参数名称并不一致。

python3 {{SKILL_PATH}}/scripts/lsit_products.py '<keyword>'        # Find product code + API version
python3 {{SKILL_PATH}}/scripts/search_apis.py '<what you want to do>'  # Natural language → API
python3 {{SKILL_PATH}}/scripts/search_documents.py '<topic>'       # Parameter details, valid values, constraints
python3 {{SKILL_PATH}}/scripts/lsit_api_overview.py <Product> <version>  # Full API list for a product

调研多个产品时并行运行脚本——能并行的操作不要串行执行。

可完全避开控制台的常用 CLI 快捷方式：

场景	CLI 命令	备注
获取百炼 API Key	aliyun modelstudio list-workspaces → aliyun modelstudio create-api-key --WorkspaceId <id>	完全无需使用控制台。几乎所有 AI 解决方案都需要它。
在 ECS 上运行命令	aliyun ecs RunCommand --Type RunShellScript --CommandContent '<script>' --InstanceId.1 <id>	使用云助手，而不是让用户通过 SSH 登录。
OSS 操作	aliyun ossutil cp/ls/mb ...	使用 ossutil 子命令，而不是 oss。

百炼 API Key 的操作模式尤其重要——几乎所有 AI 相关解决方案都需要 DashScope/百炼 SK，而用户通常不知道可以通过程序获取。只要计划涉及百炼/Bailian/DashScope，就应主动使用 modelstudio 命令获取密钥。

B.4：展示计划并确认

在运行任何写入操作之前，展示完整的执行计划。计划必须包含 RAM 权限部分，列出当前账户所需的所有权限，以便用户在执行开始前验证访问权限，避免部署过程中出现 Forbidden.RAM 错误。

根据计划中的 CLI 命令推导所需权限：每个 aliyun <product> <API> 调用都对应一个格式为 <product>:<API> 的 RAM 操作（例如，aliyun vpc CreateVpc → vpc:CreateVpc）。

所需 RAM 权限:

| 云产品 | 所需权限 (Action) | 对应步骤 | 快捷策略 |
|--------|-------------------|----------|----------|
| VPC | vpc:CreateVpc, vpc:CreateVSwitch, vpc:DescribeVpcs | 步骤 1-2 | AliyunVPCFullAccess |
| ECS | ecs:RunInstances, ecs:DescribeInstances, ecs:RunCommand | 步骤 4-6 | AliyunECSFullAccess |
| EIP | vpc:AllocateEipAddress, vpc:AssociateEipAddress | 步骤 3 | AliyunEIPFullAccess |

提示: 可使用快捷策略快速授权，或按 Action 列配置最小权限自定义策略。

---

执行计划 (共 N 步, M 步 CLI 自动化, K 步需控制台):

步骤 1 — 创建 VPC
  aliyun vpc CreateVpc --RegionId cn-hangzhou --CidrBlock 172.16.0.0/12 --VpcName demo-vpc

步骤 2 — 创建交换机 (依赖: 步骤1 VpcId)
  aliyun vpc CreateVSwitch --RegionId cn-hangzhou --VpcId <步骤1> --ZoneId cn-hangzhou-h --CidrBlock 172.16.0.0/24

步骤 3 — [控制台] 开通视觉智能 API (无 CLI)
  打开: https://vision.aliyun.com/facebody → 点击 "立即开通"

等待用户批准。云资源会产生费用，且某些操作（例如删除 RDS 实例）不可逆。

B.5：执行

对于每个步骤：

1. 先验证语法：aliyun <product> <api> --help —— 在参数错误提交到 API 之前将其发现
2. 运行命令
3. 验证结果：轮询异步操作；描述资源以确认其存在
4. 捕获输出：保存 ID、终端节点、连接字符串，供后续步骤和最终报告使用

B.6：处理错误

命令失败时：

python3 {{SKILL_PATH}}/scripts/diagnose_cli_command.py '<the full command>' '<the error message>'

诊断脚本会调用专用 API，将错误代码映射为可执行的修复方案。应用修复并重试。如果修复后仍出现相同错误，请向用户报告诊断结果，不要盲目地反复重试。

从失败步骤继续。绝不要重新运行已成功的步骤——这些资源已经存在，重新运行要么会失败（重复），要么会创建不需要的重复资源。

B.7：报告

总结：

• 已创建的资源（含 ID）
• 访问终端节点／连接字符串
• 如何使用已构建的内容
• 清理命令（按依赖关系逆序删除：ECS → 安全组 → VSwitch → VPC）

---

脚本参考

脚本	用途	示例
verify_env.sh	环境检查	bash {{SKILL_PATH}}/scripts/verify_env.sh
lsit_products.py	查找产品代码和版本	python3 {{SKILL_PATH}}/scripts/lsit_products.py 'ECS'
search_apis.py	自然语言 → API	python3 {{SKILL_PATH}}/scripts/search_apis.py '创建ECS实例'
search_documents.py	搜索文档以获取详情	python3 {{SKILL_PATH}}/scripts/search_documents.py 'ECS实例规格'
lsit_api_overview.py	获取产品的完整 API 列表	python3 {{SKILL_PATH}}/scripts/lsit_api_overview.py Ecs 2014-05-26
diagnose_cli_command.py	诊断 CLI 错误	python3 {{SKILL_PATH}}/scripts/diagnose_cli_command.py '<cmd>' '<err>'
terraform_runtime_online.sh	远程 TF 执行	参见 terraform-online-runtime.md

参考资料

• 意图映射 — 关键词 → 解决方案映射
• Terraform 默认值 — 默认参数值
• Terraform 在线运行时 — IaCService 脚本用法
• 所有技术解决方案目录 — 187 个解决方案及 TF Module 可用性
• TF 解决方案详情 — 48 个带 Registry 地址的 Terraform 模块