┌──────────────────┐      ┌─────────────────┐      ┌───────────────┐       ┌─────────────────────────┐
│ AWS DevOps Agent │──────│ Private         │──────│ Internal ALB  │───┬──→│ aws-cn (Fargate/Pod)    │
│ (Agent Space)    │ VPC  │ Connection      │ 内网 │ (HTTPS:443)   │   │   └─────────────────────────┘
└──────────────────┘ Lat. │ (Resource GW)   │      │ host-based    │   │   ┌─────────────────────────┐
                          └─────────────────┘      │ routing       │   ├──→│ aws-cn-2 (Fargate/Pod)  │
                                                   └───────────────┘   │   └─────────────────────────┘
                                                          ↑            │   ┌─────────────────────────┐
                                            ACM *.example.cloud        └──→│ aliyun-prod (Fargate)   │
                                                                           └─────────────────────────┘

.
├── README.md                    ← 你在这
├── docs/                        ← 📚 文档（见 docs/README.md 索引）
│   ├── README.md                ← 文档索引
│   ├── deploy/                  ← 🔐 当前推荐部署文档
│   │   ├── DEPLOY-ROLES-ANYWHERE.md  ← IAM Roles Anywhere 部署指南
│   │   ├── DEPLOY-RA-RECORD.md       ← 真实部署日志（精确命令）
│   │   └── REBUILD.md                ← 从零重建 runbook
│   ├── legacy-eks/              ← ⚠️ 旧版 EKS 方案（推荐改用 ECS）
│   │   ├── SETUP.md                  ← EKS 方案完整配置指南
│   │   └── MULTI-ACCOUNT.md          ← EKS 多账号扩展运维（Helm + ESO）
│   └── blog/
│       └── BLOG.md                   ← 7 层故障面故事版踩坑博客
├── docker-compose.yml           ← 本地冒烟测试
├── cfn/                         ← 🔐 IAM Roles Anywhere CloudFormation
│   ├── roles-anywhere-hub.yaml  ← Hub 账号（Trust Anchor + Profile + Hub Role）
│   ├── roles-anywhere-spoke.yaml← Spoke 账号（ReadOnly Role）
│   └── generate-certs.sh        ← 一键生成 CA + client 证书
├── deploy/
│   ├── Dockerfile               ← AWS MCP 镜像（AK/SK 模式）
│   ├── Dockerfile.ra            ← AWS MCP 镜像（Roles Anywhere 模式）
│   ├── Dockerfile.aliyun        ← 阿里云 MCP 镜像
│   ├── credential-helper.sh     ← cert → Hub 凭证 → AssumeRole → Spoke 凭证
│   └── entrypoint-ra.sh         ← RA 容器启动器（证书写盘 + 注册 credential_process）
├── terraform-ecs/               ← ⭐ ECS Fargate 方案（推荐）
│   ├── main.tf                  ← Provider
│   ├── variables.tf             ← accounts map（auth_mode: ak_sk | roles_anywhere）
│   ├── network.tf               ← IGW + NAT Gateway + 路由表
│   ├── alb.tf                   ← Internal ALB + HTTPS listener
│   ├── ecs.tf                   ← ECS Cluster + for_each Services
│   ├── iam.tf                   ← Execution Role + Task Role
│   ├── secrets.tf               ← 按 auth_mode 条件创建 secret
│   ├── outputs.tf               ← ALB DNS name + DNS 操作提示
│   └── terraform.tfvars.example ← 配置模板（含两种认证模式示例）
├── terraform/                   ← EKS 方案基础设施
│   └── main.tf                  ← VPC + EKS + IRSA
├── chart/                       ← EKS 方案 Helm chart（AWS）
├── chart-aliyun/                ← EKS 方案 Helm chart（阿里云）
└── scripts/
    └── smoke.sh                 ← 本地 docker-compose 冒烟测试

cp .env.example .env
vim .env                        # 填 AWS/aliyun 凭证

docker compose up -d
bash scripts/smoke.sh           # 对本地端口发 MCP initialize 握手

cd terraform-ecs
cp terraform.tfvars.example terraform.tfvars

# 1. TLS 证书（ACM 公共证书，需提前申请好）
certificate_arn = "arn:aws:acm:us-east-1:ACCOUNT:certificate/CERT_ID"

# 2. 目标账号凭证 + 域名
accounts = {
  aws-cn = {
    host       = "aws-cn.example.com"     # 你的域名
    aws_region = "cn-northwest-1"
    access_key = "AKIA..."                # 目标账号 AK
    secret_key = "..."                    # 目标账号 SK
  }
}

# 3. VPC（可选 — 留空自动创建，已有则填 ID）
# vpc_id             = "vpc-xxx"
# public_subnet_ids  = ["subnet-aaa", "subnet-bbb"]
# private_subnet_ids = ["subnet-ccc", "subnet-ddd"]

terraform init && terraform apply    # ~3 分钟，创建全部基础设施

# terraform output 会打印完整命令，以下是示例
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <ACCOUNT>.dkr.ecr.us-east-1.amazonaws.com
docker build --platform linux/amd64 -t <ECR_URL>:latest -f deploy/Dockerfile .
docker push <ECR_URL>:latest

# 让 ECS 拉取镜像
aws ecs update-service --cluster mcp --service mcp-aws-cn --force-new-deployment

cd terraform && terraform apply
helm install aws-load-balancer-controller ...
helm install aws-cn ./chart -f values-aws-cn.yaml -n mcp

env:
  - { name: AWS_DEFAULT_REGION,    value: "cn-north-1" }
  - { name: AWS_ACCESS_KEY_ID,     valueFrom: { secretKeyRef: { name: mcp-creds, key: AWS_CN_AK } } }
  - { name: AWS_SECRET_ACCESS_KEY, valueFrom: { secretKeyRef: { name: mcp-creds, key: AWS_CN_SK } } }

容器启动 → 写证书到文件 → 注册 credential_process（AWS_CONFIG_FILE）
SDK 按需调用 credential-helper.sh：
  aws_signing_helper → Hub 临时凭证 → sts:AssumeRole → Spoke 临时凭证
botocore 读 Expiration，临近过期自动重新调用 helper（惰性刷新，无后台线程）

RUN pip install --no-cache-dir awslabs.aws-api-mcp-server==1.3.33

# ECS 方案
aws ecs update-service --cluster mcp --service mcp-aws-cn --force-new-deployment

# EKS 方案
kubectl -n mcp rollout restart deploy/mcp-aws-cn