先决条件常见故障排除场景 Amazon ECS 托管实例中的日志分析使用 EC2 Amazon CLI 从 Amazon ECS 托管实例获取控制台输出清理其他资源

排查 Amazon ECS 托管实例问题

请使用以下过程对 Amazon ECS 托管实例进行问题排查，包括常见问题、诊断技术和解决步骤。

先决条件

在排查 Amazon ECS 托管实例的问题之前，请确保您已满足以下要求。

已安装 Amazon CLI 并配置适当的权限

有关更多信息，请参阅《Amazon Command Line Interface 用户指南》中的安装或更新到最新版本的 Amazon Command Line Interface。
访问具有 Amazon ECS 托管实例容量提供程序的集群。有关更多信息，请参阅为 Amazon ECS 托管实例创建集群。

常见故障排除场景

查看 Amazon ECS 托管实例容器代理日志

您可以通过连接到实例中运行的特权容器，在 Amazon ECS 托管实例中查看这些 Amazon ECS 日志文件。

诊断步骤

将具有权限和 Linux 功能的调试容器部署为 Amazon ECS 任务：

设置以下环境变量。

将 user-input 替换为您的值。


export ECS_CLUSTER_NAME="your-cluster-name"
export AWS_REGION="your-region"
export ACCOUNT_ID="your-account-id"

使用名为 node-debugger.json 的 CLI JSON 文件创建任务定义。


