PraveenLuke/ecs-doctor

# ECS Doctor 🩺 [](https://github.com/PraveenLuke/ecs-doctor/actions/workflows/ci.yml) [](https://pypi.org/project/ecs-doctor/) [](https://pypi.org/project/ecs-doctor/) [](LICENSE) [](https://www.python.org/downloads/) **只需一条命令即可诊断您的 ECS 服务为何失败。** 排查 ECS 问题通常需要在 ECS 控制台、CloudWatch Logs、ALB target group 和 task definition 之间来回切换——在每次事件中手动关联各种信号。ECS Doctor 将所有这些信号整合在一起，在不到一秒钟的时间内，为您提供一份带有置信度评分和修复建议的单根因报告。 ``` pipx install ecs-doctor ecs-doctor diagnose --cluster prod --service payments ```  ## 检查内容 ECS Doctor 跨越关键的 AWS API 运行 **7 项并行诊断检查**： | 检查项 | AWS API | 捕获内容 | |-------|----------|-----------------| | **Service 事件** | `ecs:DescribeServices` | 为什么您的部署停滞、回滚或从未达到稳定状态 | | **停止原因** | `ecs:ListTasks`, `ecs:DescribeTasks` | 为什么您的 container 停止——OOM、镜像损坏、缺少 secrets、启动失败等 | | **CloudWatch Logs** | `logs:GetLogEvents` | 涵盖 Python、Java、Go、Node.js 及其他 5 种 runtime 的崩溃特征——无需您手动 grep | | **ALB 健康** | `elasticloadbalancing:DescribeTargetHealth` | 为什么您的 load balancer 在丢弃流量或没有 target 可供转发 | | **指标** | `cloudwatch:GetMetricData` | CPU 或内存压力是否是根本原因，并带有基于严重程度的加权阈值 | | **Task 配置** | `ecs:DescribeTaskDefinition` | task definition 或 service 中可能导致部署悄然失败的配置错误 | | **网络** | `ec2:Describe*` | 阻止您的 task 访问 AWS 服务或互联网的连接问题 | 所有发现都会经过评分，按置信度排序，并最终归纳为一个根本原因。 ## 安装 ``` # 推荐 — 隔离安装 pipx install ecs-doctor # 仅终端 pip install ecs-doctor # 带 web UI pip install "ecs-doctor[web]" # 带交互式方向键浏览器 pip install "ecs-doctor[interactive]" # 全部 pip install "ecs-doctor[web,interactive]" ``` ## 命令行使用 ``` # 诊断服务 ecs-doctor diagnose --cluster my-cluster --service my-service # 省略 --service 以从集群中交互式选择 ecs-doctor diagnose --cluster my-cluster # 使用指定的 AWS profile ecs-doctor diagnose --cluster my-cluster --service my-service --profile staging # 指定区域 ecs-doctor diagnose --cluster my-cluster --service my-service --region eu-west-1 # 机器可读 JSON（通过管道传递给 jq、Slack bots、incident tooling） ecs-doctor diagnose --cluster my-cluster --service my-service --json # 从运行中的 tasks 流式传输实时日志（按 Ctrl+C 停止） ecs-doctor diagnose --cluster my-cluster --service my-service --stream-logs # 跳过 CloudWatch metrics（速度更快，所需 IAM permissions 更少） ecs-doctor diagnose --cluster my-cluster --service my-service --no-metrics # 交互式向导 — 引导您完成 account → region → cluster → service ecs-doctor browse ``` ### 选项参考 ``` ecs-doctor diagnose [OPTIONS] --cluster TEXT ECS cluster name or ARN [required] --service TEXT ECS service name (omit to pick interactively) --region TEXT AWS region (overrides profile / env default) --profile TEXT AWS named profile from ~/.aws/credentials --json Machine-readable JSON output --stream-logs Stream live logs from running tasks --no-metrics Skip CloudWatch metrics --no-config Skip task definition config panel ``` ## Web UI ``` pip install "ecs-doctor[web]" ecs-doctor serve # opens at http://localhost:8080 ``` Web 界面在浏览器中提供相同的诊断功能——非常适合喜欢点击操作流程或希望在屏幕上分享结果的团队。 **核心功能：** - **Profile → Cluster → Service 下拉菜单** 会根据您的 `~/.aws/credentials` 自动填充——无需手动输入 - **选项卡式结果** —— Diagnosis、Metrics、Config、Live Logs 位于不同的选项卡中，让您无需在满屏输出中滚动浏览 - **Metrics 选项卡** —— CPU 和内存以颜色编码的进度条显示（根据阈值显示为绿色/琥珀色/红色） - **Live Logs 选项卡** —— 通过 Server-Sent Events 在浏览器中直接流式传输 CloudWatch log 事件；包含 Start / Stop 按钮和状态指示器 ## 身份验证 ECS Doctor 遵循标准的 **boto3 凭证链** —— 与 AWS CLI 使用的方式相同： | 方法 | 方式 | |--------|-----| | 环境变量 | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` | | 命名 profile | `--profile my-profile` 或 `AWS_PROFILE=my-profile` | | ECS task role | 在 Fargate / ECS 内运行时自动生效 | | EC2 实例角色 | 在 EC2 上运行时自动生效 | | Web Identity / OIDC | 通过 `AWS_WEB_IDENTITY_TOKEN_FILE` 自动生效（GitHub Actions, EKS） | 如果无法解析凭证，工具将退出并给出清晰提示，列出所有支持的验证方法。 ## IAM 权限 进行全面扫描所需的最低策略： ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecs:DescribeServices", "ecs:DescribeTasks", "ecs:DescribeTaskDefinition", "ecs:DescribeClusters", "ecs:ListTasks", "ecs:ListClusters", "ecs:ListServices" ], "Resource": "*" }, { "Effect": "Allow", "Action": ["logs:GetLogEvents", "logs:FilterLogEvents", "logs:DescribeLogStreams"], "Resource": "arn:aws:logs:*:*:log-group:/ecs/*:*" }, { "Effect": "Allow", "Action": ["cloudwatch:GetMetricData", "cloudwatch:GetMetricStatistics"], "Resource": "*" }, { "Effect": "Allow", "Action": ["elasticloadbalancing:DescribeTargetHealth"], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:DescribeSecurityGroups", "ec2:DescribeSubnets", "ec2:DescribeRouteTables", "ec2:DescribeNatGateways", "ec2:DescribeNetworkInterfaces", "ec2:DescribeVpcEndpoints", "ec2:DescribeNetworkAcls" ], "Resource": "*" }, { "Effect": "Allow", "Action": ["sts:GetCallerIdentity"], "Resource": "*" } ] } ``` ## JSON 输出 传递 `--json` 参数以获取机器可读的报告——非常适合 CI pipeline、Slack 机器人、PagerDuty runbook 或任何自定义的事件处理工具： ``` ecs-doctor diagnose --cluster prod --service payments --json | jq .root_cause ``` ``` { "cause": "Container is being OOM-killed (out of memory)", "confidence": 0.97, "suggested_fix": "Increase the container memory reservation in the task definition...", "evidence": [...] } ``` ## 许可证 MIT —— 详情请见 [LICENSE](LICENSE)。 *由 [@PraveenLuke](https://github.com/PraveenLuke) (Praveen Rajkoilraj) 构建。如果 ECS Doctor 在某次事件中为您节省了时间，请考虑给该仓库点个 ⭐。*

标签：AWS, Blue Team, DPI, ECS, Terraform, 故障诊断, 自动化运维, 运维工具, 逆向工具