Libretto自托管完整指南:把浏览器自动化工作流部署到AWS或GCP

原创2026-10-24 13:58:171,926 阅读

Libretto自托管完整指南:把浏览器自动化工作流部署到AWS或GCP

Libretto 是一款为构建可靠浏览器自动化(browser automation)而生的 AI 工具包:它给你的编码 Agent 一个真实浏览器,支持页面检查、网络抓包、录制回放与故障调试。除了官方托管平台 Libretto Cloud Hosting,你还可以把 Libretto 自托管(self-hosting)到 AWS 或 GCP——本文是一条面向新手、从零到上线的完整自建部署教程,带你把 Libretto 工作流跑在自己的云账号里。

Libretto自托管宣传图:不要让浏览器Agent去做脚本该干的活

为什么选择自托管 Libretto 而不是托管平台?

先弄清楚两条生产路径的区别(详见 docs/get-started/deploying.mdx):

  • Libretto Cloud Hosting:托管平台,一条部署命令即可上线,平台代管浏览器、调度、失败诊断;
  • Alternative providers(自托管/第三方):保留 Libretto 的 CLI 与工作流运行时,但浏览器或基础设施换成你自己的。

自托管又分两种模式(见 docs/alternative-providers/overview.mdx):

模式 代表 你拥有的东西
托管浏览器提供商 Kernel、Browserbase、Steel 浏览器跑在对方云,Libretto 通过 CDP 连接
自建云基础设施 AWS、GCP 完整拥有运行时、调度器、网络、密钥与产物

当你有合规要求(数据不能出自己账号)、成本敏感、或需要深度定制调度时,GCP 和 AWS 就是最佳选择。

Libretto自托管方案总览:Alternative providers 让你在任何基础设施上运行浏览器自动化工作流

自托管 Libretto 的核心思路:一个镜像跑所有工作流

无论 AWS 还是 GCP,官方教程都用同一个模式:一个可移植的 Docker 镜像 + 一个"调度入口"(dispatcher)。

  • 镜像基于官方 Playwright 基础镜像(mcr.microsoft.com/playwright),Chromium 及依赖开箱即用;
  • 入口文件通过两个环境变量决定行为:LIBRETTO_WORKFLOW(跑哪个工作流)和 LIBRETTO_INPUT(JSON 格式的入参);
  • 每次触发都启动一个全新容器,跑完即退出——这与"浏览器自动化往往需要几分钟"的特性完美契合。

这个模式的好处:镜像一次构建,AWS 和 GCP 通用;新增工作流只改代码,不动基础设施。

GCP 部署教程:把工作流变成 Cloud Run Jobs

GCP 路径使用 Cloud Run Jobs(GCP 的一次性任务容器运行时),配套 Artifact Registry 存镜像、Cloud Build 做 CI、Secret Manager 存密钥。完整步骤见 docs/alternative-providers/gcp.mdx。

Libretto GCP自托管部署:用 Cloud Run Jobs 运行浏览器自动化工作流

第一步:确认 GCP 前置条件

  • 一个已开通计费的 GCP 项目;
  • 启用 Artifact Registry、Cloud Run、Cloud Build、Secret Manager 四个 API;
  • 一个权限收紧的服务账号(Service Account),只授予它读密钥、写 GCS 等必要权限;
  • 本地安装并登录 gcloud CLI。

第二步:写 Dockerfile 和 Job 定义

Dockerfile 的关键点只有三个:用 Playwright 基础镜像、把浏览器缓存复制到 root 用户的 ~/.cache、以 pnpm start 作为入口交给 dispatcher。别忘了加 .dockerignore,把 node_modules、.libretto/sessions、.env 等本地状态挡在镜像外面。

然后用一份 YAML 声明式地描述 Cloud Run Job(这就是 gcloud run jobs replace 生成的格式),关键字段:

  • image:指向 Artifact Registry 中的镜像;
  • limits:1 CPU / 2Gi 内存起步;
  • serviceAccountName:授予 Job 读密钥等权限的身份;
  • timeoutSeconds:建议给到 "3600",浏览器自动化经常要跑几分钟。

第三步:Cloud Build 一键构建部署

写一份 cloudbuild.yaml(构建镜像 → 打 latest 和 $BUILD_ID 双标签 → 推送 → 替换 Job 规格),之后每次发版只需一条命令:

pnpm cloud:build    # 构建镜像 + 推送 + 替换 Job 定义

第四步:密钥在运行时注入

永远不要把凭证打进镜像。在 dispatcher 里通过 Secret Manager 按需读取,并给服务账号绑定 roles/secretmanager.secretAccessor:

gcloud secrets add-iam-policy-binding MY_SECRET \
  --member="serviceAccount:browser-agent-sa@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

第五步:触发 Job

