Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Веб-приложение с PostgreSQL, построенное шаг за шагом

Небольшое веб-приложение, хранящее заметки в PostgreSQL, развиваемое за четыре шага: оно начинает с базы данных на вашей машине, получает кеш 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. Оно читает конфигурацию только из своего окружения: PGHOST, PGPORT, PGUSER, PGPASSWORD и PGDATABASE для PostgreSQL, а также REDIS_HOST и REDIS_PORT для кеша, который оно использует только тогда, когда задан REDIS_HOST. Оно слушает порт 8080, и каждый ответ о заметке сообщает в поле source, откуда заметка была прочитана, поэтому кеш виден снаружи.

Блоки вывода на этой странице скопированы из реального запуска, согласно разделу Чтение вывода на этих страницах.

Что понадобится

  • CLI aggrega — для каждого шага.
  • Docker с Compose — для 1/ и 2/, которые работают на вашей машине.
  • Для 3/ и 4/ больше ничего: они собирают файлы Terraform и останавливаются. Первая сборка каждого из них загружает модули RDS и ElastiCache из их git-репозиториев. Планирование и применение этих файлов — отдельное действие, выполняемое с вашей собственной учётной записью AWS и учётными данными после замены заполнителей.

Запуск одной командой

Первый шаг можно запустить одной командой или поручить вашему ИИ-ассистенту написать и собрать его за вас.

Выберите пароль для базы данных и сначала экспортируйте его. В 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 читает его из вашей оболочки, а база данных сохраняет первый пароль, с которым она была запущена, поэтому второму шагу нужен тот же пароль. Без него скрипт отказывается запускаться.

Скрипт сообщает, что он сделает, и спрашивает, прежде чем продолжить. Он проверяет, что может найти 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 читает его из вашей оболочки при запуске стека, поэтому ни один файл его не хранит.

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 и возвращает управление, как только обе службы запущены. Каждый раздел ниже продвигается на шаг дальше.

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты 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/`.

Веб-приложение и его 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, а порт публикуется только на loopback-адресе вашей машины.

Откройте 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/

Те же три компонента в AWS через Terraform. Manifest сопоставляет сервер с terraform/server-ecs — службой Amazon ECS на Fargate; PostgreSQL — с terraform/postgres-rds-terraform-aws-modules, который содержит встроенную копию опубликованного модуля RDS проекта terraform-aws-modules; а 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-…, группы подсетей, кластер и роль обозначают ресурсы в вашей собственной учётной записи. Сборка их принимает, потому что никогда их не проверяет; замените их перед планированием.

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 генерируются и не фиксируются в репозитории; они заново генерируются из зафиксированных файлов.