企业官网建设流程全解析

1. 为什么要把一堆工具塞进同一个容器

第一次看到 AIO Sandbox 这个项目的时候，我正在给一个内部 Agent 项目做运行环境隔离。当时的需求很朴素：让 Agent 能自己开浏览器抓页面、能跑 Shell 命令、能读写文件、能通过 MCP 协议调用外部工具，最好还能让我随时进容器里手动调试。结果我搭了四个容器，写了三套网络配置，调试的时候在四个终端之间来回切，一个下午就没了。

AIO Sandbox 解决的正是这个场景。它把浏览器、Shell、文件系统、MCP 服务端、VSCode Server 全部打包进同一个容器镜像，对外只暴露一组端口。Agent 通过统一的接口操作这些能力，人通过浏览器访问 VSCode 或桌面环境进行干预。这个项目的核心价值不在于某个单点技术有多新，而在于它把 Agent 运行所需的“手脚眼脑”收敛到了一个可复制、可迁移的单元里。

适合读这篇的人有三类：正在给 Agent 搭建执行环境但被多容器编排折磨的工程师；想理解 MCP 协议在真实项目里怎么落地的人；以及需要一套可离线、可私有化部署的 Agent 沙箱方案的技术负责人。我会从设计思路、核心组件、实操部署、问题排查四个层面展开，把我在实际使用中踩过的坑和验证过的配置都写出来。

2. 整体设计思路与方案选型拆解

2.1 单容器多能力的取舍逻辑

把这么多东西塞进一个容器，第一反应肯定是“这不符合单一职责原则”。我一开始也这么想，但实际用下来发现，Agent 场景和传统微服务场景有本质区别。

传统微服务拆分的理由是：不同服务有不同的扩缩容需求、不同的发布节奏、不同的故障域。但 Agent 沙箱是一个强状态、强交互的运行单元。浏览器里打开的页面状态、Shell 里的工作目录、文件系统里的临时产物，这些东西是相互依赖的。如果拆成多个容器，Agent 每次跨能力调用都要处理网络延迟、状态同步、文件共享挂载，复杂度陡增。

AIO Sandbox 选择单容器，本质上是把“状态一致性”放在了“服务独立性”之上。浏览器下载的文件直接落在共享文件系统里，Shell 命令可以直接操作这些文件，VSCode 打开的就是同一个目录。这种设计让 Agent 的操作链路变得极短，也让人工介入变得自然——你不需要在多个容器之间同步任何东西。

注意：单容器方案不适合需要独立扩缩容的生产级多租户场景。如果你的 Agent 要同时服务几百个用户，每个用户需要独立的沙箱实例，那应该用容器编排平台管理多个 AIO Sandbox 实例，而不是在一个容器里塞多套环境。

2.2 浏览器能力的实现路径选择

Agent 操作浏览器有几种主流路径：Playwright、Puppeteer、Selenium，以及基于 CDP 协议的直接控制。AIO Sandbox 选择的是 Playwright 作为底层驱动，同时暴露 CDP 接口供外部工具连接。

为什么是 Playwright 而不是其他？我实测下来的感受是三点。第一，Playwright 的自动等待机制对 Agent 更友好，Agent 不需要自己写一堆 sleep 和轮询逻辑，元素定位失败时框架会自动重试。第二，Playwright 对多浏览器上下文的管理更干净，Agent 可以同时开多个隔离的页面上下文，互不干扰。第三，Playwright 的 CDP 暴露比较完整，外部工具比如 Chrome DevTools 可以直接连上去调试。

这里有个细节值得展开：AIO Sandbox 里的浏览器不是无头模式跑在后台就完事了，它还提供了可视化的访问入口。你可以通过浏览器访问容器暴露的端口，看到一个完整的桌面环境或者浏览器界面。这个设计对调试极其重要——Agent 操作失败的时候，你能直接看到页面上发生了什么，而不是对着日志猜。

2.3 MCP 协议在沙箱中的角色定位

MCP 是这两年 Agent 领域最热的关键词之一，但很多人对它的理解停留在“让 AI 调用工具”这个层面。在 AIO Sandbox 里，MCP 的角色更具体：它是沙箱内部能力对外暴露的统一接口层。

