Một ứng dụng web với PostgreSQL, được xây dựng từng bước một
Một ứng dụng web nhỏ lưu ghi chú trong PostgreSQL, được phát triển qua bốn bước: ứng dụng bắt đầu với cơ sở dữ liệu trên máy của bạn, có thêm bộ nhớ đệm Redis, chuyển sang AWS với cơ sở dữ liệu trên Amazon RDS, và cuối cùng có các bản sao lưu. Mỗi bước là một không gian làm việc hoàn chỉnh riêng, nằm trong các thư mục từ 1/ đến 4/, và mỗi bước đều build được ngay ở trạng thái hiện có.
Mỗi aggregate.yaml mở đầu bằng một dòng chú thích nêu tên bước của nó, và release.yaml hoặc manifest.yaml cũng vậy ở bước có thay đổi chúng. So sánh một tệp với tệp của bước trước sẽ cho thấy chính xác bước đó thêm những gì:
diff 1/aggregate.yaml 2/aggregate.yamlỨng dụng là hub.aggrega.ai/tools/quickstart-web:1.1.0, theo giấy phép Apache-2.0. Nó chỉ đọc cấu hình từ môi trường của mình: PGHOST, PGPORT, PGUSER, PGPASSWORD và PGDATABASE cho PostgreSQL, và REDIS_HOST và REDIS_PORT cho bộ nhớ đệm, thứ mà nó chỉ dùng khi REDIS_HOST được đặt. Nó lắng nghe trên cổng 8080, và mọi câu trả lời về một ghi chú đều cho biết ghi chú được đọc từ đâu, trong trường source của nó, nên bộ nhớ đệm có thể nhìn thấy được từ bên ngoài.
Các khối output trên trang này được sao chép từ một lần chạy thật, theo Đọc output trên các trang này.
Những gì bạn cần
- CLI
aggrega, cho mọi bước. - Docker có Compose, cho
1/và2/, vốn chạy trên máy của bạn. - Không cần gì thêm cho
3/và4/: chúng build các tệp Terraform rồi dừng. Lần build đầu tiên của mỗi bước sẽ lấy các module RDS và ElastiCache từ kho git của chúng. Việc lập kế hoạch và áp dụng các tệp đó là một thao tác riêng, được thực hiện bằng tài khoản và thông tin xác thực AWS của chính bạn sau khi các giá trị giữ chỗ đã được thay thế.
Chạy bằng một lệnh
Bạn có thể chạy bước đầu tiên bằng một lệnh duy nhất, hoặc nhờ trợ lý AI của bạn viết và dựng nó cho bạn.
Hãy chọn một mật khẩu cho cơ sở dữ liệu và xuất nó trước. Trên Linux hoặc macOS:
export QUICKSTART_DB_PASSWORD=choose-a-passwordcurl -fsSL https://aggrega.ai/quickstart-web.sh | shTrên Windows, trong PowerShell:
$env:QUICKSTART_DB_PASSWORD = 'choose-a-password'irm https://aggrega.ai/quickstart-web.ps1 | iexMật khẩu phải được xuất vì Docker Compose đọc nó từ shell của bạn, và cơ sở dữ liệu giữ mật khẩu đầu tiên mà nó được khởi động cùng, nên bước thứ hai cần đúng mật khẩu đó. Script từ chối khởi động nếu không có mật khẩu.
Script cho biết nó sẽ làm gì và hỏi trước khi tiếp tục. Nó kiểm tra rằng nó có thể tìm thấy aggrega, và rằng Docker phản hồi và có Compose. Nó ghi ví dụ vào thư mục quickstart-web, hoặc dùng thư mục đó nếu thư mục đã có sẵn. Sau đó nó xây dựng bước đầu tiên và khởi động bước đó bằng Docker Compose. Script kết thúc bằng việc in ra trang của ứng dụng, http://127.0.0.1:8080/.
Để chạy một bước khác, hãy chỉ định nó: 2, 3 hoặc 4; bước 3 và 4 chỉ xây dựng. Trên Linux hoặc macOS, truyền nó sau sh -s --, và thêm --yes vào đó để tiếp tục mà không có câu hỏi:
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2Trong PowerShell, hãy đặt nó trong QUICKSTART_STEP trước. Giá trị này được giữ trong cửa sổ đó, cho mọi lần chạy sau, cho đến khi bạn xóa nó bằng Remove-Item Env:QUICKSTART_STEP:
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iexTạo ví dụ
Nếu bạn muốn build và chạy nó từng bước, hãy ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example quickstart-webSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
cd quickstart-webBuild
Các lệnh dưới đây khởi động bước đầu tiên, từ thư mục của ví dụ này. Mật khẩu do bạn tự chọn: Docker Compose đọc nó từ shell của bạn khi stack khởi động, nên không tệp nào chứa nó.
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 browserBản build ghi ra một tệp, dist/compose/docker-compose.yaml, và docker compose khởi động nó với tên dự án quickstart-web rồi trả về khi cả hai dịch vụ đã chạy. Mỗi phần bên dưới tiến thêm một bước.
Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ dùng các công cụ của Aggrega, và không tự tạo thư mục nào. Nếu thư mục workspace chưa có thư mục `quickstart-web`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `quickstart-web` và không có `dir`: nó ghi ví dụ vào một thư mục `quickstart-web` mới, với một README và các thư mục bước từ `1` đến `4`. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `quickstart-web/1`, `release` đặt thành `release.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Cho tôi biết bản build đã ghi những tệp nào; chúng nằm dưới `quickstart-web/1/dist/`.Một ứng dụng web và PostgreSQL của nó — 1/
Aggregate khai báo hai thành phần: web, thuộc kiểu core/compute/server, và db, thuộc kiểu core/datastore/postgres. Ứng dụng yêu cầu cơ sở dữ liệu trên một cạnh, dưới các tên mà nó đọc:
uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: databaseMật khẩu tới được cả hai đầu thông qua một phần đính kèm core/secret-value trên mỗi đầu, có nguồn gốc là tham chiếu biến Compose ${QUICKSTART_DB_PASSWORD}. Release nêu image, được ghim theo digest của index đa nền tảng của nó, cổng mà nó lắng nghe, port: 8080, và published_port: 8080, cổng được công bố cho nó trên máy bạn; không có published_port thì không có gì được công bố ở đó. Dịch vụ web trong 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 là db, tên dịch vụ của cơ sở dữ liệu trên mạng Compose, và cổng chỉ được công bố trên địa chỉ loopback của máy bạn.
Mở http://127.0.0.1:8080/ trong trình duyệt trên cùng máy để xem trang của ứng dụng. Trang nêu tên cơ sở dữ liệu và bộ nhớ đệm mà ứng dụng đang kết nối, và cho phép bạn thêm một ghi chú rồi đọc nó. Mỗi lần đọc cho biết nó đến từ đâu, “from PostgreSQL” hoặc “from the cache”. Khi chưa có bộ nhớ đệm nào được nối vào, trang hiển thị “No cache is wired to the app, so every read comes from PostgreSQL.”
Từ một terminal, hãy hỏi ứng dụng đang kết nối với gì, rồi lưu một ghi chú và đọc lại:
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"}Thêm bộ nhớ đệm — 2/
Aggregate thêm một thành phần cache thuộc kiểu core/datastore/redis, và thêm một cạnh nữa trên ứng dụng:
cache: cache: target: cache inject: env: - in: REDIS_HOST from: host - in: REDIS_PORT from: portManifest ánh xạ kiểu mới tới compose/redis, và Release đặt thành phần mới. Hãy build và khởi động nó với cùng tên dự án, trong khi vẫn export cùng mật khẩu đó:
cd ../2aggrega build --release release.yaml --auto-pulldocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --waitDocker Compose để cơ sở dữ liệu tiếp tục chạy, tạo lại ứng dụng với hai biến mới của nó, và khởi động bộ nhớ đệm. Cơ sở dữ liệu được tạo với mật khẩu bạn đã export ở 1/ và giữ nguyên mật khẩu đó, nên hãy giữ cùng giá trị cho bước này. Ghi chú đã lưu ở 1/ vẫn còn đó; hãy đọc nó hai lần:
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"}Lần đọc đầu tiên đến từ PostgreSQL và điền vào bộ nhớ đệm; lần thứ hai đến từ bộ nhớ đệm, nơi giữ một ghi chú trong năm phút. Trên trang, đọc một ghi chú hai lần sẽ hiển thị “from PostgreSQL”, rồi “from the cache”.
Khi đã dùng xong stack, hãy gỡ nó đi, cùng với dữ liệu của cơ sở dữ liệu:
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml down -vCùng cơ sở dữ liệu, được quản lý trên AWS — 3/
Cùng ba thành phần, trên AWS, thông qua Terraform. Manifest ánh xạ server tới terraform/server-ecs, một dịch vụ Amazon ECS trên Fargate; PostgreSQL tới terraform/postgres-rds-terraform-aws-modules, vốn đóng gói kèm module RDS đã phát hành của dự án terraform-aws-modules; và Redis tới terraform/redis-elasticache, vốn đóng gói kèm module ElastiCache của dự án đó. Các cạnh trong Aggregate không thay đổi.
Thứ mà Aggregate bỏ đi là hai phần đính kèm mật khẩu: RDS tự tạo mật khẩu của cơ sở dữ liệu, nên không đầu vào build nào mang mật khẩu. Trên AWS, RDS lưu mật khẩu trong AWS Secrets Manager, và ứng dụng quickstart, vốn chỉ đọc mật khẩu từ PGPASSWORD, không thể đăng nhập cho đến khi bạn cung cấp nó.
Release nêu, dưới infra.overrides, những gì bạn đã chạy sẵn trong tài khoản của mình: cụm ECS, các subnet và security group mà các task gắn vào, execution role mà ECS dùng để kéo image và ghi log, và các subnet group của RDS và ElastiCache. Nó cũng đặt engine_version của bộ nhớ đệm thành 7.1, vì ElastiCache chạy Redis OSS tối đa tới 7.1. Mỗi giá trị trong số đó đều là giá trị giữ chỗ: 123456789012 là số tài khoản mà tài liệu AWS dùng trong các ví dụ, còn các ID subnet-… và sg-…, các subnet group, cụm và role đại diện cho tài nguyên trong tài khoản của chính bạn. Bản build chấp nhận chúng vì nó không bao giờ tra cứu chúng; hãy thay thế chúng trước khi bạn lập kế hoạch.
cd ../3aggrega build --release release.yaml --auto-pullCấu hình gốc, 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"]}Ứng dụng nhận cùng các tên như trên Compose. PGHOST và REDIS_HOST giờ là các tham chiếu tới chính output của các module RDS và ElastiCache, mà Terraform phân giải khi áp dụng cấu hình, vì cả hai địa chỉ đều chưa tồn tại trước khi instance và bộ nhớ đệm được tạo; trình biên dịch chuyển tiếp cả hai mà không đọc chúng. Trên một bản sao của dist/terraform, tofu init -backend=false nạp module gốc và các module được đóng gói kèm và chỉ tải về các provider, rồi tofu validate in ra:
Success! The configuration is valid.Thêm bản sao lưu — 4/
RDS giữ các bản sao lưu tự động của instance trong 7 ngày, trong một khung thời gian do nó chọn, khi không có gì quy định khác — backup_retention_period = 7 ở trên. Release đính kèm core/backup vào cơ sở dữ liệu:
db: features: backup: type: core/backup infra: retention_days: 14 schedule: "30 2 * * *"và Manifest gắn Feature với terraform/backup-native, vốn tự nó không render gì cả: bản sao lưu là một thiết lập của instance, nên Recipe của cơ sở dữ liệu đọc phần đính kèm và ghi nó vào khối module của instance. RDS tạo một bản sao lưu tự động mỗi ngày, nên lịch trình mở một khung 30 phút vào thời điểm đó, theo UTC. Aggregate không thay đổi.
cd ../4aggrega build --release release.yaml --auto-pullCấu hình gốc chỉ khác cấu hình ở 3/ ở khối module db, và tofu validate trên nó cũng in ra Success! The configuration is valid.:
backup_retention_period = 7backup_retention_period = 14backup_window = "02:30-03:00"Build không phải là triển khai
3/ và 4/ ghi các tệp vào dist/ rồi dừng. Bản build không bao giờ chạy Terraform hay OpenTofu, không bao giờ xác thực với AWS, và không tra cứu bất kỳ định danh nào mà các Releases nêu ra. Lập kế hoạch và áp dụng là các bước bạn thực hiện trên kết quả đầu ra, với thông tin xác thực của chính bạn, sau khi thay thế các giá trị giữ chỗ.
Kiểm tra mọi bước
Trong một bản checkout của kho tài liệu, nơi chứa script trợ giúp build dùng chung mà một bản sao do aggrega scaffold --example ghi ra không có, ./check.sh trong thư mục này build bốn bước và kiểm tra rằng mỗi bước ghi ra đúng những gì trang này trình bày: hai tệp Compose với các dịch vụ và biến của chúng, và hai cấu hình gốc Terraform với các khối module, tham chiếu và thiết lập sao lưu của chúng. Nó in một dòng cho mỗi bước và thoát với mã khác 0 nếu có bước nào khác biệt. dist/, .aggrega/ và các tệp *.lock được sinh ra và không được commit; chúng được sinh lại từ các tệp đã được commit.