cat << EOF > node-debugger.json
{
  "family": "node-debugger",
  "taskRoleArn": "arn:aws:iam::${ACCOUNT_ID}:role/ecsTaskExecutionRole",
  "executionRoleArn": "arn:aws:iam::${ACCOUNT_ID}:role/ecsTaskExecutionRole",
  "cpu": "256",
  "memory": "1024",
  "networkMode": "host",
  "pidMode": "host",
  "requiresCompatibilities": ["MANAGED_INSTANCES", "EC2"],
  "containerDefinitions": [
    {
      "name": "node-debugger",
      "image": "public.ecr.aws/amazonlinux/amazonlinux:2023",
      "essential": true,
      "privileged": true,
      "command": ["sleep", "infinity"],
      "healthCheck": {
          "command": ["CMD-SHELL", "echo debugger || exit 1"],
          "interval": 30,
          "retries": 3,
          "timeout": 5
      },
      "linuxParameters": {
        "initProcessEnabled": true
      },
      "mountPoints": [
        {
          "sourceVolume": "host-root",
          "containerPath": "/host",
          "readOnly": false
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/aws/ecs/node-debugger",
          "awslogs-create-group": "true",
          "awslogs-region": "${AWS_REGION}",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ],
  "volumes": [
    {
      "name": "host-root",
      "host": {
        "sourcePath": "/"
      }
    }
  ]
}
EOF


aws ecs register-task-definition --cli-input-json file://node-debugger.json

TASK_ARN=$(aws ecs run-task \
  --cluster $ECS_CLUSTER_NAME \
  --task-definition node-debugger \
  --enable-execute-command \
  --capacity-provider-strategy capacityProvider=managed-instances-default,weight=1 \
  --query 'tasks[0].taskArn' --output text)

# Wait for task to be running
aws ecs wait tasks-running --cluster $ECS_CLUSTER_NAME --tasks $TASK_ARN

连接到容器。运行如下命令。


aws ecs execute-command \
  --cluster $ECS_CLUSTER_NAME \
  --task $TASK_ARN \
  --container node-debugger \
  --interactive \
  --command "/bin/sh"

查看 Amazon ECS 代理日志：

在容器的交互式会话中，运行以下命令：


# Install required tools
yum install -y util-linux-core

# View ECS agent logs
nsenter -t 1 -m -p cat /var/log/ecs/ecs-agent.log | tail -50

# Check agent registration
nsenter -t 1 -m -p grep "Registered container instance" /var/log/ecs/ecs-agent.log

Example Output:

{"level":"info","time":"2025-10-16T12:39:37.665","msg":"Registered container instance with cluster!"}

# Verify capabilities
nsenter -t 1 -m -p grep "Response contained expected value for attribute" /var/log/ecs/ecs-agent.log

查看代理指标：

运行以下命令以查看日志。


# View metrics logs
nsenter -t 1 -m -p cat /var/log/ecs/metrics.log | tail -20

任务放置问题

下面是任务放置问题的症状：

任务停滞在 PENDING 状态
在 Amazon ECS 托管实例上启动任务失败
资源不足错误

诊断步骤

请运行以下命令来诊断任务放置问题并收集有关集群容量、容器实例和系统服务的信息：


# Check cluster capacity
aws ecs describe-clusters --clusters cluster-name --include STATISTICS

# Check cluster capacity providers
aws ecs describe-clusters --clusters cluster-name --include STATISTICS --query 'clusters[].capacityProviders'

# List container instances
aws ecs list-container-instances --cluster cluster-name

# Check container instance details
aws ecs describe-container-instances --cluster cluster-name --container-instances container-instance-arn

# Check container instance remaining resources CPU/Mem
aws ecs describe-container-instances --cluster $ECS_CLUSTER_NAME --container-instances container-instance-arn --query 'containerInstances[].remainingResources'

# Check container instance Security Group
aws ecs describe-container-instances --cluster $ECS_CLUSTER_NAME --container-instances container-instance-arn --query 'containerInstances[].ec2InstanceId' --output text
aws ec2 describe-instances --instance-ids instance-id --query 'Reservations[0].Instances[0].SecurityGroups'
aws ec2 describe-security-groups --group-ids security-group-id

系统服务监控：


# Check Containerd status
nsenter -t 1 -m -p systemctl status containerd.service

# Check Amazon ECS container agent status
nsenter -t 1 -m -p systemctl status ecs

解决方案

要解决任务放置问题，请按照下面的步骤确保配置和容量正确：

验证任务资源要求和可用容量
查看放置约束和策略
确保已配置 Amazon ECS 托管实例容量提供程序
确保任务和容器实例安全组具有允许 Amazon ECS 代理管理端点流量的出站规则。

联网问题

下面是网络问题的症状：

任务无法访问外部服务
DNS 解析问题

诊断步骤

网络连接测试：

在调试容器中，运行以下命令：

注意

确认附加到您的容量提供程序或 Amazon ECS 任务的安全组允许流量。


# Install DNS Utility
yum install bind-utils -y

# Test DNS resolution
nslookup amazon.com

# Test external connectivity
curl -I https://amazon.com

资源约束

下面是网络问题的症状：

由于内存限制，任务被终止
CPU 节流
磁盘空间问题

诊断步骤

请运行命令来监控资源和容器限制。

资源监控：


# Check memory usage
nsenter -t 1 -m -p free -h

# Check disk usage
nsenter -t 1 -m -p lsblk

# Check disk usage
nsenter -t 1 -m -p df -h

容器限制：


# Check OOM kills
nsenter -t 1 -m -p dmesg | grep -i "killed process"

容器实例代理断开连接问题

下面是容器实例代理断开连接问题的症状：

容器实例在 Amazon ECS 控制台中显示为已断开连接
任务未能放置到特定实例上
日志中的代理注册失败

诊断步骤

如果主机上已有 ECS Exec 可以访问的特权任务正在运行，请运行下面的命令来诊断代理连接问题：


# check service status 
nsenter -t 1 -m -p systemctl restart ecs 
nsenter -t 1 -m -p systemctl restart containerd 

# restart stopped services 
nsenter -t 1 -m -p systemctl restart ecs 
nsenter -t 1 -m -p systemctl restart containerd

否则，请强制注销 Amazon ECS 托管实例。运行如下命令：


# list ECS Managed Instance container
aws ecs list-container-instances --cluster managed-instances-cluster --query 'containerInstanceArns' --output text

# deregister the specific container instance
aws ecs deregister-container-instance \
    --cluster $ECS_CLUSTER_NAME \
    --container-instance container-instance-arn \
    --force

解决方案

要解决代理断开连接问题，请按照下面的步骤进行操作：

验证容器实例的 IAM 角色权限
检查安全组规则是否允许出站 HTTPS 流量流向 ECS 端点。
确保可通过网络与 Amazon 服务连接
如有必要，请重启 ECS 代理服务：nsenter -t 1 -m -p systemctl restart ecs
验证 /etc/ecs/ecs.config 中的 ECS_CLUSTER 配置是否与您的集群名称匹配。

Amazon ECS 托管实例中的日志分析

系统日志

请使用下面的命令来检查系统日志并识别托管实例的潜在问题：


# Check system messages
nsenter -t 1 -m -p journalctl --no-pager -n 50

# Check kernel logs
nsenter -t 1 -m -p dmesg | tail -20

# Check for disk space errors
nsenter -t 1 -m -p journalctl --no-pager | grep -i "no space\|disk full\|enospc"

使用 EC2 Amazon CLI 从 Amazon ECS 托管实例获取控制台输出

使用 Amazon EC2 实例 ID 来检索控制台输出。

将 user-input 替换为您的值。


aws ec2 get-console-output --instance-id instance-id --latest --output text

清理

请运行下面的命令来停止调试任务并注销任务定义。


# Stop debug task
aws ecs stop-task --cluster $ECS_CLUSTER_NAME --task $TASK_ARN

# Deregister task definition (optional)
aws ecs deregister-task-definition --task-definition node-debugger

其他资源

有关 Amazon ECS 托管实例故障排除的更多信息，请参阅以下资源：

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

Amazon Fargate 节流配额

排查 Amazon ECS 托管实例问题