企业官网建设流程全解析

最近这两百多天的“一天一个开源项目”系列更新里，我一直在断断续续追踪 AI Agent 相关的基础设施。说实话，Agent 开发这件事，模型层已经卷得飞起，但真正让我头疼的反而是执行环境：想让 Agent 去浏览器里点两下按钮，环境里连浏览器都没有；想让它执行一段 Shell 脚本，又怕权限没控好把宿主机文件搞坏；想在 VSCode 里盯着它一步一步跑日志，来回切编辑器就切得人烦躁。直到我用了 AIO Sandbox，这个问题才算有了比较优雅的解法。

AIO Sandbox 不是一个大模型项目，也不是一个 Agent 框架，它更像是一个“Agent 的集装箱房屋”——把浏览器、Shell、文件、MCP 和 VSCode 五种能力全部塞进同一个 Docker 容器里，开箱即用。这也是它名字里 AIO（All-In-One）的由来。它最适合两类人：一类是正在做 Agent 应用开发、想把执行环境隔离起来并且能快速跑通的开发者；另一类是被“配环境”劝退的新手，想低成本拥有一套“什么都有”的开发工作台。这篇文章我会从它为啥这么设计讲起，再带你从零部署一遍，中间穿插大量实操细节和我实际踩过的坑。

1. AIO Sandbox 到底是什么：一个容器装下五个开发模块

1.1 为什么 Agent 开发者需要一个“环境避难所”

抛开概念，先聊一个最现实的问题：Agent 开发和普通 Web 开发，对运行环境的依赖有什么本质不同？

普通后端服务是确定性的。你写好 Dockerfile，依赖锁定，端口固定，跑起来之后行为是可控的。Agent 恰恰相反，它的行为不可预知。同一个 Agent 任务，上一秒还在读文件，下一秒就可能在 Shell 里安装一个新依赖，再下一秒甚至会把浏览器打开去操作页面。如果这些动作直接发生在你的 MacBook 或 Linux 服务器上，几个后果很难避免：依赖冲突、环境变量污染、不可复现的行为，以及最要命的——权限失控。

我自己实测过几种常见方案，体验差别非常大：

表格里“自己拼 Docker 镜像”看起来也不难，但我试过之后才明白为什么有人愿意直接做整合好的镜像。你要处理的细节包括但不限于：无头浏览器依赖的几十个系统库（libnss3、libatk、libgbm 这些，少一个 Chrome 就起不来）、VSCode Web Server 的鉴权和端口配置、MCP Server 运行时的 Node 环境，以及这些服务之间的权限打通。每一样单独拎出来都能写篇博客，但串在一起确实非常消耗精力。AIO Sandbox 的思路就是把这些脏活集中预置掉，让你把注意力放在 Agent 本身的逻辑上。

1.2 浏览器、Shell、文件、MCP、VSCode 五件套怎么分工

你可能会好奇，这五个模块在一个容器里到底是怎么共存的？我按用途拆开看，逻辑会清晰很多。

• Browser（浏览器）：容器里内置了 Chromium 系浏览器，既能无头运行，也能通过 noVNC 以远程桌面的形式在网页里看到有头界面。Agent 可以通过 Playwright MCP 或 CDP 协议去操作页面，这是目前 Agent 做端到端验证最常用的方式。
• Shell：容器内是标准的 bash 环境，预装了 git、curl、python3、node 这些常规工具。Agent 通过 MCP 的终端能力可以执行真实命令，而不是靠模拟器猜输出。
• File（文件系统）：工作目录可以挂载宿主机目录，也可以使用容器内置空间。Agent 通过文件系统 MCP 读写代码文件、生成报告、保存截图。
• MCP：这是整个环境的中枢，预置了文件系统、浏览器、终端等 MCP Server，Agent 可以通过标准协议直接调用，不用为每个工具单独写适配器。
• VSCode：以 Web IDE 形态提供，浏览器打开就是一个完整的代码编辑器，适合开发者观察 Agent 改动、手动修改代码、查看日志。

