跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

使用 PostgreSQL 的 Web 应用,一步一步搭建

一个把笔记保存在 PostgreSQL 中的小型 Web 应用,分四步逐渐扩展:它从在你机器上运行的数据库起步,接着加入 Redis 缓存,然后迁移到 AWS 并将数据库放在 Amazon RDS 上,最后获得备份。每一步都是一个独立完整的工作区,分别位于目录 1/ 到 4/ 中,并且每一步都可以按原样构建。

每个 aggregate.yaml 都以一行注明其所属步骤的注释开头;在某一步修改了 release.yaml 或 manifest.yaml 时,这些文件也是如此。将一个文件与上一步的对应文件比较,即可准确看出该步骤新增了什么:

Terminal window
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 字段中说明该笔记从何处读取,因此从外部即可看到缓存。

本页的输出块复制自一次真实运行,参见 阅读这些页面上的输出。

你需要准备的内容

  • aggrega CLI,每一步都需要。
  • 带 Compose 的 Docker,用于在你的机器上运行的 1/ 和 2/。
  • 3/ 和 4/ 不需要其他东西:它们构建 Terraform 文件后即停止。两者各自的首次构建会从这些模块的 git 仓库获取 RDS 和 ElastiCache 模块。规划和应用这些文件是另一项单独的操作,需在替换占位符后使用你自己的 AWS 账户和凭据完成。

用一条命令运行

你可以用一条命令运行第一步,或者让你的 AI 助手为你编写并构建它。

为数据库选择一个密码,并先将其导出。在 Linux 或 macOS 上:

Terminal window
export QUICKSTART_DB_PASSWORD=choose-a-password
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh

在 Windows 上,在 PowerShell 中执行:

Terminal window
$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 可跳过询问直接继续:

Terminal window
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2

在 PowerShell 中,先在 QUICKSTART_STEP 中设置它。它会在该窗口中保持设置,对之后的每次运行都有效,直到你用 Remove-Item Env:QUICKSTART_STEP 将其删除:

Terminal window
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iex

生成示例

如果你更想一步一步地构建和运行,请将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example quickstart-web

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd quickstart-web

构建

以下命令在本示例的目录中启动第一步。密码由你自行选择:Docker Compose 在服务栈启动时从你的 shell 中读取它,因此任何文件都不保存它。

Terminal window
cd 1
aggrega build --release release.yaml --auto-pull
export QUICKSTART_DB_PASSWORD=choose-a-password
docker 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.”

在终端中,问应用它连接到了什么,然后存储一条笔记并读回来:

Terminal window
curl -s http://localhost:8080/
curl -s -X POST --data 'hello from the quickstart' http://localhost:8080/notes
curl -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 放置新组件。在同一个密码仍保持导出的情况下,以相同的项目名构建并启动它:

Terminal window
cd ../2
aggrega build --release release.yaml --auto-pull
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait

Docker Compose 让数据库继续运行,用两个新变量重新创建应用,并启动缓存。数据库是用你在 1/ 中导出的密码创建的,并会一直保留该密码,因此这一步请使用相同的值。在 1/ 中存储的笔记仍然在;读取它两次:

Terminal window
curl -s http://localhost:8080/
curl -s http://localhost:8080/notes/1
curl -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”。

用完这组服务后,将其删除,连同数据库的数据一起:

Terminal window
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、子网组、集群和角色代表你自己账户中的资源。构建之所以接受它们,是因为它从不查找它们;请在规划之前替换它们。

Terminal window
cd ../3
aggrega 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 不变。

Terminal window
cd ../4
aggrega build --release release.yaml --auto-pull

根配置与 3/ 中的相比,仅 db 模块块不同,对它运行 tofu validate 同样打印 Success! The configuration is valid.:

backup_retention_period = 7
backup_retention_period = 14
backup_window = "02:30-03:00"

构建不等于部署

3/ 和 4/ 将文件写到 dist/ 下,然后停止。构建从不运行 Terraform 或 OpenTofu,从不向 AWS 进行身份验证,也不查找 Releases 所指定的任何标识符。规划和应用是你在替换占位符之后,用你自己的凭据对输出执行的步骤。

检查每一步

在文档仓库的检出中(它包含由 aggrega scaffold --example 写出的副本所不具备的共享构建辅助脚本),本目录中的 ./check.sh 会构建这四步,并检查每一步写出的内容是否与本页展示的一致:两个 Compose 文件及其服务和变量,以及两个 Terraform 根配置及其模块块、引用和备份设置。它每一步打印一行,只要有任何一步不同,就以非零状态退出。dist/、.aggrega/ 和 *.lock 文件是生成的,不会提交;它们由已提交的文件重新生成。