• 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 的技术细节
使用本主题中的信息有助于您实施 AWS Systems Manager Agent (SSM Agent) 并了解该代理的工作原理。
**Topics**
+ [SSM Agent 版本 3.2.x.x 凭证行为](#credentials-file)
+ [SSM Agent 凭证优先级](#credentials-precedence)
+ [配置 SSM Agent 以与美国联邦信息处理标准（FIPS）结合使用](#fips-compliant-configurations)
+ [关于本地 ssm-user 账户](#ssm-user-account)
+ [SSM Agent 和 Instance Metadata Service (IMDS)](#imds)
+ [保持 SSM Agent 的最新状态](#updating)
+ [确保 SSM Agent 安装目录未被修改、移动或删除](#installation-directory)
+ [按 AWS 区域 的 SSM Agent 滚动更新](#rolling-updates)
+ [SSM Agent 与 AWS 托管 S3 存储桶进行通信](#ssm-agent-minimum-s3-permissions)
+ [GitHub 上的 SSM Agent](#github)
+ [了解 SSM Agent 休眠](#ssm-agent-hibernation)
## SSM Agent 版本 3.2.x.x 凭证行为
使用 Quick Setup 中的默认主机管理配置加载实例时，SSM Agent 将一组临时凭证存储在 `/var/lib/amazon/ssm/credentials`（适用于 Linux 和 macOS）或 `%PROGRAMFILES%\Amazon\SSM\credentials`（适用于 Windows Server）。临时凭证具有您为默认主机管理配置选择的 IAM 角色指定的权限。在 Linux 上，只有 root 账户才能访问这些凭证。在 Windows Server 上，只有 SYSTEM 账户和本地管理员才能访问这些凭证。
## SSM Agent 凭证优先级
本主题介绍有关如何向 SSM Agent 授予对资源执行操作的权限的重要信息。
**注意**
对边缘设备的支持略有不同。必须将边缘设备配置为使用 AWS IoT Greengrass Core 软件，配置一个 AWS Identity and Access Management（IAM）服务角色，并使用 AWS IoT Greengrass 将 SSM Agent 部署到设备。有关更多信息，请参阅 [使用 Systems Manager 管理边缘设备](systems-manager-setting-up-edge-devices.md)。
在计算机上安装 SSM Agent 后，需要适当的权限才能与 Systems Manager 服务进行通信。在 Amazon Elastic Compute Cloud (Amazon EC2) 实例上，将在附加到实例的实例配置文件中提供这些权限。在非 EC2 计算机上，SSM Agent 通常从共享的凭证文件中获取所需的权限，该文件位于 `/root/.aws/credentials`（Linux 和 macOS）或 `%USERPROFILE%\.aws\credentials`（Windows Server）。所需的权限将在[混合激活](activations.md)过程中添加至此文件。如果取消注册混合激活节点，代理可能会进入休眠模式。有关更多信息，请参阅 [了解 SSM Agent 休眠](#ssm-agent-hibernation)。
但是，在极少数情况下，计算机的权限最终可能会添加至多个位置，SSM Agent 将检查这些位置是否有权运行其任务。
例如，您可能将 EC2 实例配置为由 Systems Manager 托管。该配置包括附加实例配置文件。但是，之后您决定还将该实例用于开发人员或终端用户任务，并在上面安装 AWS Command Line Interface（AWS CLI）。此类安装会导致将其他权限添加至实例上的凭证文件。
在实例上运行 Systems Manager 命令时，SSM Agent 可能会尝试使用与您期望使用的凭证不同的凭证，例如凭证文件而不是实例配置文件中的凭证。这是因为 SSM Agent 将按照*默认凭证提供程序链*的规定顺序查找凭证。
**注意**
在 Linux 和 macOS 上，SSM Agent 以根用户身份运行。因此，SSM Agent 在此过程中查找的环境变量和凭证文件仅属于根用户（`/root/.aws/credentials`）。SSM Agent 在搜索凭证期间，不会查看实例上任何其他用户的环境变量或凭证文件。
默认提供程序链将按照以下顺序查找凭证：
1. 环境变量（`AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY`）（如果已配置）。
1. 共享的凭证文件 (对于 Linux 和 macOS，为 `$HOME/.aws/credentials`；对于 Windows Server，为 `%USERPROFILE%\.aws\credentials`）以及混合激活或 AWS CLI 安装等提供的权限。
1. 任务的 AWS Identity and Access Management (IAM) 角色，如果存在一个应用程序使用 Amazon Elastic Container Service (Amazon ECS) 任务定义或 **RunTask** API 操作。
1. 附加到 Amazon EC2 实例的实例配置文件
1. 为默认主机管理配置选择的 IAM 角色。
有关信息，请参阅以下主题：
+ EC2 实例的实例配置文件 — [配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)
+ 混合激活 — [创建混合激活以将节点注册到 Systems Manager](hybrid-activation-managed-nodes.md)
+ AWS CLI 凭证 - *AWS Command Line Interface 用户指南*中的[配置和凭证文件设置](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)
+ 默认凭证提供程序链 -*适用于 Go 的 AWS SDK Developer Guide* 中的[指定凭证](https://docs.aws.amazon.com/sdk-for-go/latest/developer-guide/configuring-sdk.html#specifying-credentials)
**注意**
*适用于 Go 的 AWS SDK Developer Guide* 中的本主题介绍了 SDK for Go 的默认提供程序链；但是，评估 SSM Agent 的凭证时也遵循同一原则。
## 配置 SSM Agent 以与美国联邦信息处理标准（FIPS）结合使用
如果您需要将 Systems Manager 与经美国联邦信息处理标准（FIPS）140-3 验证的加密模块结合使用，则可以将 AWS Systems Manager Agent（SSM Agent）配置为在支持的区域中使用 FIPS 端点。
**若要配置 SSM Agent 以连接至 FIPS 140-3 端点**
1. 连接到您的托管节点
1. 导航到包含 `amazon-ssm-agent.json` 文件的目录：
+ Linux：`/etc/amazon/ssm/`
+ macOS: `/opt/aws/ssm/`
+ Windows Server: `C:\Program Files\Amazon\SSM\`
1. 打开名为 `amazon-ssm-agent.json` 的文件进行编辑。
**提示**
如果尚不存在任何 `amazon-ssm-agent.json` 文件，请将 `amazon-ssm-agent.json.template` 的内容复制到名为 `amazon-ssm-agent.json` 的新文件中。Save`amazon-ssm-agent.json`在同一目录中，其中`amazon-ssm-agent.json.template`位于中。
1. 将以下内容添加到该文件。将 *region* 占位符值替换为分区的相应区域代码：
```
{
---Existing file content, if any---
"Mds": {
"Endpoint": "ec2messages-fips.region.amazonaws.com",
},
"Ssm": {
"Endpoint": "ssm-fips.region.amazonaws.com",
},
"Mgs": {
"Endpoint": "ssmmessages-fips.region.amazonaws.com",
"Region": "region"
},
"S3": {
"Endpoint": "s3-fips.dualstack.region.amazonaws.com",
"Region": region"
},
"Kms": {
"Endpoint": "kms-fips.region.amazonaws.com"
}
}
```
支持的区域包括以下：
+ 美国东部（弗吉尼亚州北部）区域为 `us-east-1`
+ 美国东部（俄亥俄州）区域为 `us-east-2`
+ 美国西部（北加利福尼亚）区域为 `us-west-1`
+ 美国西部（俄勒冈州）区域为 `us-west-2`
+ 加拿大西部（卡尔加里）区域为 `ca-west-1`
1. 保存文件并重新启动 SSM Agent。
每次更改配置时，请重新启动 SSM Agent。
您可以按照相同的过程自定义 SSM Agent 的其他功能。有关可用配置属性及其默认值的最新列表，请参阅 GitHub 的 `amazon-ssm-agent` 存储库中的[配置属性定义](https://github.com/aws/amazon-ssm-agent#config-property-definitions)。
有关 FIPS 的 AWS 支持的更多信息，请参阅[美国联邦信息处理标准（FIPS）140-3](https://aws.amazon.com/compliance/fips/)。
## 关于本地 ssm-user 账户
从 SSM Agent 2.3.50.0 版开始，该代理会创建一个名为 `ssm-user` 的本地用户账户，并将其添加至 `/etc/sudoers.d` 目录（Linux 和 macOS）或管理员组 (Windows Server)。在 2.3.612.0 之前的代理版本上，账户会在 SSM Agent 安装后首次启动或重启时创建。在版本 2.3.612.0 及更高版本上，`ssm-user` 账户将在会话在实例上首次启动时创建。当会话在Session Manager（AWS Systems Manager 中的一项工具）中启动会话时，该 `ssm-user` 是默认操作系统用户。您可以通过将 `ssm-user` 移动到权限较低的组或更改 `sudoers` 文件来更改权限。在卸载 SSM Agent 后，不会从系统中移除 `ssm-user` 账户。
在 Windows Server 上，SSM Agent 处理每个会话启动时对 `ssm-user` 账户的新密码的设置。Linux 托管实例上没有为 `ssm-user` 设置密码。
从 SSM Agent 2.3.612.0 版开始，不会在用作域控制器的 Windows Server 计算机上自动创建 `ssm-user` 账户。要在 Windows Server 域控制器上使用 Session Manager，手动创建 `ssm-user` 账户（如果尚不存在），然后向用户分配域管理员权限。
**重要**
为了能够创建 `ssm-user` 账户，附加到实例的实例配置文件必须提供必要的权限。有关信息，请参阅[步骤 2：验证或添加 Session Manager 的实例权限](session-manager-getting-started-instance-profile.md)。
## SSM Agent 和 Instance Metadata Service (IMDS)
Systems Manager 需要依靠 EC2 实例元数据才能正常运行。Systems Manager 可以使用 Instance Metadata Service 1 或 2 版（IMDSv1和IMDSv2）访问实例元数据。您的实例必须能够访问实例元数据服务的 IPv4 地址：169.254.169.254。有关更多信息，请参阅《Amazon EC2 用户指南**》中的[实例元数据和用户数据](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)。
## 保持 SSM Agent 的最新状态
如果有新工具添加至 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)页面。
**注意**
如果有新工具添加至 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 的 Amazon Machine Images (AMIs) 可能需要长达两周时间更新为最新版本的 SSM Agent。我们建议您将 SSM Agent 的自动更新配置为更高的频率。
## 确保 SSM Agent 安装目录未被修改、移动或删除
SSM Agent 安装在 `/var/lib/amazon/ssm/`（Linux 和 macOS）和 `%PROGRAMFILES%\Amazon\SSM\`（Windows Server）上。这些安装目录包含 SSM Agent 使用的关键文件和文件夹，例如凭证文件、进程间通信（IPC）资源和编排文件夹。不得修改、移动或删除安装目录中的任何内容。否则，SSM Agent 可能会停止正常运行。
## 按 AWS 区域 的 SSM Agent 滚动更新
SSM Agent 更新在 GitHub 存储库中可用后，可能需要长达两周时间，更新的版本才会在不同的时间推广到所有 AWS 区域。为此，当您尝试在区域中部署 SSM Agent 的新版本时，可能会收到以下错误：“在当前平台上不受支持”或“正在将 amazon-ssm-agent 更新为早期版本，请启用‘允许降级’以继续”。
要确定您的可用 SSM Agent 版本，可以运行 `curl` 命令。
要查看全局下载存储桶中的可用代理版本，请运行以下命令。
```
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/VERSION
```
要查看特定区域中的可用代理版本，请运行以下命令，将 *region* 替换为与您正在使用的区域，例如对于美国东部（俄亥俄州）区域使用 `us-east-2`。
```
curl https://s3.region.amazonaws.com/amazon-ssm-region/latest/VERSION
```
还可以直接在浏览器中打开 `VERSION` 文件，无需使用 `curl` 命令。
## SSM Agent 与 AWS 托管 S3 存储桶进行通信
在执行各种 Systems Manager 操作过程中，AWS Systems Manager Agent (SSM Agent) 将访问许多 Amazon Simple Storage Service (Amazon S3) 存储桶。这些 S3 存储桶可以公开访问，默认情况下，SSM Agent 使用 `HTTP` 调用连接到这些存储桶。
但是，如果您正在 Systems Manager 操作中使用虚拟私有云（VPC）端点，则必须在 Systems Manager 的 Amazon Elastic Compute Cloud（Amazon EC2）实例配置文件中提供显式权限，或者在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的非 EC2 计算机的服务角色中提供。否则，资源无法访问这些公有存储桶。
要在使用 VPC 端点时授予这些存储桶的托管式节点访问权限，您需要创建一个自定义 Amazon S3 权限策略，然后将其附加到您的实例配置文件（适用于 EC2 实例）或服务角色（适用于非 EC2 托管式节点）。
有关在 Systems Manager 操作中使用虚拟私有云（VPC）端点的信息，请参阅[使用适用于 Systems Manager 的 VPC 端点提高 EC2 实例的安全性](setup-create-vpc.md)。
**注意**
这些权限仅提供对 SSM Agent所需的 AWS 托管存储桶的访问。它们不提供其他 Amazon S3 操作所需的权限。它们也不提供您自己的 S3 存储桶的权限。
有关更多信息，请参阅以下主题：
+ [配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)
+ [在混合和多云环境中创建 Systems Manager 所需的 IAM 服务角色](hybrid-multicloud-service-role.md)
+ [参考：用于修补操作的 Amazon S3 存储桶](patch-operations-s3-buckets.md)
**Topics**
+ [所需的存储桶权限](#ssm-agent-minimum-s3-permissions-required)
+ [示例](#ssm-agent-minimum-s3-permissions-example)
+ [使用硬件指纹验证混合激活的计算机](#fingerprint-validation)
### 所需的存储桶权限
下表介绍了对于 Systems Manager 操作 SSM Agent 可能需要访问的每个 S3 存储桶。
**注意**
*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** 列。
SSM Agent 所需的 Amazon S3 权限
| S3 存储桶 ARN | 说明 |
| --- | --- |
| `arn:aws:s3:::aws-windows-downloads-region/*` | 需要一些仅支持 Windows Server 操作系统的 SSM 文档，还需要一些用于跨平台支持，例如 `AWSEC2-ConfigureSTIG`。 |
| `arn:aws:s3:::amazon-ssm-region/*` | 更新 SSM Agent安装所必需的。这些存储桶包含 SSM Agent安装软件包，以及 AWS-UpdateSSMAgent 文档和插件引用的安装清单。如果未提供这些权限，则 SSM Agent 会发出 HTTP 调用以下载更新。 |
| arn:aws:s3:::aws-ssm-region/\$1 | 提供对 S3 存储桶的访问权限，其中包含与 Systems Manager 文档（SSM 命令文档）一起使用所需的模块，包括非修补操作和修补操作。例如：arn:aws:s3:::aws-ssm-us-east-2/\$1。 下面是一些常用 SSM 文档，它们使用这些存储桶中的模块。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/ssm-agent-technical-details.html) |
| `arn:aws:s3:::patch-baseline-snapshot-region/*` –或者–`arn:aws:s3:::patch-baseline-snapshot-region-unique-suffix/*` | 提供对包含补丁基准快照的 S3 存储桶的访问权限。如果您使用下列 SSM 命令文档，则这是必需的： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/ssm-agent-technical-details.html) 最支持 AWS 区域 的存储桶使用以下格式： `arn:aws:s3:::patch-baseline-snapshot-region` 对于某些区域，存储桶名称中还会包含额外的唯一后缀。例如，中东（巴林）区域（me-south-1）的存储桶名称如下： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/ssm-agent-technical-details.html) 有关补丁基准快照存储桶名称的完整列表，请参阅 [包含 AWS 托管补丁基准快照的存储桶](patch-operations-s3-buckets.md#aws-patch-manager-buckets-baseline-snapshots)。 如果您使用本地防火墙并计划使用 Patch Manager，还必须允许该防火墙访问适当的补丁基准端点。 |
| 对于 Linux 和 Windows Server 托管式节点：`arn:aws:s3:::aws-patch-manager-region-unique-suffix/*` 对于 macOS 的 Amazon EC2 实例：`arn:aws:s3:::aws-patchmanager-macos-region-unique-suffix/*` | 提供对 S3 存储桶的访问权限，该存储桶包含 SSM 命令文档用于在 Patch Manager 中进行修补操作的模块。每个存储桶名称都包含唯一后缀，例如美国东部（俄亥俄州）（us-east-2）区域的存储桶后缀为 `552881074`： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/ssm-agent-technical-details.html) SSM 文档 下面是一些常用 SSM 文档，它们使用这些存储桶中的模块。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/ssm-agent-technical-details.html) 有关修补操作的 AWS 托管 S3 存储桶的完整列表，请参阅以下主题： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/ssm-agent-technical-details.html) |
### 示例
以下示例演示了如何提供对美国东部（俄亥俄州）区域 (us-east-2) 中 Systems Manager 操作所需的 S3 存储桶的访问权限。在大多数情况下，仅当使用 VPC 端点时，才需要在实例配置文件或服务角色中显式提供这些权限。
**重要**
我们建议您避免在该策略中使用通配符 (\$1) 以替代特定区域。例如，使用 `arn:aws:s3:::aws-ssm-us-east-2/*` 而不使用 `arn:aws:s3:::aws-ssm-*/*`。使用通配符可能会提供对您不打算授予访问权限的 S3 存储桶的访问。如果要将实例配置文件用于多个区域，我们建议每个区域重复使用第一个 `Statement` 块。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": [
"arn:aws:s3:::aws-windows-downloads-us-east-2/*",
"arn:aws:s3:::amazon-ssm-us-east-2/*",
"arn:aws:s3:::aws-ssm-us-east-2/*",
"arn:aws:s3:::patch-baseline-snapshot-us-east-2/*",
"arn:aws:s3:::aws-patch-manager-us-east-2-552881074/*",
"arn:aws:s3:::aws-patchmanager-macos-us-east-2-552881074/*"
]
}
]
}
```
------
### 使用硬件指纹验证混合激活的计算机
当非 EC2 计算机处于[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中时，SSM Agent 将收集许多系统属性（称为*硬件哈希*），并使用这些属性计算*指纹*。指纹是代理传递给某些 Systems Manager API 的不透明字符串。这种唯一的指纹将调用方与特定混合激活的托管节点关联起来。代理将指纹和硬件哈希存储在本地磁盘上名为*文件库*的位置。
当计算机注册为与 Systems Manager 一起使用时，代理会计算硬件哈希和指纹。然后，在代理发送 `RegisterManagedInstance` 命令时，将指纹传递回 Systems Manager 服务。
稍后，当发送 `RequestManagedInstanceRoleToken` 命令时，代理将检查文件库中的指纹和硬件哈希，以确保当前计算机属性与存储的硬件哈希匹配。如果当前计算机属性确实与文件库中存储的硬件哈希匹配，则代理将在指纹中从文件库传递到 `RegisterManagedInstance`，从而成功调用。
如果当前计算机属性与存储的硬件哈希不匹配，SSM Agent 将计算新的指纹，将新的硬件哈希和指纹存储在文件库中，然后将新指纹传递给 `RequestManagedInstanceRoleToken`。*这会导致 `RequestManagedInstanceRoleToken` 失败，并且代理将无法获取连接到 Systems Manager 服务的角色令牌。*
此失败是特意设计的，将用作验证步骤，以防多个托管式节点作为同一托管式节点与 Systems Manager 服务进行通信。
将当前计算机属性与在文件库中存储的硬件哈希进行比较时，代理使用以下逻辑来确定旧哈希和新哈希是否匹配：
+ 如果 SID（系统/计算机 ID）不同，则表示不匹配。
+ 否则，如果 IP 地址相同，则表示匹配。
+ 否则，将计算计算机属性的匹配百分比，并与用户配置的相似性阈值进行比较，以确定是否存在匹配。
相似性阈值作为硬件哈希的一部分存储在文件库中。
可以在注册实例后使用如下所示的命令设置相似性阈值。
在 Linux 计算机上：
```
sudo amazon-ssm-agent -fingerprint -similarityThreshold 1
```
在使用 PowerShell 的 Windows Server 计算机上：
```
cd "C:\Program Files\Amazon\SSM\" `
.\amazon-ssm-agent.exe -fingerprint -similarityThreshold 1
```
**重要**
如果用于计算指纹的组件之一发生了变化，则这可能会导致代理休眠。为了帮助避免出现这种休眠，请将相似性阈值设置为低值，例如 **1**。有关休眠的更多信息，请参阅 [了解 SSM Agent 休眠](#ssm-agent-hibernation)。
## GitHub 上的 SSM Agent
[https://github.com/aws/amazon-ssm-agent](https://github.com/aws/amazon-ssm-agent) 上提供 SSM Agent 的源代码，便于您根据需要调整代理。我们鼓励您针对要包含的更改提交[提取请求](https://github.com/aws/amazon-ssm-agent/blob/mainline/CONTRIBUTING.md)。但是，Amazon Web Services 不支持运行此软件的已修改副本。
## 了解 SSM Agent 休眠
AWS Systems Manager 代理（SSM Agent）休眠是一种运行模式，当代理无法与 Systems Manager 服务保持正常通信时发生。在休眠期间，代理会降低其通信频率并进入待机状态。
**发生 SSM Agent 休眠时**
以下情况下可能会出现 SSM Agent 休眠：
取消注册混合节点
当您从 Systems Manager 取消注册[混合激活节点](hybrid-activation-managed-nodes.md)时，该节点上的 SSM Agent 无法刷新其授权令牌。这会导致代理进入休眠模式，因为它无法通过服务进行身份验证。
硬件指纹变更
SSM Agent 使用硬件指纹验证混合激活的计算机。如果用于计算指纹的组件之一发生了显著变化，则代理可能会出于安全措施而休眠。这是特意设计的，为了防止多个托管节点作为同一节点与 Systems Manager 进行通信。有关更多信息，请参阅 [使用硬件指纹验证混合激活的计算机](#fingerprint-validation)。
Amazon EC2 实例上的 SSM Agent 休眠
在某些情况下，例如当 Systems Manager 服务出现连接问题或身份验证问题时，Amazon EC2 实例上也可能会发生休眠。
**休眠通信行为**
当 SSM Agent 进入休眠模式时，其与 Systems Manager 服务的通信模式会发生变化：
+ **正常运行**：代理定期与 Systems Manager 通信（通常每隔几分钟一次），以检查新命令并报告状态。
+ **休眠模式**：默认情况下，执行 ping 命令的频率从 5 分钟开始，逐渐增加到每小时一次（可配置为最长 24 小时）。这种降低的通信频率有助于最大限度地减少不必要的网络流量，同时使代理在条件发生变化时仍有可能恢复。
在休眠期间，代理会继续以较低的频率重试身份验证和连接尝试，但在休眠状态解除前，它无法处理新命令或报告详细的状态信息。
**防止混合实例休眠的配置选项**
帮助防止硬件指纹变更导致休眠的主要配置选项是调整相似度阈值：
在 Linux 计算机上：
```
sudo amazon-ssm-agent -fingerprint -similarityThreshold 1
```
在使用 PowerShell 的 Windows Server 计算机上：
```
cd "C:\Program Files\Amazon\SSM\" `
.\amazon-ssm-agent.exe -fingerprint -similarityThreshold 1
```
相似度阈值决定了代理将当前计算机属性与存储的硬件哈希值进行比较的严格程度：
+ 值越高，需要的匹配属性越多
+ 较低的值（例如 **1**）更宽松，可帮助避免因轻微硬件变更导致的休眠
**休眠日志记录和监控**
当 SSM Agent 进入休眠模式时，它会创建日志条目，帮助您识别休眠状态并进行故障排除：
+ **代理日志文件**：休眠事件记录在标准 SSM Agent 日志文件中。有关日志文件位置的更多信息，请参阅 [使用 SSM Agent 日志文件进行故障排除](troubleshooting-ssm-agent.md#systems-manager-ssm-agent-log-files)。
+ **Amazon EC2 控制台日志**：对于 EC2 实例，休眠消息现在记录到 Amazon EC2 控制台系统日志中，使代理状态更加清晰可见。要访问日志，请在 EC2 控制台中选择实例，然后选择**操作**、**监控和问题排查**、**获取系统日志**。
+ **特定的日志文件**：休眠开始时，会创建特定的日志文件，其中包含有关休眠触发条件和状态的详细信息。
监控这些日志源可尽早检测到休眠事件，并采取纠正措施恢复代理的正常运行。
**从休眠中恢复**
要从休眠中恢复，请解决根本原因：
+ **对于已取消注册的混合节点**：使用新的激活码和 ID 向 Systems Manager 重新注册该节点，如 [取消注册及重新注册托管式节点（Linux）](hybrid-multicloud-ssm-agent-install-linux.md#systems-manager-install-managed-linux-deregister-reregister)和 [取消注册及重新注册托管式节点（Windows Server）](hybrid-multicloud-ssm-agent-install-windows.md#systems-manager-install-managed-win-deregister-reregister)中所述。
+ **对于硬件指纹问题**：按照上文**防止混合实例休眠的配置选项**下所述调整相似度阈值；或者如果硬件变更较大，则重新注册节点。
+ **对于连接问题**：验证网络连接并确保所需的端点可访问。有关更多信息，请参阅 [使用 `ssm-cli` 排除托管节点可用性的故障](troubleshooting-managed-nodes-using-ssm-cli.md)。
解决根本问题后，代理应自动退出休眠模式，并在下次尝试通信时恢复正常运行。