跳到正文

在 AWS 上部署 Kaeso

在 AWS 上运行 Kaeso,有两个模板,都基于 CloudFormation。快速服务器,一键把 Compose 软件包,装进一台 Graviton 实例;托管堆栈,运行在 ECS Fargate 上,配有负载均衡器、RDS 和 ElastiCache。

发布日期
阅读时间
5 分钟
作者
Kaeso Team
淡雅的绿色与青绿色渐变,沿对角线向上折叠

Kaeso 仓库中的 deploy/aws/ 有两个 CloudFormation 模板,满足两种不同的需求。快速服务器是一台 EC2 实例上的 Compose 软件包,和您自己的服务器完全一样,一键即可启动。托管堆栈在 ECS Fargate 上运行 Kaeso,使用 AWS 自己的数据存储,适合一台机器已经不够用的实例。

每个版本都会把这两个模板上传到 https://kaeso-cloudformation.s3.amazonaws.com/vX.Y.Z/,稳定版本还会上传到 latest/。

快速服务器

Launch on AWS(在新标签页中打开) 会在 CloudFormation 中打开已发布的模板。它会创建:

  • 一台运行 Ubuntu 24.04 的 Graviton 实例,默认是 t4g.medium,带 40 GB 磁盘;
  • 一个弹性 IP,以及一个允许 HTTP、HTTPS 和 HTTP/3 的安全组,SSH 只对您选择的地址范围开放;
  • 可选的 Route 53 域名记录。

首次启动时,实例会运行 Kaeso 的安装脚本。它安装 Docker,写入设置,生成主密钥,并启动 Compose 软件包,其中包括 Caddy、用于请求日志的内置 ClickHouse 和更新器。所以控制台中的更新可以使用,与任何 Compose 实例一样。

在 CLI 中,用仓库的一个克隆:

aws cloudformation deploy --stack-name kaeso --template-file deploy/aws/quick-server.yaml \  --parameter-overrides Domain=kaeso.example.com KeyName=my-key \  AllowedSshCidr=203.0.113.0/24 HostedZoneId=Z0123456789
参数含义
DomainKaeso 应答的域名;不设 HostedZoneId 时,请把它的 A 记录指向输出 PublicIp
KaesoVersion要安装的版本;留空则安装最新的稳定版本
InstanceType、DiskSizeGb默认是 t4g.medium 和 40 GB
KeyName、AllowedSshCidrSSH 访问,kaeso setup-link 需要它
HostedZoneId该域名的一个 Route 53 托管区域,用于创建它的记录

堆栈创建完成、Caddy 拿到证书后,通过 SSH 运行输出 SetupLink。它会打印用于创建第一个用户的一次性链接。

托管堆栈

deploy/aws/managed.yaml 用 AWS 服务搭建 Kaeso:

  • 一个 VPC,包含两个公有子网、两个私有子网和一个 NAT 网关;
  • 一个 Application Load Balancer,使用您的 ACM 证书,把 HTTP 重定向到 HTTPS,用路径规则把 API、MCP 服务器及其登录发往网关、其他所有内容发往控制台,并为长时间的流设置 300 秒的空闲超时;
  • 一个运行在 Fargate 上、使用 Graviton 的 ECS 集群,位于私有子网中:一个网关服务,默认 2 个任务,每个 2 个 vCPU 和 4 GB;以及一个控制台服务;
  • RDS PostgreSQL 18,以及使用 noeviction、TLS 和 AUTH 令牌的 ElastiCache Valkey,两者都只有网关能访问;
  • Secrets Manager 中的机密,保存主密钥、数据库密码、Valkey 令牌、SMTP 密码和 ClickHouse URL;
  • CloudWatch 日志组,以及可选的 Route 53 别名记录。
aws cloudformation deploy --stack-name kaeso --template-file deploy/aws/managed.yaml \  --capabilities CAPABILITY_IAM --parameter-overrides \  Domain=kaeso.example.com \  CertificateArn=arn:aws:acm:eu-central-1:123456789012:certificate/example \  MasterKeys="$(docker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generate)" \  SetupEmail=owner@example.com SmtpHost=smtp.example.com SmtpUser=kaeso \  SmtpPassword=secret SmtpFrom="Kaeso <kaeso@example.com>"

主密钥也请在密码管理器中保存一份副本:Kaeso 用它加密服务商密钥。其他参数决定堆栈的规格:网关的 GatewayCpu、GatewayMemory 和 GatewayCount,以及数据存储的 DatabaseInstanceClass、DatabaseStorageGb 和 CacheNodeType。多个网关任务通过 Valkey 共享限额、缓存和路由的冷却状态。如需请求日志,把 ClickHouseUrl 设为一个 ClickHouse,例如 ClickHouse Cloud;留空则保持关闭。

在第一个用户创建之前,网关会把一次性设置链接发送到 SetupEmail。它只信任来自 VPC(负载均衡器节点所在之处)的 X-Forwarded-For。负载均衡器检查网关的 /readyz 和控制台的 /healthz,网关任务停止时有 75 秒的时间处理完剩余请求。

更新和回滚

在快速服务器上,可以从控制台更新,也可以在您选择的时间窗口内自动更新,或手动更新,与任何 Compose 实例一样。再次部署模板并不会更新 Kaeso。

在托管堆栈上,发布新版本会修改 managed.yaml 中的镜像标签。把新模板部署到堆栈上:ECS 会替换任务,并借助断路器在失败时自动回滚;网关在启动时迁移数据库,只向前进行。如需主动回滚,部署上一个版本的模板即可。

已验证的内容

2026 年 11 月 7 日,快速服务器以 CloudFormation 堆栈的形式,在 us-east-1 从空白账户启动,使用第 8 个候选版本。在测试实例上把主密钥文件的所有权改回安装脚本之后,它创建了第一个用户,并通过了路由、流式传输和日志记录的检查。模板现在不再更改这个所有权,但修正后的模板尚未从空白账户重新部署。托管堆栈在 CI 中经过 lint 和格式检查,尚未部署过。

下一步

作者:Kaeso Team

本页内容

网关归您。记录也归您。

curl -fsSLhttps://kaeso.app/install.sh | sh