API 触发(服务间调用)时,把 LIBRETTO_WORKFLOW 和 LIBRETTO_INPUT 作为环境变量覆盖传入即可;临时手动跑则用 CLI:

gcloud run jobs execute browser-agent-job \
  --region=us-central1 \
  --update-env-vars LIBRETTO_WORKFLOW=pull-referrals,LIBRETTO_INPUT='{"limit":50}'

AWS 部署教程:把工作流变成 ECS Fargate 任务

AWS 路径与 GCP 几乎一一对应:ECS Fargate 就是 Cloud Run Jobs 的 AWS 版本——注册一个 Task Definition,按需调用,Fargate 启动新容器、跑完即退出。镜像复用 GCP 里那套即可。完整步骤见 docs/alternative-providers/aws.mdx。

Libretto AWS自托管部署:用 ECS Fargate 任务运行浏览器自动化工作流

第一步:确认 AWS 前置条件

  • 带 VPC 的 AWS 账号(默认 VPC 起步即可);
  • 目标区域可用 ECR、ECS、CodeBuild、Secrets Manager;
  • 一个任务执行角色(Task Execution Role)和一个权限收紧的任务角色(Task Role);
  • 本地安装并认证 AWS CLI。

第二步:构建并推送镜像到 ECR

aws ecr create-repository --repository-name browser-agent --region us-east-1

aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  123456789012.dkr.ecr.us-east-1.amazonaws.com

随后 docker build + docker push。接入 CI 时用 CodeBuild 写 buildspec.yml,同时打 :latest 和 :$CODEBUILD_RESOLVED_SOURCE_VERSION 两个标签。

第三步:注册 Task Definition

一份 JSON 描述任务:FARGATE 兼容、awsvpc 网络模式、1024 CPU / 2048 MB 内存、绑定 ECR 镜像,并把 awslogs 日志驱动指向 CloudWatch Logs 的 /ecs/browser-agent 日志组。然后一条命令注册:

aws ecs register-task-definition \
  --cli-input-json file://browser-agent-task.json --region us-east-1

第四步:Secrets Manager 注入凭证

与 GCP 同理:密钥不写进 Task Definition,而是在 dispatcher 内通过 AWS SDK 拉取,并给任务角色只授予具体密钥 ARN 的 secretsmanager:GetSecretValue 权限。

第五步:触发任务与定时调度

从 API 用 RunTaskCommand 发起任务,通过 containerOverrides 传入 LIBRETTO_WORKFLOW / LIBRETTO_INPUT;需要定时跑时,给 Task Definition 挂一条 EventBridge 的 cron 规则即可,无需自己写调度器。

观测与排障:让失败可复现

自托管后,"出问题时怎么办"是最关键的收尾工作。Libretto 每次运行都会在网络日志、动作日志、页面快照等详细资料写入 .libretto/sessions/<name>/ 目录,两个平台的观测要点:

维度 GCP AWS
运行日志 gcloud logs read browser-agent-job CloudWatch Logs(/ecs/browser-agent)
执行历史 gcloud run jobs executions list aws ecs list-tasks --desired-status STOPPED
会话产物 把 .libretto/sessions/<name>/ 上传到 GCS 上传到 S3

官方建议:在每次运行结束(尤其是失败时)把会话目录传上对象存储。这样你就能拿着网络日志、动作日志和快照,在本地完整复现生产故障。排障流程详见 docs/guides/debugging-workflows.mdx。

AWS 还是 GCP?一张表帮你选

对比项 GCP AWS
核心运行时 Cloud Run Jobs ECS Fargate 任务
镜像仓库 Artifact Registry ECR
CI Cloud Build CodeBuild
密钥管理 Secret Manager Secrets Manager
定时触发 Cloud Scheduler EventBridge cron 规则
日志 Cloud Logging CloudWatch Logs
会话产物 GCS S3

简单说:技术栈偏 Google 的选 GCP(声明式 YAML + 一条命令部署,体验更顺滑);已有 AWS 账号、需要和现有 VPC/IAM 体系整合的选 AWS。两条路共用同一个 Docker 镜像和 dispatcher,后期迁移成本极低。

总结

把 Libretto 自托管到 AWS 或 GCP,本质就是四件事:

  1. 用 Playwright 基础镜像打包你的工作流,dispatcher 通过 LIBRETTO_WORKFLOW / LIBRETTO_INPUT 选择要跑的任务;
  2. 在云上注册"一次性任务"(Cloud Run Job 或 Fargate Task);
  3. 密钥运行时从 Secret(s) Manager 注入,绝不打进镜像;
  4. 会话目录上传到 GCS/S3,让生产故障可复现。

按 docs/alternative-providers/gcp.mdx 和 docs/alternative-providers/aws.mdx 的步骤走下来,你就能在一个完全属于自己的基础设施上,稳定运行 Libretto 浏览器自动化工作流。

登录后查看全文
libretto