使用 PostgreSQL 的 Web 应用,一步一步搭建
一个把笔记保存在 PostgreSQL 中的小型 Web 应用,分四步逐渐扩展:它从在你机器上运行的数据库起步,接着加入 Redis 缓存,然后迁移到 AWS 并将数据库放在 Amazon RDS 上,最后获得备份。每一步都是一个独立完整的工作区,分别位于目录 1/ 到 4/ 中,并且每一步都可以按原样构建。
每个 aggregate.yaml 都以一行注明其所属步骤的注释开头;在某一步修改了 release.yaml 或 manifest.yaml 时,这些文件也是如此。将一个文件与上一步的对应文件比较,即可准确看出该步骤新增了什么:
diff 1/aggregate.yaml 2/aggregate.yaml该应用是 hub.aggrega.ai/tools/quickstart-web:1.1.0,采用 Apache-2.0 许可证。它只从环境中读取配置:PostgreSQL 使用 PGHOST、PGPORT、PGUSER、PGPASSWORD 和 PGDATABASE,缓存使用 REDIS_HOST 和 REDIS_PORT,并且只在设置了 REDIS_HOST 时才使用缓存。它监听端口 8080,每个关于笔记的回答都会在其 source 字段中说明该笔记从何处读取,因此从外部即可看到缓存。
本页的输出块复制自一次真实运行,参见 阅读这些页面上的输出。
你需要准备的内容
aggregaCLI,每一步都需要。- 带 Compose 的 Docker,用于在你的机器上运行的
1/和2/。 3/和4/不需要其他东西:它们构建 Terraform 文件后即停止。两者各自的首次构建会从这些模块的 git 仓库获取 RDS 和 ElastiCache 模块。规划和应用这些文件是另一项单独的操作,需在替换占位符后使用你自己的 AWS 账户和凭据完成。
用一条命令运行
你可以用一条命令运行第一步,或者让你的 AI 助手为你编写并构建它。
为数据库选择一个密码,并先将其导出。在 Linux 或 macOS 上:
export QUICKSTART_DB_PASSWORD=choose-a-passwordcurl -fsSL https://aggrega.ai/quickstart-web.sh | sh在 Windows 上,在 PowerShell 中执行:
$env:QUICKSTART_DB_PASSWORD = 'choose-a-password'irm https://aggrega.ai/quickstart-web.ps1 | iex必须导出密码,因为 Docker Compose 从你的 shell 中读取它,而数据库会保留其首次启动时使用的密码,因此第二步需要相同的密码。没有密码,脚本会拒绝启动。
脚本会说明它将执行的操作,并在继续之前询问你。它会检查能否找到 aggrega,以及 Docker 是否响应并带有 Compose。它将示例写入文件夹 quickstart-web,如果该文件夹已存在则直接使用。随后它构建第一步,并用 Docker Compose 启动。脚本最后会打印应用的页面,http://127.0.0.1:8080/。
要运行其他步骤,请指定它:2、3 或 4;第 3 步和第 4 步只进行构建。在 Linux 或 macOS 上,在 sh -s -- 之后传入它,并在那里添加 --yes 可跳过询问直接继续:
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2在 PowerShell 中,先在 QUICKSTART_STEP 中设置它。它会在该窗口中保持设置,对之后的每次运行都有效,直到你用 Remove-Item Env:QUICKSTART_STEP 将其删除:
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iex生成示例
如果你更想一步一步地构建和运行,请将示例写入一个以其命名的新文件夹:
aggrega scaffold --example quickstart-web然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd quickstart-web构建
以下命令在本示例的目录中启动第一步。密码由你自行选择:Docker Compose 在服务栈启动时从你的 shell 中读取它,因此任何文件都不保存它。
cd 1aggrega build --release release.yaml --auto-pullexport QUICKSTART_DB_PASSWORD=choose-a-passworddocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait# then open http://127.0.0.1:8080/ in your browser构建写出一个文件 dist/compose/docker-compose.yaml,docker compose 以项目名 quickstart-web 启动它,并在两个服务都启动后返回。下面的每一节都会再前进一步。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `quickstart-web` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `quickstart-web`,且不设置 `dir`:它会将示例写入新的 `quickstart-web` 文件夹,其中包含一个 README 以及步骤文件夹 `1` 到 `4`。然后调用 `build` 工具,将 `workspace_root` 设为 `quickstart-web/1`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `quickstart-web/1/dist/` 下。一个 Web 应用及其 PostgreSQL — 1/
该 Aggregate 声明了两个组件:web,类型为 core/compute/server;db,类型为 core/datastore/postgres。应用通过一条边请求数据库,使用的是它所读取的名称:
uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: database密码通过两端各自的一个 core/secret-value 附加项到达两端,该附加项的来源是 Compose 变量引用 ${QUICKSTART_DB_PASSWORD}。该 Release 指定镜像(以其多平台索引的摘要固定版本)、它监听的端口 port: 8080,以及 published_port: 8080,即在你的机器上为它发布的端口;没有 published_port,那里就不会发布任何端口。web 服务,位于 dist/compose/docker-compose.yaml 中:
web: image: hub.aggrega.ai/tools/quickstart-web:1.1.0@sha256:72d42d6db51d34d1268108eca1989e1467ccb2c66d15ed3e50ca97e09003c8fb environment: PGDATABASE: appdb PGHOST: db PGPASSWORD: ${QUICKSTART_DB_PASSWORD} PGPORT: "5432" PGUSER: appuser ports: - 127.0.0.1:8080:8080 [… omitted: the aggrega.ai/ labels every service carries] networks: - compose depends_on: - db deploy: resources: limits: cpus: "0.1" memory: "134217728" reservations: cpus: "0.1" memory: "134217728"PGHOST 是 db,即数据库在 Compose 网络上的服务名,端口只发布在你机器的回环地址上。
在同一台机器上用浏览器打开 http://127.0.0.1:8080/,即可看到应用的页面。页面会列出应用所连接的数据库和缓存,并允许你添加一条笔记并读取它。每次读取都会注明来源,“from PostgreSQL”或“from the cache”。在尚未接入缓存时,页面显示“No cache is wired to the app, so every read comes from PostgreSQL.”
在终端中,问应用它连接到了什么,然后存储一条笔记并读回来:
curl -s http://localhost:8080/curl -s -X POST --data 'hello from the quickstart' http://localhost:8080/notescurl -s http://localhost:8080/notes/1{ "cache": "not wired", "database": "postgresql at db:5432/appdb", "service": "quickstart-web"}{ "id": 1, "text": "hello from the quickstart", "created_at": "2026-11-01T17:22:34.261989Z", "source": "postgresql"}{ "id": 1, "text": "hello from the quickstart", "created_at": "2026-11-01T17:22:34.261989Z", "source": "postgresql"}加入缓存 — 2/
该 Aggregate 新增一个 cache 组件,类型为 core/datastore/redis,并在应用上再加一条边:
cache: cache: target: cache inject: env: - in: REDIS_HOST from: host - in: REDIS_PORT from: port该 Manifest 将新类型映射到 compose/redis,该 Release 放置新组件。在同一个密码仍保持导出的情况下,以相同的项目名构建并启动它:
cd ../2aggrega build --release release.yaml --auto-pulldocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --waitDocker Compose 让数据库继续运行,用两个新变量重新创建应用,并启动缓存。数据库是用你在 1/ 中导出的密码创建的,并会一直保留该密码,因此这一步请使用相同的值。在 1/ 中存储的笔记仍然在;读取它两次:
curl -s http://localhost:8080/curl -s http://localhost:8080/notes/1curl -s http://localhost:8080/notes/1{ "cache": "cache:6379", "database": "postgresql at db:5432/appdb", "service": "quickstart-web"}{ "id": 1, "text": "hello from the quickstart", "created_at": "2026-11-01T17:22:34.261989Z", "source": "postgresql"}{ "id": 1, "text": "hello from the quickstart", "created_at": "2026-11-01T17:22:34.261989Z", "source": "cache"}第一次读取来自 PostgreSQL 并填充缓存;第二次来自缓存,缓存会将一条笔记保留五分钟。在页面上,读取同一条笔记两次,会先显示“from PostgreSQL”,再显示“from the cache”。
用完这组服务后,将其删除,连同数据库的数据一起:
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml down -v同一个数据库,托管在 AWS 上 — 3/
同样的三个组件,通过 Terraform 运行在 AWS 上。该 Manifest 将服务器映射到 terraform/server-ecs,即 Fargate 上的一个 Amazon ECS 服务;将 PostgreSQL 映射到 terraform/postgres-rds-terraform-aws-modules,它内置了 terraform-aws-modules 项目发布的 RDS 模块;将 Redis 映射到 terraform/redis-elasticache,它内置了该项目的 ElastiCache 模块。Aggregate 中的边不变。
该 Aggregate 去掉的是两个密码附加项:RDS 自行生成数据库的密码,因此没有任何构建输入携带密码。在 AWS 上,RDS 将密码保存在 AWS Secrets Manager 中,而 quickstart 应用只从 PGPASSWORD 读取密码,在你提供密码之前无法登录。
该 Release 在 infra.overrides 下指明你已在账户中运行的资源:ECS 集群、任务所连接的子网和安全组、ECS 用来拉取镜像和写入日志的执行角色,以及 RDS 和 ElastiCache 子网组。它还将缓存的 engine_version 设为 7.1,因为 ElastiCache 运行的 Redis OSS 最高为 7.1。这些值全都是占位符:123456789012 是 AWS 文档在示例中使用的账号,而 subnet-… 和 sg-… ID、子网组、集群和角色代表你自己账户中的资源。构建之所以接受它们,是因为它从不查找它们;请在规划之前替换它们。
cd ../3aggrega build --release release.yaml --auto-pull根配置 dist/terraform/aggrega.modules.tf:
# Root configuration for this boundary. Each component rendered here is one# module block below, and the directory that block points at holds that# component's own files. One configuration means one dependency graph, which is# what lets a reference or a depends_on reach from one component to another.
module "cache" { source = "./modules/cache"
create_security_group = false create_subnet_group = false engine = "redis" engine_version = "7.1" node_type = "cache.t3.small" port = 6379 replication_group_id = "cache" security_group_ids = ["sg-0123456789abcdef1"] subnet_group_name = "example-private-cache-subnets" transit_encryption_enabled = false}
module "db" { source = "./modules/db"
allocated_storage = 10 backup_retention_period = 7 create_db_subnet_group = false db_name = "appdb" db_subnet_group_name = "example-private-db-subnets" engine = "postgres" engine_version = "16" family = "postgres16" identifier = "db" instance_class = "db.t3.small" manage_master_user_password = true multi_az = false port = "5432" skip_final_snapshot = false storage_type = "gp3" username = "appuser" vpc_security_group_ids = ["sg-0123456789abcdef0"]}
module "web" { source = "./modules/web"
assign_public_ip = false cluster = "example-cluster" cpu = "256" desired_count = 1 environment = {"PGDATABASE":"appdb","PGHOST":"${module.db.db_instance_address}","PGPORT":"5432","PGUSER":"appuser","REDIS_HOST":"${module.cache.replication_group_primary_endpoint_address}","REDIS_PORT":"6379"} execution_role_arn = "arn:aws:iam::123456789012:role/example-ecs-task-execution" image = "hub.aggrega.ai/tools/quickstart-web:1.1.0@sha256:72d42d6db51d34d1268108eca1989e1467ccb2c66d15ed3e50ca97e09003c8fb" memory = "512" name = "web" port = 8080 security_groups = ["sg-0fedcba9876543210"] subnet_ids = ["subnet-0123456789abcdef0","subnet-0fedcba9876543210"]}应用收到的名称与在 Compose 上相同。PGHOST 和 REDIS_HOST 现在是对 RDS 和 ElastiCache 模块自身输出的引用,Terraform 在应用配置时解析它们,因为在实例和缓存创建之前,这两个地址都不存在;编译器原样传递二者,不读取它们。在 dist/terraform 的副本上,tofu init -backend=false 加载根模块和内置的模块,并且只获取提供程序,随后 tofu validate 打印:
Success! The configuration is valid.加入备份 — 4/
在没有其他设置时,RDS 会将实例的自动备份保留 7 天,备份窗口由它自行选择,即上文中的 backup_retention_period = 7。该 Release 将 core/backup 附加到数据库:
db: features: backup: type: core/backup infra: retention_days: 14 schedule: "30 2 * * *"而该 Manifest 将该 Feature 绑定到 terraform/backup-native,它自身不渲染任何内容:备份是实例的一项设置,因此数据库的 Recipe 读取该附加项,并把它写在实例的模块块上。RDS 每天进行一次自动备份,因此该计划在那个时间打开一个 30 分钟的窗口,采用 UTC 时间。Aggregate 不变。
cd ../4aggrega build --release release.yaml --auto-pull根配置与 3/ 中的相比,仅 db 模块块不同,对它运行 tofu validate 同样打印 Success! The configuration is valid.:
backup_retention_period = 7backup_retention_period = 14backup_window = "02:30-03:00"构建不等于部署
3/ 和 4/ 将文件写到 dist/ 下,然后停止。构建从不运行 Terraform 或 OpenTofu,从不向 AWS 进行身份验证,也不查找 Releases 所指定的任何标识符。规划和应用是你在替换占位符之后,用你自己的凭据对输出执行的步骤。
检查每一步
在文档仓库的检出中(它包含由 aggrega scaffold --example 写出的副本所不具备的共享构建辅助脚本),本目录中的 ./check.sh 会构建这四步,并检查每一步写出的内容是否与本页展示的一致:两个 Compose 文件及其服务和变量,以及两个 Terraform 根配置及其模块块、引用和备份设置。它每一步打印一行,只要有任何一步不同,就以非零状态退出。dist/、.aggrega/ 和 *.lock 文件是生成的,不会提交;它们由已提交的文件重新生成。