沙箱里的 Shell、文件系统、浏览器操作，都可以通过 MCP Server 的形式暴露给外部的 Agent 框架。Agent 不需要知道沙箱内部是怎么实现的，只需要按照 MCP 协议发送请求，就能驱动这些能力。这种设计的好处是解耦——Agent 框架和沙箱实现可以独立演进，只要协议不变，两边都能换。

我实际用下来，MCP 在沙箱场景里最大的价值是“能力发现”。Agent 连接上 MCP Server 之后，可以查询当前沙箱支持哪些工具、每个工具需要什么参数。这让 Agent 的行为更加动态，不需要在代码里硬编码工具列表。

2.4 VSCode Server 的集成考量

把 VSCode 塞进容器，用的是 code-server 这个开源项目。它的作用不是让 Agent 去写代码，而是给人提供一个干预入口。

Agent 在沙箱里跑任务的时候，经常会出现需要人工确认或者修正的情况。比如 Agent 要修改一个配置文件，但改错了，你需要进去手动改回来。如果沙箱里只有 Shell，你得用 vim 或者 nano 在终端里操作，效率很低。有了 VSCode Server，你可以直接在浏览器里打开一个完整的 IDE，有文件树、有语法高亮、有终端，操作体验和本地开发几乎一样。

这个设计还带来一个额外好处：你可以把沙箱里的工作目录直接当成一个开发环境来用。Agent 生成的代码、脚本、配置文件，你都可以在 VSCode 里直接查看和编辑，不需要额外的文件传输步骤。

3. 核心组件细节与实操要点

3.1 容器镜像的层次结构

AIO Sandbox 的镜像不是简单地把所有东西装在一起，而是有明确的层次划分。从下往上大致是：基础操作系统层、运行时环境层、能力组件层、服务编排层。

基础层通常是一个精简的 Linux 发行版，我见过的版本里用的是 Debian 或者 Ubuntu 的 slim 镜像。这一层只包含最基本的系统工具和库，目的是控制镜像体积。运行时层安装 Python、Node.js 这些 Agent 和工具链需要的语言运行时。能力组件层就是浏览器、code-server、MCP Server 这些具体的东西。服务编排层负责在容器启动时把这些组件拉起来，并管理它们之间的依赖关系。

这个分层结构对实操的意义在于：如果你需要定制镜像，比如加一个特定的 Python 包或者系统工具，你应该在对应的层里操作。加系统工具在基础层，加 Python 包在运行时层，不要混在一起，否则镜像构建的缓存会频繁失效，构建时间会变得很长。

3.2 端口规划与访问方式

AIO Sandbox 对外暴露的端口不多，但每个都有明确用途。我整理了一个表格，方便你部署的时候对照检查。

端口映射的时候有个坑要注意：如果你在本地用 Docker Desktop，默认的端口映射是绑定到 127.0.0.1 的，局域网内其他机器访问不了。如果需要从其他机器访问，要在启动命令里显式指定绑定地址，比如-p 0.0.0.0:3000:3000。但这样会带来安全风险，所以更推荐的做法是用 SSH 隧道或者反向代理来做访问控制。

3.3 文件系统的挂载策略

沙箱里的文件系统设计直接决定了 Agent 能做什么、不能做什么。AIO Sandbox 通常会把几个关键目录挂载出来或者做成卷，方便持久化和人工干预。

工作目录一般挂载在/workspace或者类似的路径下，Agent 的所有文件操作默认都在这个目录里进行。这个目录通常会被映射到宿主机的某个路径，这样容器重启后文件不会丢。浏览器下载目录、临时文件目录、日志目录也都有各自的挂载点。

我踩过的一个坑是权限问题。容器里的进程通常以非 root 用户运行，但挂载出来的宿主机目录如果权限不对，容器里的用户就写不进去。解决办法是在启动容器之前，先确认宿主机目录的属主和权限，或者用--user参数指定容器运行时的 UID 和 GID，让它和宿主机目录的属主匹配。

