well-architected-iac-analyzer

一句话总结

Well-Architected IaC Analyzer 是 AWS 官方 sample 仓库里的一个生成式 AI 应用：把 CloudFormation / Terraform / CDK 模板、架构图、PDF 设计文档丢进去，它用 Amazon Bedrock 拉来 AWS Well-Architected 六支柱最佳实践做对照，输出一份可排序、可追问、带整改建议的架构体检报告。

故事：凌晨两点的那份 CloudFormation

做云平台运维的人大概都熟悉这种场景。业务上线前，你把一份 800 行的 CloudFormation 模板丢给同事 review，对方的回复是"看着还行"。然后流量一上来，ALB 没开访问日志、VPC 没开 Flow Logs、ECS 任务角色权限给了 *、RDS 没加密没开备份——每一个单看都不是致命错误，叠在一起就是一次事故预告。

AWS Well-Architected Framework Review（WAFR）本来是解决这个问题的标准流程：六大支柱（运营卓越、安全、可靠性、性能效率、成本优化、可持续性）逐条打分，产出一份几十页的评估报告。但它是靠人做的，一次完整评审通常需要架构师投入数天到数周，成本极高，只能挑重点系统做，不可能每个 IaC 变更都跑一遍。

这个项目想做的就是：把那套标准答案塞进 LLM，让机器去做初筛。

它到底在做什么

三层能力叠在一起：

第一层，IaC 与图纸的解析入口。 支持 CloudFormation（YAML/JSON）、Terraform（.tf）、AWS CDK（任意受支持语言）、PNG/JPEG 架构图、PDF 设计文档（最多 5 个，单个 4.5MB 以内），也支持多文件整体上传或 ZIP 打包的完整 IaC 项目。新版 Claude 模型的 Citations API 让 PDF 里的文字、图表甚至内嵌示意图都能被"读"进去。

第二层，Best Practices 的知识供给。 AWS Well-Architected 的白皮书被同步进 Amazon Bedrock Knowledge Base，作为 RAG 的知识底座。默认向量库换成了 Amazon S3 Vectors，官方称相比 OpenSearch Serverless 成本可降约 80%，同时保留 OpenSearch Serverless 选项。

第三层，评估与追问。 每个"未应用"的最佳实践都会被打上 Criticality（来自知识库风险等级）、Complexity（整改复杂度）两个维度，再通过艾森豪威尔矩阵推出 Immediate / Short-term / Long-term 三档优先级。

配套的 Priorities 标签页把这些点铺在一张可交互的四象限矩阵上——Quick wins、Major initiatives、Delegate、Reconsider。点任一点弹出详情面板，可以一键追问 Analyzer Assistant 聊天机器人。聊天历史支持 Markdown，可下载、可删除。分析结果和全部字段都能导出 CSV。

模型侧支持 Claude Sonnet 5.5（默认）、Opus 5.5、Fable 5.1、Sonnet 5、Opus 5 等，用 Adaptive Thinking 做复杂推理，原生 1M token 上下文，可以一次吃掉很大的 IaC 项目。分析并行度由 batch_size 控制（1–30，默认 5），官方称整体框架评审比逐题串行快最多 80%。输出语言支持英/日/韩/巴西葡/西/法六种，本地化目录 localization/ 里可以看到对应的 prompt 调整。

还有一个容易被忽略的能力：从架构图反向生成 IaC 模板，生成结果按 Well-Architected 最佳实践来写。

技术架构

后端是 NestJS 12 + TypeScript 5.9，Express 平台，Socket.IO 负责实时推送；前端是 React 19 + Vite 8 + AWS Cloudscape Design System；基础设施完全用 AWS CDK（Python）定义，入口是 app.py → ecs_fargate_app/wa_genai_stack.py（约 65KB 的栈定义）。整体跑在 ECS Fargate + ALB + Cognito 之上，Lambda 承担知识库同步、迁移和栈清理等旁路任务，DynamoDB 存会话，Amazon Bedrock（Agent Runtime + Knowledge Base）做推理，S3 存上传件。

ecs_fargate_app/ 下分成 backend/（NestJS）、frontend/（React）、lambda_kb_synchronizer/、lambda_migration/、lambda_stack_cleanup/、well_architected_docs/ 六个子模块。finch/ 目录里放了四份 Dockerfile（backend / frontend，各含 prod 与 dev 两版）加两份 nginx 配置，finch-compose.dev.yaml 提供本地 docker compose 编排；dev.sh 和 package.json 的 npm scripts 都支持 -c docker 与 -c finch 两种后端。

怎么部署

两条路：

1. CloudFormation 部署栈（官方推荐）：cfn_deployment_stacks/iac-analyzer-deployment-stack.yaml（约 51KB），在 AWS 控制台或 CLI 走 changeset 上线。
2. CDK 部署：pip install -r requirements.txt 后 cdk deploy，配合 config.ini 配置模型、向量库、认证方式。

本地开发走 npm run dev:up（docker）或 npm run dev:up:finch（Finch）。

