• AWS Systems Manager CloudWatch 控制面板在 2026 年 4 月 30 日之后将不再可用。客户可以像现在一样继续使用 Amazon CloudWatch 控制台来查看、创建和管理其 Amazon CloudWatch 控制面板。有关更多信息，请参阅 [Amazon CloudWatch 控制面板文档](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。

# 排除 SSM Agent 问题
<a name="troubleshooting-ssm-agent"></a>

如果您在托管式节点上运行操作时遇到问题，可能是 AWS Systems Manager Agent (SSM Agent) 出现了问题。使用以下信息可帮助您查看 SSM Agent日志文件和排查该代理的问题。如果您的代理似乎没有响应或通信频率降低，请参阅 [了解 SSM Agent 休眠](ssm-agent-technical-details.md#ssm-agent-hibernation)。

**Topics**
+ [SSM Agent 已过时](#ssm-agent-out-of-date)
+ [使用 SSM Agent 日志文件进行故障排除](#systems-manager-ssm-agent-log-files)
+ [代理日志文件不会滚动 (Windows)](#systems-manager-ssm-agent-troubleshooting-log-rotation)
+ [无法连接到 SSM 端点](#systems-manager-ssm-agent-troubleshooting-endpoint-access)
+ [验证您的 VPC 配置](#agent-ts-vpc-configuration)
+ [验证 VPC DNS 相关属性](#agent-ts-dns-attributes)
+ [验证端点安全组的入口规则](#agent-ts-ingress-egress-rules)
+ [使用 `ssm-cli` 排查托管节点可用性的问题](#agent-ts-ssm-cli)

## SSM Agent 已过时
<a name="ssm-agent-out-of-date"></a>

如果有新工具添加至 Systems Manager 或者对现有工具进行了更新，则将发布 SSM Agent 的更新版本。无法使用代理的最新版本可能会阻止托管式节点使用 Systems Manager 的各项工具和功能。因此，我们建议您自动完成确保机器上的 SSM Agent 为最新的过程。有关更多信息，请参阅 [自动更新到 SSM Agent](ssm-agent-automatic-updates.md)。要获得有关 SSM Agent 更新的通知，请在 GitHub 上订阅 [SSM Agent 发布说明](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)页面。

## 使用 SSM Agent 日志文件进行故障排除
<a name="systems-manager-ssm-agent-log-files"></a>

SSM Agent在下列日志文件中记录信息。这些文件中的信息还可以帮助您排查问题。有关 SSM Agent 日志文件的更多信息（包括如何打开调试日志记录），请参阅 [查看 SSM Agent 日志](ssm-agent-logs.md)。

**注意**  
如果您选择使用 Windows 文件资源管理器查看这些日志，请务必在“文件夹选项”中允许查看隐藏文件和系统文件。

**在 Windows 上**
+  `%PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log` 
+  `%PROGRAMDATA%\Amazon\SSM\Logs\errors.log` 

**在 Linux 和 macOS 上**
+  `/var/log/amazon/ssm/amazon-ssm-agent.log` 
+  `/var/log/amazon/ssm/errors.log` 

对于 Linux 托管式节点，您可以在写入以下目录的 `messages` 文件中查找更多信息：`/var/log`。

有关使用代理日志进行故障排除的更多信息，请参阅《AWS re:Post 知识中心》**中的[如何使用 SSM Agent 日志排查托管实例中的 SSM Agent 问题？](https://repost.aws/knowledge-center/ssm-agent-logs)。

## 代理日志文件不会滚动 (Windows)
<a name="systems-manager-ssm-agent-troubleshooting-log-rotation"></a>

如果您在 seelog.xml 文件（在 Windows Server 托管式节点上）中指定基于日期的日志文件轮换，并且日志不轮换，请指定 `fullname=true` 参数。下面是指定了 `fullname=true` 参数的 seelog.xml 配置文件的示例。

```
<seelog type="adaptive" mininterval="2000000" maxinterval="100000000" critmsgcount="500" minlevel="debug">
   <exceptions>
      <exception filepattern="test*" minlevel="error" />
   </exceptions>
   <outputs formatid="fmtinfo">
      <console formatid="fmtinfo" />
      <rollingfile type="date" datepattern="200601021504" maxrolls="4" filename="C:\ProgramData\Amazon\SSM\Logs\amazon-ssm-agent.log" fullname="true" />
      <filter levels="error,critical" formatid="fmterror">
         <rollingfile type="date" datepattern="200601021504" maxrolls="4" filename="C:\ProgramData\Amazon\SSM\Logs\errors.log" fullname="true" />
      </filter>
   </outputs>
   <formats>
      <format id="fmterror" format="%Date %Time %LEVEL [%FuncShort @ %File.%Line] %Msg%n" />
      <format id="fmtdebug" format="%Date %Time %LEVEL [%FuncShort @ %File.%Line] %Msg%n" />
      <format id="fmtinfo" format="%Date %Time %LEVEL %Msg%n" />
   </formats>
</seelog>
```

## 无法连接到 SSM 端点
<a name="systems-manager-ssm-agent-troubleshooting-endpoint-access"></a>

SSM Agent 必须允许到以下端点的 HTTPS（端口 443）出站流量：
+  `ssm.region.amazonaws.com` 
+  `ssmmessages.region.amazonaws.com` 

*region* 表示 AWS Systems Manager 支持的 AWS 区域 的标识符，例如 `us-east-2` 对应美国东部（俄亥俄州）区域。有关支持的 *region* 值的列表，请参阅*《Amazon Web Services 一般参考》*中的 [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) 的 **Region** 列。

**注意**  
在 2024 年之前，还需要 `ec2messages.region.amazonaws.com`。对于在 2024 年之前推出的 AWS 区域，仍然需要允许流向 `ssmmessages.region.amazonaws.com` 的流量，但流向 `ec2messages.region.amazonaws.com` 的流量是可选的。  
对于 2024 年及之后推出的区域，需要允许流向 `ssmmessages.region.amazonaws.com` 的流量，但这些区域不支持 `ec2messages.region.amazonaws.com` 端点。

如果 SSM Agent 无法与前面的端点进行通信（如上所述），则其无法正常运行，即使您使用 AWS 提供的 Amazon Machine Images（AMIs），例如 Amazon Linux 2 或 Amazon Linux 2023。您的网络配置必须具有开放的互联网访问权限，或者您必须配置自定义 Virtual Private Cloud (VPC) 端点。如果您不打算创建自定义 VPC 端点，请检查您的互联网网关或 NAT 网关。有关如何管理 VPC 端点的更多信息，请参阅 [使用适用于 Systems Manager 的 VPC 端点提高 EC2 实例的安全性](setup-create-vpc.md)。

## 验证您的 VPC 配置
<a name="agent-ts-vpc-configuration"></a>

如果使用了虚拟私有云 (VPC)，则要使用 Systems Manager 管理 EC2 实例，就必须为 `ssm.region.amazonaws.com`、`ssmmessages.region.amazonaws.com` 正确配置 VPC 端点，在某些情况下，本主题前面的 [无法连接到 SSM 端点](#systems-manager-ssm-agent-troubleshooting-endpoint-access) 和 `ec2messages.region.amazonaws.com` 中对此进行了说明。

**注意**  
使用 VPC 端点的替代方法是，在托管实例上允许出站 Internet 访问。在这种情况下，托管实例还必须允许以下端点的 HTTPS（端口 443）出站流量：  
`ssm.region.amazonaws.com`
`ssmmessages.region.amazonaws.com`
`ec2messages.region.amazonaws.com`
SSM Agent 将在云中启动所有与 Systems Manager 服务的连接。因此，您无需为 Systems Manager 配置防火墙以允许入站流量到达您的实例。  
有关对这些端点的调用的更多信息，请参阅 [参考：ec2messages、ssmmessages 和其他 API 操作](systems-manager-setting-up-messageAPIs.md)。

要排查 VPC 端点的问题，请执行以下操作：
+ 确保在 VPC 级别包含 VPC 端点。如果在 VPC 上找不到具有特定服务名称的 VPC 端点，请先验证是否已在 VPC 级别启用 DNS 支持。接下来，创建一个新的 VPC 端点，将其与每个可用区中的一个子网关联。
+ 确保在 VPC 端点级别启用私有 DNS 名称。私有 DNS 名称默认处于启用状态，但可能在某些时候被手动禁用。
+ 确保现有 VPC 端点与适当的子网关联。此外，请确保 VPCE 已与该可用区中的子网关联。

有关更多信息，请参阅以下主题：
+ 《AWS PrivateLink 指南》**中的[使用接口 VPC 端点访问 AWS 服务](https://docs.aws.amazon.com//vpc/latest/privatelink/create-interface-endpoint.html)
+ 《AWS PrivateLink 指南》**中的[关联私有 DNS 名称](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#associate-private-dns-name)
+ [使用适用于 Systems Manager 的 VPC 端点提高 EC2 实例的安全性](setup-create-vpc.md)

## 验证 VPC DNS 相关属性
<a name="agent-ts-dns-attributes"></a>

如果使用了虚拟私有云 (VPC)，则作为验证 VPC 配置的一部分，需确保属性 `enableDnsSupport` 和 `enableDnsHostnames` 已启用。

您可以使用 Amazon EC2 [ModifyVPCAttribute](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyVpcAttribute.html) API 操作或 AWS CLI 命令 [modify-vpc-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-vpc-attribute.html) 启用这些属性。

有关在 Amazon VPC 控制台启用这些属性的信息，请参阅《Amazon VPC 用户指南》**中的[查看和更新 VPC 的 DNS 属性](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns-updating.html)。

**注意**  
使用 VPC 端点的替代方法是，在托管实例上允许出站 Internet 访问。在这种情况下，托管实例还必须允许以下端点的 HTTPS（端口 443）出站流量：  
`ssm.region.amazonaws.com`
`ssmmessages.region.amazonaws.com`
`ec2messages.region.amazonaws.com`
SSM Agent 将在云中启动所有与 Systems Manager 服务的连接。因此，您无需为 Systems Manager 配置防火墙以允许入站流量到达您的实例。  
有关对这些端点的调用的更多信息，请参阅 [参考：ec2messages、ssmmessages 和其他 API 操作](systems-manager-setting-up-messageAPIs.md)。

## 验证端点安全组的入口规则
<a name="agent-ts-ingress-egress-rules"></a>

确保您配置的任何 VPC 端节（`ssm`、`ssmmessages` 和 `ec2messages`）在其安全组中包含入口规则，以允许流量在端口 443 上进入。如有必要，您可以在 VPC 中创建一个新的安全组，并设置一条入口规则来允许端口 443 上的流量通过 VPC 的无类别域间路由 (CIDR) 块。创建安全组后，将其附加到每个 VPC 端点。

有关更多信息，请参阅以下主题：
+ [如何创建 VPC 端点，以便在没有互联网接入的情况下使用 System Manager 管理私有 EC2 实例？](https://repost.aws/knowledge-center/ec2-systems-manager-vpc-endpoints)AWS re:Post
+ 《Amazon VPC 用户指南》**中的 [VPC CIDR 块](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-cidr-blocks.html)

## 使用 `ssm-cli` 排查托管节点可用性的问题
<a name="agent-ts-ssm-cli"></a>

从 SSM Agent 版本 3.1.501.0 开始，可以使用 `ssm-cli` 来确定托管式节点是否满足由 Systems Manager 管理的主要要求，并出现在 Fleet Manager 中的托管式节点列表。`ssm-cli` 是包含在 SSM Agent 安装中的独立命令行工具。包含用于收集所需信息的预配置命令，以帮助您诊断您已确认正在运行的 Amazon EC2 实例或非 EC2 计算机未包含在 Systems Manager 的托管式节点列表中的原因。这些命令会在您指定 `get-diagnostics` 选项时运行。

有关更多信息，请参阅 [使用 `ssm-cli` 排除托管节点可用性的故障](troubleshooting-managed-nodes-using-ssm-cli.md)。