Libretto自托管完整指南:把浏览器自动化工作流部署到AWS或GCP
Libretto自托管完整指南:把浏览器自动化工作流部署到AWS或GCP
Libretto 是一款为构建可靠浏览器自动化(browser automation)而生的 AI 工具包:它给你的编码 Agent 一个真实浏览器,支持页面检查、网络抓包、录制回放与故障调试。除了官方托管平台 Libretto Cloud Hosting,你还可以把 Libretto 自托管(self-hosting)到 AWS 或 GCP——本文是一条面向新手、从零到上线的完整自建部署教程,带你把 Libretto 工作流跑在自己的云账号里。
为什么选择自托管 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 的核心思路:一个镜像跑所有工作流
无论 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。
第一步:确认 GCP 前置条件
- 一个已开通计费的 GCP 项目;
- 启用 Artifact Registry、Cloud Run、Cloud Build、Secret Manager 四个 API;
- 一个权限收紧的服务账号(Service Account),只授予它读密钥、写 GCS 等必要权限;
- 本地安装并登录
gcloudCLI。
第二步:写 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。
第一步:确认 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,本质就是四件事:
- 用 Playwright 基础镜像打包你的工作流,dispatcher 通过
LIBRETTO_WORKFLOW/LIBRETTO_INPUT选择要跑的任务; - 在云上注册"一次性任务"(Cloud Run Job 或 Fargate Task);
- 密钥运行时从 Secret(s) Manager 注入,绝不打进镜像;
- 会话目录上传到 GCS/S3,让生产故障可复现。
按 docs/alternative-providers/gcp.mdx 和 docs/alternative-providers/aws.mdx 的步骤走下来,你就能在一个完全属于自己的基础设施上,稳定运行 Libretto 浏览器自动化工作流。