config.ini 是配置中枢，值得细看几个开关：

• model_id — 默认 global.anthropic.claude-sonnet-5-5，走 global 跨区推理配置。若有数据驻留合规要求，应改成 us. / eu. 前缀的地理推理配置。Claude Fable 5.1 属于 Anthropic 的 "Covered Model"，使用前需在 Bedrock 里把数据保留模式设为 aws_review。
• vector_store_type — s3_vectors（默认）或 opensearch_serverless。
• authentication / auth_type — none / new-cognito / existing-cognito / oidc。强烈建议不要用 none：默认 ALB 是公网入口，关掉认证等于把整个应用和它的全部 AWS 凭据权限暴露在网上。
• public_load_balancer — 内部场景可置 False。
• certificate_arn / callback_urls / cognito_domain_prefix — 认证开启时必填。

值得说清楚的局限

它正在被官方"接管"。 README 顶部挂了一条 IMPORTANT 公告：2026 年 10 月 1 日 AWS 发布了 AWS Well-Architected Agent（公测），覆盖了这个项目的大部分能力，而且做得更多——持续分析真实 AWS 环境、跨支柱影响与权衡分析、直接给出可部署的整改代码（IaC、AWS CLI、控制台引导）。项目方的表态是：继续维护，但主要做安全补丁，鼓励用户去试官方 Agent。这对一个 sample 仓库来说是合理且坦诚的收尾，但使用者需要清楚：这个项目不再是 AWS 在 IaC 评审方向的主推方案。

它是 sample，不是产品。 app.py 里的 cdk-nag 抑制列表本身就是一份"最佳实践别开"的清单：VPC Flow Logs 关闭（省成本）、ALB 访问日志关闭、ALB 安全组对 0.0.0.0/0 开放（靠 Cognito 兜底）、Cognito 未启用 Advanced Security Mode、MFA 未强制、环境变量里放非敏感配置。每条都有 reason 说明是"为了让你低成本试玩"，生产环境必须逐条翻过来。

准确率取决于底座。 结论质量由两件事决定：Bedrock 知识库里同步的 Well-Architected 文档是否新鲜、当前选择的 Claude 模型表现。README 明确说项目主要针对 Anthropic 系列模型测试过，换其他模型可能出现预期外结果。LLM 生成的架构建议是"倾向性意见"，不能替代人工评审——尤其涉及安全合规的部分。

模型获取有门槛。 部分模型需要 Bedrock 访问权限、跨区推理配置，个别还需要 AWS 审核 opt-in。对没有 Bedrock 使用经验的人来说，"跑起来"这一步的隐性成本比文档写的高。

成本不可忽略。 Bedrock Token 消耗 + Fargate 常驻 + Cognito + S3，一条完整框架评审跑完是真实账单。batch_size 调大能提速，但也会推高限流风险和费用。

分析范围受输入限制。 只能看到你上传的东西。线上真实环境的资源标签、运行时配置、跨服务依赖都在 IaC 文本之外，"没上传等于不存在"是这个工具的结构性盲区。

行业意义

这个项目大概率不会成为 AWS 的旗舰产品，但它是"生成式 AI + 既有方法论资产"这条路线的一个标准样本。它的方法论很值得复用：先有一套成熟的、结构化的、可枚举的最佳实践清单，再让 LLM 去做逐项比对和自然语言解释——这比让 LLM 自由发挥"帮你优化架构"要可控得多，也更容易被工程团队接受。

另一层价值是艾森豪威尔矩阵这个交互设计。它把 AI 给出的几十条建议直接映射成"该先干哪个"——这是把 AI 输出接回真实工程决策流的正确姿势，绝大多数 AI 辅助工具缺的就是这一层。

从更长的视角看，基础设施即代码的评审正在从"人读 YAML"走向"机器读 YAML + 机器给意见 + 人做决策"。这个项目是这条链路上一块具体、可运行、已被 AWS 验证过的砖。

适合谁用

• 已经在用 AWS、有 CloudFormation/Terraform/CDK 代码库、想给 IaC 加一道自动化初审的团队
• 需要在方案评审前快速自查的架构师
• 想学"如何把结构化知识 + LLM 做成垂直工具"的人——这个仓库的 prompt 设计、知识库同步流程、并行批处理策略都值得拆开看

不适合谁用

• 没有 AWS 账号或 Bedrock 访问权限的环境（核心能力跑不起来）
• 已经在用 AWS Well-Architected Agent 的团队（重复建设）
• 期待它替代人工安全审计的团队（它是初筛工具，不是合规工具）

上手门槛小结

维度	评价
部署难度	中等偏高 — 依赖 AWS 账号 + Bedrock 模型权限 + Cognito 配置，但有 CFN/CDK 一键栈
本地开发	便捷 — npm run dev:up，Docker/Finch 双路径
Web UI	有 — React + Cloudscape，成熟度好
文档质量	优秀 — README 42KB + AGENTS.md 76KB + 专项子目录文档
生产可用性	低 — 官方明确定位 sample/non-production