aws-samples/sample-multi-tenant-openclaw-on-firecracker

# 基于 Firecracker 的多租户 OpenClaw **[English](README.md)** | **[中文](docs/README-CN.md)** 使用 Firecracker microVM 在 AWS 上进行 OpenClaw AI 智能体的多租户隔离部署，也称为 **OpenClaw Pool**。每个租户运行在自己的 microVM 中，拥有独立的 kernel、filesystem 和 network。通过 API 进行管理，支持主机自动扩缩容和空闲资源回收。 ## 功能特性 - **租户管理** — 通过 API 创建/删除/查询租户。每个租户都是运行在隔离的 Firecracker microVM 中的 OpenClaw 实例，拥有独立的 rootfs、数据卷和网络 - **安全隔离** — 基于 Firecracker microVM 的隔离：每个租户拥有独立的 kernel、网络和 filesystem - **自动调度** — 自动选择具有可用资源的主机；当容量不足时自动扩容 - **自动缩容** — 空闲主机在超时后被回收（两轮确认机制以防止误杀） - **健康检查** — 实时 VM 健康监控，自动更新状态 - **Web 控制台** — 基于 Cognito 身份验证的在线管理控制台，提供实时主机/租户状态 - **Rootfs 预构建** — Rootfs + 数据模板通过 S3 分发，在主机初始化时下载 - **Dashboard 访问** — 一键通过 HTTPS 访问每个租户的 OpenClaw Dashboard，无需自定义域名 - **自动备份与恢复** — EventBridge 定时将所有租户的数据卷备份到 S3，支持手动触发、跨租户备份查询以及一键恢复到新租户（支持孤儿备份 — 源租户无需存在） - **AgentCore 集成** — 可选开关；启用后，所有 VM 将自动连接到 AgentCore Gateway（MCP 工具中心）、Memory、Code Interpreter 和 Browser - **共享技能** — 所有租户共享统一的技能集（由 S3 管理，自动同步到所有 VM），但拥有独立的 memory - **配置模板** — 针对不同 LLM 提供商/模型的自定义 OpenClaw 配置模板，可在创建租户时选择 - **默认工具链** — 每个 VM 预装 Python3/uv/git/gh/Node.js/htop/tmux/tree ## 快速开始 **前置条件:** - AWS 账户 + 已配置的 CLI - CDK CLI + Python 3.12+ - uv (Python 包管理器) ``` # 配置 cp config.yml.example config.yml # Edit infrastructure config cp templates/openclaw.json.example templates/openclaw.json # Set your API key, model provider, etc. # 部署基础设施 ./setup.sh ap-northeast-1 lab # 环境变量已保存至 .env.deploy # 构建 rootfs (自动上传至 S3 + 推送至主机) source .env.deploy ./build-rootfs.sh v1.0 # 创建租户 (OpenClaw 实例) source .env.deploy curl -s -X POST "${API_URL}tenants" -H "x-api-key: ${API_KEY}" \ -d '{"name":"my-agent","vcpu":2,"mem_mb":4096}' | jq . # 打开 Console — 管理租户、模板和设置 # 部署后会打印 Console URL ``` ## 管理控制台 基于 Web 的控制台托管在 CloudFront (`/console/`) 上，使用 Cognito 身份验证。 功能: - **租户** — 主机资源概览、创建/删除租户、一键访问 Dashboard - **应用** — 共享技能列表、配置模板管理（创建/编辑/删除） - **备份** — 跨租户备份浏览器，按租户分组、孤儿过滤、一键恢复到新租户 - **设置** — API 连接、AgentCore 状态、系统信息 ### 截图   ## Dashboard 访问 每个租户的 OpenClaw Dashboard 可通过 CloudFront + ALB + Nginx 反向代理访问： ``` https://{cloudfront-domain}/vm/{tenant-id}/ → Tenant Dashboard (WebSocket) ``` HTTPS 由 CloudFront 开箱即用提供 — 无需自定义域名或 ACM 证书。控制台的 "Open Dashboard" 按钮包含 gateway token，可实现一键访问。 流量走向：`Browser → CloudFront:443 → ALB:80 → Host Nginx:80 → VM Gateway:18789` Nginx 配置由 launch-vm.sh / stop-vm.sh 自动管理。 ## 自定义域名 (可选) 将自定义域名 + HTTPS 绑定到 CloudFront。配置位于 `config.yml` 中的 `cloudfront:` 下；你可以直接编辑文件或向 `setup.sh` 传递标志： ``` # 前提条件： # 1. 在 us-east-1 中请求 ACM 证书 (CloudFront 要求) 并完成 DNS 验证 # 2. CNAME 您的域名至 CloudFront 域名 (参见 DashboardUrl 输出) # 单行命令：设置 config.yml + 在一次运行中完成部署 ./setup.sh ap-northeast-1 lab \ --domain claw.example.com \ --cert arn:aws:acm:us-east-1:xxx:certificate/xxx # 或者手动编辑 config.yml，然后不带任何参数运行 setup.sh。 # 要解绑自定义域：使用 --domain "" 并重新运行 setup.sh。 ``` 自定义域名和证书流程通过 CDK 处理（非带外操作），因此后续的 `setup.sh` 运行会保留该绑定。 ## 自动备份与恢复 EventBridge 每日定时将所有运行中的租户数据卷备份到 S3。同时支持手动触发。 **备份流程**：暂停 VM → pigz 压缩 data.ext4 → 恢复 VM → 上传到 S3。即使发生失败，VM 也会自动恢复 (trap cleanup)。 ``` source .env.deploy # 手动备份 (异步，返回 202) curl -s -X POST "${API_URL}tenants/{id}/backup" -H "x-api-key: ${API_KEY}" | jq . # 列出一个租户的备份 curl -s "${API_URL}tenants/{id}/backups" -H "x-api-key: ${API_KEY}" | jq . # 列出所有租户的所有备份 (标记孤立与活跃) curl -s "${API_URL}backups" -H "x-api-key: ${API_KEY}" | jq . # 配置 (config.yml)： # backup_cron: "cron(0 19 * * ? *)" # UTC 19:00 = 北京时间 03:00 # backup_retention_days: 7 # S3 生命周期自动清理 ``` 备份存储在 `s3://{bucket}/backups/{tenant-id}/{timestamp}.gz`。 ### 从备份恢复 恢复操作使用备份的数据卷创建一个**新**租户。源租户无需存在 — 来自已删除租户的孤儿备份完全可以恢复。 ``` # 从 (可能已删除的) 租户的最新备份中恢复 curl -s -X POST "${API_URL}tenants" -H "x-api-key: ${API_KEY}" -d '{ "name": "restored-agent", "vcpu": 2, "mem_mb": 4096, "restore_from": {"tenant_id": "my-agent-ab12"} }' | jq . # 从特定的备份时间戳恢复 curl -s -X POST "${API_URL}tenants" -H "x-api-key: ${API_KEY}" -d '{ "name": "restored-agent", "restore_from": {"tenant_id": "my-agent-ab12", "timestamp": "20260428-125402"} }' | jq . ``` - `restore_from` 与 `vcpu`/`mem_mb`/`config_template` 解耦 — 后者遵循新租户的规格 - 数据卷大小等于备份的实际大小 (不调整大小) - 新租户获取一个全新的 ID；不继承源租户的身份标识 ## 共享技能 所有租户共享统一的技能集 (SKILL.md 文件)，但每个租户拥有独立的 memory。 ``` # 上传 skills 至 S3 (自动同步至所有 VM) aws s3 sync ./my-skills/ s3://${ASSETS_BUCKET}/skills/ --profile $PROFILE # 同步链： # S3 → 主机 /data/shared-skills/ (cron 5分钟) → 所有运行中的 VM # 新 VM 在启动时会将 skills 注入数据卷 ``` ## 自动扩缩容 **扩容** — 创建租户时没有可用主机 → 租户进入 `pending` 状态 → ASG 启动新实例 → 初始化后自动分配 pending 状态的租户 **缩容** — Scaler Lambda 每 5 分钟检查一次： 1. `vm_count=0` 且超过 `idle_timeout_minutes` 的主机 → 标记为 `idle` 2. 下一轮确认仍处于空闲状态且 ASG 实例数 > 最小值 → 终止 3. 如果在此期间有租户被分配到该主机 → 自动恢复为 `active` ## 配置 ### 配置文件 | 文件 | 用途 | |------|---------| | `config.yml` | 基础设施配置 — 从 `config.yml.example` 复制并自定义 | | `templates/openclaw.json` | OpenClaw 应用配置 (模型、API key、提供商) — 从 `.example` 复制 | | `.env.deploy` | 部署环境 (region、API URL/Key、bucket) — 由 setup.sh 自动生成 | ### config.yml | 节 | 键 | 默认值 | 描述 | |---------|-----|---------|-------------| | host | instance_type | m8i.2xlarge | 必须支持 NestedVirtualization (c8i/m8i/r8i) | | host | data_volume_gb | 200 | 用于 rootfs 模板 + VM 磁盘的数据卷 | | host | cpu_overcommit_ratio | 2.0 | CPU 超分 (1.0=无超分, 2.0=分配 2x vCPU) | | host | mem_overcommit_ratio | 1.0 | 内存超分 (需要启用 balloon) | | host | keep_data_volume | true | 实例终止后保留 EBS 数据卷 | | vm | default_vcpu | 2 | 每个租户的默认 vCPU | | vm | default_mem_mb | 4096 | 每个租户的默认内存 (MB) | | vm | rootfs_overlay_mb | 8192 | 每个 VM 可写 rootfs 层上限 (稀疏文件，不预分配) | | vm | data_disk_mb | 8192 | 每个 VM 数据卷 `/home/agent` 上限 (稀疏文件) | | balloon | enabled | false | 用于内存超分的 Firecracker balloon 设备 | | balloon | max_inflate_ratio | 0.4 | VM 声明内存的最大可回收比例 | | balloon | min_guest_available_mb | 512 | 客户机中保留的最低可用内存 | | asg | min_capacity | 1 | 最小主机实例数 | | asg | max_capacity | 5 | 最大主机实例数 | | asg | use_spot | false | Spot 实例 (节省约 60-70%，可能被回收) | | scaler | idle_timeout_minutes | 10 | 空闲主机回收超时时间 | | health_check | interval_minutes | 5 | Lambda 监控间隔 | | agentcore | enabled | false | AgentCore Gateway/Memory/CodeInterpreter/Browser | | console_auth | enabled | false | 控制台的 Cognito 身份验证 | | console_auth | self_sign_up | false | 允许用户自行注册 | 有关所有选项请参阅 `config.yml.example`。更改后重新部署：`./setup.sh ` ### 卸载 ``` ./scripts/destroy.sh # Destroy stack, keep S3 bucket and DynamoDB tables ./scripts/destroy.sh --purge # Full cleanup including S3 data and DynamoDB tables ``` ## 架构 ``` Admin / User │ ├── API Gateway (HTTPS, x-api-key) ──→ Lambda ──→ DynamoDB │ ├── tenants │ └── hosts │ └── ALB (HTTPS) ──→ Host Nginx:80 ──→ VM Gateway:18789 ├── /vm/{tenant-a}/ → 172.16.1.2 └── /vm/{tenant-b}/ → 172.16.2.2 Lambda ── SSM Run Command ──→ EC2 Host ├── microVM 01 (172.16.1.2) ├── microVM 02 (172.16.2.2) └── ... S3: rootfs distribution + data backup + shared skills ASG: auto-scaling hosts EventBridge: health checks + idle reclamation + scheduled backup ```