提示：如果你在 macOS 或 Windows 上用 Docker Desktop，文件挂载的性能会比 Linux 上差不少，尤其是大量小文件读写的时候。如果 Agent 的任务涉及频繁的文件操作，建议把工作目录放在容器内部的卷里，只把最终产物挂载出来。

3.4 MCP Server 的配置与连接

MCP Server 是 Agent 和沙箱之间的桥梁，它的配置直接决定了 Agent 能调用哪些能力。AIO Sandbox 里的 MCP Server 通常以独立进程的形式运行，监听一个端口，等待 Agent 连接。

连接方式有两种：SSE 和 WebSocket。SSE 更适合简单的请求-响应场景，WebSocket 更适合需要双向实时通信的场景。Agent 框架支持哪种就用哪种，如果都支持，我建议用 WebSocket，因为它的连接状态更稳定，断线重连的逻辑也更清晰。

配置 MCP Server 的时候，工具列表是可以裁剪的。如果你不希望 Agent 拥有 Shell 执行权限，可以在配置里把对应的工具禁用掉。这个裁剪操作在安全敏感的场景里很重要——一个能执行任意 Shell 命令的 Agent，风险等级和只能读写文件的 Agent 完全不是一个量级。

4. 完整部署流程与关键环节实现

4.1 环境准备与 Docker 安装确认

在开始部署之前，先确认你的 Docker 环境是正常的。Linux 上直接用包管理器安装 Docker Engine 就行，Windows 和 macOS 上需要安装 Docker Desktop。

Windows 上安装 Docker Desktop 最常见的报错是 “Virtualization support not detected”。这个报错的意思是 CPU 虚拟化功能没有在 BIOS 里开启，或者被其他虚拟化软件占用了。解决办法是进 BIOS 开启 Intel VT-x 或 AMD-V，如果开了还是报错，检查一下是不是 Hyper-V 和 WSL2 冲突了。Docker Desktop 现在默认用 WSL2 后端，需要确保 WSL2 已经正确安装并设置为默认版本。

Linux 上安装完 Docker 之后，记得把当前用户加到 docker 组里，否则每次执行 docker 命令都要加 sudo。命令是sudo usermod -aG docker $USER，执行完之后要重新登录才能生效。

验证 Docker 是否正常，跑一个docker run hello-world就行。如果能看到欢迎信息，说明基础环境没问题。

4.2 拉取镜像与启动容器

AIO Sandbox 的镜像可以从公共镜像仓库拉取。拉取之前先确认镜像的标签，不同标签对应的组件版本可能不一样。我一般会用 latest 标签先跑起来看看，确认功能正常之后再固定到具体的版本标签。

启动命令的核心参数有这么几个：端口映射、卷挂载、环境变量、资源限制。我写一个典型的启动命令作为参考：

docker run -d \ --name aio-sandbox \ -p 3000:3000 \ -p 5900:5900 \ -p 8080:8080 \ -p 9222:9222 \ -v /host/workspace:/workspace \ -e VNC_PASSWORD=yourpassword \ -e MCP_TOKEN=yourtoken \ --shm-size=2g \ --memory=4g \ --cpus=2 \ aio-sandbox:latest

这里有几个参数值得展开说。--shm-size是共享内存大小，浏览器跑起来之后对共享内存的需求比较大，默认的 64MB 经常不够，会导致浏览器崩溃。我一般设成 2GB，如果任务比较重可以再往上加。--memory和--cpus是资源限制，防止 Agent 跑飞了把宿主机资源吃光。MCP_TOKEN是 MCP Server 的访问令牌，不设置的话任何人都能连上来调用工具，安全风险很大。

4.3 验证各组件是否正常工作

容器启动之后，不要急着让 Agent 连上来，先手动验证一遍各个组件。

code-server 的验证最简单，浏览器打开http://localhost:3000，能看到 VSCode 界面就说明正常。如果打不开，先检查容器日志docker logs aio-sandbox，看看 code-server 进程有没有报错。

VNC 的验证需要一个 VNC 客户端，连上localhost:5900，输入密码，应该能看到一个桌面环境。如果桌面是黑的，可能是窗口管理器没启动，检查一下容器里的进程列表。