这五个模块不是孤立存在的，串起来才是真正有用的形态。举个例子，我调试一个前端项目时，会先用 VSCode 打开源码，让 Agent 在 Shell 里跑单元测试，测试挂了它自己去读代码修复，修完再启动开发服务器，然后用浏览器操作页面验证登录跳转，最后把验证结果和截图写到工作目录里。整个过程我在浏览器里盯 VSCode 就能完成，不需要频繁切换环境。

2. 技术架构与运行机制：为什么是“容器 + MCP”的组合

2.1 为什么底座选择 Docker 而不是虚拟机

AIO Sandbox 把底座选在 Docker 容器上，这背后不是图方便，而是三个硬指标决定的：启动速度、资源占用和可复制性。

启动速度这块，容器秒级拉起，虚拟机至少要等几十秒，有的甚至分钟级。Agent 任务往往是高频短时的，每次调试都要等上一分钟，整个人的心气都会磨没。资源占用上，一个带浏览器和 VSCode 的沙箱镜像大概 2~3GB，运行时内存控制在 4GB 以内绰绰有余，而我之前试过给虚拟机分配 8GB 内存依然觉得卡。最关键的还是可复制性，Dockerfile 一旦写好，团队里每个人拉下来都是同一个环境，不会再出现经典的“在我机器上是好的”问题。Agent 开发尤其吃环境一致性，模型执行效果如果依赖本机残留的临时变量，那排查起来会非常痛苦。

当然，容器也有它的边界。它的隔离依赖 Linux 内核命名空间和 cgroups，做不到虚拟机那种硬件级隔离。如果你跑的 Agent 涉及不可信第三方代码，还想要真正的强隔离，那建议再套一层虚拟机或者用 gVisor 这类运行时。但作为日常开发调试和业务自动化，容器隔离已经足够用了。

2.2 MCP 协议凭什么成为工具调用的“通用插座”

MCP（Model Context Protocol）这两年从概念走向落地，速度比我预想的快得多。你可以把它理解成给 Agent 装了一个 USB 接口：以前接一个工具要单独写一套集成代码，现在只要 Agent 支持 MCP 客户端，就能接入所有实现了 MCP 协议的工具。这个标准化的意义在沙箱环境里体现得最明显。

AIO Sandbox 里预置的 MCP Server 通常包括这么几类：文件系统 MCP（对工作目录读写、快照备份）、Playwright MCP（导航、点击、输入、截图）、终端 MCP（执行命令并返回输出）、还有内存 MCP（给 Agent 做短期记忆缓存）。从实现上看，这些 Server 本质上是一个个独立进程，通过 JSON-RPC 和 Agent 对话。它的好处是，换一个 Agent 框架不需要把浏览器操作、Shell 调用这些能力重新实现一遍，只要框架支持 MCP 客户端，同一套工具就直接复用。

我在实际项目中试过把同一个沙箱分别接入两个不同框架的 Agent，代码改动量比我预想的小得多。这也是为什么我会强烈推荐在 Agent 项目早期就统一用 MCP 来封装工具能力，后面扩展新工具的成本会线性下降。

2.3 单容器内多进程协作的正确姿势

一个容器里同时跑 VSCode Server、浏览器、MCP Gateway 和多个 Shell 会话，这就引出一个很实际的问题：容器里没有 systemd，多进程怎么管？

常见做法是在容器里内置一个轻量进程管理器，比如 supervisord。AIO Sandbox 这类镜像通常会用 supervisor 来编排各个服务的启动顺序：先拉起 MCP Runtime，再启动 VSCode Server，最后把 noVNC 和浏览器代理跑起来。每个服务的日志会写到独立文件，排查问题时可以直接看日志流，不用瞎猜。

端口规划也得提前想清楚。我常用的分配方式大概是：VSCode Web 走 8080，noVNC 走 6080，MCP Gateway 走 3000，需要暴露业务服务的话再加一个 8000~8100 的动态段。这样在宿主机上做端口映射时不容易冲突，Agent 回调时也能按端口识别是哪个服务。

