# 问题排查
<a name="microvms-troubleshooting"></a>

本节介绍如何调试和排查在使用 AWS Lambda MicroVMs 时的常见问题。

## Shell 访问权限
<a name="microvms-troubleshooting-shell"></a>

使用 Shell 访问权限直接连接到正在运行的 MicroVM，以进行调试和问题排查。

您可以通过两种方式连接到 MicroVM Shell：
+ **控制台**：在 Lambda 控制台中选择您的 MicroVM，然后选择“连接”。
+ **CLI**：使用 `create-microvm-shell-auth-token` 生成 Shell 令牌，然后使用该令牌建立连接。

生成一个 Shell 令牌，然后连接：

```
aws lambda-microvms create-microvm-shell-auth-token \
  --microvm-identifier <id> --expiration-in-minutes 30
# In Console: select MicroVM -> Connect
# In shell: ctr task ls, then ctr task exec -t --exec-id shell <id> /bin/sh
```

MicroVM 必须使用 `SHELL_INGRESS` 网络连接器 (`arn:aws:lambda:{{us-east-1}}:aws:network-connector:aws-network-connector:SHELL_INGRESS`) 运行。如果 MicroVM 不是使用该连接器启动的，则 `create-microvm-shell-auth-token` 会返回 `ValidationException` 错误。

有关其他问题，请执行以下操作：
+ 检查 `get-microvm` 响应中的 `terminationMessage` 字段，确认是否存在已终止的 MicroVM。
+ 检查 CloudWatch 构建日志，确认映像创建问题。
+ 检查 `StateReason` 字段，确认是否有网络连接器处于 `FAILED` 状态。

## 问题排查
<a name="microvms-troubleshooting-troubleshooting"></a>

本节提供了在使用 Lambda MicroVMs 时的常见问题的解决方法。


| 症状 | 可能的原因和解决方法 | 
| --- | --- | 
| 映像构建失败 (CREATION\_FAILED) | 检查位于 /aws/lambda/microvms/<image-name> 的构建日志。验证 Dockerfile 语法、Amazon S3 权限和基础映像可用性。在本地运行 docker build 以进行复制。 | 
| MicroVM 卡滞在 PENDING 状态 | 请稍候，然后重试。如果问题持续存在，请检查服务运行状况。确认您的并发配额尚未用完。 | 
| 恢复后应用程序无响应 | 实施 /resume 生命周期挂钩以重建连接并验证状态。恢复后，请检查应用程序是否绑定到 8080 端口（或配置的端口）。 | 
| 来自端点的 502 Bad Gateway 错误 | 应用程序崩溃或未进行侦听。检查运行时日志。验证 Dockerfile 中的 EXPOSE 和 CMD。如果启用了自动恢复，则 MicroVM 可能恢复失败（通过 get-microvm 检查状态）。 | 
| 429 请求过多 | 超出请求速率。使用指数回退和抖动重试。 | 
| 连接掉线 | 触发空闲超时。实施 ping/pong Keepalive。或者延长空闲策略中的 maxIdleDurationSeconds。 | 
| 端点延迟高 | 带宽已饱和。检查流量是否超过 MicroVM 大小对应的带宽容量。纵向扩展到更大的大小。 | 
| 身份验证令牌已过期 (403) | 令牌具有可配置的过期时间。在旧令牌失效之前生成新令牌。在客户端中实施令牌刷新逻辑。 | 
| VPC 出口不起作用 | 验证网络连接器是否处于 ACTIVE 状态。检查安全组规则是否允许出站流量。确认子网具有通往目标资源的路由。 | 

## 常见错误（映像创建）
<a name="microvms-troubleshooting-image-errors"></a>


| 错误 | 原因 | 解决方案 | 
| --- | --- | --- | 
| S3\_ACCESS\_DENIED | 构建角色缺少检索 Amazon S3 构件的权限。 | 为您的构件存储桶添加 s3:GetObject 权限。 | 
| S3\_NO\_SUCH\_KEY | 存储桶中不存在构件密钥。 | 验证 Amazon S3 路径是否正确。 | 
| S3\_NO\_SUCH\_BUCKET | Amazon S3 存储桶不存在。 | 检查存储桶名称并确认其已经创建。 | 
| S3\_INVALID\_OBJECT | Glacier 或不可直接访问存储类别中的构件。 | 将构件移至“标准”存储类别。 | 
| S3\_CROSS\_REGION\_ACCESS\_DENIED | 构件与 MicroVM 映像不在同一区域。 | 确保您的构件与 MicroVM 映像位于同一区域。 | 
| ARCHIVE\_DOCKERFILE\_NOT\_FOUND | Zip 存档的根目录中缺少 Dockerfile。 | 将 Dockerfile 添加到 zip 存档的根目录。 | 
| ARCHIVE\_INVALID | 存档文件不是有效的 ZIP 文件或已损坏。 | 重建并重新上传 zip 存档。 | 
| CONTAINER\_BUILD\_FAILED | Dockerfile 指令无效、缺少文件或有语法错误。 | 使用 docker build 在本地调试 Dockerfile。 | 
| DISK\_STORAGE\_FULL | 构建期间 MicroVM 的存储空间不足。 | 降低构件大小或联系支持人员。 | 
| INTERNAL\_PLATFORM\_ERROR | 出现内部错误。 | 重试该操作。如果问题持续存在，请联系支持人员。 | 

## 网络连接器问题排查
<a name="microvms-troubleshooting-connector-errors"></a>


| 错误代码 | 原因 | 解决方案 | 
| --- | --- | --- | 
| DisallowedByVpcEncryptionControl | VPC 具有会阻止未加密网络接口或流量的加密控制策略。Lambda 无法创建满足加密要求的 ENI。 | 将 Lambda 添加到 VPC 加密控制排除列表中。如果无法排除，请使用未应用限制性加密控制的 VPC 或子网。 | 
| Ec2RequestLimitExceeded | Lambda 会调用 EC2 API（例如 CreateNetworkInterface、DescribeSubnets）来设置连接。并发 EC2 API 调用过多会导致节流。 | 请稍等片刻后重试操作。如果问题持续存在，请减少并发网络连接器操作或通过 AWS Support 申请提高 EC2 API 节流限额。 | 
| InsufficientRolePermissions | 操作者角色缺少所需的 EC2 权限。 | 确保该 IAM 角色具有必要的 EC2 联网权限。 | 
| InternalError | 处理网络连接器请求时，Lambda 服务出现意外错误。 | 重试该操作。如果多次重试后问题仍然存在，请联系 AWS Support，并提供网络连接器 ARN 和大致时间戳。 | 
| InvalidSecurityGroup | 安全组 ID 不存在、已被删除或与指定的子网不属于同一 VPC。 | 验证所有安全组 ID 是否存在，并且与子网属于同一 VPC。使用 aws ec2 describe-security-groups --group-ids <sg-id> 进行验证。 | 
| InvalidSubnet | 子网 ID 不存在、已被删除或所属的 VPC 不符合预期。 | 验证所有子网 ID 都存在且属于正确的 VPC。使用 aws ec2 describe-subnets --subnet-ids <subnet-id> 进行验证。 | 
| SubnetOutOfIPAddresses | 子网的 CIDR 数据块已用尽：所有 IP 都已分配给其他资源（ENI、实例等），因此 Lambda 无法创建网络接口。 | 通过移除未使用的 ENIS/实例来释放 IP 地址，或者使用其他具有可用容量的子网。考虑为网络连接器使用更大的子网（例如 /24 或更大）。 |