跳到正文

在 DigitalOcean 上部署 Kaeso

用一键部署按钮,部署到 App Platform;或在生产环境中,用 doctl 和托管 Valkey。应用自带的边缘服务,在同一个域名上,路由控制台和 API。

发布日期
阅读时间
4 分钟
作者
Kaeso Team
明亮的橙色与桃色渐变,沿对角线向下折叠,一角透着暖光

DigitalOcean 的 App Platform 把容器运行在一个边缘服务之后,由它终结 TLS 并按路径路由。Kaeso 直接使用这个边缘服务:应用把 API 发往网关,其他所有内容发往控制台,所以这里不运行 kaeso-edge。

仓库中有两份应用规范。.do/deploy.template.yaml 供 Deploy to DigitalOcean 按钮读取,Valkey 运行在应用内部。.do/app.yaml 则改用托管的 Valkey 数据库,需要用 doctl 创建。想试用 Kaeso 就用按钮,要长期保留的实例就用 doctl。

您会得到什么

  • kaeso-gateway
    类型
    端口 8080 上的服务,网关镜像
    规格
    apps-s-1vcpu-2gb
  • kaeso-console
    类型
    端口 3000 上的服务,控制台镜像
    规格
    apps-s-1vcpu-0.5gb
  • kaeso-postgres
    类型
    开发数据库,PostgreSQL 18
    规格
    512 MB
  • kaeso-valkey(按钮)
    类型
    端口 6379 上的服务,只供应用自己的组件使用
    规格
    apps-s-1vcpu-0.5gb
  • kaeso-valkey(doctl)
    类型
    托管 Valkey 数据库,需先创建
    规格
    由您选择

边缘服务把 /v1、/v1beta、/v2、/platform、/mcp、/oauth 和 /.well-known 路由到网关,把其他所有路径路由到控制台。网关信任来自私有网络(边缘服务所在之处)的 X-Forwarded-For,并把指标保留在回环地址上。

KAESO_PUBLIC_URL 是 ${APP_URL},即应用的主地址;数据库地址来自各个数据库,所以这些都不用您手动输入。

需要填写的值

值填写内容
KAESO_MASTER_KEYS主密钥,同时保存在密码管理器中
KAESO_SETUP_EMAIL您的邮箱地址;网关把设置链接发送到这里
KAESO_SMTP_HOST、KAESO_SMTP_USER、KAESO_SMTP_PASSWORD、KAESO_SMTP_FROM您的 SMTP 服务器
KAESO_CLICKHOUSE_URL用于请求日志的、带用户名和密码的 ClickHouse HTTP URL,或留空

用 Docker 生成主密钥:

docker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generate

App Platform 在首次收到 SECRET 值时会将其加密。

用按钮部署

  1. 打开 Deploy to DigitalOcean(在新标签页中打开)。App Platform 从 prod 分支读取规范,该分支包含最新版本。
  2. 在 kaeso-gateway 的环境变量中填写上面的值;如有需要,可以选择其他区域。
  3. 创建应用,等待它的首次部署上线。
  4. 打开网关发给您的一次性设置链接,创建第一个用户。

按钮只能创建开发数据库,而开发数据库只支持 PostgreSQL。所以按钮的 Valkey 作为应用中的一个服务运行,数据保持在 256 MB 以内,从不驱逐任何键。它在每次部署时都从空开始,这对它保存的内容没有影响:网关会从 PostgreSQL 重建预算计数器,速率窗口则重新开始。不过开发数据库不保留备份,所以生产环境请用 doctl,或把应用迁到托管的 PostgreSQL 集群和托管的 Valkey 上。

用 doctl 部署

安装 doctl(在新标签页中打开),登录,并在应用所在的区域创建 Valkey 数据库:

doctl auth initdoctl databases create kaeso-valkey --engine valkey --region fra1 --size db-s-1vcpu-1gb --num-nodes 1 --wait

在数据库的 Settings 中,把 Eviction policy 设为 No eviction,这样数据库写满时会拒绝写入,而不是丢弃限额计数器。然后从您要部署的版本中复制 .do/app.yaml,填好值,创建应用:

doctl apps create --spec app.yaml --wait

托管的 Valkey 使用 TLS,其证书由 DigitalOcean 自己的证书颁发机构签发,规范会把它作为 KAESO_VALKEY_CA 交给网关。如需带备份的数据库,请创建一个托管 PostgreSQL 集群,并用 production: true 和它的 cluster_name 让 kaeso-postgres 指向它。

使用自己的域名

用按钮部署时:在应用的 Settings 中,于 Domains 下添加域名,并按 App Platform 的提示设置 DNS 记录。${APP_URL} 会跟随主域名,所以网关会以新地址重新部署。

用 doctl 部署时:在规范的 domains 下添加该域名,设置 type: PRIMARY,用 doctl apps update 应用规范,并按应用 Networking 标签页的提示设置 DNS 记录。

更新和回滚

发布新版本会修改 kaeso-gateway 和 kaeso-console 的镜像标签。在应用的规范中设置这两个标签,然后应用它:

doctl apps spec get $APP_ID > app.yamldoctl apps update $APP_ID --spec app.yaml --wait

网关在启动时迁移数据库,只向前进行。要回滚,在应用的 Activity 标签页中,选择之前某次部署旁边的 Rollback;App Platform 会保留最近十次成功的部署。

已验证的内容

2026 年 11 月 9 日,App Platform 的校验和提案 API 接受了按钮的规范。Kaeso 尚未从空白账户部署到 DigitalOcean。如果您部署了,请告诉我们结果如何。

下一步

作者:Kaeso Team

本页内容

网关归您。记录也归您。

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