提示：启动容器后，第一件事不是急着写代码，而是确认 5 个核心端口都返回了预期响应。比如访问 8080 能看到登录页，访问 6080 能看到沙箱桌面，MCP 端口能握手成功。这一步做好，后面排查问题会省一半时间。

3. 实操部署：十分钟从零拉起一个 AIO Sandbox

3.1 开始前需要准备的 3 件事

部署这个沙箱的门槛其实很低，你只需要本机装好 Docker 或 Podman，内存建议 4GB 以上，硬盘预留 10GB 左右给镜像和依赖。操作系统方面 Windows、macOS、Linux 都行，Docker Desktop 在 Windows 和 macOS 上跑也挺稳，就是注意内存限额要给够。

如果你在 macOS 上用 Docker Desktop，记得去设置里把内存调到 4GB 以上，否则沙箱里的浏览器很容易被系统杀掉。我在 8GB 内存的 MacBook 上跑过，限制到 4GB 还是能用的，但是你要是同时开多个标签页，页面会自动刷新，那是内存告急的信号。

另外建议预先建一个工作目录，比如~/aio-workspace。挂载进容器之后，Agent 的所有产出都在这个目录里，宿主机也好访问。

3.2 用 docker run 把沙箱拉起来

下面这个命令是我常用的启动方式，参数上都加了注释理解：

docker run -d \ --name aio-sandbox \ -p 8080:8080 \ -p 6080:6080 \ -p 3000:3000 \ -v $(pwd)/workspace:/home/dev/workspace \ --shm-size=1g \ --restart unless-stopped \ aiosandbox/aio-sandbox:latest

这里有个参数必须单独强调：--shm-size=1g。浏览器容器如果不开这个，Chrome 跑复杂页面时大概率会白屏或者直接崩掉。原因很简单，Chrome 的跨进程共享内存默认挂在/dev/shm上，Docker 默认只有 64MB，这对现代浏览器远远不够。我第一次部署时没加这个参数，连开三个标签页就频繁出问题，加上之后世界清净了。

如果你的本机 8080 端口被占了，把左侧端口映射改成18080:8080即可，VSCode 访问地址随之变成http://localhost:18080。

3.3 从浏览器打开 VSCode Web IDE

容器起来后，在浏览器里打开http://localhost:8080。第一次进入通常会要求输入密码，密码可以在容器启动日志里找到，或者通过环境变量直接指定。我建议显式设置密码，避免每次去看日志：

docker run -d \ -e PASSWORD='your-password' \ ...

进入 VSCode 后，你会看到一个完整的编辑器界面，跟我平时用的桌面版几乎一样，支持插件、终端、Git 面板。对于 Agent 开发来说，这个 Web IDE 最大的价值不是写代码，而是“旁观”：Agent 在 Shell 里改了哪些文件、跑挂了多少次测试、生成了什么截图，你都能实时看到，出问题也能直接中断操作。

注意：VSCode Web 的终端默认是普通用户权限。如果你需要 Agent 安装系统级依赖，记得在配置里开启 sudo 权限或使用 root 用户启动容器。安全问题后面专门讲。

3.4 把 MCP Server 接进沙箱

AIO Sandbox 一般会预装一个 MCP 管理配置，但你要接入自己的 MCP Server 时，找到配置文件或者通过环境变量注入即可。下面是一个典型的配置示例：

