• AWS Systems Manager CloudWatch 控制面板在 2026 年 4 月 30 日之后将不再可用。客户可以像现在一样继续使用 Amazon CloudWatch 控制台来查看、创建和管理其 Amazon CloudWatch 控制面板。有关更多信息，请参阅 [Amazon CloudWatch 控制面板文档](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。
# 排除 Session Manager 问题
可以使用以下信息来帮助解决 AWS Systems Manager Session Manager 问题。
**Topics**
+ [调用 TerminateSession 操作时的 AccessDeniedException](#session-manager-troubleshooting-access-denied-exception)
+ [文档处理意外失败：文档工作线程超时](#session-manager-troubleshooting-document-worker-timed-out)
+ [Session Manager 无法从 Amazon EC2 控制台连接](#session-manager-troubleshooting-EC2-console)
+ [没有启动会话的权限](#session-manager-troubleshooting-start-permissions)
+ [SSM Agent 不在线](#session-manager-troubleshooting-agent-not-online)
+ [没有更改会话首选项的权限](#session-manager-troubleshooting-preferences-permissions)
+ [托管式节点不可用或未为 Session Manager 配置托管式节点](#session-manager-troubleshooting-instances)
+ [未找到 Session Manager 插件](#plugin-not-found)
+ [Session Manager 插件未自动添加到命令行路径（Windows）](#windows-plugin-env-var-not-set)
+ [Session Manager 插件变得没有响应](#plugin-unresponsive)
+ [TargetNotConnected](#ssh-target-not-connected)
+ [启动会话后显示空白屏幕](#session-manager-troubleshooting-start-blank-screen)
+ [托管式节点在长时间运行会话期间变得没有响应](#session-manager-troubleshooting-log-retention)
+ [调用 StartSession 操作时出现错误（InvalidDocument）](#session-manager-troubleshooting-invalid-document)
## 调用 TerminateSession 操作时的 AccessDeniedException
**问题**：尝试终止会话时，Systems Manager 会返回以下错误：
```
An error occurred (AccessDeniedException) when calling the TerminateSession operation:
User: is not authorized to perform: ssm:TerminateSession on resource:
because no identity-based policy allows the ssm:TerminateSession action.
```
**解决方案 A：确认节点上已安装[最新版本的 Session Manager 插件](https://docs.aws.amazon.com/systems-manager/latest/userguide/plugin-version-history.html)**
在终端中输入以下命令，然后按 Enter。
```
session-manager-plugin --version
```
**解决方案 B：安装或重新安装最新版本的插件**
有关更多信息，请参阅 [为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
**解决方案 C：尝试重新建立与节点的连接**
验证节点是否在响应请求。尝试重新建立会话。或者，在必要时，打开 Amazon EC2 控制台并验证实例的状态是否正在运行。
## 文档处理意外失败：文档工作线程超时
**问题**：启动与 Linux 主机的会话时，Systems Manager 返回以下错误：
```
document process failed unexpectedly: document worker timed out,
check [ssm-document-worker]/[ssm-session-worker] log for crash reason
```
如果您配置了SSM Agent 日志记录（如 [查看 SSM Agent 日志](ssm-agent-logs.md) 中所述），则可以在调试日志中查看更多详细信息。对于此问题，Session Manager 显示以下日志条目：
```
failed to create channel: too many open files
```
此错误通常表示运行的 Session Manager 工作线程进程过多，底层操作系统达到了极限。您有两个选项来解决此问题。
**解决方案 A：提高操作系统文件通知限制**
您可以在单独的 Linux 主机上运行以下命令来提高限制。该命令使用 Systems Manager Run Command。指定值会将 `max_user_instances` 增加到 8192。此值远高于默认值 128，但它不会占用主机资源：
```
aws ssm send-command --document-name AWS-RunShellScript \
--instance-id {{i-02573cafcfEXAMPLE}} --parameters \
"commands=sudo sysctl fs.inotify.max_user_instances=8192"
```
**解决方案 B：减少 Session Manager 在目标主机中使用的文件通知**
在单独的 Linux 主机上运行以下命令，以列出目标主机上运行的会话：
```
aws ssm describe-sessions --state Active --filters key=Target,value={{i-02573cafcfEXAMPLE}}
```
查看命令输出，以确定不再需要的会话。您可以在单独的 Linux 主机上运行以下命令来终止这些会话：
```
aws ssm terminate-session —session-id {{session ID}}
```
或者，一旦远程服务器上不再运行会话，您可以通过在单独的 Linux 主机上运行以下命令来释放更多资源。此命令将终止远程主机上运行的所有 Session Manager 进程，从而终止与远程主机的所有会话。在运行此命令之前，请确认没有要保留的正在进行的会话：
```
aws ssm send-command --document-name AWS-RunShellScript \
--instance-id {{i-02573cafcfEXAMPLE}} --parameters \
'{"commands":["sudo kill $(ps aux | grep ssm-session-worker | grep -v grep | awk '"'"'{print $2}'"'"')"]}'
```
## Session Manager 无法从 Amazon EC2 控制台连接
**问题**：创建新实例后，Amazon Elastic Compute Cloud（Amazon EC2）控制台中的**链接**按钮 > **会话管理器**选项卡不提供连接选项。
**解决方案 A：创建实例配置文件**：如果您尚未执行此操作（按照 EC2 控制台中**会话管理器**选项卡上的信息的说明），使用Quick Setup创建 AWS Identity and Access Management（IAM）实例配置文件。Quick Setup是 AWS Systems Manager 中的一项工具。
Session Manager 需要 IAM 实例配置文件才能连接到实例。您可以使用 Quick Setup 创建[主机管理配置](https://docs.aws.amazon.com/systems-manager/latest/userguide/quick-setup-host-management.html)，以创建实例配置文件并将其分配给实例。*主机管理配置*创建具有所需权限的实例配置文件并将其分配给实例。主机管理配置还可以启用其他 Systems Manager 工具，并创建用于运行这些工具的 IAM 角色。使用Quick Setup或主机管理配置启用的工具不会产生任何费用。[打开 Quick Setup 并创建主机管理配置](https://console.aws.amazon.com/systems-manager/quick-setup/create-configuration&configurationType=SSMHostMgmt)。
**重要**
创建主机管理配置后，Amazon EC2 可能需要几分钟来注册更改并刷新 **会话管理器**选项卡。如果选项卡在两分钟后没有显示**连接**按钮，请重新启动实例。如果重新启动后仍然看不到连接选项，请打开[快速设置功能](https://console.aws.amazon.com/systems-manager/quick-setup/create-configuration&configurationType=SSMHostMgmt)，确认只有一个主机管理配置。如果有两个主机管理配置，请删除较旧的配置并等待几分钟。
如果在创建主机管理配置后仍然无法连接，或者收到错误（包括关于 SSM Agent 的错误），请参阅以下解决方案之一：
+ [解决方案 B：没有错误，但仍然无法连接](#session-manager-troubleshooting-EC2-console-no-error)
+ [解决方案 C：关于缺失 SSM Agent 的错误](#session-manager-troubleshooting-EC2-console-no-agent)
### 解决方案 B：没有错误，但仍然无法连接
如果您创建了主机管理配置，等待了几分钟才尝试连接，但仍然无法连接，则可能需要手动将主机管理配置应用于实例。使用以下过程更新 Quick Setup 主机管理配置并将更改应用于实例。
**使用 Quick Setup 更新主机管理配置**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Quick Setup**。
1. 在**配置**列表中，选择您创建的**主机管理配置**。
1. 选择**操作**，然后选择**编辑配置**。
1. 在**目标**部分的底部附近，于**选择您希望如何定位目标**下选择**手动**。
1. 在**实例**部分中，选择您创建的实例。
1. 选择**更新**。
等待几分钟，让 EC2 刷新**会话管理器**选项卡。如果仍然无法连接或收到错误，请查看该问题的其余解决方案。
### 解决方案 C：关于缺失 SSM Agent 的错误
如果您无法使用 Quick Setup 创建主机管理配置，或者收到有关未安装 SSM Agent 的错误，则可能需要在实例上手动安装 SSM Agent。SSM Agent 是 Amazon 软件，它允许 Systems Manager 通过使用 Session Manager 连接到实例。SSM Agent 默认安装在大多数亚马逊机器映像（AMI）上。如果您的实例是从非标准 AMI 或较旧的 AMI 创建的，则可能需要手动安装代理。有关安装 SSM Agent 的过程，请参阅以下与您的实例操作系统相对应的主题。
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/manually-install-ssm-agent-windows.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/manually-install-ssm-agent-windows.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/manually-install-ssm-agent-macos.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/manually-install-ssm-agent-macos.html)
+ [AlmaLinux](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-alma.html)
+ [Amazon Linux 2 和 AL2023](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-al2.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-deb.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-deb.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-oracle.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-oracle.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-rhel.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-rhel.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-rocky.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-rocky.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-ubuntu.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-ubuntu.html)
有关 SSM Agent 的问题，请参阅 [排除 SSM Agent 问题](troubleshooting-ssm-agent.md)。
## 没有启动会话的权限
**问题**：您尝试启动会话，但系统提示您没有必要的权限。
+ **解决方案**：系统管理员尚未授予您启动 Session Manager 会话的 AWS Identity and Access Management (IAM) 策略权限。有关更多信息，请参阅[控制用户会话对实例的访问权限](session-manager-getting-started-restrict-access.md)。
## SSM Agent 不在线
**问题**：您在 Amazon EC2 实例 **Session Manager** 选项卡上看到一条消息，表明：“SSM Agent 不在线。SSM Agent 不能够连接到 Systems Manager 端点以将其自身注册到服务中。”
**解决方案**：SSM Agent 是在 Amazon EC2 实例上运行的 Amazon 软件，从而 Session Manager 可以与其建立连接。如果您看到此错误，则 SSM Agent 不能够建立与 Systems Manager 端点的连接。问题的可能原因可能是防火墙限制、路由问题或互联网连接不足。要解决此问题，请调查网络连接问题。有关更多信息，请参阅[排除 SSM Agent 问题](troubleshooting-ssm-agent.md)和[排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md)。有关 Systems Manager 端点的信息，请参阅《AWS 一般参考》中的 [AWS Systems Manager 端点和配额](https://docs.aws.amazon.com/general/latest/gr/ssm.html)。
## 没有更改会话首选项的权限
**问题**：您尝试更新组织的全局会话首选项，但系统提示您没有必要的权限。
+ **解决方案**：系统管理员尚未授予您设置 Session Manager 首选项的 IAM policy 权限。有关信息，请参阅[授予或拒绝更新 Session Manager 首选项的用户权限](preference-setting-permissions.md)。
## 托管式节点不可用或未为 Session Manager 配置托管式节点
**问题 1**：您要在 **Start a session**（启动会话）控制台页面上启动一个会话，但托管式节点不在列表中。
+ **解决方案 A**：可能尚未为 AWS Systems Manager 配置您要连接的托管式节点。有关更多信息，请参阅 [为组织设置 Systems Manager 统一控制台](systems-manager-setting-up-organizations.md)。
**注意**
如果在附加 IAM 实例配置文件时 AWS Systems Manager SSM Agent 已在托管式节点上运行，则在 **Start a session **（启动会话）控制台页面上列出该实例之前，可能需要重新启动代理。
+ **解决方案 B**：您应用于托管式节点上 SSM Agent 的代理配置可能不正确。如果代理配置不正确，托管式节点将无法到达所需的服务终端节点，或节点可能会向 Systems Manager 报告为不同的操作系统。有关更多信息，请参阅[配置 SSM Agent 以在 Linux 节点上使用代理](configure-proxy-ssm-agent.md)和[配置 SSM Agent以使用 Windows Server 实例的代理](configure-proxy-ssm-agent-windows.md)。
**问题 2**：**Start a session**（开启会话）控制台页面上的列表中显示了要连接的托管式节点，但页面报告“The instance you selected isn't configured to use Session Manager”（您选择的实例未配置为使用 ）。
+ **解决方案 A**：托管式节点已配置为可以使用 Systems Manager 服务，但附加到节点的 IAM 实例配置文件不包含Session Manager工具所需的权限。有关更多信息，请参阅[验证或创建具有 Session Manager 权限的 IAM 实例配置文件](session-manager-getting-started-instance-profile.md)。
+ **解决方案 B**：托管式节点未运行支持 Session Manager 的 SSM Agent 版本。将节点上的 SSM Agent 更新为版本 2.3.68.0 或更高版本。
根据操作系统类型，按照 [在适用于 Windows Server 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-windows.md)、[在适用于 Linux 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-linux.md) 或 [在适用于 macOS 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-macos.md) 中的步骤操作，手动更新托管式节点上的 SSM Agent。
或者，使用 Run Command 文档 `AWS-UpdateSSMAgent` 一次性更新一个或多个托管式节点上的代理版本。有关信息，请参阅[使用 Run Command 更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample)。
**提示**
为了让代理始终保持最新状态，建议使用以下方法之一按照定义的自动计划将 SSM Agent更新为最新版本：
作为 State Manager 关联的一部分运行 `AWS-UpdateSSMAgent`。有关信息，请参阅[演练：使用 AWS CLI 自动更新 SSM Agent](state-manager-update-ssm-agent-cli.md)。
运行 `AWS-UpdateSSMAgent` 作为维护时段的一部分。有关使用维护时段的信息，请参阅 [使用控制台创建和管理维护时段](sysman-maintenance-working.md) 和 [教程：使用 AWS CLI 创建和配置维护时段](maintenance-windows-cli-tutorials-create.md)。
+ **解决方案 C**：托管式节点无法到达必要的服务终端节点。您可以使用由 AWS PrivateLink 提供支持的接口端点连接到 Systems Manager 端点，以提高托管式节点的安保状况。使用接口端点的替代方法是，在托管式节点上允许出站互联网访问。有关更多信息，请参阅[使用 PrivateLink 为 Session Manager 设置 VPC 端点](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started-privatelink.html)。
+ **解决方案 D**：托管式节点的可用 CPU 或内存资源有限。尽管您的托管式节点可能正常运行，但是如果该节点没有足够的可用资源，则您无法建立会话。有关更多信息，请参阅[对无法访问的实例进行故障排除](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-console.html)。
## 未找到 Session Manager 插件
要使用 AWS CLI 运行会话命令，还必须在本地计算机上安装 Session Manager 插件。有关信息，请参阅[为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
## Session Manager 插件未自动添加到命令行路径（Windows）
在 Windows 上安装 Session Manager 插件时，`session-manager-plugin` 可执行文件应自动添加到操作系统的 `PATH` 环境变量中。如果在运行检查是否正确安装了 Session Manager 插件的命令后命令失败 (`aws ssm start-session --target {{instance-id}}`)，则需要使用以下过程进行手动设置。
**修改您的 PATH 变量 (Windows)**
1. 按 Windows 键并输入 **environment variables**。
1. 选择 **Edit environment variables for your account**（编辑您账户的环境变量）。
1. 选择 **PATH**，然后选择 **Edit**。
1. 向 **Variable value (变量值)** 字段添加路径，用分号分隔，如下例所示：{{`C:\existing\path`}};{{`C:\new\path`}}
{{`C:\existing\path`}} 表示字段中已存在的值。{{`C:\new\path`}} 表示要添加的路径，如以下示例所示。
+ **64 位计算机**：`C:\Program Files\Amazon\SessionManagerPlugin\bin\`
1. 选择 **OK**（确定）两次以应用新设置。
1. 关闭任何运行的命令提示符并重新打开。
## Session Manager 插件变得没有响应
如果您的本地计算机上安装了防病毒软件，在端口转发会话期间，可能会停止转发流量。在某些情况下，防病毒软件会干扰 Session Manager 插件，从而导致进程死锁。要解决此问题，请在防病毒软件中设置允许 Session Manager 插件或将其排除在外。有关 Session Manager 插件的默认安装路径的信息，请参阅 [为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
## TargetNotConnected
**问题**：您尝试启动会话，但系统返回错误消息：“An error occurred (TargetNotConnected) when calling the StartSession operation: {{InstanceID}} isn't connected.”（调用 StartSession 操作时发生错误 (TargetNotConnected)：InstanceID 未连接。）
+ **解决方案 A**：如果会话的指定目标托管式节点未完全配置为与 Session Manager 一起使用，则会返回此错误。有关信息，请参阅[设置 Session Manager](session-manager-getting-started.md)。
+ **解决方案 B**：如果您尝试在位于不同 AWS 账户 或 AWS 区域 的托管式节点上启动会话，也会返回此错误。
## 启动会话后显示空白屏幕
**问题**：在您启动会话后，Session Manager 显示空白屏幕。
+ **解决方案 A**：如果托管式节点上的根卷已满，则可能出现此问题。由于磁盘空间不足，节点上的 SSM Agent 停止工作。要解决此问题，请使用 Amazon CloudWatch 从操作系统中收集指标和日志。有关更多信息，请参阅 *Amazon CloudWatch 用户指南*中的[使用 CloudWatch 代理收集指标、日志和跟踪信息](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。
+ **解决方案 B**：如果您使用包含不匹配端点和区域对的链接访问控制台，则会显示空白屏幕。例如，在以下控制台 URL 中，`us-west-2` 是指定的端点，但 `us-west-1` 是指定的 AWS 区域。
```
https://us-west-2.console.aws.amazon.com/systems-manager/session-manager/sessions?region=us-west-1
```
+ **解决方案 C**：托管式节点正在使用 VPC 终端节点连接到 Systems Manager，并且您的 Session Manager 首选项将会话输出写入 Amazon S3 存储桶或 Amazon CloudWatch Logs 日志组，但 VPC 中不存在 `s3` 网关端点或 `logs` 接口端点。如果您的托管式节点使用 VPC 终端节点连接到 Systems Manager，并且您的 Session Manager 首选项将会话输出写入 Amazon S3 存储桶，则需要格式为 **`com.amazonaws.{{region}}.s3`** 的 `s3` 端点。或者，如果您的托管式节点使用 VPC 终端节点连接到 Systems Manager，并且您的 Session Manager 首选项将会话输出写入 CloudWatch Logs 日志组，则需要格式为 **`com.amazonaws.{{region}}.logs`** 的 `logs` 端点。有关更多信息，请参阅 [为 Systems Manager 创建 VPC 端点](setup-create-vpc.md#create-vpc-endpoints)。
+ **解决方案 D**：您在会话首选项中指定的日志组或 Amazon S3 存储桶已删除。要解决此问题，请使用有效的日志组或 S3 存储桶更新会话首选项。
+ **解决方案 E**：您在会话首选项中指定的日志组或 Amazon S3 存储桶未加密，但您已将 `cloudWatchEncryptionEnabled` 或 `s3EncryptionEnabled` 输入设置为 `true`。要解决此问题，请使用加密的日志组或 Amazon S3 存储桶更新会话首选项，或将 `cloudWatchEncryptionEnabled` 或 `s3EncryptionEnabled` 输入设置为 `false`。此方案仅适用于使用命令行工具创建会话首选项的客户。
## 托管式节点在长时间运行会话期间变得没有响应
**问题**：在长时间运行会话期间，托管式节点变得没有响应或崩溃。
**解决方案**：减少 Session Manager 的 SSM Agent 日志保留时间。
**要减少会话的 SSM Agent 日志保留时间，请执行以下步骤：**
1. 在 Linux 的 `/etc/amazon/ssm/` 目录或 Windows 的 `C:\Program Files\Amazon\SSM` 中找到 `amazon-ssm-agent.json.template`。
1. 将 `amazon-ssm-agent.json.template` 的内容复制到同一目录中名为 `amazon-ssm-agent.json` 的新文件中。
1. 减小 `SSM` 属性中 `SessionLogsRetentionDurationHours` 值的默认值，然后保存该文件。
1. 重启 SSM Agent。
## 调用 StartSession 操作时出现错误（InvalidDocument）
**问题**：使用 AWS CLI 启动会话时，您会收到以下错误。
```
An error occurred (InvalidDocument) when calling the StartSession operation: Document type: 'Command' is not supported. Only type: 'Session' is supported for Session Manager.
```
**解决方案**：您为 `--document-name` 参数指定的 SSM 文档不是*会话*文档。请按照以下过程在 AWS 管理控制台 中查看会话文档列表。
**查看会话文档列表**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择**文档**。
1. 在**类别**列表中，选择**会话文档**。