MCP Server 的验证稍微麻烦一点，需要用 MCP 客户端或者 curl 来测试。如果是 SSE 传输，可以先用 curl 请求一下工具列表接口，看看能不能返回 JSON 格式的工具描述。如果返回 401，说明令牌不对；如果连接被拒绝，说明端口没映射对或者服务没起来。

CDP 端口的验证可以用 curl 请求http://localhost:9222/json/version，正常应该返回浏览器版本信息。这个接口通了，说明 Playwright 和外部调试工具都能连上。

4.4 Agent 接入与任务下发

Agent 接入沙箱的方式取决于你用的 Agent 框架。如果框架原生支持 MCP，直接在配置里填上 MCP Server 的地址和令牌就行。如果不支持 MCP，可能需要写一个适配层，把框架的工具调用转换成 MCP 请求。

任务下发的时候，我建议先从简单的任务开始测试，比如让 Agent 打开一个网页、截个图、把截图保存到工作目录。这个任务链路覆盖了浏览器操作、文件写入两个核心能力，能跑通说明基础环境没问题。然后再逐步增加复杂度，比如让 Agent 执行 Shell 命令、修改文件、再通过浏览器验证修改结果。

注意：Agent 第一次连接 MCP Server 的时候，可能会花几秒钟来获取工具列表和初始化连接。如果你的 Agent 框架有超时设置，记得把这个时间考虑进去，否则会出现连接超时的误报。

5. 常见问题与排查技巧实录

5.1 容器启动失败类问题

容器启动失败最常见的原因是端口冲突。如果你宿主机上已经有服务占用了 3000 或 8080 端口，容器启动时会报 “port is already allocated”。解决办法是换一个宿主机端口，比如把-p 3000:3000改成-p 13000:3000。

另一个常见原因是卷挂载的路径不存在。Docker 在挂载卷的时候，如果宿主机路径不存在，默认会创建一个目录，但权限可能不对。如果容器里的进程没有权限写入这个目录，启动过程中就会报错。解决办法是提前创建好目录并设置正确的权限。

还有一种情况是镜像拉取失败，报 “manifest unknown” 或者 “pull access denied”。这通常是镜像标签写错了，或者镜像仓库需要登录。确认一下镜像名称和标签是否正确，如果需要登录，先执行docker login。

5.2 浏览器相关故障排查

浏览器起不来或者起来之后崩溃，十有八九是共享内存不够。前面提到的--shm-size参数就是解决这个问题的。如果你已经设了 2GB 还是崩溃，可以看看容器日志里有没有 “Out of memory” 的关键字，如果有，继续加大共享内存或者加内存限制。

浏览器能起来但 Agent 操作不了，可能是 Playwright 的连接配置有问题。检查一下 Agent 连接浏览器时用的地址和端口，在容器内部应该用localhost:9222，从容器外部连应该用宿主机的 IP 和映射的端口。如果 Agent 和浏览器不在同一个网络命名空间里，地址写错了就连不上。

页面加载慢或者超时，可能是容器内的 DNS 配置有问题。Docker 默认会用宿主机的 DNS，但如果宿主机 DNS 不稳定，容器里的解析就会很慢。可以在启动容器时用--dns参数指定一个可靠的 DNS 服务器。

5.3 MCP 连接与工具调用问题

MCP 连接失败的第一排查点是令牌。如果 Agent 报 401 或者 403，先确认令牌是否和容器启动时设置的一致。令牌通常放在请求头里，格式是Authorization: Bearer <token>，检查一下 Agent 框架有没有正确设置这个头。

工具调用返回错误但连接是正常的，可能是工具的参数格式不对。MCP 协议对参数的类型和结构有明确要求，Agent 生成的参数如果不符合 schema，服务端会拒绝执行。排查方法是把 Agent 发送的请求内容打印出来，和 MCP Server 的工具描述对比，看看哪里不匹配。

如果某些工具在列表里看不到，说明在 MCP Server 配置里被禁用了。检查一下配置文件，确认你需要用的工具没有被注释掉或者设成 disabled。

5.4 性能与资源类问题

