alibabacloud-ecs-patch-management

ECS 补丁管理

使用 OOS 模板 ACS-ECS-BulkyApplyPatchBaseline 扫描并安装 Alibaba Cloud ECS 实例上的操作系统补丁。

架构

ECS + OOS + Cloud Assistant + Snapshot（可选）

• OOS 模板：ACS-ECS-BulkyApplyPatchBaseline — 用于批量补丁操作的内置公共模板
• Cloud Assistant：在 ECS 实例上执行补丁命令（需要安装 Cloud Assistant 客户端）
• Snapshot Service：创建补丁安装前的磁盘快照，以便安全回滚（可选）
• 补丁基线：定义要扫描或安装的补丁（使用默认系统基线或自定义基线）

预检查：需要 Aliyun CLI >= 3.3.3

运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装或更新， 或参阅 references/cli-installation-guide.md 了解安装说明。

预检查：需要更新 Aliyun CLI 插件

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

预检查：需要 Alibaba Cloud 凭证

安全规则：

• 绝不读取、回显或打印 AK/SK 值
• 绝不要求用户在对话或命令行中直接输入 AK/SK
• 绝不使用包含明文凭证值的 aliyun configure set
• 仅使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否有有效配置（AK、STS 或 OAuth 身份）。

如果没有有效配置，请在此处停止。

1. 从 Alibaba Cloud Console 获取凭证
2. 在此会话之外配置凭证（通过终端中的 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回并在 aliyun configure list 显示有效配置后重新运行

AI-Mode 生命周期管理

