1. 整体设计思路存储、隔离、协议为什么必须放一起讲1.1 第二篇先交代上下文省得后面看不懂这个系列聊的是一个偏个人向的 AI 助手/Agent 网关项目第一篇讲的是总体架构和消息路由。这一篇我专门把存储后端、沙盒隔离、MCP 三个模块拎出来放一起聊原因很简单这三块直接决定了助手能不能记住东西、敢不敢动手干活、以及门外的人能不能轻松接入。很多朋友做 AI 应用上来先问用哪个模型模型当然重要但真正让一个助手从demo 玩具变成可以天天用的往往是它背后这层基础设施。我做过几个项目之后最大的体感是模型决定天花板存储、隔离、协议这三样决定地板。地板的洞补不好天花板再高也白搭。先交代一下项目背景这个助手不是 Web 聊天框而是一个常驻本机的 Agent能读文件、查资料、操作浏览器、调外部 API。所以存储后端负责记忆从哪来、往哪去沙盒隔离负责工具在什么边界内运行MCP 负责工具用什么样的话跟模型交流。这三者拼在一起才是完整的一张图。1.2 一条主线AI 助手的边界取决于它能安全地碰到什么我做这个系列第一篇时就定了一条主线一个合格的 Agent不只要会聊天更要会干活。干活意味着它有权限触碰外部世界而权限触碰外部世界就意味着风险。你让模型生成一段文字不难难的是让它去你的文件系统里删一个文件、帮你在浏览器上下单、或者调一个部署在某处的 API。这些动作一旦放出去就要有人回答三个问题干完的活记录在哪干活的进程被关在哪个笼子里干活之前用什么样的协议确认这活儿是模型自己要干还是它被网页上的一段恶意内容骗着干的存储、隔离、协议恰好对应这三个问题。所以我才坚持把它们放在同一篇里讲而不是拆成三篇独立的教程。单独看任何一个都行但只有把三者放到同一个设计约束下你才能真正理解为什么这样选型、为什么留这样的幂等钩子、为什么 MCP Server 要跑在沙盒里而不是本机裸奔。1.3 设计哲学的起点克制、可观测、可回滚每次做架构设计我习惯先把设计哲学写下来不然到后面很容易被各种花活带跑偏。这个项目我定的是六个字克制、可观测、可回滚。克制指默认拒绝而不是默认允许。新的工具、新的存储权限、新的 MCP Server一律先关着用到了再开用完再关。这个原则在后面沙盒隔离那一节会反复出现。可观测指每一步动作都要有日志、有记录。模型调了什么工具、工具传了什么参数、返回了什么内容、存进了哪个表、花了多少 token全部要能看到。否则出了问题你只能盯着黑盒猜。可回滚指任何一次写入都要有撤销的路径。文件先备份再改数据库记录留带版本浏览器操作尽量用无痕环境。这三条不是口号是我实际做选型时拿来做否决权的任何一个方案如果能满足这三条优先选不能满足就要解释清楚。2. 存储后端别急着上向量库先把数据落地方案定下来2.1 存储后端决定的是记忆的形态不只是数据放哪里的问题直接说结论个人助手的存储别一上来就整 Kafka、Elasticsearch 那种大件。你要解决的是这个助手能不能记住上次聊到哪了、能不能在下次对话时召回相关笔记、能不能留下操作审计日志这些需求用一套分层文件存储就能覆盖九成。我在这个项目里把存储分成了四层第一层是原始日志目录存所有未加工的对话记录和工具调用流水用 JSON Lines 格式一行一条方便回溯。第二层是结构化数据库SQLite 起步存用户信息、会话索引、工具调用结果摘要。第三层是向量索引接一个本地的向量库用来做语义召回。第四层是文件仓库存 Agent 帮忙处理过的文件以及各类导出的产物。这个分层的逻辑是日志负责审计数据库负责查询向量库负责联想文件仓库负责交付物。每一层的存储策略都不一样你不能要求一个东西同时满足四种需求那是过度设计。2.2 为什么我选 SQLite 而不是 PG 或者 Redis很多朋友问为什么不用 PostgreSQL答案是个人的单机助手SQLite 完全够而且运维成本几乎为零。SQLite 的事务、索引、JSON 支持都很成熟WAL 模式下一万条消息级别的读写毫无压力。它唯一的短板是并发写但个人助手根本不会出现几十个进程同时写库的场景。Redis 我也试过当时是想把会话状态放内存里图它快。后来发现一个问题进程一重启会话状态全没了。你当然可以开 AOF 持久化但那就又多了一个要维护的存储源。最后我的方案是Redis 只做临时缓存和分布式锁真正的会话状态全部落 SQLite。缓存丢了可以重建状态丢了就真要命了。这里要给一个实操上的提醒SQLite 单文件看着简单但并发写和连接管理要处理清楚。我踩过最典型的一个坑是多个 Python 进程同时 open 同一个 SQLite 文件出现 database is locked。解法没那么玄学打开PRAGMA journal_modeWAL;然后所有写操作走同一个写队列读操作可以放开。我用的是一个简单的单线程写者模式实测下来很稳。2.3 向量索引的选型先小后大不要过度投入向量库这块我见过太多人一上来就部署 Milvus、Weaviate结果数据量只有几千条资源吃了几 GB。个人项目我建议从更轻量的方案起步。我实际用的是 SQLite sqlite-vec插件把文本向量直接存在一张表里。为什么要这么干因为我可以把向量和原始文本、业务字段放在同一个事务里写一致性特别好不用维护两套存储之间的同步。当数据量真的大到几百万条再迁移到 Chroma 或者 Qdrant 也不迟先把接口抽象好就行。接口抽象这件事我会在 4.3 节展开说。这里只强调一句存储后端一定要藏在接口后面业务代码只依赖save_memory()、search_memory()这种操作不依赖具体某家数据库。这样你从 SQLite 迁到 Postgres、从文件向量库迁到云向量库都只是替换一个实现类而不是重写整个业务。2.4 备份策略本地优先的取舍个人助手的数据最重要的一点是本地优先。所有核心数据都落在本机云服务只做同步副本不同步的话单机也可以用。这样的好处是离线可用、隐私可控坏处是你要自己想备份方案。我的方案非常朴素每天凌晨用sqlite3 .backup把三个关键库打包一次保留最近 7 天文件仓库用 rsync 增量同步到另一块磁盘向量索引不单独备份丢了可以从原始文本重新生成。算下来一台小主机一个星期产生的数据量也就几百 MB根本不需要复杂的备份系统。这里有一个容易被忽略的点备份完之后一定要偶尔真真正正地恢复一次。光有备份任务在跑从来不验证恢复等于没有备份。我因为这个吃过亏某次数据库文件损坏恢复出来的库半年前的数据是空的整个过程没有任何报错只是静默失败。从那以后我每周都会手动跑一次恢复演练确认备份不是形式主义。3. 沙盒隔离给 Agent 套上可控的笼子3.1 为什么要隔离MCP 工具不是函数调用是边界突破在做 MCP 接入之前我对工具调用的认知是模型发一个 JSON代码在同一个进程里执行一个函数。这种模式写 demo 很舒服但一上生产就心慌——因为工具执行环境跟主进程共享了全部文件系统、网络和权限。举个例子你接了一个读取网页内容的 MCP Server这个工具内部用 Playwright 渲染页面并抓取正文。看起来只是读网页但坏网页完全可以在页面上放一段带 prompt injection 的内容诱导模型去调用另一个工具比如读取本地 ~/.ssh/id_rsa 并发送出去。如果所有工具都在同一个进程里这种攻击链路是真能走通的。所以沙盒隔离不是可有可无的加固项而是 MCP 架构里必须的一层。我自己定的原则是凡是会接触不受信任输入的 MCP Server一律不能直接跑在主进程里必须隔离到沙盒中。3.2 三层隔离进程层、容器层、浏览器层我实践下来把隔离拆成三层来做比较合理。第一层是进程层MCP Server 用子进程方式启动跟主进程只通过 stdio 通信。这样即使 Server 挂了主进程不会跟着挂同时主进程可以精确控制子进程的资源配额比如 CPU 时间、内存上限、文件描述符数量。这一层最基础但也最容易被忽略——很多人把 MCP Server 写进主进程里当模块 import那就完全没有进程边界了。第二层是容器层用 Docker 或者 Podman 把每一个不受信任的 MCP Server 包起来。容器提供文件系统隔离Server 想读宿主机的/etc、~/默认是读不到的除非你显式挂载。这在多租户或多人共用的系统里尤其重要。第三层是浏览器层凡是涉及网页渲染的工具比如 Playwright MCP、Chrome DevTools MCP要在浏览器层面再做一道隔离。这里最实用的做法是每次任务开一个新的浏览器上下文用无痕模式用完直接销毁不留 Cookies、不写浏览历史。这样即使网页里真的藏了攻击载荷它能碰到的也只有一个临时的空浏览器环境。3.3 实操把 MCP Server 跑进 Docker 的具体配置讲点可以直接抄的配置。我用的 Compose 文件大致是这样services: mcp-browser: image: mcp/playwright:latest init: true read_only: true tmpfs: - /tmp - /home/pptruser/.cache cap_drop: - ALL security_opt: - no-new-privileges:true pids_limit: 256 mem_limit: 512m cpu_quota: 50000 networks: - mcp-egress command: [node, dist/index.js]几个关键点解释一下read_only: true意思是容器根文件系统只读任何试图写入系统目录的操作都会直接失败。tmpfs给浏览器留了缓存和临时文件的空间但又不落盘。cap_drop: ALL加上no-new-privileges保证容器内拿不到 Linux 内核的扩展能力这是反容器逃逸的基本操作。pids_limit限制进程数防止浏览器开一百个子进程把你的机器拖死。网络这里单独挂了一个 egress 网我待会说为什么。这套配置跑 Playwright 和 Chromium 完全没问题。实测一个渲染网页 截图的 MCP Server内存峰值大概在 300MB 左右512M 的限额够用但不算宽裕留了余量。3.4 网络隔离默认断网按需放行网络隔离是我特别想强调的一点。很多沙盒方案做了文件系统隔离却忽略了网络结果容器里的进程还是可以随便访问内网、访问元数据服务、访问任意公网地址。对 Agent 来说网络权限等于操作权限的一部分必须逐条收权。我试过的做法是默认创建一个没有任何外网路由的 Docker 网络只允许容器访问宿主机上的 MCP 网关端口需要访问公网的 Server单独加一个mcp-egress网络并且在宿主机上画一条 NAT 规则把出口 IP 固定到一台代理上。这样任何容器里的可疑流量都能在代理日志里被记录下来。这一步看着麻烦但对能不碰就不碰的个人项目来说其实成本极低。你不需要上什么复杂的零信任产品Docker 自带的能力加上 iptables 几条规则就能搭出一套可以审计的边界。而且这也呼应了设计哲学里的可观测——如果你连网络出口日志都没有出了问题根本没法溯源。4. MCP 协议工具接入的普通话4.1 MCP 是什么为什么它值得成为默认选择如果你还没用过 MCP先用一句话理解MCPModel Context Protocol是一个模型上下文协议它规定了大模型应用如何以统一的方式发现、调用外部工具和数据资源。过去每个 AI 应用都要跟每种工具做一套专属集成有了 MCP你只需要为工具写一个标准接口任何支持 MCP 的客户端都能直接使用。为什么叫普通话因为以前各家的 AI 应用互相不认对方的插件协议张三的助理只能调张三写的函数李四的编辑器只能调李四写的插件。现在大家商量好一套共同语言工具也好、数据源也好、提示词模板也好都通过这套语音表达。这不是什么魔法本质上是把工具集成从点对点变成了一对多。在我这个项目里MCP 的角色是所有外部能力——文件系统、浏览器、API 查询、本地应用——全部包装成 MCP Server。模型侧不需要知道这些工具内部是用 Python 写的还是 Node 写的也不需要知道它们跑在哪个沙盒里它只需要知道每个 MCP Server 暴露了哪些 Tools、哪些 Resources、哪些 Prompts。4.2 MCP 的三类能力Tools、Resources、Prompts具体到协议层面MCP Server 对外暴露的能力分三类搞清这三类的边界写 Server 时思路会特别顺。Tools 是可执行的动作比如搜索文件打开网页执行 SQL 查询。它们会修改状态、产生副作用所以在客户端侧需要用户授权不能由模型默默调用。Resources 是只读的数据比如一个文件的内容、一个数据库的 schema、一篇文档。它们回答有什么可看的问题客户端可以按需读取。Prompts 是预定义的提示模板目的是让固定场景下的交互更稳定比如总结这个文件生成周报。我在实践中最常犯的一个错是把所有东西都塞进 Tools。后来想通了能做成 Resource 的尽量做成 Resource因为资源的读取走协议原生的缓存和权限管理比硬编码工具参数安全得多。比如读取笔记这种事用 Resource 暴露一个note://前缀的 URI 集客户端天然能支持收藏和批量拉取而用 Tool 做就只能每次手动传参数。4.3 从零起一个 MCP Server一个最小可用的例子直接上代码。下面这个 Python 例子用一个官方 SDK 实现一个最小 MCP Server它只暴露一个获取当前时间的 Toolfrom mcp.server.fastmcp import FastMCP from datetime import datetime mcp FastMCP(time-server) mcp.tool() def current_time(timezone: str Asia/Shanghai) - str: 获取指定时区的当前时间。 # 这里省略时区转换细节body 里调用 datetime.now() 即可 return datetime.now().astimezone().isoformat() if __name__ __main__: mcp.run(transportstdio)看到没有一个 Tool 就是不到十行代码。FastMCP帮我们处理了传输层、JSON-RPC 封装、参数校验这些脏活。跑起来之后任何支持 MCP 的客户端都可以连上去客户端看到的工具名是current_time描述是获取指定时区的当前时间模型就能根据用户的自然语言请求自动决定要不要调用它。这里要说一下我建议的工具命名习惯名字做到动词 名词描述里写清楚用途、参数含义、可能的副作用。因为模型是靠描述决定调不调用的描述写得好不好直接决定调用准确率。我在项目里发现同一个工具描述写详细和写简略触发准确率能差出 20 个百分点。4.4 客户端接入权限确认是必须的一步MCP 的传输方式主要有两种一种是stdio适合本地进程间通信Server 由客户端拉起另一种是 HTTP/SSE 或者 Streamable HTTP适合远程服务。我这个项目的网关两种都支持本地工具用 stdio远程工具走 HTTP。但不管哪种传输客户端接入时都少不了一道权限确认流程。也就是说当模型请求调用某个 Tool 时客户端不能直接放行至少要弹一次授权确认或者走用户预设的规则白名单。这一点我在设计哲学里说过默认拒绝。哪怕麻烦一点也绝对不能把模型想干什么就干什么当成默认行为。接入实战里还有一个细节MCP 连接断开之后要能自动重连且状态要可恢复。我踩过一个坑——某个远程 MCP Server 因为网络抖动断开网关没有实现重连逻辑结果模型一脸茫然地说工具不可用。后来我加了一个带退避指数的重连机制问题就消失了。这也解释了为什么要可观测如果没有日志你根本不知道是网络断的还是 Server 崩的还是权限被拦的。5. 常见问题与排查技巧实录5.1 MCP 连接失败先分方向再查协议MCP 连接出问题是我被问得最多的一类。我一般先让人按三个方向排查客户端能不能连上 Server协议层有没有报错模型有没有拿到正确的工具列表用stdio传输时最常见的问题是路径写错或者启动命令的工作目录不对。很多 MCP 客户端允许你配置command和args但不会告诉你默认在哪个目录下启动子进程。我建议所有路径都写成绝对路径或者写成一个启动脚本把环境变量都设好再拉起 Server能省掉大量调试时间。如果是 HTTP 传输重点看两件事鉴权头和超时配置。有些 Server 需要Authorization头有些要求建立会话后再握手。协议的报错信息一般都比较直白但如果你把日志级别设为 DEBUG开机就能看到 JSON-RPC 的具体报文很多问题一眼就能定位。最后还有一个小技巧先不要接模型用 MCP Inspector 这类调试工具直接连 Server看 Tools/Resources 列表是否正常。如果直连都不通问题一定在 Server 端如果直连通但模型用不了再去怀疑模型配置和授权策略。这个排查顺序能帮你省下至少一半的无效时间。5.2 沙盒里跑浏览器自动化三个真实踩过的坑第一个坑是 Chromium 在 Docker 里跑起来没声音、显示崩溃因为缺少依赖库。read_only镜像加上最小基镜像很容易缺字体、缺libnss3一类的东西。解法是做一个专用镜像把 Chromium 需要的系统依赖提前装好不要用通用的 node 镜像硬凑。第二个坑是容器内存限额导致浏览器直接被杀。Playwright 启动 Chromium 的初始内存消耗比我预期的大特别是一次性渲染多个页面时。后来我把mem_limit提高到 512m并且用tmpfs挂载浏览器缓存目录才稳定下来。不要小看浏览器这个胖客户端它对资源的要求远高于一般 Node 进程。第三个坑是网络策略太死导致 Playwright 无法访问网页。我前面提到mcp-egress网络实际调试时就发现出站代理的 DNS 解析需要额外放行否则页面一直超时。这个教训是网络隔离一定要留一条可观测的调试通道建议先跑通再收紧不要一上来就把所有出口关死否则你连排查问题的入口都没有。5.3 存储读写的性能问题先用慢日志说话存储性能出了问题我第一反应不是调参数而是先看慢日志。SQLite 端我开启dbstat或者建一个临时表记录超过 100ms 的查询。向量库端我记录每个查询的耗时和召回条数看看是不是数据量增长后 KDTree 退化成了全量扫描。实践证明大部分性能问题不是引擎慢而是设计问题比如查询没走索引、每次请求都打开一个新的连接、全表扫描大 JSON 字段。我在项目里修过最典型的一处搜索历史记录时WHERE子句里用LIKE %关键词%直接扫全表一万条数据就卡到几秒。后来改成用倒排索引或者向量召回同样的查询毫秒级返回。还有一条经验永远不要在生产环境用多线程直接写同一个 SQLite 文件。我之前看到有人说 WAL 模式可以多线程并发写理论上没错但现实中队列满了照样锁库。最稳的方案就是单写者 消息队列写操作全部串行读操作走副本。这个方案也许不够炫酷但它稳定省心。5.4 给常见问题做一张速查表症状最常见原因排查顺序MCP 工具列表为空传输路径错误或鉴权失败先用调试工具直连 Server再看客户端配置模型报工具不存在Server 返回的列表被客户端过滤检查授权策略、白名单、版本缓存容器内 Chromium 崩溃缺少系统依赖或内存限额不足检查容器日志逐步提高 mem_limit网页访问超时出站代理 / DNS 未放行关闭 egress 限制测试确认后再收紧SQLite 写入锁库多进程并发写同一文件开启 WAL改单写者模式向量召回结果无意义分块策略或 embedding 模型不合适检查分块大小、相似度阈值、索引刷新这张表不是全量字典但覆盖了我自己踩过的大部分坑照着排查通常能解决八成问题。剩下两成就得靠日志慢慢啃了。关于这套设计我再说几句体己话这个项目做到今天最大的感受是架构里那些不性感的部分才是真正决定长期体验的部分。存储、隔离、协议听起来没有让模型更聪明那么带感但它们决定了你的 Agent 敢不敢放开手脚干活。如果只能留一条经验我会说把安全默认写进代码里而不是写在文档里。用户授权、沙盒限制、网络放行这些规则应该是默认生效的任何例外都要显式配置。我见过太多项目的安全策略只存在于设计文档代码里为了方便全部放开结果出事的概率直接翻倍。另一个小建议是MCP Server 的日志一定要认真设计。不要只打一行server started要把每一次工具调用、参数摘要、耗时、结果大小全部打出来。这套日志不但是调试的命根子也是你衡量这个工具到底值不值得让模型用的数据来源。这个系列后面我还会写模型路由、记忆优化、权限管理这几个模块的具体实现。如果你也在做类似的个人 Agent 项目欢迎按这套思路先去把存储和隔离做扎实再来聊怎么让模型更聪明——顺序反了后面补功课的成本会高很多。