CrewMeld OpenSandbox 工具沙箱:如何用 Docker/K8s 安全隔离 AI 生成代码的完整指南
CrewMeld OpenSandbox 工具沙箱:如何用 Docker/K8s 安全隔离 AI 生成代码的完整指南
CrewMeld 是一个企业级 AI 数字员工平台,它的 OpenSandbox 工具沙箱能把你(或 AI)编写的 JavaScript / Python 代码放进独立容器里执行,支持 Docker 与 Kubernetes 两种运行时,并通过出站网络白名单(Egress Allowlist)把代码的访问范围锁死在最小集合内。本文带你从零理解这套机制:它为什么必要、如何一键启动、如何配置网络隔离与依赖缓存。
为什么 AI 生成的代码必须进沙箱?
CrewMeld 的核心理念是"像管理真人团队一样管理 AI 员工"——AI 员工会写代码、调工具、跑脚本。如果这些代码直接在平台进程里执行,一次失控的 rm -rf、一个内存泄漏循环、一段恶意依赖安装,都可能拖垮整个平台。
CrewMeld 的答案是:把"跑代码的地方"和"平台本身"物理隔开。每一次工具调用都在一个全新的、用完即毁的容器里发生,容器崩溃了,平台纹丝不动。这就是 README.zh-CN.md 中描述的工具层定位:
工具层:OpenSandbox 隔离 Node.js / Python 进程,代码隔离
架构一览:三层隔离是怎么搭起来的
整套沙箱由三个部分组成(见 docker-compose.yml 中的 opensandbox-docker profile):
| 组件 | 镜像 | 职责 |
|---|---|---|
| OpenSandbox Server | opensandbox/server:v0.1.14 |
沙箱生命周期管理:创建、查询、销毁容器 |
| execd | opensandbox/execd:v1.0.16 |
每个沙箱容器内的命令执行代理 |
| egress | opensandbox/egress:v1.0.12 |
出站流量代理,按白名单做 DNS 级过滤 |
CrewMeld 主服务通过 REST 客户端与 OpenSandbox Server 对话,核心封装在 opensandbox-client.ts 中,只暴露创建、等待就绪、执行、销毁这几个生命周期方法。
平台侧有两条执行路径:
- Dev Studio 采纳的工具(脚本型 / 服务型):通过 tool-sandbox.ts 创建临时沙箱,把工具代码、共享依赖库、每次调用的 IO 目录挂载进容器,跑完即销毁(默认存活 300 秒)。
- AI 即兴生成的代码(临时脚本):由 job-runner.ts 在 Kubernetes 里创建一次性 Job,Pod 跑完自动清理,默认资源上限 500m CPU / 512Mi 内存。
两种路径的隔离语义完全一致:代码永远不在宿主机或平台进程里运行。
一键启动:Docker 与 K8s 两种运行时
方式一:Docker 运行时(最省心)
在仓库根目录执行:
./start.sh --profile opensandbox-docker --profile minio
这条命令会启动三个组件:渲染配置、预拉取镜像、拉起 OpenSandbox Server。CrewMeld 容器随后通过 OPENSANDBOX_SERVER_URL(如 http://opensandbox-server:30080)和 OPENSANDBOX_API_KEY 两个环境变量接入沙箱服务。
纯 Docker Compose 用户也可以直接:
docker compose --profile opensandbox-docker --profile minio up -d
方式二:Kubernetes 运行时(生产推荐)
生产环境建议使用 k3s,CrewMeld 提供了现成的 opensandbox-k3s profile,会内嵌一个 k3s 节点并用 Helm 部署 OpenSandbox,随后 CrewMeld 的工具代码就以 K8s Job 的形式运行在集群中。对应的容器镜像默认是 node:22-bookworm 与 python:3.12-bookworm(可通过 K8S_IMAGE_NODE / K8S_IMAGE_PYTHON 覆盖)。
💡 国内网络环境下,沙箱内的
pip/npm安装默认走清华 TUNA(pypi.tuna.tsinghua.edu.cn)与 npmmirror(registry.npmmirror.com)镜像源,依赖安装开箱即快。
安全加固:容器里能做什么,配置说了算
OpenSandbox 的默认配置(opensandbox-server.docker.toml)就是一份相当硬核的安全清单:
[docker]
drop_capabilities = ["AUDIT_WRITE", "MKNOD", "NET_ADMIN", "NET_RAW", "SYS_ADMIN", "SYS_MODULE", "SYS_PTRACE", "SYS_TIME", "SYS_TTY_CONFIG"]
no_new_privileges = true
pids_limit = 4096
drop_capabilities:剥离NET_ADMIN、SYS_PTRACE等高危能力,容器内的代码无法嗅探网络、无法 trace 其他进程;no_new_privileges:禁止权限提升,setuid二进制无效;pids_limit:限制进程数,防 fork 炸弹。
K8s Job 路径上还有第二道闸:activeDeadlineSeconds 超时自动杀 Pod、ttlSecondsAfterFinished 结束 60 秒后自动 GC、restartPolicy: Never 绝不重启——失败就失败,绝不给你"再试一次"的机会,避免失控代码反复拉起。
出站白名单:让沙箱代码"只去该去的地方"
这是整个沙箱体系里最有企业味的一环。默认出站是不限制的,但你可以切换到 allowlist 模式,此时沙箱代码能访问的 IP 和域名必须在你登记的白名单里。
在设置页配置
进入 设置 → 沙箱 页面(源码:page.tsx/settings/sandbox/page.tsx)),你会看到三组配置:
- 预设 Python 包:如
requests、pandas,所有沙箱共享,安装一次缓存复用; - 出站模式:
unrestricted(不限制)或allowlist(白名单); - 允许的 IP / 域名:支持单 IP 与 CIDR(如
192.168.1.0/24)、FQDN(如api.example.com)。
这些配置持久化在 platform_settings 表中,读取与校验逻辑在 settings.ts 中,保存时会严格校验包名、IP/CIDR、域名格式,非法值直接拒绝。
白名单在 K8s 里如何落地
当模式为 allowlist 时,network-policy.ts 会在 Job 创建之前 先生成一个 Kubernetes NetworkPolicy,把该 Pod 的出站流量钉死到:
- 集群 DNS(kube-dns / CoreDNS,53 端口)——保证域名解析可用;
- 你配置的 IP / CIDR;
- 你配置的域名(创建时解析成 CIDR 快照);
- 必要的系统端点(如 MinIO 文件存储)。
其余一切——包括整个互联网——默认拒绝。执行结束后策略随 Job 一起删除;进程启动时还有孤儿清理器,专门扫掉那些 Job 已消失但策略残留的 NetworkPolicy,不污染集群。
⚠️ 一个运维提示:域名是创建时解析成 IP 的快照,如果目标域名后面挂了轮转 IP 的 CDN,长任务中途可能访问失败。这类域名建议同时登记对应的 IP 段。
SOP 沙箱演练:上线前先在"影子环境"跑一遍
除了执行 AI 代码,CrewMeld 还有一个 SOP 沙箱演练功能:用真实 SOP 引擎跑你的流程定义,但通过注入 _sandboxPolicy 拦截 LLM 调用、邮件、消息推送等外部副作用(见 sop-sandbox-executor.ts)。执行状态、耗时、每个节点的成败都会实时镜像到 sandbox_runs 表,供你在页面上复盘——不花一分钱 API 额度、不发一封真实邮件,就能验证整个 SOP。
依赖缓存:为什么第二次运行这么快
每个 K8s Job 都挂载了共享的 crewmeld-deps-cache PVC。启动脚本按"依赖列表哈希"分目录缓存:同一批依赖的第二个 Job 直接命中缓存,跳过 pip install / npm install;管理员修改预设包列表只会使预设缓存失效,不影响用户代码各自的缓存。Python 工具还共享 Playwright 浏览器缓存,浏览器类工具冷启动显著更快。
关键文件速查
| 想了解什么 | 看这里 |
|---|---|
| 沙箱服务端 Docker 配置(安全加固、端口、存储) | opensandbox-server.docker.toml |
| K8s Job 执行器(镜像、超时、日志解析) | job-runner.ts |
| 出站白名单 → NetworkPolicy 构建 | network-policy.ts |
| 沙箱设置读取与校验 | settings.ts |
| 沙箱设置页 UI | settings/sandbox/page.tsx/settings/sandbox/page.tsx) |
| 工具临时沙箱创建/销毁 | tool-sandbox.ts |
| SOP 演练执行器 | sop-sandbox-executor.ts |
| 启动编排(profile 定义) | docker-compose.yml |
小结
CrewMeld 的沙箱体系可以浓缩成三句话:
- 🐳 隔离:代码永远在一次性容器/K8s Job 里跑,资源、进程、能力都被封顶;
- 🌐 可控:出站白名单 + NetworkPolicy 把网络访问面收到最小;
- ⚡ 高效:依赖哈希缓存 + 国内镜像源 + SOP 演练,安全不牺牲速度。
如果你正在评估把 AI 生成代码纳入生产流水线,这套"Docker 起步、K8s 落地、白名单兜底"的组合,值得作为一个参考模板。