在 Core Workflow 开始时（调用任何 CLI 之前）： [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-ecs-patch-management"

[MUST] 在每个退出点禁用 AI-Mode — 无论出于何种原因，在发送最终回复之前，始终先禁用 AI-mode。此要求适用于所有退出路径：工作流成功、工作流失败、错误或异常、用户取消、会话结束，或其他任何不会再执行 CLI 命令的情况。 AI-mode 仅用于 Agent Skill 调用场景，Skill 停止运行后不得继续启用。

aliyun configure ai-mode disable

RAM 策略

此 Skill 所需权限：

服务	操作	用途
OOS	StartExecution、ListExecutions、CancelExecution、ListTemplates、GetTemplate	管理补丁执行
OOS	ListPatchBaselines、GetPatchBaseline、ListInstancePatches、ListInstancePatchStates	查询补丁基线和状态
ECS	DescribeInstances、DescribeInvocations、DescribeInvocationResults、InvokeCommand	实例验证和 Cloud Assistant
ECS	CreateSnapshot、DescribeSnapshots	快照管理（可选）

完整详情：references/ram-policies.md

[MUST] 权限失败处理： 执行期间的任何时候，如果命令或 API 调用因权限错误而失败，请按以下流程处理：

1. 阅读 references/ram-policies.md，获取此 SKILL 所需权限的完整列表
2. 使用 ram-permission-diagnose Skill 指导用户申请所需权限
3. 暂停操作，等待用户确认已授予所需权限

需要用户确认的参数

重要：参数确认 — 执行任何命令或 API 调用之前，必须与用户确认所有可由用户自定义的参数（例如 RegionId、实例 ID、操作类型、快照设置等）。切勿在未经用户明确同意的情况下假设或使用默认值。

参数	必填	说明	默认值
regionId	是	Alibaba Cloud 区域 ID（例如，cn-hangzhou、cn-shanghai）	无
instanceIds	是	目标 ECS 实例 ID（例如，["i-bp1example0000000001"]）	无
action	是	操作类型：scan（仅扫描）或 install（扫描 + 安装）	无
rebootIfNeed	否（仅安装时）	如果补丁需要重启，是否重启实例	false
whetherCreateSnapshot	否（仅安装时）	安装补丁前是否创建快照	false
retentionDays	否（仅安装时）	快照保留天数。建议：7–30（API 范围：1–65536）	7

上述参数名称与 --parameters 中使用的 JSON 字段名称一致（顶层键为 camelCase）。请注意，嵌套的 targets 对象使用 PascalCase 键（ResourceIds、RegionId、Type）——请参阅下方步骤 3 中的示例。

核心工作流

步骤 0：启用 AI 模式

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ecs-patch-management"

# [MUST] Register a shell trap so AI-mode is disabled on EVERY exit path
# (success, error, signal, Ctrl-C, abnormal termination). This is the
# fail-safe complement to the explicit `disable` call in Step 7.
trap 'aliyun configure ai-mode disable' EXIT

步骤 1：验证 CLI 和凭证

aliyun version
aliyun configure list

步骤 2：验证目标实例

确认目标 ECS 实例存在且状态为 Running：

aliyun ecs describe-instances \
  --region <RegionId> \
  --instance-ids '<InstanceIds_JSON>' \
  --cli-query 'Instances.Instance[].{InstanceId:InstanceId, Status:Status, OSName:OSName}'

前提条件：目标 ECS 实例必须已安装并运行 Cloud Assistant 客户端。大多数 Alibaba Cloud 公共镜像默认已包含该客户端。

步骤 3：启动补丁执行

[MUST] 按照用户要求执行操作。 如果用户明确要求安装补丁（例如“装补丁”“安装补丁”“install patches”），你必须执行 action=install。即使之前的扫描结果显示没有缺失补丁，也不得跳过安装调用。扫描结果仅供参考——安装操作有自己的检测逻辑，且用户的明确意图始终优先。

[MUST] StartExecution 是异步的。 响应仅确认执行已提交，并不代表执行已完成。响应会返回格式为 exec-xxx 的 ExecutionId（例如，exec-example0000000001）。你必须捕获此 ExecutionId，并轮询 ListExecutions（步骤 4），直到 Status 达到终止值（Success 或 Failed），才能将操作视为完成。不得将成功的 StartExecution 响应视为补丁操作成功的证明。

[MUST] 通过 ClientToken 实现幂等性。 StartExecution 是写入操作。网络超时、传输层错误或 Agent 重试循环可能导致同一调用被执行多次，否则会创建重复执行（对于 install，还可能重复创建快照或重启）。你必须根据请求输入确定性地生成 --client-token，使相同输入的重试最终指向同一次执行。

生成规则 — 根据规范化输入（action、region、排序后的实例 ID，以及会改变行为的仅限安装选项）计算稳定哈希：

# 根据规范化输入生成确定性的 ClientToken（≤ 64 个字符）。
# 每次重试都使用相同的公式 — 服务端会在约 24 小时内去重。
CLIENT_TOKEN="patch-$(printf '%s|%s|%s|%s|%s|%s' \
  "<action>" "<RegionId>" "<sorted_comma_joined_InstanceIds>" \
  "<rebootIfNeed_or_empty>" "<whetherCreateSnapshot_or_empty>" "<retentionDays_or_empty>" \
  | shasum -a 256 | cut -c1-32)"
# 示例输出：patch-9f3c1a8b7e6d5c4f3a2b1d0e9c8b7a6f

每次调用 start-execution 时，都将生成的值作为 --client-token "$CLIENT_TOKEN" 传递。如果必须在暂时性故障后重试，请重复使用相同的 token；切勿重新生成。

选项 A：仅扫描

aliyun oos start-execution \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --template-name ACS-ECS-BulkyApplyPatchBaseline \
  --client-token "$CLIENT_TOKEN" \
  --parameters '{"regionId":"<RegionId>","action":"scan","targets":{"ResourceIds":<InstanceIds_JSON>,"RegionId":"<RegionId>","Type":"ResourceIds"}}'

选项 B：安装补丁

🚨 危险 — 此操作具有破坏性，必须获得用户明确确认。 action=install 会修改目标实例上的系统软件包；如果 rebootIfNeed=true，还可能会重启实例，导致服务中断。

执行以下命令之前，你必须：

1. 在一条确认消息中向用户展示完整的执行计划：regionId、目标实例 ID 的确切列表（以及数量）、rebootIfNeed、whetherCreateSnapshot、retentionDays。
2. 明确说明：“即将在 的 N 个实例上安装补丁。重启=<true/false>。快照=<true/false>。是否继续？”
3. 等待用户明确回复（yes / 确认 / proceed）。不要根据之前的对话推断用户已同意，也不要在用户未回复时默认同意。
4. 如果用户更改了任何参数，请重新生成 CLIENT_TOKEN 并再次确认。

aliyun oos start-execution \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --template-name ACS-ECS-BulkyApplyPatchBaseline \
  --client-token "$CLIENT_TOKEN" \
  --parameters '{"regionId":"<RegionId>","action":"install","rebootIfNeed":<true/false>,"whetherCreateSnapshot":<true/false>,"retentionDays":<number>,"targets":{"ResourceIds":<InstanceIds_JSON>,"RegionId":"<RegionId>","Type":"ResourceIds"}}'

示例 — 扫描 cn-hangzhou 中的实例 i-bp1example0000000001：

CLIENT_TOKEN="patch-$(printf 'scan|cn-hangzhou|i-bp1example0000000001|||' | shasum -a 256 | cut -c1-32)"

aliyun oos start-execution \
  --region cn-hangzhou \
  --biz-region-id cn-hangzhou \
  --template-name ACS-ECS-BulkyApplyPatchBaseline \
  --client-token "$CLIENT_TOKEN" \
  --parameters '{"regionId":"cn-hangzhou","action":"scan","targets":{"ResourceIds":["i-bp1example0000000001"],"RegionId":"cn-hangzhou","Type":"ResourceIds"}}'

示例 — 安装补丁并创建快照、自动重启：

CLIENT_TOKEN="patch-$(printf 'install|cn-hangzhou|i-bp1example0000000001|true|true|7' | shasum -a 256 | cut -c1-32)"

aliyun oos start-execution \
  --region cn-hangzhou \
  --biz-region-id cn-hangzhou \
  --template-name ACS-ECS-BulkyApplyPatchBaseline \
  --client-token "$CLIENT_TOKEN" \
  --parameters '{"regionId":"cn-hangzhou","action":"install","rebootIfNeed":true,"whetherCreateSnapshot":true,"retentionDays":7,"targets":{"ResourceIds":["i-bp1example0000000001"],"RegionId":"cn-hangzhou","Type":"ResourceIds"}}'

步骤 4：监控执行状态

从步骤 3 的响应中提取 ExecutionId（格式：exec-xxx），然后轮询 ListExecutions，直到执行进入终止状态：

aliyun oos list-executions \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --execution-id <ExecutionId> \
  --cli-query 'Executions.Execution[0].{ExecutionId:ExecutionId, Status:Status, StartDate:StartDate, EndDate:EndDate}'

终止状态（当 Status 与以下任一状态匹配时，停止轮询）：

状态	含义	后续操作
Success	执行成功完成	继续执行步骤 5（查看日志）和步骤 6（验证补丁）
Failed	执行失败	在步骤 5 中检查日志以诊断故障
Cancelled	执行已取消	无需进一步操作；如有需要，可重新运行

非终止状态（继续轮询）：Started、Running、Queued、Waiting。以合理的间隔（例如每 10–30 秒）继续轮询，直到进入终止状态。只有当 Status 为 Success 或 Failed 时，才能认为补丁操作已完成。

步骤 5：查看执行日志

aliyun oos list-execution-logs \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --execution-id <ExecutionId>

步骤 6：验证补丁结果

scan 或 install 执行进入 Success 后，可通过两个互补的 API 查看每个实例上的补丁状态：

6a. ListInstancePatches — 单个实例的补丁详情

返回在实例上检测到的所有单个补丁，并附带补丁名称/KB、分类、严重性和每个补丁的状态（例如 Installed、Missing、NotApplicable）等元数据。使用此 API 查看哪些补丁已存在、缺失或安装失败。

aliyun oos list-instance-patches \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --instance-id <InstanceId>

6b. ListInstancePatchStates — 跨实例的状态数量汇总

按状态汇总每个实例的补丁数量（例如 InstalledCount、MissingCount、FailedCount、NotApplicableCount）。使用此 API 快速了解每类补丁的数量，而无需逐一列出补丁。

aliyun oos list-instance-patch-states \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --instance-ids '<InstanceIds_JSON>'

如何选择：

• 需要高层级的合规性汇总（例如“实例 i-xxx 仍有 3 个缺失补丁”）？→ ListInstancePatchStates
• 需要确定具体的补丁（例如“哪些 CVE 仍然缺失”）？→ ListInstancePatches

步骤 7：禁用 AI 模式

aliyun configure ai-mode disable

[MUST] 无论在哪个退出点，都必须始终禁用 AI 模式 — 无论成功、失败、出错还是取消。

成功验证

详细验证步骤请参阅 references/verification-method.md。

快速验证清单：

步骤	检查项	命令
1	CLI 版本 >= 3.3.3	aliyun version
2	凭据有效	aliyun configure list
3	实例正在运行	aliyun ecs describe-instances
4	执行已启动	响应包含 ExecutionId
5	执行成功	通过 list-executions 检查 Status = Success
6	补丁已应用	list-instance-patches 显示 Missing 数量减少

清理

取消正在运行的执行

aliyun oos cancel-execution \
  --region <RegionId> \
  --execution-id <ExecutionId>

快照生命周期

使用 whetherCreateSnapshot=true 创建的快照会在 retentionDays 保留期限到期后自动删除。请勿手动删除这些快照——依靠保留期限进行清理，可确保清理过程确定，并避免意外删除其他回滚工作流仍需要的快照。

查看现有快照（只读）：

aliyun ecs describe-snapshots \
  --region <RegionId> \
  --instance-id <InstanceId>

最佳实践

1. 安装前务必扫描——先运行 action: scan，了解有哪些可用补丁，再决定是否安装。但是，如果用户明确要求安装补丁，则无论扫描结果如何，都必须执行 action=install。 扫描显示没有缺失补丁，并不意味着可以跳过安装——用户的明确意图优先。install 操作会自行执行内部扫描，并可能发现独立扫描未发现的补丁。用户要求安装时，绝不可用扫描代替安装。
2. 为生产环境启用快照——为生产实例设置 whetherCreateSnapshot: true 和适当的 retentionDays，以支持回滚。快照会自动过期——无需手动清理。
3. 安排在维护时段执行——安装补丁可能需要重启。请与业务相关方协调。
4. 先在非生产环境测试——将补丁应用到生产环境之前，务必先在预发布／开发实例上验证。
5. 监控执行日志——使用 list-execution-logs 跟踪实时进度并排查故障。
6. 谨慎处理重启——仅在可以接受实例停机时设置 rebootIfNeed: true。对于关键服务，请设置 rebootIfNeed: false 并手动重启。
7. 合理设置 retentionDays——建议设置为 7–30 天。保留时间越长，存储成本越高。

参考链接

资源	路径
CLI 安装指南	references/cli-installation-guide.md
RAM 策略	references/ram-policies.md
相关命令	references/related-commands.md
验证方法	references/verification-method.md
验收标准	references/acceptance-criteria.md

相关文档

• OOS 官方文档
• ACS-ECS-BulkyApplyPatchBaseline 模板
• 补丁管理概述
• 云助手