系统架构


部署架构


## 项目结构 ``` sample-multi-tenant-openclaw-on-firecracker/ ├── deploy/ # CDK project │ ├── app.py # CDK app entry │ ├── stack.py # Infrastructure definition │ ├── lambda/ │ │ ├── api/handler.py # Tenant CRUD + host management │ │ ├── templates/handler.py # Config template CRUD │ │ ├── skills/handler.py # Shared skills list │ │ ├── health_check/handler.py # Scheduled health checks │ │ ├── agentcore_tools/handler.py # AgentCore Gateway Lambda tools │ │ └── scaler/handler.py # Idle host reclamation │ └── userdata/ │ ├── init-host.sh # Host initialization │ ├── host-agent.py # VM health polling + DDB writes + balloon │ ├── launch-vm.sh # microVM launch │ └── stop-vm.sh # microVM stop ├── console/ # Web management console │ ├── index.html # Alpine.js SPA (4 tabs) │ └── style.css ├── tests/ # Test suite (unit + e2e) ├── templates/ # OpenClaw config templates │ └── openclaw.json.example # Example config ├── pyproject.toml # Python project config + dependencies ├── cdk.json # CDK app config + feature flags ├── config.yml # Infrastructure config (single source of truth) ├── setup.sh # One-click deploy + export .env.deploy ├── build-rootfs.sh # Build rootfs + data template, upload to S3 ├── scripts/ │ ├── destroy.sh # Tear down stack │ ├── oc-connect.sh # SSH-style helper to reach a tenant VM │ └── oc-dashboard.sh # Open a tenant's Dashboard URL └── docs/ ``` ## API 参考 所有请求都需要 `x-api-key` 请求头。 | 方法 | 路径 | 描述 | |--------|------|-------------| | GET | /tenants | 列出所有租户 | | POST | /tenants | 创建租户 `{"name":"xx","vcpu":2,"mem_mb":4096}` — 添加 `"restore_from":{"tenant_id":"..."}` 以从备份恢复 | | GET | /tenants/{id} | 获取租户详情 | | DELETE | /tenants/{id} | 删除租户 (`?keep_data=true` 保留数据卷) | | POST | /tenants/{id}/restart | 重启 VM (复用磁盘，速度快) | | POST | /tenants/{id}/stop | 停止 VM (保留磁盘) | | POST | /tenants/{id}/start | 启动已停止的 VM | | POST | /tenants/{id}/pause | 冻结 vCPU (Firecracker 原生，瞬间完成) | | POST | /tenants/{id}/resume | 恢复已暂停的 VM | | POST | /tenants/{id}/reset | 重新安装 rootfs (保留数据卷) | | POST | /tenants/{id}/backup | 手动数据备份 (异步，返回 202) | | GET | /tenants/{id}/backups | 列出单个租户的备份 | | GET | /backups | 列出所有租户的备份 (包含孤儿标志) | | GET | /hosts | 列出所有主机 | | POST | /hosts | 注册主机 (由 UserData 调用) | | POST | /hosts/refresh-rootfs | 将最新 rootfs 推送到所有主机 | | GET | /hosts/rootfs-version | 查询当前 rootfs 版本 (manifest.json) | | DELETE | /hosts/{id} | 注销主机 | ## 网络模型 每个 VM 使用一个独立的 /24 子网，通过 TAP 设备与主机通信： ``` VM1: tap-vm1 host=172.16.1.1/24 guest=172.16.1.2/24 VM2: tap-vm2 host=172.16.2.1/24 guest=172.16.2.2/24 VMn: tap-vmN host=172.16.N.1/24 guest=172.16.N.2/24 ``` - 出站：iptables MASQUERADE → 互联网 - 入站：ALB → Nginx 反向代理 → VM:18789 - VM 间：完全隔离，子网之间无路由 ## Rootfs 管理 构建脚本生成两个镜像：rootfs (OS + 软件) 和数据模板 (/home/agent 预配置内容)。 版本通过 S3 `manifest.json` 进行管理。主机和租户会追踪其 `rootfs_version`。 ``` # 构建并上传 (更新 manifest.json + 刷新主机) ./build-rootfs.sh v1.8 # 手动刷新主机镜像 source .env.deploy curl -s -X POST "${API_URL}hosts/refresh-rootfs" -H "x-api-key: ${API_KEY}" | jq . # 查询当前版本 curl -s "${API_URL}hosts/rootfs-version" -H "x-api-key: ${API_KEY}" | jq . # 新 VM 使用最新版本；现有 VM 需要重置才能更新 ``` ## 安全 更多信息请参见 [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications)。 ## 许可证 本库基于 MIT-0 许可证授权。请参阅 [LICENSE](LICENSE) 文件。

标签：AgentCore 集成, AI Agent 平台, AI 智能体, Auto-Scaling, AWS, Cognito 身份验证, Dashboard, DPI, EC2, EventBridge, Firecracker, IaC, LLM, MCP 工具中心, MicroVM, Orchestration, S3 存储, Unmanaged PE, Web 管理控制台, 事件驱动, 代码解释器, 大模型, 安全隔离, 微型虚拟机, 技能共享, 数据备份与恢复, 根文件系统预构建, 浏览器工具, 漏洞探索, 独立内核, 独立网络, 租户隔离, 自动化运维, 自动扩缩容, 虚拟化, 资源调度, 逆向工具, 配置模板