Macro 基础设施即代码实践:Pulumi、共享网关与 ECS 服务部署指南
Macro 基础设施即代码实践:Pulumi、共享网关与 ECS 服务部署指南
Macro 的 AWS 基础设施全部以 TypeScript 编写的 Pulumi 工程维护在 infra/ 目录下,通过 Bun 执行,生产主区域为 us-east-1。本文以仓库官方基础设施指南为主线,逐层拆解目录职责、ECS 服务组件的组装方式、共享网关路由的优先级机制、Doppler 密钥链路、部署流水线的触发条件与已知陷阱,帮助读者在不触发线上变更的前提下读懂并安全演进这套基础设施。
文中所有结论均对应仓库中的实际文件;涉及"为什么这样设计"的部分会明确标注为源码推断。阅读前请先记住一条仓库级硬性约束。
Agent 永不部署。 除非用户在当前对话中明确要求,否则不要执行
pulumi up、pulumi destroy、wrangler deploy、wrangler secret put或触发部署 workflow。准备改动、"把线接好"、做引导初始化都不算授权。pulumi preview是允许的。
一、整体形态:Pulumi 主导 AWS,Wrangler 单独负责 Cloudflare Workers
这套体系有两条互不混合的交付路径:
- AWS 侧:Pulumi(TypeScript)+ Bun,代码位于 infra,主体区域
us-east-1。可观测性试点栈 infra/stacks/observability 例外地运行在us-east-2。 - Cloudflare 侧:Workers 用
wrangler部署,不经过 Pulumi。例如 services/sync-service 的 worker 与 services/cla-worker。
区域信息在代码中也是显式读取的:infra/packages/shared/src/index.ts 开头从 aws.config.region 取出 awsRegion,为空就直接抛错,避免出现"忘了配区域却静默部署到默认区域"的事故。
要新增一个完整服务,请配合阅读 新增服务指南;它把"一个新服务需要在十几个地方登记"的清单列全,本文聚焦其中的基础设施部分。
二、目录结构:stacks 组装,packages 复用
| 路径 | 内容 |
|---|---|
infra/stacks/<name>/ |
每个目录一个 Pulumi project,包含 Pulumi.yaml 与 Pulumi.dev.yaml / Pulumi.prod.yaml |
infra/packages/shared |
常量、配置单例、类型化 stack reference、网关优先级、Doppler、服务 URL |
infra/packages/resources |
可复用组件:ALB、target group、队列、RDS、Redis、DynamoDB、Kafka、bucket、Datadog sidecar、告警 |
infra/packages/service |
EcrImage、最小权限 DynamoDB、集群 stack reference |
infra/packages/lambda |
Lambda 组件与 WorkerTrigger |
infra/packages/vpc |
所有服务共用的唯一 VPC 的 ID(get_coparse_api_vpc()) |
真实文件与上表一一对应,例如 infra/packages/shared/src/gateway_priorities.ts、infra/packages/resources/src/resources/service_target_group.ts、infra/packages/service/src/ecr.ts、infra/packages/lambda/src/lambda.ts、infra/packages/vpc/src/index.ts。
infra/package.json 把 stacks/* 与 packages/* 声明为 Bun workspaces,依赖固定包括 @pulumi/pulumi、@pulumi/aws、@pulumi/awsx、@pulumi/datadog、@pulumiverse/doppler 等;preinstall 脚本会在非 Bun 包管理器下直接失败,这是刻意为之的约束。
Stack 命名与稳定的"项目名"
Stack 分为 macro-inc/dev 与 macro-inc/prod。少数栈只在单一环境存在:monitoring、doppler-projects 是 prod-only,github-runners、web-app-preview 是 dev-only。
项目名通常等于目录名,而且这个字符串在三处被当作主键使用:Doppler 项目名、.github/services-config.json 里的 key、以及 nix 中的 serviceName。三者必须完全一致(crate 包名则用 snake_case)。docs/guides/new-service.md 专门点名 calendar-service 的 DOPPLER_PROJECT: 'calendar_service' 是个反面示例——下划线混入 kebab-case 体系后,配置链路很容易对不上。
Stack reference:dev 永远只读 dev
栈之间通过 macro-inc/<project>/${stack} 读取输出,因此 dev 永远不会读到 prod 的值。仓库要求使用 packages/shared 里的类型化 helper,而不是裸 StackReference:
getGatewayAlb()—— 共享网关 ALB 与 HTTPS listener。document-storage输出共享 ECS 集群(cloudStorageClusterArn),由 infra/packages/service/src/cluster.ts 包装成cloudStorageClusterName/cloudStorageClusterArn。getKafkaClusterPolicy()、getMacroNotify()、getSearchEventQueue()、getAiToolsInfra()等用于其他共享资源。
getGatewayAlb() 的实现(infra/packages/shared/src/gateway.ts)做了两件事值得注意:第一,它用模块级变量 _GATEWAY_ALB 缓存,保证一个 Pulumi 程序内只创建一次 StackReference;第二,它用 requireOutput 而不是 getOutput,即 gateway 栈未部署时会在部署期明确失败,而不是拿到 undefined 后在运行时炸掉。
StackReference 的第一个参数是逻辑名,必须在程序内唯一;当 helper 与调用方引用同一个栈时,要给逻辑名加前缀。另外,引用关系隐含了部署顺序——新增一个引用可能制造 bootstrap 循环(A 需要 B 的输出,B 又需要 A 的)。
三、当前 ECS 服务模式:一个组件拼七块
官方推荐直接复制 infra/stacks/calendar-service/ 或 infra/stacks/lexical-service/。仓库里没有通用 service 组件,每个栈自己写一个小的 ComponentResource 把下列部件组合起来(calendar-service 的实现在 infra/stacks/calendar-service/service.ts):
- Task role:只授予服务真正需要的权限——特定 secret ARN 上的
GetSecretValue、特定队列上的 SQS 动作、以及getKafkaClusterPolicy()。 - Image:
EcrImage(docker/Dockerfile,构建参数SERVICE_NAME)。CI 会替换成"拷贝 nix 产出的二进制"的 prebuilt Dockerfile;新增 Dockerfile 必须加进 infra/packages/service/src/ecr.ts 的映射表,否则在USE_PREBUILT_SERVICE_BINARIES=true时会抛错。 - Gateway 路由:
ServiceTargetGroup({ service: GatewayService.X, pathPatterns: [...] }),挂在getGatewayAlb()上。 - Secrets:
DopplerEcsEnvironment(pulumi.getProject()),产出一个 execution role 加上唯一一个容器 secretAPP_SECRETS_JSON。 - Service:
awsx.ecs.FargateService,走私有子网,启用带回滚的部署熔断,continueBeforeSteadyState: DEFAULT_CONTINUE_BEFORE_STEADY_STATE,容器包括log_router(fargateLogRouterSidecarContainer)、datadog_agent(datadogAgentContainer)和服务本身;dependsOntarget group 的 listener rule——因为 ECS 拒绝尚未挂到 listener 上的 target group。 - Autoscaling:按 ALB 每 target 请求数、CPU、内存三条目标追踪策略。
- 告警:
EcsDeploymentFailureAlarm加上 CPU、内存、target 5xx,全部路由到CLOUD_TRAIL_SNS_TOPIC_ARN。
健康检查、注销延迟与稳态行为来自 infra/packages/resources/src/resources/ecs_deployment_defaults.ts,其默认值相当保守:
export const DEFAULT_CONTINUE_BEFORE_STEADY_STATE = true;
export const DEFAULT_TARGET_GROUP_HEALTH_CHECK = {
interval: 10,
healthyThreshold: 2,
unhealthyThreshold: 2,
timeout: 5,
matcher: '200-399',
} satisfies Partial<aws.types.input.lb.TargetGroupHealthCheck>;
export const DEFAULT_DEREGISTRATION_DELAY_SECONDS = 15;
即每 10 秒探一次、连续 2 次成功即健康、5 秒超时、接受 200–399、注销延迟 15 秒。容器统一监听 8080 并提供 GET /health。
六大部件的关键实现细节
Task role 与最小权限。calendar-service 把 secretsmanager:GetSecretValue + DescribeSecret 限定在 secretKeyArns 列表上,SQS 权限拆成两条语句:对自身 backfill 队列给 SendMessage/ReceiveMessage/DeleteMessage,对 email-service 的 link-manager 队列只给 SendMessage。这种"同一个 role 内按队列细分动作"的写法,就是本文档"只授予需要的策略"的落地方式。
镜像与 ECR 生命周期。EcrImage 在 infra/packages/service/src/ecr.ts 中禁用了默认生命周期策略,改为自定义规则:保留最近 20 个 untagged 镜像。注释解释了原因——镜像是按数量而不是按时间保留的,因为一旦 latest 移动,上一版任务定义钉住的镜像就变成 untagged,而 ECS 回滚和任务替换仍然需要拉取它。
网络与安全组。服务的安全组只加一条"允许所有出站"(ipProtocol: '-1',0.0.0.0/0),入站由 ServiceTargetGroup 自动补:它成对创建"ALB SG → 服务 SG 的入站"和"服务 SG 出口到 ALB SG"两条规则,端口精确等于容器端口。这解释了为什么服务栈只需关心出站。
Fargate 资源规格与遥测。calendar-service 的容器规格随环境变化(prod cpu: 512 / memory: 1024,dev 256 / 512),stopTimeout: 10;日志通过 awsfirelens 驱动直接推 Datadog。withTelemetry()(infra/packages/resources/src/resources/telemetry.ts)负责把 log_router、datadog_agent 以及可选的 Grafana 副本一起注入,因此业务容器不必重复写日志配置。
自动扩缩。三个策略的目标值分别是:ALB 每 target 1000 请求(scaleIn 60s / scaleOut 120s)、平均 CPU 70%、平均内存 70%(后两者 scaleIn 100s / scaleOut 300s);容量上限 prod 3、dev 2,下限均为 1。注意请求数策略的 resourceLabel 由 <albArnSuffix>/<targetGroupArnSuffix> 拼接而成,这正是 GatewayAlb 类型里要导出 albArnSuffix 的原因。
告警阈值。CPU/内存使用率 80%、周期 180 秒、1 个评估周期即触发;target 5xx 使用 Sum 统计、阈值 25、GreaterThanOrEqualToThreshold。EcsDeploymentFailureAlarm 则基于 EventBridge 规则匹配 aws.ecs 的 SERVICE_DEPLOYMENT_FAILED 事件,再转成 CloudWatch 告警。
无端口的 worker 怎么写
SQS 或 Kafka 消费者没有监听端口,照抄 HTTP 服务会多出无用的 target group。参考 infra/stacks/cloud-storage-service/slack-import-worker.ts:不要 target group,只用出站安全组,显式指定 CPU 与内存,并使用更长的 stopTimeout。
该文件里几个可复用的做法:worker 用 config.getBoolean('deploy_slack_import_worker') 做开关,未开启时 deploySlackImportWorker() 返回 undefined;assignPublicIp: false;容器内存 1536、task 级 cpu: '1024'、memory 在开启 Grafana 遥测时提升到 3072(否则 2048),stopTimeout: 120 给足优雅退出时间;dependsOn 策略附件与出站规则,避免任务先起来却没有权限。
四、网关路由:一个 ALB、一张优先级表
gateway.macro.com(dev 为 dev-gateway.macro.com)是由 gateway 栈独占的一个 ALB,服务通过路径规则挂到它的 HTTPS listener 上。网关栈本身很短(infra/stacks/gateway/index.ts),只负责创建 ALB 并导出 albArn、httpsListenerArn、albSecurityGroupId、albDnsName、albZoneId、albArnSuffix 六个输出——它们正是 GatewayAlb 类型定义的字段。
三条硬规则:
- 优先级只写在
GATEWAY_PRIORITIES(infra/packages/shared/src/gateway_priorities.ts)。新增服务要加一个GatewayService枚举成员和一个唯一优先级;重复值在模块加载时直接抛错。 - ALB 先匹配数字最小的规则。一个数字更小、范围更宽的路径会遮蔽你的规则:文档记录的真实事故是 calendar 的
/calendar曾被 email-service 吞掉,直到优先级被修正(现为CALENDAR_SERVICE = 140,EMAIL_SERVICE = 110)。 - ALB 原样转发路径,所以 Rust 路由必须也在
/<prefix>下挂载。calendar 的GATEWAY_PATH_PREFIX = "/calendar"与mount_at_root_and_prefix见 services/calendar_service/src/api.rs。
此外 ALB 与 target group 名称上限 32 字符(含 -tg 后缀),命名时要把这一位算进去。
优先级表本身也能读出路由设计意图。当前分配如下:
| 服务 | 优先级 | 服务 | 优先级 |
|---|---|---|---|
AGENT_COGNITION_PUBLIC_HOST |
5 | CONNECTION_GATEWAY |
90 |
AGENT_MCP_PUBLIC_HOST |
6 | AUTHENTICATION_SERVICE |
100 |
DOCUMENT_STORAGE_SERVICE |
10 | EMAIL_SERVICE |
110 |
UNFURL_SERVICE |
20 | DOCUMENT_COGNITION_SERVICE |
120 |
NOTIFICATION_SERVICE |
30 | MCP_SERVER |
130 |
CONTACTS_SERVICE |
40 | CALENDAR_SERVICE |
140 |
SEARCH_PROCESSING_SERVICE |
50 | PREVIEW_GATEWAY |
150 |
IMAGE_PROXY_SERVICE |
60 | LEXICAL_SERVICE |
160 |
AGENT_HARNESS_SERVICE |
70 | CONVERT_SERVICE |
3000 |
AGENT_HARNESS_EGRESS |
75 | ||
AGENT_SCHEDULE_SERVICE |
80 |
源码注释点明了为什么两个 *_PUBLIC_HOST 必须排在最前:按主机名路由要先于路径规则匹配,因为 cognition 自身就有 /mcp 路径。ServiceTargetGroup 也支持 hostHeaders——用于"在一个共享 listener 上独占整个主机名"的 target group,且 pathPatterns 与 hostHeaders 必须二选一,service 与 priority 也必须二选一,二者都在构造函数里显式校验。
五、密钥与配置:Doppler 是唯一源头
值如何进入代码,由 配置文件与服务 URL 规则 约定;就基础设施而言,规则可以压缩成四句话。
Doppler 是源头。 infra/stacks/doppler-projects 为每个服务创建一个 project,含 lcl、dev、prd 三个环境,并同步到 Secrets Manager 的 /doppler-sync/<project>/<dev|prod>。见 infra/stacks/doppler-projects/doppler_project.ts:dev 环境 personalConfigs: false、prd 同理,各自绑定一个 doppler.secretssync.AwsSecretsManager。新增服务要把名字加进 infra/stacks/doppler-projects/index.ts 的 SERVICE_NAMES,且必须使用 Pulumi 项目名。
ECS 里的 MacroConfig 只读 APP_SECRETS_JSON。 一个普通的容器 environment: 条目对它完全不可见。因此基础设施产出的值(ARN、endpoint)必须通过 Pulumi 的 doppler.Secret 写进 Doppler,参考 infra/stacks/agent-harness-service/index.ts 中的 configurationSecrets;这种栈需要把 doppler:dopplerToken 作为 secure: 配置。普通 environment: 只用于 ENVIRONMENT、DD_*,以及通过 macro_env_var 或 OVERRIDE_* 读取的值。
链路的具体形态由 DopplerEcsEnvironment 决定(infra/packages/shared/src/doppler_environment.ts):它以 /doppler-sync/${name}/${stack}/doppler 为 secret id 取 ARN,给 execution role 加上 secretsmanager:GetSecretValue(开启 Grafana 遥测时额外加上 ingest secret),最后只产出一条容器 secret:
this.containerSecrets = [
{
name: 'APP_SECRETS_JSON',
valueFrom: pulumi.interpolate`${dopplerSecretSyncArn}`,
},
];
注意路径里的 name 是 pulumi.getProject(),而环境段是 stack——dev 栈取 /doppler-sync/<project>/dev/doppler,与 doppler-projects 栈写入的 /doppler-sync/<project>/dev 对得上。
密钥放 Doppler,不新增 Secrets Manager secret。 手工创建 Secrets Manager secret、把名字写进 Pulumi config、再用 aws.secretsmanager.getSecretVersionOutput(...) 解析,是旧模式;老栈仍在用(例如 calendar 的 secretKeyArns 就是这种写法),但不要复制。只有少数必须留在 Pulumi 自身的值才用 secure: 配置。
绝不把 secretString 解析成明文环境变量。 这一条是红线:一旦明文进入任务定义的 environment,它会出现在控制台、describe-task-definition 输出和任何能读 ECS 的地方。
六、嵌入式构建产物:nix 源码过滤器
部署构建不使用整个 checkout,而是用 nix/cloud-storage.nix 里过滤后的源码。因此任何新增的 include_str! / include_bytes! 资产都必须加进它的源码过滤器,否则本地能编译、CI 构建失败。
过滤器在 srcFilter 中组合了多个谓词,其中 assetFilter 是最容易被忽略的一个:
assetFilter =
path: _type:
builtins.match ".*\\.(md|html|txt|json|jsonl|canvas|sql|sh|ttf|xml|graphql|mjs|proto)$" path != null;
扩展名白名单每一项都有明确用途,注释里写得清楚:.sh 用于 crates/agent_harness/container/ensure_ready.sh;.ttf、.xml 用于 crates/pptx_engine 以 include_bytes! 嵌入的字体与预设形状;.graphql 用于 static_assets/schema.graphql;.jsonl 用于 agent_fold 测试嵌入的录制会话;.mjs 用于 Deno bootstrap 与打包的公共 SDK、Handlebars 运行时;.proto 用于 whatsmeow_proto 与 whatsmeow_signal 的构建脚本。此外还有 .bin、.sqlx、pdfium 动态库与本地 CA 的独立过滤器。
code-execution-assets 这个 Nix check 用来验证 Deno bootstrap、SDK 与 Handlebars 打包产物在三处都存活:workspace 过滤器、pruned 的 agent-harness 部署源码、以及构建出的目录。Rust CI 会在 clippy 之前跑它。本地可单独执行:
nix build --no-link .#checks.x86_64-linux.code-execution-assets
七、其他常用资源:用对组件,而不是裸资源
| 需求 | 使用 | 参考 |
|---|---|---|
| SQS 队列 + DLQ + 告警 | Queue(packages/resources),名字需与 macro_queues 常量一致 |
calendar-service/index.ts |
| Kafka topic | 加到 crates/macro_event_topics,运行 cargo x kafka-topics;绝不手改 .github/kafka-cluster-topics.json |
kafka-cluster/topics.ts |
| Kafka 访问权限 | task role 上 getKafkaClusterPolicy(),broker 取 bootstrapBrokersSaslIam |
calendar-service/service.ts |
| Lambda | Lambda(packages/lambda),二进制登记在 deploy_lambdas |
deleted-item-poller/lambda.ts |
| Redis | Redis(packages/resources) |
calendar-service/index.ts |
| DynamoDB | ServiceDynamoDBTable(最小权限),不要用 DynamoDBTable(dynamodb:*) |
packages/service/src/dynamodb.ts |
| Bucket | createBucketV2 |
packages/resources/src/resources/bucket.ts |
| Datadog monitor | infra/stacks/monitoring(prod only,手动部署) |
monitoring/monitors/ai-editing.ts |
Queue 组件的命名约定值得单独说明:infra/packages/resources/src/resources/queue.ts 会拼出 ${name}-queue-${stack} 与 ${name}-dlq-${stack}(FIFO 时追加 .fifo),DLQ 保留 14 天(1209600 秒),并对 DLQ 的 ApproximateNumberOfMessagesVisible > 0 直接告警。因此 calendar-service 里传 calendar-service-backfill,最终就得到 Rust 侧 macro_queues::CalendarServiceBackfillQueue 期望的 calendar-service-backfill-queue-{dev,prod}。maxReceiveCount 默认 5、visibilityTimeoutSeconds 默认 30,calendar 分别覆盖为 20 和 60。
ServiceDynamoDBTable 默认 PAY_PER_REQUEST、pointInTimeRecovery 默认关闭,并把最小权限策略与表一起产出,避免调用方再手写 IAM。
新增 prod 队列或 bucket 时,还要同步加进本地清册 tooling/xtask/crates/xtask_local/src/local/resources.rs——Pulumi 不会创建本地资源。该文件头部注释解释了原因:队列创建了却没导出、或导出了却不存在,都会让服务"连不上一个其实存在的队列",因此本地资源共用同一份清单。
八、命名与状态约定
- 资源命名统一为
${BASE_NAME}-<thing>-${stack},其中BASE_NAME = pulumi.getProject();组件类型 token 为my:components:<Name>(ServiceTargetGroup、DopplerEcsEnvironment、EcrImage、Queue等均是如此)。 - 把栈的
tags对象(environment、tech_lead、project)传给每一个资源,因为没有默认 tag。 calendar 的 tags 形如{ environment: stack, tech_lead: 'gab', project: 'calendar-service' }。 - 组件内部传
{ parent: this },保证资源树正确、删除时按序回收。 - 对有状态或已收养(adopted)的资源加
protect:MacroDB、KMS key、WAF、prod 的 Kafka。文档明确的警告是——把某个deploy_*配置开关关掉,会销毁它守护的东西。 - 收养资源后要移除
import:选项,否则下一次运行会把它替换掉。 - 用 Biome 格式化;infra/biome.jsonc 排除了"原样上传"的文件,例如 FusionAuth 当作外部脚本模板消费的
populate_jwt.js、作为 CloudFront Function 代码原样上传的wwwRedirect/handler.js——重排这些文件的格式等于更新线上函数。
本地校验命令(只读检查,不涉及部署):
bun install --cwd infra
bun run --cwd infra lint # biome check .
bun run --cwd infra check # tsc + web-app tsc + web-delivery 回归
check 脚本的内容也印证了文档说法:先 tsc --noEmit,再用独立 tsconfig 检查 stacks/web-app,最后用独立 Bun 进程跑 publication.test.ts、app-route.test.ts、app-cache.test.ts 三个"无后端"的交付回归。
九、部署:四条触发路径与它们各自的边界
| 触发条件 | 运行内容 |
|---|---|
push 到 main |
deploy_on_push.yml:构建 nix 二进制与 Lambda,在 in-VPC runner 上跑 migration,然后对 .github/services-config.json 中每个服务执行 dev 的 pulumi up |
| 发布 GitHub release | release-production.yml:同样的流程打 prod,之后是 workers、website、web app |
| 触碰已映射栈的 PR | pulumi_preview_pr.yml 对 dev 做 preview 并评论;code_check_infra.yml 跑 Biome 与 tsc |
| 手动 | deploy-pulumi-stack.yml、deploy-service-generic.yml、migrate-macro-db.yml |
services-config.json 是部署白名单
只有列在 services-config.json 中的栈会自动部署;gateway、macrodb、doppler-projects、monitoring 等属于手动栈。矩阵构建逻辑直接读这个文件(.github/workflows/deploy_all_services.yml):
services=$(jq -c '[.services | to_entries[] | select(.value.deploy_enabled != false and .value.bootstrap_pending == null) | .key]' "$cfg")
也就是说,标记了 bootstrap_pending 或 deploy_enabled: false 的服务会被跳过。当前仓库中 convert-service 即为 deploy_enabled: false 的示例。另有 deploy_binaries / deploy_lambdas 两个数组决定是否进入对应构建矩阵,空的清单不会占用 runner。
工作流的编排顺序也写在 YAML 头部注释里,且带一条重要的设计说明:每个 stage 都在每次 push 时部署,故意不做 path 过滤。原因是流水线串行在单个 concurrency group 上,而 GitHub 每个 group 只保留一个 pending run——新排队的 run 会取消已在等待的 run(cancel-in-progress: false 只保护正在执行的那个)。一旦加了变更过滤,push A(后端)被 B(纯前端)挤掉后永远不会部署。无条件全量部署让"合并即无损":存活的 run 总是覆盖被它挤掉的 run 的超集,而 Nix 缓存与"未变更栈的 Pulumi no-op"已经把成本压得很低。
MacroDB 与读副本的扩容顺序
dev 的 MacroDB 主库与读副本都配置为 db.t4g.large(8 GiB)——见 infra/stacks/macrodb/Pulumi.dev.yaml 的 instance_size 与 read_replica_instance_size。prod 则是 db.m9g.8xlarge 主库、db.m9g.2xlarge 副本,备份保留 6 天(dev 为 1 天)。
调整副本规格需要单独部署一次 macrodb;dev 的 applyImmediately 为真(代码里写作 applyImmediately: stack !== 'prod'),这意味着那次 resize 会中断副本连接。因此正确顺序是:
- 先扩容读副本;
- 再通过服务栈部署 DSS 连接池变更;
- 确认旧 DSS 任务已经排空,再依赖新的连接上限。
文档给出的连接数推演值得记住:三个 dev 任务在滚动完成后允许 60 个副本连接,后续发布完全重叠期允许 120;但第一次滚动可能放开到 360——三个旧任务各 100 连接,加三个新任务各 20 连接。如果按稳态数字规划副本规格,第一次上线就会打满。
迁移先于服务,且必须向后兼容
Migration 在服务之前部署,并且必须能与"正在运行的旧代码"共存,详见 数据库指南。这正是流水线中 migrate-db 被 deploy-services 作为 needs 且要求 result == 'success' 的原因。
continueBeforeSteadyState 的含义
该标志为真时,"部署 job 变绿"并不证明旧任务已经停止。失败部署由熔断器回滚;其余情况要么向前修复,要么重新部署一个更旧的 ref。所以观察发布结果时,不能只看 CI 状态,还要看 ECS 服务事件与任务数。
十、不要复制的历史写法
- 通过
serviceLoadBalancer()给单个服务建 ALB(auth、document cognition、MCP、static files 仍是如此)。新的 HTTP 服务一律上共享网关。 - 裸
aws.sqs.Queue代替Queue;createImage;createServiceRole(它授予dynamodb:*)。 - Lambda 环境变量里存放已解析的 secret 值。
web-app与website把@pulumi/aws钉在 v6。bun run check会在它们独立的 TypeScript 工程里检查 web-app,然后用独立 Bun 进程跑无后端的 web 交付回归。
关于 Web 产物发布顺序、静态资源/错误缓存策略与无后端检查,见 web-app 交付说明 与 网站 CDN 说明。
文档还点名了两份已过时、需存疑阅读的材料:SLACK_IMPORT_ROLLOUT.md(该 worker 现在已经开启并会收到 APP_SECRETS_JSON)与 fusion-auth/README.md。
十一、Agent 后端:一个 ECS 服务承担多条职责
agent-harness-service 是唯一的 ECS agent 服务。它的进程同时承载 chat/completions、workspace MCP/OAuth、preview 的 SSH/HTTP/控制面、routine 的 cron 与事件 worker,以及 projection 刷新扫描。
合并之后各栈保留的东西很克制:preview-gateway 只保留网络资源;document-cognition 保留 projection 队列与公有 DNS 记录;mcp-server 保留它的公有 DNS 记录。两个主机名都指向共享网关,从而保住对外 URL 与 OAuth 回调地址不变。退役的 MCP 与 schedule 栈程序里不再包含任何计算资源。
这条路径有前置条件:部署前必须按 agent 服务合并指南 完成切换,旧的 listener 规则要先退役,harness 才能占用它们的优先级——否则同一 listener 上会出现优先级冲突。
十二、上手检查清单
在不触发任何部署的前提下,按下面顺序理解或修改这套基础设施:
- 读 infra/packages/shared/src/index.ts 与 gateway_priorities.ts,建立常量与路由的表感。
- 以 infra/stacks/calendar-service/service.ts 为模板读懂七块组件,再对照 infra/stacks/calendar-service/index.ts 看栈如何注入 VPC、队列、tags 与 secrets。
- 修改前执行
bun run --cwd infra check与 Biome;涉及嵌入式资产时补跑nix build --no-link .#checks.x86_64-linux.code-execution-assets。 - 需要看变更影响时只用
pulumi preview;pulumi up/destroy、wrangler deploy/secret put必须由用户显式要求。 - 新增队列、bucket、Kafka topic 或服务时,同步更新
services-config.json、xtask_local清册、macro_event_topics(用cargo x kafka-topics生成)与GATEWAY_PRIORITIES,任何一处遗漏都会在 CI 或首次部署时暴露。
这套基础设施的核心思路可以概括为:用少量可复用的组件收口权限、遥测和部署语义,用一张唯一的优先级表收口路由,用 Doppler 收口所有配置,用 services-config.json 收口部署范围。 理解了这四个"收口点",infra/ 下四十多个栈的行为就是可预测的。