{ "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }, "filesystem": { "command": "npx", "args": ["@modelcontextprotocol/server-filesystem", "/home/dev/workspace"] }, "terminal": { "command": "npx", "args": ["@modelcontextprotocol/server-command", "bash"] } } }

配好之后，在 Agent 框架里加载这个配置，它就能调用沙箱里的这些工具了。我常用的验证方式是直接问 Agent“读取工作目录下的 README.md，并把第一行内容存成一个新文件”，如果它成功执行，说明文件系统 MCP 已经通了。然后再让它“截图当前页面并保存”，验证浏览器链路。

4. 组合出 Agent 的真实工作流：从“工具”到“干活”

4.1 用浏览器 MCP 让 Agent 操作真实页面

单个 MCP 工具本身没什么神奇，真正有价值的是组合使用。我拿一个实际案例来说：帮朋友调试一个前端登录跳转问题。

以前的做法是，我先自己打开 DevTools、看 Network、找问题、改代码、再刷新验证，来回折腾好一阵。这次我把任务直接丢给了沙箱里的 Agent：目标是在本地开发服务器上完成登录操作，定位跳转失败的原因，并给出修复建议。Agent 先通过 Shell 启动开发服务器，再通过浏览器 MCP 导航到登录页，填好测试账号密码，点击登录按钮。页面跳转失败后，它没有停，而是继续在浏览器里抓取控制台日志，发现是跨域配置导致的请求被拦截。接着它定位到后端配置文件，在 VSCode 里查看相关代码，提出了修改建议。

整个过程我基本只做了两件事：在 VSCode 里看着日志流动，然后在 Agent 给出修改建议后点了一下确认。这种“Agent 自己发现问题、自己分析、自己提出修复方案”的体验，只有在执行环境足够完整的情况下才可能实现。如果沙箱里缺了浏览器或者缺了 Shell，这个闭环就断掉了。

4.2 Shell 命令、文件读写与代码修改的三方闭环

在 Agent 开发里，有一个循环出现频率极高：测试失败 -> 查看日志 -> 定位代码 -> 修改 -> 重新跑。AIO Sandbox 里这个循环被拆成了三个 MCP 工具协作完成。

Shell 负责执行测试命令并返回输出，文件系统负责读取源码和修改源码，浏览器负责验证最终效果。关键是这三个工具的根目录要一致。我的习惯是统一使用/home/dev/workspace作为工作区，挂载到宿主机，这样 Agent 在 Shell 里创建的文件、在文件系统 MCP 里读写的项目、在 VSCode 里打开的工作区都是同一个目录，不会出现“文件确实改了但编辑器里看不到”的割裂感。

还有一个细节容易被忽略：让 Agent 修改代码前，先让它用 Git 建一个分支或者至少做一个备份点。Agent 改代码的能力现在已经很强了，但它的“试错心态”也意味着可能把好好的代码改成面目全非。有一个快速回滚点，你就能放手让它大胆尝试。

4.3 自定义 MCP Server 与多 Agent 协同

内置的五个模块只是起点，AIO Sandbox 真正有想象力的是 MCP 生态扩展能力。现在市面上已经出现了非常多实用的 MCP Server，覆盖了数据库查询、设计稿标注、云服务操作、协作办公工具等场景。你只需要在配置里追加一行，Agent 就多了一项技能。

我最近在沙箱里接了一个团队协作工具类 MCP，让 Agent 能读取项目需求文档并自动提取验收标准。配合沙箱里的代码和测试环境，它可以更准确地判断一个需求是否被真正实现。这其实就是把“需求理解”和“开发验证”打通的关键一步。

多 Agent 协同也是一个趋势。你可以同时跑两个沙箱实例，一个负责代码开发，一个负责测试验证，它们各自有独立的浏览器和文件系统，互不干扰。由于所有操作都通过 MCP 标准化，两个 Agent 之间共享状态的成本很低，共享一个挂载卷就能完成交付物传递。

5. 常见问题与排查方案：我在沙箱环境里踩过的五个坑

5.1 端口被占用和重复启动

这是最常碰到的问题。宿主机上已经有一个服务占了 8080 端口，你再启动容器就会报错。排查时先看容器状态和端口监听：

docker ps -a --filter name=aio-sandbox lsof -i :8080

如果确认是端口冲突，最简单的做法是换一个宿主端口映射，比如18080:8080。还有一个容易被忽略的情况：容器已经存在但没删除，再次docker run会直接报 name 冲突。处理方式就两条，要么删掉重建，要么docker start复重用旧的容器。

5.2 挂载目录与宿主机 UID 权限冲突

这个问题在 Linux 上特别典型。你在宿主机当前用户的 UID 是 1000，容器里默认用户也是 1000，基本没问题。但如果你在容器里用 root 创建了一堆文件，这些文件在宿主机上就归 root 所有，普通用户删不掉。反过来也成立。

我踩过的坑是：Agent 在容器里生成了一堆日志和构建产物，全部归 root，宿主机上我只能用 sudo 清理。解决办法有两个方向：一是启动容器时映射当前用户进容器，二是把工作目录的属主改成与容器内用户一致的 UID。哪种都行，关键是提前想清楚，别等到文件一堆了再头疼。

5.3 浏览器标签页一多就卡死

浏览器是沙箱里的资源大户。虽然前面加了--shm-size=1g，但你要是一次开十个标签页，4GB 内存的沙箱照样扛不住。故障现象一般是页面变得极慢，再严重一点浏览器进程直接被系统 OOM Kill。

我的经验是给浏览器并发设上限，建议同时打开的标签页不要超过 5 个。如果你用 Playwright MCP，可以在配置里限制最大页面数。另外，做批量页面抓取时，记得每处理完一个页面就主动关闭，把资源释放出来。

5.4 MCP 连接超时和依赖安装失败

MCP Server 连接超时这个坑，排查起来容易走弯路。因为 MCP Server 是独立进程，Agent 框架和它之间的连接需要握手，一旦握手超时，Agent 就会报错。先确认 MCP 进程是否真的在运行，再确认协议传输方式是否匹配。

还有就是 npx 首次运行会去下载包，网络如果不稳定就会一直卡住。我的建议是在容器内先手动执行一次npx @playwright/mcp@latest --version这类命令，确认依赖已经缓存到本地，再让 Agent 去调用。这相当于给 Agent 把路铺好，它就不会因为网络抖动而失败。

5.5 镜像体积和启动速度的取舍

说实话，AIO Sandbox 这类全量镜像体积不小，拉取一次可能要等几分钟。我见过有人因此放弃使用，这其实大可不必。你可以把镜像长期保留在本地，不要反复docker rmi；或者在自己的私有仓库里维护一个定制版，去掉用不到的语言运行时，体积能减不少。

启动速度方面，服务器上快的能做到 3 到 5 秒内进入可用状态。如果你需要更快的冷启动，可以考虑预热镜像，就是提前把容器拉起来放在那边 idle，需要时直接复用，能省掉镜像加载和初始化进程的时间。

6. 我对 AIO Sandbox 的实际感受与配置建议

项目用了两三周之后，我最大的体会是：AIO Sandbox 这类工具真正改变的，不是“多了一个软件”，而是把 Agent 开发的工作重心从“环境运维”拉回了“逻辑设计”。以前写 Agent 应用，一半时间在处理环境问题，一半时间在写业务逻辑；现在几乎可以把全部精力放在 Agent 的任务编排和工具适配界面上。

我的另一个感受是，它特别适合做教学场景。把 AIO Sandbox 直接分发给初学者，对方不需要配置任何本地依赖就能看到 Agent 的真实工作过程，浏览器怎么被控制、命令怎么被执行、文件怎么被修改，都一目了然。这种“看得见的 Agent”对建立直觉非常有帮助。

最后分享一个我个人觉得特别好用的配置习惯：把沙箱里的工作目录直接在 VSCode 中打开并固定为一个多根工作区，再把 Agent 的日志输出重定向到工作区下的logs/app.log。这样每次调试时，VSCode 的终端和日志面板并排显示，Agent 执行到哪一步、卡在什么地方，一眼就能定位。如果你也在折腾 Agent 沙箱环境，建议试试这种组合方式，大概率能让你的调试体验提升一个台阶。