Agent 任务跑得慢，可能是资源限制太紧。用docker stats看一下容器的 CPU 和内存使用率，如果一直贴着限制跑，说明需要放宽限制。但也不要一上来就给太多资源，先观察实际使用量再调整。

文件操作慢，如果工作目录挂载在宿主机上，尤其是 macOS 和 Windows 上，大量小文件读写会明显变慢。解决办法是把工作目录放在容器内部的卷里，只把需要持久化的产物定期同步出来。

网络请求慢，可能是容器内的网络配置有问题。检查一下容器的网络模式，默认的 bridge 模式性能通常够用，但如果 Agent 需要访问大量外部资源，可以考虑用 host 网络模式，减少一层 NAT 转换。不过 host 模式会带来端口冲突的风险，用之前要确认宿主机端口没有被占用。

5.5 常见问题速查表

6. 安全加固与生产化建议

6.1 访问控制的最小化原则

AIO Sandbox 默认配置是面向开发调试的，直接放到生产环境会有很多安全隐患。第一件事就是给所有对外暴露的服务加上认证。code-server 要设密码，VNC 要设密码，MCP Server 要设令牌，CDP 端口最好不要对外暴露，只允许容器内部访问。

如果沙箱需要被多个 Agent 或者多个用户共享，建议在前面加一层反向代理，做统一的认证和访问日志记录。反向代理还可以做速率限制，防止某个 Agent 疯狂调用工具把沙箱打挂。

6.2 能力裁剪与权限隔离

不是每个 Agent 都需要完整的 Shell 权限。如果你的 Agent 只需要操作浏览器和读写文件，那就把 Shell 工具禁掉。MCP Server 的配置里通常支持按工具粒度启用或禁用，利用好这个功能可以大幅降低风险。

容器本身也可以做权限限制。用--read-only把根文件系统设成只读，只把需要写入的目录挂载成可写。用--cap-drop去掉不需要的 Linux 能力，比如CAP_NET_RAW和CAP_SYS_ADMIN。这些操作在 Docker 的文档里都有详细说明，花十分钟配置一下，安全性会有明显提升。

6.3 日志与审计

Agent 在沙箱里的所有操作都应该有日志可查。MCP Server 的请求日志、Shell 命令的执行记录、文件系统的变更记录，这些在排查问题和审计的时候都用得上。

Docker 本身的日志驱动可以配置成把容器日志写到文件或者日志系统里。如果沙箱里跑了多个服务，建议每个服务的日志分开存放，不要混在一起。code-server 和 MCP Server 通常都有自己的日志配置项，可以指定日志级别和输出路径。

提示：日志里可能会包含敏感信息，比如 Agent 操作的文件内容、访问的 URL 等。如果日志需要长期保存，记得做脱敏处理，或者把日志存在访问受控的地方。

7. 我实际使用中的几个体会

这个项目我用下来的最大感受是，它把 Agent 运行环境的搭建从“搭积木”变成了“开箱即用”。以前给 Agent 配环境，光是让浏览器、Shell、文件系统三者协同工作就要花不少时间，现在一个容器起来就全有了。

几个我觉得特别实用的点：VNC 桌面让调试变得直观，Agent 操作浏览器的时候你能实时看到画面，出问题了一眼就能定位；MCP 的工具发现机制让 Agent 的能力扩展变得简单，加一个新工具只需要在 MCP Server 里注册，Agent 那边不用改代码；文件系统的统一挂载让 Agent 的产物管理变得清晰，所有输出都在一个目录里，打包带走就行。

也有几个需要留意的地方。单容器方案在资源隔离上不如多容器，如果 Agent 的任务负载波动很大，可能会互相影响。镜像体积不小，拉取和启动都需要一点时间，如果要做快速扩缩容，需要提前把镜像分发到各个节点上。MCP 协议本身还在演进，不同版本的 Agent 框架对协议的支持程度不一样，接入之前最好先确认兼容性。

最后分享一个小技巧：如果你在本地开发，可以把沙箱的端口映射到本地，然后用本地的 VSCode 通过 Remote-SSH 或者 Dev Containers 插件连进去。这样你既能用本地的编辑器体验，又能利用沙箱里的完整环境，两全其美。