rashmiranjanDevOps/incident-autopilot

# incident-autopilot 一个小型 AWS pipeline，用于监控几种特定的故障，自动修复可安全修复的问题，并将其他所有问题发送至 Slack 通知——同时保留其所做操作及原因的完整记录。 ## 这是什么项目？ 这是一个基于 AWS Lambda、SQS、SNS、DynamoDB 和 CloudWatch 构建的 serverless 系统。一个后台作业（即 "worker"）处理队列中的消息。当出现异常时——例如开始受到限流、消息持续处理失败，或遇到权限错误——CloudWatch 会监测到这些情况，并由另一个 Lambda 函数来决定后续操作：如果是安全且明确的情况，则自动修复；否则，将其留给人工处理。 ## 为什么开发这个项目？ 这是我的第二个作品集项目，紧随 [`employee-task-app`](https://github.com/rashmiranjandevops/employee-task-app)（一个 Kubernetes/GitOps 部署项目）之后。前一个项目主要涉及长期运行的容器和 ArgoCD——我希望通过第二个项目探索 AWS 完全不同的领域：serverless、事件驱动，并重点关注当系统出现故障时的实际应对方式，而不仅仅是最初如何部署。 ## 它解决什么问题？ 大多数作品集项目展示的是你具备部署系统的能力。但很少有项目能展示当系统在凌晨 2 点发生故障时的应对策略。这个项目正是我试图专门回答的问题：如何发现故障，如何判断是否能在无人干预的情况下安全修复，如果可以则实际进行修复，并且无论结果如何都留下完整记录，确保事后不需要任何人猜测发生了什么。 ## 架构 ``` flowchart TD subgraph Detection["Detection side"] Q[SQS work queue] --> W[Worker Lambda] W -->|3 failed attempts| DLQ[Dead-letter queue] W -->|Throttles metric| CW[CloudWatch Alarms] DLQ -->|queue depth| CW W -->|logs AccessDenied| MF[Log metric filter] --> CW end CW --> SNS[SNS topic] subgraph Response["Response side"] SNS --> T[Triage Lambda] T -->|safe| R[Remediate Lambda] T -->|not safe / unknown| SLACK1[Slack escalation] R -->|result| T T --> DDB[(DynamoDB audit log)] end subgraph Reporting["Reporting"] EB[EventBridge — weekly] --> D[Digest Lambda] DDB --> D D --> SLACK2[Slack weekly digest] end ``` 后台作业从 SQS 队列中提取消息。如果失败次数达到阈值，消息会被移至死信队列（dead-letter queue）。CloudWatch 会监控这一情况，以及限流和日志中的权限错误——其中任何一项都会触发 SNS 消息。Triage Lambda 接收到该消息后，会检查一个小型规则文件，判断其是否适合安全地自动修复。接着它会调用 Remediate Lambda（该函数仅能执行一种非常特定且可逆的操作），或者将消息发送到 Slack 供人工查看。无论是哪种情况，它都会将发生的情况记录到 DynamoDB 中。每周，一个独立的 Lambda 会读取该日志并发布摘要。 关于这些组件如何协同工作（以及我为何做出其中一些选择）的更多细节，请参阅 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。 ## 技术栈 - **AWS**：Lambda、SQS（+ DLQ）、SNS、DynamoDB、CloudWatch（告警、日志、metric filter）、EventBridge、Secrets Manager、IAM - **IaC**：Terraform，系统的每个部分对应一个 module - **CI/CD**：GitHub Actions，通过 OIDC 向 AWS 进行身份验证（任何地方都不存储长期有效的 AWS 密钥） - **语言**：所有四个 Lambda 函数均使用 Python 3.12 - **测试**：pytest，mock 了 `boto3` 调用——包含 25 个单元测试，运行它们不需要 AWS 账户 ## 功能 - 检测三种真实的故障类型：限流、持续失败的消息（死信队列）以及权限错误 - 自动修复唯一一种真正可安全修复的故障类型（在硬性上限范围内提高 worker 的并发限制） - 将其他所有故障升级至 Slack，而不是盲目猜测 - 将每项决策（发生了什么、采取了什么应对措施、发生时间）记录到 DynamoDB - 每周向 Slack 发布摘要，确保即使在没有任何紧急情况时，整个系统也保持可见 - 每个函数都拥有独立的 IAM 角色，且仅包含其实际所需的权限 - 每次推送到 `main` 分支时，在运行完整测试套件后，通过 GitHub Actions 自动部署 ## 项目结构 ``` terraform/ main.tf root config — OIDC role, wires up all the modules below modules/ core/ the SQS queue+DLQ, DynamoDB table, SNS topic, Secrets Manager secret lambda-worker/ the background job + its IAM role lambda-triage/ the decision-maker + its IAM role lambda-remediate/ the one whitelisted safe action + its IAM role lambda-digest/ the weekly summary + its IAM role alarms/ the 3 CloudWatch alarms + the log metric filter lambda/ worker/ source + tests triage/ source + tests + rules.json remediate/ source + tests digest/ source + tests scripts/ bootstrap-backend.sh one-time Terraform state setup chaos.sh triggers the throttling scenario simulate-dlq.sh triggers the DLQ scenario simulate-permission-failure.sh triggers the permission-error scenario cleanup.sh tears everything down safely check.sh confirms everything is actually deployed docs/ ARCHITECTURE.md how it fits together, and why DEPLOYMENT.md setup, cost, teardown, troubleshooting SECURITY.md IAM design and secrets handling TESTING.md what's covered and how to run it RUNBOOK.md what to do for each type of alert DIAGRAMS.md the architecture diagram above, on its own ``` ## 如何部署 简短版本： ``` ./scripts/bootstrap-backend.sh us-east-1 # 使用它打印出的 bucket 名称更新 terraform/backend.hcl cd terraform && terraform init -backend-config=backend.hcl && terraform apply # 然后设置 Slack webhook secret，并将 deploy role ARN 添加为 GitHub secret ``` 包含完整逐步说明（包括 Slack webhook 和 CI 设置）的详细文档请见 [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md)。 ## 截图 *（部署完成后会添加这些内容——以下是我计划截取的内容，因为这些截图能够真正证明 pipeline 运行正常，而不仅仅是口头描述。）* - [ ] **`terraform apply` 成功完成** —— 证明这是一个真实且有效的部署，而不仅仅是从未运行过的代码 - [ ] **GitHub Actions 运行显示通过** —— 测试通过且部署步骤成功，清晰地表明 CI/CD pipeline 确实能正常运行 - [ ] **自动修复场景的 Slack 消息** —— 触发限流告警并显示带有前后并发数值的“自动修复”消息。这是整个代码库中最具说服力的截图——它展示了 pipeline 确实捕获了异常并进行了修复，而不是仅仅描述它会做什么 - [ ] **升级处理的 Slack 消息**（DLQ 或权限失败场景） —— 展示了逻辑中“不要自动修复你不确定的问题”的一面，而不仅仅是理想情况下的处理 - [ ] **显示处于 ALARM 状态的 CloudWatch 控制台告警** —— 证明故障检测机制是真实有效的 - [ ] **审计表中的 DynamoDB item** —— 证明审计跟踪是一个真实且可查询的记录，而不仅仅是 README 中的声明 - [ ] **每周摘要的 Slack 消息** —— 展示报告循环能够端到端正常运行 ```      ``` ## 演示 部署完成后，您可以按需触发三个预设场景——每个场景都在 [`docs/RUNBOOK.md`](docs/RUNBOOK.md) 中有详细记录，包括具体会发生什么： ``` ./scripts/chaos.sh # throttling -> auto-remediated ./scripts/simulate-dlq.sh # a message that always fails -> escalated ./scripts/simulate-permission-failure.sh apply # a permissions error -> escalated ./scripts/simulate-permission-failure.sh revert # always run this after the one above ``` ## 未来改进 这些是我考虑过但暂时刻意搁置的内容，而不是我遗忘的功能： - **AI 辅助的告警摘要** —— 我确实考虑过使用 LLM 来辅助编写分诊决策，但最终决定放弃：相比于调用模型，小型规则文件更容易信任、审计和解释，而且这也能让本项目保持为 DevOps 项目，而不是 AI 项目。未来可能会重新考虑*仅仅*使用它来编写更易读的 Slack 摘要，作为一个明显独立且不参与决策的步骤。 - 第二种安全的修复操作（目前只有一种） - 分级升级（目前所有消息都会发送到一个 Slack 频道——真实的值班设置会根据严重程度进行路由） - 多区域部署——对于这样的演示项目来说并不是必需的，但值得说明我将如何实现它

标签：AWS, DPI, 故障自动化修复, 自动化运维, 自愈系统, 逆向工具