Rust Codecov Linux License Changelog

```text ███████ ██ ██████ ███████ ██████ ██████ █████ ██████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ █████ ██ ██████ █████ ██ ██████ ███████ ██████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███████ ██████ ██ ██ ██ ██ ██████ ```

在自有服务器上运行应用和 AI 智能体的开源 microVM 平台

English · 한국어 · 日本語 · 中文 · Bahasa Indonesia

![Firecrab 演示](assets/dashboard/firecrab-demo.gif) ## 概述
目标 在自有服务器上创建和管理 Firecracker microVM。 部署应用镜像，管理更新和回滚。 在隔离的 MicroVM 环境中运行 AI 智能体。 通过浏览器仪表盘、CLI 或 REST API 管理平台。
主要功能 - **VM 管理** — 创建、启动、停止、删除 microVM，以及浏览器串行控制台。 - **[应用部署](public-docs/guides/microservices.md)** — 部署 OCI 镜像、管理副本和健康检查，以及[更新或回滚](public-docs/guides/deploy.md)运行中的应用。 - **[AI 智能体](public-docs/guides/ai-sandbox.md)** — 在隔离的 MicroVM 工作区中运行编程智能体和项目任务。 - **镜像与磁盘** — M2Image 模板、OCI 镜像导入和 MicroStorage 磁盘位置配置。 - **网络** — MicroNetwork 子网与每个 VM 的互联网访问或隔离策略。 - **主机平台** — Linux 直接运行；macOS 和 Windows 使用 microManager（Windows 为 Preview）。
平台比较 | 核心项 | **Firecrab** | [KVM + libvirt](https://libvirt.org/) | [OpenStack](https://docs.openstack.org/nova/latest/) | | --- | --- | --- | --- | | 目标 | 单主机 microVM 管理 | 通用 VM 管理 | 私有云 | | 虚拟化 | Firecracker + KVM | QEMU/KVM | 通常为 QEMU/KVM | | 管理 | 仪表盘、CLI、REST | libvirt API、CLI；GUI 单独配置 | Horizon、CLI、REST | | 部署 | 单台主机 | 按主机管理 | 控制器与计算服务 |
## 架构 [详细架构](public-docs/reference/architecture.md)：各操作系统的 microManager 层、VM 启动、镜像与内核供应、来宾功能及 CLI 更新流程。 ### Firecrab 概览 ![Firecrab 概览](assets/architecture/firecrab-at-a-glance.en.svg) 1. 通过浏览器或 CLI 操作，选择 M2Image、MicroNetwork 与 MicroStorage 来创建 MicroVM。 2. Firecrab 验证 M2Image、准备 MicroNetwork，并在 MicroStorage 中创建 VM 专用磁盘。 3. 每台 MicroVM 启动一个 Firecracker 进程，各自使用自己的内核启动。 4. 来宾报告网络就绪后，MicroVM 进入 running 状态。 ### 各平台运行方式 ![各平台运行方式](assets/architecture/firecrab-runs-anywhere.en.svg) Linux 只需要 `install.sh`。macOS 与 Windows 使用 `firecrab service install` 创建管理用 Debian VM 来运行同样的 Firecrab，均通过 `localhost:5523` 打开相同的仪表盘。 macOS 需要 Apple silicon M3 或更新型号，已在 Apple M5 上验证。Windows 因 WSL2 尚无法启动 microVM 而标记为 Preview。 Linux、Apple、Debian 标志来自 simple-icons（CC0），齿轮图标来自 Lucide（ISC）。所有标志和商标均属于其各自所有者。 ## 安装
在 Linux、macOS 或 Windows 上安装 ### Linux 需要 Linux x86_64 或 ARM64、可用的 `/dev/kvm`、网络，以及有 `sudo` 权限的普通用户。以该用户执行安装器，**不要在前面加 `sudo`**。如果 KVM 不可用，请先启用硬件虚拟化或嵌套虚拟化。 ```sh curl -fsSL https://github.com/SteelCrab/firecrab/releases/latest/download/install.sh | bash ``` 诊断与卸载选项见[安装指南](public-docs/getting-started/installation.md)。如果只在 Linux 安装远程 CLI，请使用下面包含校验和验证的 `install-cli.sh` 流程；它自动选择 GNU/musl，默认安装到 `~/.local/bin`。 ### macOS 需要 Apple silicon、macOS 15 以上和运行时支持嵌套虚拟化的主机（M3 以上；完整验证为 M5/macOS 26.6.2）。先验证安装器校验和，再安装 CLI 与 helper。 ```sh curl -fLO https://github.com/SteelCrab/firecrab/releases/latest/download/install-cli.sh curl -fLO https://github.com/SteelCrab/firecrab/releases/latest/download/SHA256SUMS grep ' install-cli.sh$' SHA256SUMS > install-cli.sh.sha256 if command -v sha256sum >/dev/null; then sha256sum -c install-cli.sh.sha256 else shasum -a 256 -c install-cli.sh.sha256 fi && sh install-cli.sh ``` 然后检查主机能力并安装 Debian 管理环境： ```sh firecrab service doctor firecrab service install ``` 单独安装 CLI 不会创建管理 VM。microManager 使用 `Virtualization.framework`、独立的持久数据磁盘和常驻 launchd 服务。详见 [macOS 指南](public-docs/getting-started/macos.md)。 ### Windows 需要 x86_64 或 ARM64 Windows、Microsoft Store WSL2 和嵌套 KVM。在普通 PowerShell 中下载并验证 CLI 安装器： ```powershell Invoke-WebRequest https://github.com/SteelCrab/firecrab/releases/latest/download/install-cli.ps1 -OutFile install-cli.ps1 Invoke-WebRequest https://github.com/SteelCrab/firecrab/releases/latest/download/SHA256SUMS -OutFile SHA256SUMS $expected = ((Get-Content SHA256SUMS | Where-Object { $_ -match ' install-cli\.ps1$' }) -split '\s+')[0] if ((Get-FileHash install-cli.ps1 -Algorithm SHA256).Hash -ne $expected) { throw 'installer checksum mismatch' } & ./install-cli.ps1 ``` 如果 `firecrab` 尚未加入 `PATH`，请打开新的 PowerShell，然后检查能力并安装。ARM64 安装尚未完成端到端验证。详见 [Windows 指南](public-docs/getting-started/windows.md)。 ```powershell firecrab service doctor firecrab service install ``` **Windows：** 安装时选择最新稳定版 Firecrab 来宾。使用 `firecrab update --apply` 更新现有托管来宾。需要嵌套 KVM。请参阅 [Windows 指南](public-docs/getting-started/windows.md)。
## 运行
在 Linux、macOS 或 Windows 上启动与停止 ### Linux 安装器会启动两个 systemd 服务。之后使用以下命令启动、查看或停止： ```sh sudo systemctl start firecrab-helper firecrab-api systemctl status firecrab-helper firecrab-api sudo systemctl stop firecrab-api firecrab-helper ``` ### macOS microManager 启动常驻管理 VM 和 localhost API 隧道： ```sh firecrab service start firecrab service status firecrab service debug --logs --tail 100 firecrab service stop ``` ### Windows microManager 通过用户级计划任务保持 WSL2 管理发行版运行： ```powershell firecrab service start firecrab service status firecrab service debug --logs --tail 100 firecrab service stop ``` **Windows：** 安装时选择最新稳定版 Firecrab 来宾。使用 `firecrab update --apply` 更新现有托管来宾。需要嵌套 KVM。请参阅 [Windows 指南](public-docs/getting-started/windows.md)。 状态正常时打开 `http://127.0.0.1:5523/`。创建 MicroNetwork，选择已安装镜像，创建并启动 VM，待状态为 `running` 后打开终端。远程主机请配置 [CLI 主机配置](public-docs/reference/cli.md#host-profiles)。
## 从源码运行
Linux API 与仪表盘 / macOS 与 Windows CLI 在仓库根目录使用指定的 [Rust 工具链](rust-toolchain.toml)、Node.js 22 以上和 npm。实际运行 VM 还需要 Linux KVM 及[主机前置条件](public-docs/getting-started/installation.md)。 ### Linux 使用三个终端。helper 以特权运行，API 以普通用户运行。本地数据路径以仓库根目录为基准。 ```sh # 1 cargo build -p firecrab-helper --locked sudo -u root -g "$(id -gn)" FIRECRAB_NET_HELPER_ALLOWED_UID="$(id -u)" \ ./target/debug/firecrab-helper # 2 cargo run -p firecrab-api --locked # 3 npm ci --prefix firecrab-frontend FIRECRAB_DEV_API_PORT=5523 npm run dev --prefix firecrab-frontend # http://localhost:8080/ ``` 让 API 提供已构建的仪表盘时，先停止开发 API，再运行： ```sh npm run build --prefix firecrab-frontend FIRECRAB_STATIC_ROOT="$PWD/firecrab-frontend/dist" cargo run -p firecrab-api --locked # http://127.0.0.1:5523/ ``` ### macOS 构建当前源码的 CLI 和已签名原生 helper，再安装管理服务；已安装时使用 `service start`。 ```sh cargo build -p firecrab-cli --locked scripts/build-micromanager-macos.sh target/debug/firecrab-micromanager-macos ./target/debug/firecrab service install ./target/debug/firecrab service status ``` ### Windows 在 PowerShell 中构建当前源码的 CLI，再安装管理服务；已安装时使用 `service start`。 ```powershell cargo build -p firecrab-cli --locked .\target\debug\firecrab.exe service install .\target\debug\firecrab.exe service status ``` macOS 与 Windows 上的这些命令运行源码构建的 CLI/helper 和已安装的来宾 API，**不会**在 Debian 内重新构建修改后的 `firecrab-api` 源码。完整 API/net-helper 运行时开发请在 Linux 进行；管理服务开发详见上述平台指南。
## 测试
检查、覆盖率与浏览器 E2E 在仓库根目录执行基本检查： ```sh cargo fmt --all -- --check cargo clippy --workspace --all-targets -- -D warnings cargo test --workspace --locked npm ci --prefix firecrab-frontend npm run lint --prefix firecrab-frontend npm run build --prefix firecrab-frontend python3 scripts/check-doc-links.py python3 scripts/check-changelog.py ``` 可选本地覆盖率（需要 `cargo-llvm-cov`）： ```sh cargo llvm-cov --workspace --locked --lcov --output-path lcov.info ``` 跳过来宾启动的浏览器 E2E： ```sh npm ci --prefix firecrab-e2e npm run install-browsers --prefix firecrab-e2e FIRECRAB_E2E_SKIP_GUEST_BOOT=1 npm test --prefix firecrab-e2e ``` PowerShell 中在 `npm test --prefix firecrab-e2e` 前设置 `$env:FIRECRAB_E2E_SKIP_GUEST_BOOT="1"`。这会跳过来宾启动，不验证 KVM 或 nginx HTTP。实际来宾运行及全部安装检查详见 [TEST.md](public-docs/development/testing.md)、[韩语检查清单](public-docs/development/testing.ko.md)和 [E2E 指南](firecrab-e2e/README.md)。
## 使用方法：nginx
导入 nginx → 创建 microVM → HTTP 访问 使用 API 与 CLI 正在运行的受支持 Linux 主机或 macOS microManager。以下命令适用于 Linux/macOS 的 POSIX shell。仪表盘中也可按 Images → OCI Import、Networks、MicroVM 完成同样操作。 1. 检查并导入镜像。重复查询状态，直到任务成功且 `nginx-1.27` 已安装： ```sh firecrab image inspect nginx:1.27 firecrab image import nginx:1.27 firecrab image import-status nginx-1.27 ``` 2. 选择不重叠的子网创建网络。将下面的 `NETWORK_ID` 替换为第一条命令返回的 UUID： ```sh firecrab network create --name nginx-net --subnet-cidr 172.31.20.0/24 firecrab vm create --name nginx-demo --template nginx-1.27 --network NETWORK_ID ``` 3. 将 `VM_ID` 替换为创建 VM 返回的 UUID，启动后等待列表中的状态变为 `running`： ```sh firecrab vm start VM_ID firecrab vm list ``` 4. 通过 REST API 配置 TCP 主机端口 `8081` → 来宾端口 `80`，再检查 nginx 响应。此 PUT 会替换 VM 的整个端口转发列表；请在请求中保留其他需要的规则。 ```sh curl -fsS -X PUT http://127.0.0.1:5523/api/vms/VM_ID/port-forwards \ -H 'Content-Type: application/json' \ -d '{"portForwards":[{"hostPort":8081,"guestPort":80,"protocol":"tcp"}]}' ``` Linux 上从另一台机器访问 `http://FIRECRAB_HOST_IP:8081/`；DNAT 不提供主机自身的 loopback 访问。macOS 使用 TCP 转发的 `http://127.0.0.1:8081/`。远程访问时还需在主机与路由器防火墙中允许 8081 端口。 ```sh curl -I http://FIRECRAB_HOST_IP:8081/ # macOS curl -I http://127.0.0.1:8081/ ``` OCI import 创建以 `/etc/firecrab/busybox` 为 PID 1 的可启动 rootfs，并将 nginx 入口点作为服务运行。`EXPOSE 80` 不会自动创建主机端口转发。详见 [OCI 镜像](public-docs/guides/oci.md)与[网络指南](public-docs/guides/networking.md)。 停止示例 VM： ```sh firecrab vm stop VM_ID ```
仪表盘界面说明 ![firecrab M2 仪表盘演示](assets/dashboard/firecrab-m2.gif) 仪表盘通过左侧导航将日常操作分为 **MicroVM**、每台 VM 的 **终端**、**网络** 和 **镜像**。 ### MicroVM 在表单中选择名称、镜像、CPU、RAM、磁盘、存储位置、MicroNetwork 和出站策略后创建 VM。下方列表 每三秒刷新状态、镜像、资源和 ID；运行中的 VM 会显示 **终端** 和 **停止** 操作。选择 VM 名称可查看 启动进度、日志、网络、存储及其他详情。 ![MicroVM 创建与列表](assets/dashboard/microvm.png) ### 终端 运行中的 VM 可通过 **终端** 在独立标签页打开浏览器串口控制台。它实时显示启动输出与登录提示并接受 命令。工具栏可调整显示设置、复制或保存控制台日志，以及切换到仅终端视图；下方各面板显示 VM 的 常规信息、规格、网络和存储。 ![VM 浏览器串口终端](assets/dashboard/terminal.png) ### 网络 可使用名称、子网 CIDR 和互联网策略创建 **MicroNetwork**。列表显示每个网络的网关、互联网状态和 ID；可通过 **阻止互联网/启用互联网** 改变整个网络经 NAT 的出站访问，或删除该网络。选择一行可查看 子网地址使用情况、bridge/TAP、NAT、防火墙和成员 VM 的详情。 ![MicroNetwork 创建与列表](assets/dashboard/networks.png) ### 镜像 **M2Image** 列表显示每个镜像的大小及 `软件包已就绪`、`已安装` 等状态。选择一行可查看其别名、 版本、最小磁盘、rootfs 大小、状态以及正在使用该镜像的 VM。`…` 菜单会根据状态提供软件包安装、 引导或删除操作。只有已安装的镜像可以用于创建 VM。 同一页面还可以检查 OCI 引用（`nginx:1.27`）是否匹配本机架构，并将其导入为模板。 导入在后台进行，页面会显示进度、错误以及注册后的别名。 ![M2Image 列表](assets/dashboard/images.png) 请求格式、生命周期语义和错误 envelope 见 [API 指南](public-docs/reference/api.md)。镜像包与浏览器引导 流程见[镜像指南](public-docs/guides/images.md)。OCI 检查与导入见 [OCI 镜像指南](public-docs/guides/oci.md)。
## 文档与贡献 默认文档语言为英语；顶部链接提供韩语、日语、中文与印度尼西亚语 README。仪表盘支持英语与韩语。 - [public-docs/](public-docs/README.md): 安装、API、运维与故障排查 - [CONTRIBUTING.md](CONTRIBUTING.md): 维护者说明、开发环境与 PR 检查 采用 [Apache License, Version 2.0](LICENSE) 许可证。