Docker 镜像内置 microVM:构建时装好运行时、预拉沙箱镜像;deploy.sh 检测到 KVM 先试启动一台,起得来才交给容器;没有 KVM 时服务端不再选 microVM

- microvm_sandbox:Linux 上 available() 要求 /dev/kvm 存在且可读写,不可用时给出具体原因(没装、运行时没装、没有 KVM、没有权限)
- 新增 app.sandbox.selftest:真起一台 VM 执行一行代码,部署脚本用它判断
- Dockerfile:WITH_MICROVM(默认 1)构建期 install 并 pull python:3.12-slim,自带的 msb、libkrunfw 改为链接,镜像约多 150 MB
- deploy.sh:ENABLE_MICROVM=auto|0|1,有 KVM 时用临时容器试启动,成功才加 --device /dev/kvm 和所属组;部署完和 status 打印实际用的沙箱
- package-docker.sh:--no-microvm;部署说明、配置模板、README 同步
This commit is contained in:
ThearchyHelios
2026-09-30 11:17:19 +08:00
parent fec356089c
commit 78f24dfe3f
9 changed files with 440 additions and 51 deletions
+40 -12
View File
@@ -21,7 +21,8 @@
- **架构要一致**:这个包是 `linux/__AGENTLAB_ARCH__`。在目标机上运行 `uname -m`:
`aarch64` 对应 arm64(ARM 单板机要装 64 位系统),`x86_64` 对应 amd64。不一致的镜像跑不起来,
deploy.sh 会在导入前就报出来;
- 磁盘:镜像导入后约 0.6~0.8 GB(看 Docker 用的存储方式),另留数据目录的空间;
- 磁盘:镜像导入后约 0.8~1 GB(看 Docker 用的存储方式),另留数据目录的空间;
- 可选:宿主机支持 KVM(有 `/dev/kvm`)时,代码会在 microVM 里执行,隔离最强,见下面的「代码沙箱」;
- 当前用户能用 docker(在 `docker` 组里),或者用 `sudo` 运行 deploy.sh。
## 三步部署
@@ -90,7 +91,7 @@ cp ../agentlab-<旧版本>-linux-__AGENTLAB_ARCH__/agentlab.env . # 沿用原
## 查看状态和日志
```bash
./deploy.sh status # 容器状态、健康检查、数据目录、访问地址
./deploy.sh status # 容器状态、健康检查、数据目录、代码沙箱、访问地址
./deploy.sh logs # 最后 200 行
./deploy.sh logs -f # 持续跟随,Ctrl-C 退出
./deploy.sh logs --tail 1000
@@ -123,26 +124,43 @@ cp ../agentlab-<旧版本>-linux-__AGENTLAB_ARCH__/agentlab.env . # 沿用原
## 代码沙箱
工作流里的代码节点、界面上的沙箱都在服务端执行代码。容器里能用哪种隔离,实测结果如下:
工作流里的代码节点、界面上的沙箱都在服务端执行代码。AgentLab 按下表从上往下,挑第一种能用的:
| 容器权限 | 实际使用的沙箱 | 隔离效果 |
| 沙箱 | 条件 | 隔离效果 |
| --- | --- | --- |
| 默认(`ENABLE_BWRAP=0`) | local:容器里的普通子进程 | 隔离边界只有容器本身。代码伤不到宿主机,但和 AgentLab 同一个容器、同一个用户,读得到数据目录里的数据库和加密密钥、读得到传进容器的 API Key、能联网 |
| `ENABLE_BWRAP=1` | bubblewrap | 代码看不到数据目录、看不到别的进程,默认断网 |
| microVM | 宿主机有 KVM(默认 `ENABLE_MICROVM=auto`,自动检测) | 每段代码在独立内核的虚拟机里执行:看不到数据目录、密钥和别的进程,内存上限真正生效 |
| bubblewrap | `ENABLE_BWRAP=1` | 共享内核的隔离环境:看不到数据目录和别的进程,默认断网 |
| local | 前两种都用不了 | 容器里的普通子进程。隔离边界只有容器本身:代码伤不到宿主机,但和 AgentLab 同一个容器、同一个用户,读得到数据目录里的数据库和加密密钥、读得到传进容器的 API Key、能联网 |
默认权限下 bubblewrap 无法创建命名空间(Docker 默认的系统调用过滤不允许),AgentLab 会自动退回 local,
「设置 → 运行环境」里的「选择原因」会写明。只运行你信得过的工作流;完全不需要执行代码的话,
在 `agentlab.env` 里设 `AGENTLAB_SANDBOX_BACKEND=off`。
实际用的是哪一种,deploy.sh 部署完会打印「代码沙箱:……」,`./deploy.sh status` 和界面「设置 → 运行环境」里
也看得到。只运行你信得过的工作流;完全不需要执行代码的话,在 `agentlab.env` 里设 `AGENTLAB_SANDBOX_BACKEND=off`。
要用 bubblewrap:把 `agentlab.env` 里的 `ENABLE_BWRAP` 改成 `1`,运行 `./deploy.sh install`。
### microVM
要宿主机是支持 KVM 的 Linux:物理机、树莓派 5 这类 64 位 ARM 单板机、开了嵌套虚拟化的云主机。
Mac、Windows 上的 Docker Desktop 和多数云主机没有 KVM,用不了。检查:`ls -l /dev/kvm` 能看到这个设备就行。
运行时和沙箱镜像(`python:3.12-slim`)已经打在镜像里,部署时不用联网。`./deploy.sh install` 会这样处理:
1. 本机没有 `/dev/kvm`:不启用,照常部署;
2. 有 `/dev/kvm`:先用一个临时容器真起一台 microVM、执行一行代码。起得来,就给正式容器加上
`--device /dev/kvm` 和 `/dev/kvm` 所属的组(容器里的服务以 uid 10001 运行,要靠这个组读写它);
起不来,打印原因,照常部署但不启用。
`agentlab.env` 里的 `ENABLE_MICROVM`:`auto` 按上面处理(默认),`1` 起不来就报错停下,`0` 不启用。
已知缺口:代码节点关掉网络时,HTTP/HTTPS 和域名解析都会断,但 UDP/53 仍然放行,存在经 DNS 外泄数据的可能。
### bubblewrap
把 `agentlab.env` 里的 `ENABLE_BWRAP` 改成 `1`,运行 `./deploy.sh install`。microVM 已经启用时用不上它。
Docker 默认权限下 bubblewrap 无法创建命名空间(默认的系统调用过滤不允许),所以
deploy.sh 会给容器加 `--security-opt seccomp=unconfined`、`--security-opt systempaths=unconfined`、
`--security-opt apparmor=unconfined`。代价是整个容器少了系统调用过滤和对 `/proc`、`/sys` 部分路径的遮蔽,
内核暴露给容器的面变大(AgentLab 自己仍以非 root 运行)。这组权限在 Docker Desktop(arm64)上实测生效。
Ubuntu 24.04 默认还限制非特权 user namespace:开了之后「设置 → 运行环境」里仍显示 local 的话,
要在宿主机上执行 `sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0`,这会放宽整台机器的限制,自行权衡。
microVM(独立内核)需要 `/dev/kvm` 和额外下载的运行时与镜像,离线包默认不支持。
## 常见问题
**端口被占用。** deploy.sh 报「端口 8000 已被别的程序占用」,或 docker 报 `port is already allocated` /
@@ -165,3 +183,13 @@ microVM(独立内核)需要 `/dev/kvm` 和额外下载的运行时与镜像
- `agentlab.env` 里的值带了引号、或者注释写在了值后面:去掉。
**`sha256sum -c` 报 image.tar FAILED。** 包在拷贝中损坏了,重新拷一份。
**有 `/dev/kvm`,microVM 却没启用。** deploy.sh 会打印试启动失败的原因。常见的几种:
- 权限类报错(`Permission denied`、`Operation not permitted`):先确认 `ls -l /dev/kvm` 的属组是 `kvm` 之类的普通组。
仍然不行的话,可能是 Docker 默认的系统调用过滤拦住了,可以试 `ENABLE_BWRAP=1`(它会放开这项过滤)再 `./deploy.sh install`;
- 云主机上报虚拟化相关的错:机型不支持或没打开嵌套虚拟化,这种情况用不了 microVM;
- 想让它起不来就停下、而不是悄悄不用:把 `ENABLE_MICROVM` 设成 `1`。
**启用 microVM 后,机器重启时容器没起来。** 容器启动时要用到 `/dev/kvm`,开机时 kvm 模块没加载,
Docker 就启动不了这个容器。`ls -l /dev/kvm` 确认设备在,再运行 `./deploy.sh install`,它会重新检测。
+23 -11
View File
@@ -5,7 +5,7 @@
# - 值不要加引号,引号会原样变成值的一部分;
# - 注释只能单独成行,不能写在值后面。
#
# 前四项(HOST_PORT、BIND_ADDR、DATA_DIR、CONTAINER_NAME)和 ENABLE_BWRAP 是给 deploy.sh 用的;
# 前四项(HOST_PORT、BIND_ADDR、DATA_DIR、CONTAINER_NAME)和 ENABLE_MICROVM、ENABLE_BWRAP 是给 deploy.sh 用的;
# 其余的变量原样传进容器,给 AgentLab 自己用。
# ---- 访问 ----
@@ -46,16 +46,30 @@ CONTAINER_NAME=agentlab
# NO_PROXY=localhost,127.0.0.1
# ---- 代码沙箱 ----
# auto:按 microvm → bubblewrap → local 挑第一个能用的。可选值 auto | bubblewrap | local | off
#
# 容器里实测(Docker 默认权限):bubblewrap 无法创建命名空间,auto 自动退回 local,也就是在容器里
# 起一个普通子进程执行代码。这时隔离的边界只有容器本身:代码伤不到宿主机,但和 AgentLab 在同一个容器、
# 同一个用户下,读得到数据目录里的数据库和加密密钥、读得到传进容器的 API Key、能联网。
# 只运行你信得过的工作流;不需要执行代码就设成 off。
# auto:按 microvm → bubblewrap → local 挑第一个能用的。可选值 auto | microvm | bubblewrap | local | off
# microvm 每段代码在独立内核的虚拟机里执行,看不到容器里的数据目录、密钥和别的进程,内存上限真正生效。
# 隔离最强,但要宿主机有 KVM,见下面的 ENABLE_MICROVM。
# bubblewrap 共享内核的隔离环境:看不到数据目录和别的进程,默认断网。要额外的容器权限,见下面的 ENABLE_BWRAP。
# local 前两种都用不了时的退路:在容器里起一个普通子进程执行代码。隔离的边界只有容器本身,
# 代码伤不到宿主机,但和 AgentLab 在同一个容器、同一个用户下,读得到数据目录里的数据库和
# 加密密钥、读得到传进容器的 API Key、能联网。只运行你信得过的工作流。
# off 不执行代码。
# 实际用的是哪一种,deploy.sh 部署完会打印出来,./deploy.sh status 和界面「设置 → 运行环境」里也看得到。
AGENTLAB_SANDBOX_BACKEND=auto
#
# 想让代码在 bubblewrap 里执行(看不到数据目录、看不到别的进程、默认断网),把下面改成 1,
# 然后运行 ./deploy.sh install。deploy.sh 会给容器加三项权限:
# microVM 要宿主机是支持 KVM 的 Linux:物理机、树莓派 5 这类 64 位 ARM 单板机、开了嵌套虚拟化的云主机。
# Mac、Windows 上的 Docker Desktop 和多数云主机没有 KVM,用不了。
# auto 本机有 /dev/kvm 时,先用一个临时容器试着启动一台 microVM,起得来才启用;起不来照常部署,
# 只是不用 microVM(默认)
# 1 必须启用,启动不了就报错停下
# 0 不启用
# 启用后 deploy.sh 给容器加上 --device /dev/kvm,以及 /dev/kvm 所属的组(容器里的服务以 uid 10001 运行,
# 要靠这个组读写 /dev/kvm)。运行时和沙箱镜像(python:3.12-slim)已经打在镜像里,部署时不用联网。
# 已知缺口:代码节点关掉网络时,HTTP/HTTPS 和域名解析都会断,但 UDP/53 仍然放行,存在经 DNS 外泄数据的可能。
ENABLE_MICROVM=auto
#
# 想让代码在 bubblewrap 里执行,把下面改成 1,然后运行 ./deploy.sh install。microVM 已经启用时用不上它。
# 容器里实测(Docker 默认权限):bubblewrap 无法创建命名空间,所以 deploy.sh 要给容器加三项权限:
# --security-opt seccomp=unconfined 放开 Docker 默认的系统调用过滤,才能创建命名空间
# --security-opt systempaths=unconfined 取消对 /proc、/sys 部分路径的遮蔽,才能在沙箱里挂载 /proc
# --security-opt apparmor=unconfined Ubuntu 上 Docker 默认的 AppArmor 配置不允许沙箱里的挂载
@@ -65,5 +79,3 @@ AGENTLAB_SANDBOX_BACKEND=auto
# sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0
# 这一步会放宽整台机器的限制,自行权衡。
ENABLE_BWRAP=0
#
# microVM(独立内核)需要 /dev/kvm 和额外下载的运行时与镜像,离线包默认不支持。
+83 -2
View File
@@ -21,10 +21,11 @@ usage() {
install 部署(默认):导入镜像、创建数据目录、启动容器,等健康检查通过后打印访问地址。
已经有同名容器的,先停掉再换成新的,数据保留。改了 agentlab.env 也用它让配置生效。
本机有 KVM 时会先试着启动一台 microVM,起得来才让代码在 microVM 里执行(见 agentlab.env)。
upgrade 用这个包里的镜像替换正在用的容器,数据保留。旧镜像留着,方便回退。
start | stop | restart
启动 / 停止 / 重启容器。
status 查看容器状态、健康检查、数据目录和访问地址。
status 查看容器状态、健康检查、数据目录、代码沙箱和访问地址。
logs [-f] [--tail N]
查看日志(默认最后 200 行),-f 持续跟随。
uninstall [--purge-image]
@@ -104,6 +105,7 @@ BIND_ADDR="0.0.0.0"
DATA_DIR="./data"
CONTAINER_NAME="agentlab"
ENABLE_BWRAP="0"
ENABLE_MICROVM="auto"
read_env() {
[ -f "$ENV_FILE" ] || die "找不到 ${ENV_FILE},它应该和 deploy.sh 在同一个目录"
@@ -118,7 +120,7 @@ read_env() {
key="$(trim "${line%%=*}")"
val="${line#*=}"
case "$key" in
HOST_PORT|BIND_ADDR|DATA_DIR|CONTAINER_NAME|ENABLE_BWRAP)
HOST_PORT|BIND_ADDR|DATA_DIR|CONTAINER_NAME|ENABLE_BWRAP|ENABLE_MICROVM)
printf -v "$key" '%s' "$(unquote "$(trim "$val")")" ;;
AGENTLAB_DATA_DIR|AGENTLAB_WEB_DIST|AGENTLAB_PORT|AGENTLAB_HOST)
die "agentlab.env 第 $n 行:不要设 ${key}。容器里的路径和端口是固定的,改宿主机这边用 DATA_DIR、HOST_PORT、BIND_ADDR" ;;
@@ -137,6 +139,7 @@ read_env() {
''|[!a-zA-Z0-9]*|*[!a-zA-Z0-9_.-]*) die "CONTAINER_NAME 只能用字母、数字和 _ . -,并以字母或数字开头:$CONTAINER_NAME" ;;
esac
case "$ENABLE_BWRAP" in 0|1) ;; *) die "ENABLE_BWRAP 只能是 0 或 1:$ENABLE_BWRAP" ;; esac
case "$ENABLE_MICROVM" in auto|0|1) ;; *) die "ENABLE_MICROVM 只能是 auto、0 或 1:$ENABLE_MICROVM" ;; esac
# 相对路径以 deploy.sh 所在的目录为准,和从哪里运行无关
# 下面比较的就是字面上的 ~,不需要展开
@@ -273,6 +276,79 @@ fix_data_owner() {
|| die "无法修改 $DATA_ABS 的属主"
}
# ---------------------------------------------------------------------------
# microVM:本机有 KVM、镜像里带了运行时,就先用一个临时容器真起一台 VM,起得来才把 /dev/kvm
# 交给正式容器。只看设备在不在不够:系统调用过滤、嵌套虚拟化没开,都可能让 VM 起不来。
# 起不来还把设备交出去,服务端会选中 microVM,之后每次执行代码都失败
# ---------------------------------------------------------------------------
KVM_OPTS=()
MICROVM_OPTS=()
kvm_opts() {
# 容器里的服务以 uid 10001 运行,要靠 /dev/kvm 所属的组才能读写它;其他用户本来就能读写的不用加组
local perm gid
perm="$(ls -lL /dev/kvm | cut -c1-10)"
gid="$(ls -nL /dev/kvm | awk '{print $4}')"
KVM_OPTS=(--device /dev/kvm)
case "$perm" in
???????rw*) ;;
*) KVM_OPTS+=(--group-add "$gid") ;;
esac
}
microvm_selftest() {
# 和正式容器一样的配置和权限,只是不挂数据目录、不开端口。只取最后一行:结论,或者报错的最后一句
local extra=()
[ "$ENABLE_BWRAP" = 1 ] && extra=("${BWRAP_OPTS[@]}")
docker run --rm \
--env-file "$ENV_FILE" \
-e AGENTLAB_MICROVM_BOOT_TIMEOUT=120 \
"${KVM_OPTS[@]}" ${extra[@]+"${extra[@]}"} \
--entrypoint python "$IMAGE" -m app.sandbox.selftest 2>&1 | tail -n 1
}
decide_microvm() {
MICROVM_OPTS=()
[ "$ENABLE_MICROVM" != 0 ] || return 0
local baked out
baked="$(docker image inspect -f '{{index .Config.Labels "agentlab.microvm"}}' "$IMAGE" 2>/dev/null || true)"
if [ "$baked" != 1 ]; then
[ "$ENABLE_MICROVM" = auto ] || die "ENABLE_MICROVM=1,但这个包打的时候没有带 microVM 运行时(用了 --no-microvm)。
换一个默认方式打出来的包,或者把 ENABLE_MICROVM 改成 auto"
return 0
fi
if [ ! -e /dev/kvm ]; then
if [ "$ENABLE_MICROVM" = 1 ]; then
die "ENABLE_MICROVM=1,但这台机器没有 /dev/kvm,启动不了 microVM。
- 物理机:确认 CPU 支持虚拟化、BIOS 里已打开,并已加载 kvm 模块(ls -l /dev/kvm 能看到它);
- 云主机:要选支持嵌套虚拟化的机型并打开这项功能;
- 不需要 microVM 的话,把 ENABLE_MICROVM 改成 auto 或 0。"
fi
say "这台机器没有 KVM(/dev/kvm),不启用 microVM"
return 0
fi
kvm_opts
say "检测到 /dev/kvm,试着启动一台 microVM(第一次要十几秒到一分钟)"
if out="$(microvm_selftest)"; then
MICROVM_OPTS=("${KVM_OPTS[@]}")
say "$out"
return 0
fi
[ "$ENABLE_MICROVM" = auto ] || die "ENABLE_MICROVM=1,但 microVM 启动不了:${out:-没有输出}
常见原因见 README 的常见问题。不需要 microVM 的话,把 ENABLE_MICROVM 改成 auto 或 0"
warn "microVM 启动不了,这次不启用,代码仍按原来的方式执行。原因:${out:-没有输出}"
}
# 服务端实际选中的沙箱。镜像里没有 curl,用 python 从容器里问
sandbox_summary() {
docker exec "$CONTAINER_NAME" python -c '
import json, urllib.request as u
r = u.build_opener(u.ProxyHandler({})).open("http://127.0.0.1:8000/api/sandbox/health", timeout=5)
d = json.load(r)
print(d.get("selected_because") or d.get("backend") or "未知")
' 2>/dev/null || echo "查不到"
}
# ---------------------------------------------------------------------------
# 容器
# ---------------------------------------------------------------------------
@@ -318,6 +394,7 @@ run_container() {
-v "$DATA_ABS:/data" \
--log-opt max-size=10m --log-opt max-file=3 \
${extra[@]+"${extra[@]}"} \
${MICROVM_OPTS[@]+"${MICROVM_OPTS[@]}"} \
"$IMAGE" >/dev/null
}
@@ -397,6 +474,7 @@ deploy_container() {
if wait_healthy "$CONTAINER_NAME"; then
[ -z "$had_old" ] || docker rm "$prev" >/dev/null 2>&1 || true
say "AgentLab $VERSION 已就绪,数据目录 $DATA_ABS"
say "代码沙箱:$(sandbox_summary)"
print_access
return 0
fi
@@ -420,6 +498,7 @@ cmd_install() {
prepare_data
check_existing
fix_data_owner
decide_microvm
deploy_container
}
@@ -440,6 +519,7 @@ cmd_upgrade() {
prepare_data
check_existing
fix_data_owner
decide_microvm
deploy_container
if [ "$old_image" != "$IMAGE" ] && docker image inspect "$old_image" >/dev/null 2>&1; then
echo "旧镜像 $old_image 还留着,方便回退。确认新版本没问题后可以删:docker rmi $old_image"
@@ -492,6 +572,7 @@ cmd_status() {
echo "镜像 $image"
echo "端口 $(docker port "$CONTAINER_NAME" 8000/tcp 2>/dev/null | tr '\n' ' ')"
echo "数据目录 ${src:-(未挂载)}"
[ "$state" != running ] || echo "代码沙箱 $(sandbox_summary)"
echo "这个包 $IMAGE"
if [ "$state" = running ]; then print_access; fi
}