AWS 部署设计（Terraform 待交付）

BitzOrcas 当前仓库没有可直接投入生产、受版本支持的 AWS Terraform 模块。本页是部署设计约束，不是复制后即可上线的 IaC。团队可以据此实现自己的模块，但必须单独评审、测试和维护状态。

服务映射

Terraform 模块验收线

模块至少应包含私有子网、安全组、加密、Secret 注入、日志与指标、备份策略、远端 State 锁定，以及不同环境的参数边界。计划阶段必须先决定使用 SQL Server 还是 PostgreSQL、ECS 还是 EKS；文档不替团队做这个选择。

首次生产发布前完成故障转移、数据库恢复、Redis 密钥环恢复和消息积压演练。只有验证过的模块才能被标记为“受支持部署方式”。

先做不可逆选择

ECS 与 EKS 的差异不在“能否跑容器”，而在控制面、网络、升级、伸缩和运维所有权。没有 Kubernetes 运维能力时，不应仅为统一 YAML 选择 EKS。

SQL Server 与 PostgreSQL 选择会影响 Provider、迁移、排序/时区、备份、授权和 parity 证据。确认目标模块在所选数据库有生产适配器与测试后再创建 RDS。

Amazon MQ 需要验证 CAP、TLS、拓扑权限、重试和积压；ElastiCache 还可能承载协调与 Data Protection 状态，不能统一按“可清空缓存”设计。

模块边界建议

# ① 根模块组合稳定接口；子模块独立输出 ARN、endpoint 与安全组。
module "database" {
  source              = "./modules/database"
  environment         = var.environment
  subnet_ids          = module.network.private_subnet_ids
  deletion_protection = var.environment == "production"
}

module "api" {
  source         = "./modules/container-service"
  image_digest   = var.api_image_digest
  subnet_ids     = module.network.private_subnet_ids
  secret_arns    = module.secrets.api_secret_arns
  readiness_path = "/health/ready"
  liveness_path  = "/health/live"
}

示例表达输入/输出和不可变摘要，不是仓库现成模块。生产代码还需 provider/version 锁、加密 remote state、锁定、tag policy、日志保留和组织 guardrail。

网络与身份

• API/JobHost 放私有子网，只让入口进入 API；
• 数据库、MQ、Redis 仅允许 owner task 安全组；
• 使用 Task Role/IRSA 访问 S3、Secrets Manager、KMS 和遥测；
• 禁止长期 Access Key 进入 task definition、tfvars 或 CI 日志；
• 出站通过受控 NAT/VPC Endpoint，并登记第三方数据流；
• ALB 转发头、TLS 和 WebSocket 与 Forwarded Headers 配置一致。

Secret 与配置注入

# ② 只展示引用；部署平台从 Secrets Manager 解析真实值。
environment:
  # 非敏感环境标识进入普通环境变量。
  ASPNETCORE_ENVIRONMENT: Production
  OTEL_SERVICE_NAME: BitzOrcas.Api
  OTEL_DEPLOYMENT_ENVIRONMENT: production
secrets:
  # Secret 只保存 ARN 引用，任务启动时解析值。
  ConnectionStrings__Default: arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:bitzorcas/db-credentials
  RabbitMq__Password: arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:bitzorcas/rabbitmq-password
  Licensing__Runtime__TrustedPublicKeys__0: arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:bitzorcas/license-public-key

License DeploymentId/cache 与 Data Protection key ring 必须跨任务重启持久化并限制身份访问。放在临时文件系统会在滚动发布时改变实例身份、破坏 Cookie/Token 兼容。

发布与迁移

1. 受保护环境生成 Terraform plan 并附可读摘要。
2. 数据库先完成备份、VERIFYONLY 与 expand migration。
3. 候选 API/JobHost 不切流启动，验证 startup guard 与 readiness。
4. 按镜像 digest 灰度，观察错误预算、队列和数据库。
5. 达到停止条件回滚 task definition；schema 使用前向修复。
6. 观察期后才执行 contract migration 和旧资源清理。

状态、漂移与销毁保护

生产 state 加密、版本化、锁定并限制读取。CI 运行 fmt、validate、安全策略和 plan 审批；定期 refresh-only plan 发现控制台漂移。

RDS、S3、备份库、KMS key 与日志启用 deletion protection/retain。销毁需要独立审批，普通 PR 不自动执行。

可观测性与恢复

CloudWatch 资源指标不替代应用 OTel。API/JobHost 仍输出 service.name、version、environment、Trace 和业务 Meter，告警绑定 Runbook。

恢复演练从 RDS 备份恢复到隔离实例，挂载对象副本，重建 Redis/密钥环，控制 RabbitMQ 重放，并跑多租户、文件、工作流与审计 smoke。

交付清单

• ADR 说明 ECS/EKS、数据库与区域选择；
• 镜像使用 digest，provider/module 有版本锁；
• 网络、IAM、KMS、Secret 和出站最小权限；
• startup guard、live/ready 与终止通过真实 ALB；
• migration、backup、restore、rollback 和区域故障有演练；
• 成本、容量、保留与数据驻留有 owner；
• Terraform 有版本、升级说明、测试和支持矩阵；
• 证据完成前继续标记“待交付”。

另见

• 部署概览
• 生产安全清单