1. 从“手机写代码”开始这可不是个伪需求先说个真实场景。去年夏天我在外地出差客户现场出了个紧急 bug线上环境里某个接口突然超时。我身边只有一部手机和一台借来的 Windows 笔记本连开发环境都没装。当时满脑子就一个想法要是能在手机浏览器里直接打开项目、改一行代码、点一下部署哪会有这种尴尬。这不是个别现象。身边越来越多的朋友开始用 iPad 或者安卓平板处理轻量开发任务——不是重度重构而是改个配置、修个文案、看个日志、调个参数。传统的做法是自己装一个 Termux再配 SSH 连远程服务器靠 Vim 或者 VS Code Remote 撑着。这套东西能用但门槛实在不低对网络环境、终端模拟器的稳定性、键盘映射都有要求。更别说多人协同、一键预览、AI 辅助这些现代开发刚需在纯终端方案里基本是奢望。所以后来我干脆做了个实验项目代号就叫 WebCode。目标很简单粗暴让用户打开一个网页像用桌面 IDE 一样写代码后端自动分配一个完整的开发容器代码实时受控、自动提示、随时预览并且把 AI 能力直接塞进编辑器里。这个项目从最开始的“手机上跑代码”的疯狂想法逐步长成了一整套 AI 编程平台。这篇文章就把整个架构思路、技术选型、落地过程中踩过的坑从头到尾拆给你看。要提前说明的是下面的架构描述是基于我个人以及同行在同类项目中普遍采用的方案结合 WebCode 的项目定位做的合理梳理不是某一家公司的官方文档。但这些设计思路绝对都是实战沉淀下来的适合想在 Web IDE 和 AI 编程平台方向上动手的同学参考。2. 平台定位与技术选型先想清楚“边界”在哪里2.1 WebCode 到底解决什么问题很多人一听“WebCode”第一反应是“又一个云 IDE”。这个理解只对了一半。云 IDE 的鼻祖如 Cloud9、CodeSandbox、GitHub Codespaces确实解决了“远程开发环境”的问题但它们天然偏重“完整开发环境模拟”。WebCode 的差异化定位更偏向“轻量级 AI 原生编程工作台”不只是给你一个终端和编辑器更强调从需求的语义理解到代码生成、从自动修复到一键部署的完整闭环。换句话说WebCode 不是替代你电脑上的 JetBrains而是让“没有电脑环境”的人也能跟上开发节奏同时让有电脑的人多一个“随时随地下发任务、查看结果、介入修复”的入口。围绕这个定位技术选型的核心约束有三个终端适配要广泛Web 是天然跨平台方案手机平板桌面都能跑后端环境必须隔离每个项目要有独立的运行时不能互相干扰AI 能力不是外挂而是编辑器体系里的“一等公民”2.2 前后端与基础设施的选型逻辑前端选型上我没有走“拉一个 VS Code Web 版然后魔改”的路线。VS Code Web 尽管成熟但它自带一套非常厚重的扩展机制和 UI 框架在手机端的触摸交互、虚拟键盘弹出、小屏布局适配上都比较僵硬。自己基于 Monaco Editor 从零搭建编辑器壳反而能更自由地控制交互模型。Monaco 是 VS Code 的核心编辑器组件它具备语法高亮、智能提示、多光标编辑、Diff 预览等能力而且支持在浏览器里直接跑是构建 Web IDE 的最优选。后端服务这块我选了 Node.js 的 NestJS 作为主框架。NestJS 的模块化约束特别适合这种“一个平台里横跨项目管理、容器调度、AI 网关、协同服务”的中型系统。它天然支持依赖注入、消息队列接入、WebSocket 网关而且 TypeScript 全栈让前后端能共享类型定义。容器调度层用的是 Kubernetes 加自研的 Runner Manager。每个项目在服务端创建一个隔离的 Pod里面预装 Node、Python、Go、Java 这些常用运行时用户编辑的代码实时同步到 Pod 内通过虚拟终端和端口映射对外提供预览服务。数据库选型比较常规PostgreSQL 存储用户、项目、成员关系等结构化数据Redis 承担在线状态、会话缓存、频率控制这些短期数据对象存储放项目快照和构建产物。文件实时同步不走数据库而是走分布式的文件事件总线。2.3 为什么一定要做“AI 原生”而不是“AI 接入”市面上很多云 IDE 也有 AI 功能但基本上是“编辑器 一个聊天窗口”的拼凑。WebCode 的架构从第一天起就把 AI 编排层作为独立核心模块来设计。原因很简单AI 能力在编程场景里不是单一能力而是由代码补全、语义搜索、代码解释、Bug 修复、测试生成、提交信息生成等一系列能力组成的复杂系统。如果每一个能力都单独接模型、单独写逻辑后面一定会乱成一锅粥。3. 整体架构解析一张没有画出来的全景图3.1 五层架构从上到下怎么划分WebCode 平台的架构可以概括为五层客户端层面向 Web 浏览器的单页应用包含编辑器、终端、文件树、预览面板、AI 对话面板接入层统一 API 网关负责鉴权、路由、限流、WebSocket 连接升级业务服务层项目服务、用户服务、协同服务、AI 网关服务、计费与配额服务基础设施层Kubernetes 集群、对象存储、PostgreSQL、Redis、消息队列AI 模型层文本补全模型、对话模型、Embedding 模型、代码解析服务这里要特别强调的是“接入层”和“AI 模型层”之间的解耦。接入层只负责“把人/代码的请求递给合适的服务”它不关心具体是哪个 AI 模型在处理请求。AI 模型层是一个独立的 Proxy所有模型调用都通过抽象接口走后续无论是换模型供应商、调整模型版本、还是做私有化部署都只需要改动 Proxy 这一层。3.2 典型请求链路从编辑到补全的全过程很多人问在 WebCode 里按一下回车编辑器是怎么知道下一个该补全什么的这条链路看起来简单实际涉及好几个环节。第一步前端编辑器监听输入事件把当前文件的路径、光标位置、最近的代码上下文打包成一个请求。这个请求不是直接发给 AI 模型而是发给 WebCode 的即时补全网关。第二步补全网关在拿到请求后先做两件事。第一根据文件后缀和代码内容判断语言类型从而决定用哪个补全模型和补全参数。第二检查用户当前的套餐配额和模型路由策略比如是走开源模型还是商业大模型。第三步补全网关调用底层模型拿到若干个候选补全片段按概率排序后返回。前端拿到结果后会先做一次缩进和对齐修正再显示为灰色幽灵文本。整个过程我们要控制在 200 毫秒以内返回首个 token不然体感就明显卡顿。3.3 事件驱动架构为什么选择“异步总线”而不是“同步调用”WebCode 中文件保存、容器启停、模型调用、协同编辑这些动作天然是异步的。如果全用同步 HTTP 调用一个操作动辄要等几百毫秒甚至几秒用户体验会很差。所以在业务服务层里我引入了一个轻量级的消息总线核心事件包括project.updated项目配置变更触发容器重建或重启file.changed文件保存触发类型检查、测试运行、AI 审查container.status容器生命周期变化记录状态机ai.task.createdAI 异步任务如代码评审、长文本生成已提交每个服务通过订阅这些事件来驱动自己的业务逻辑。这个事件驱动架构在后期加功能时节省了大量成本。比如后来要新增“CI 自动检查”我只需要写一个监听 file.changed 事件的服务而不用去改编辑器的保存逻辑。4. 核心难点一文件同步与协同编辑机制4.1 从“保存后上传”到“实时受控同步”的演进第一版 WebCode 的文件同步逻辑很简单编辑器里点了保存就把整个文件内容 POST 到后端后端再写入容器。这个方案在文件小、单人编辑的情况下没太大问题一旦文件超过几百 KB 或者多人同时编辑问题就来了。首先是网络开销。一个 1MB 的文件每次保存都全量上传一次就要浪费几 MB 流量在手机网络环境下体验极差。其次是冲突两个人同时改一个文件后保存的人会把前面的人覆盖掉。后来我引入了类似 OTOperational Transformation的思路但做了一些简化。前端编辑器每次变更不再直接上传完整文件而是生成一组变更块每个变更块包含起始位置、删除长度、插入文本。后端的协同服务会把变更块转换成一种中间格式追加到文件版本记录里同时广播给当前项目里其他在线编辑者。这个方案把同步粒度从“文件级”降到了“操作级”网络负载显著下降。4.2 CRDT 还是 OT我的实际选择做协同编辑绕不开 CRDT 和 OT 之争。CRDT 的优点是天然支持无中心化并发合并不需要服务端做太多逻辑适合文档类产品。OT 需要中心服务器做转换逻辑但控制能力强适合对操作顺序有严格要求的环境。WebCode 最后选的是 OT 的简化变体。我没有用非常严格的 OT 算法比如 Google Wave 那种而是基于 Yjs 底层的 YATA 算法做了二次封装。Yjs 虽然本质上是 CRDT但它也暴露了操作转换和撤销重做的接口用惯了之后会发现它在真实编辑器场景里很顺手。具体的实现流程是前端 Monaco Editor 每次变更通过一个监听器把操作映射成 Yjs 的 Y.Text 更新然后在本地应用。Yjs 的更新包通过 WebSocket 发送给协同服务协同服务负责把更新包转发给同一文档的其他在线用户。由于 Yjs 自带了冲突解决逻辑即使两个用户同时改同一段代码也能合并出一个合理的结果不会出现内容互相覆盖。4.3 离线编辑与回放机制移动端网络不稳定离线编辑是刚需。我实现的方案是把 Yjs 的更新记录存储在浏览器 IndexedDB 里网络断开时编辑操作先写入本地网络恢复后重放所有离线更新。为了让用户在“断网”期间也能获得基本的语法高亮和关键字补全我在本地缓存了当前打开文件的整个文本以及当前文件语言的关键字列表。5. 核心难点二AI Agent 与编程工作流的深度融合5.1 编辑器内的 AI 能力矩阵WebCode 里的 AI 能力不是单一入口我设计了一个能力矩阵覆盖了开发者在不同阶段的需求。从日常写代码的角度说最常用的是行内补全。行内补全由独立的补全服务承载延迟要求高但上下文长度需求小。往上一个层级是代码对话开发者可以选中一段代码让模型解释它做了什么、有什么隐患或者直接对选中内容提需求。再往上一层是代码评审文件保存后会自动触发一次差异审查模型会给出潜在 bug、性能隐患、风格建议。这三个层级共享同一个 AI 网关但对模型选择和参数配置完全不同。代码补全我倾向于用参数量小但推理速度快的模型比如某种基于代码语料微调的 7B~14B 模型对话和审查则使用更大的模型毕竟这两个场面对推理质量的要求更高。5.2 Agent 架构从“单次调用”到“多步任务”当需求不只是“补全一行代码”而是“帮我加一个用户登录模块”单次模型调用根本不够。这时候就需要 Agent 架构。WebCode 的 Agent 层遵循了一个比较经典的三段式设计Planner、Executor、Verifier。Planner 负责拆解任务比如“登录模块”会被拆成“设计用户数据表”“实现接口”“编写前端页面”“配置路由”四个子任务。Executor 负责逐个执行子任务它不是一个固定的代码生成器而是一个能调用工具的动态 runner。Verifier 负责测试和反馈每个子任务执行完后Agent 会运行对应的测试或者代码检查如果验证失败就重新回到 Executor 调整。Executor 这个环节是最复杂的。它不能像 ChatGPT 那样只在对话框里吐代码而是要真实操作项目文件。为此我实现了一个“沙箱文件操作”的接口Agent 可以通过工具调用在项目工作区创建、修改、删除文件。关键的一步是在每次写入前做一次 AST 级别的语法检查宁可执行失败也不允许写入明显损坏的代码。5.3 上下文管理Agent 的“记忆”怎么不丢LLM 的上下文窗口有限一个大型项目动辄几百个文件Agent 不可能全部读进来。我实际采用的是“分而治之”的上下文管理层。具体做法是建立项目索引把每个文件的函数、类、接口定义通过 AST 解析后存储到向量数据库中。当 Agent 需要执行一个任务时不是读所有文件而是通过语义搜索找出与当前任务最相关的 10~15 个代码片段将这些片段拼接成上下文。这种设计让 Agent 在面对大型项目时也能保持比较高的准确性而且每次调用消耗的 token 数不会无限制膨胀。5.4 自主编程的边界什么时候该停下来问人AI 编程平台最容易犯的错是“过度自主”Agent 闷头改代码改到最后人都不知道改了什么。WebCode 里我加了一个“人工介入闸门”机制和高风险操作审批类似。当 Agent 准备执行以下操作之一时会暂停并等待用户确认删除文件批量重命名文件修改依赖清单改动数据库迁移文件。这四个操作都具备“不可逆”或“影响面大”的特征让 Agent 自己做主风险太高。6. 核心难点三容器化开发环境的调度与网络打通6.1 为什么不用“大而全”的开发镜像第一版我打包了一个“全家桶”镜像把 Node、Python、Java、Go、Ruby 全塞进去想着省事。结果镜像体积超过 3GB拉取速度极慢容器启动一次要一两分钟开发体验一路下跌。后来改成了“按需加载基础镜像 初始化脚本”的方案。每个项目创建时根据项目技术栈生成一个轻量基础镜像比如一个 Python 后端项目只包含 Python 3.12 和 pip 相关的环境而不装 Java。项目初始化时通过一个 setup.sh 脚本安装依赖这个过程用异步任务执行前端会显示一个进度条。6.2 Runner Manager容器的“生命周期管家”Runner Manager 是 WebCode 基础设施里的一个常驻服务。它负责三件事创建容器、监控容器、销毁容器。创建容器的流程是用户点击“启动环境”业务服务层发一个消息到 Runner Manager 的队列Runner Manager 从镜像仓库拉取对应镜像调用 Kubernetes API 创建一个 Deployment同时创建对应的 Service 和 Ingress 路由。创建成功后Runner Manager 返回一个访问地址前端用它来建立终端 WebSocket 连接和预览 HTTP 连接。监控部分利用了 Kubernetes 的 liveness 和 readiness 探针。每个容器里跑了一个轻量的 agent 进程负责上报 CPU、内存、磁盘占用以及当前运行中的开发服务器进程列表。这些数据会通过 WebSocket 直接推送到前端在状态栏里展示。销毁容器分主动和被动两种情况。主动销毁是用户显式点击停止被动销毁有一个超时回收机制容器如果持续 30 分钟没有活跃会话就会自动暂停防止资源被无意义地占用。6.3 端口转发与预览让手机也能看效果网页开发的预览功能看似简单——后端容器里跑了一个 dev server前端这边加一个 iframe 指向它。但实际有一个老大的障碍跨域和安全策略。我在接入网关层做了一个“端口代理”模块把容器内的任意端口映射成一个 WebCode 域名下的子路径通过反向代理转发内部流量。这个方案的优点是前端不用处理繁琐的 CORS 配置所有预览请求走同一个域名Cookie 和鉴权逻辑可以统一。手机上打开预览还有一个特殊处理容器内的设备模拟器比如 iOS Safari 的 user-agent默认是桌面模式我在预览入口处加了一个模式切换让用户自由选择模拟不同设备宽度。7. 安全与多租户隔离一台服务器上跑无数个项目7.1 请求层面的鉴权链路WebCode 的安全体系是分层的。最外层是 API 网关的统一鉴权所有请求先校验 JWT Token。Token 的有效期设得非常短15 分钟并配合 Refresh Token 轮换机制。这里有一个小细节如果用户的 IP 发生变化即使 Token 没过期也会要求重新认证一次。这个策略有效阻断了一部分 Token 被窃取的场景。往里一层是项目级别的权限校验。每个项目有一个独立的访问控制列表读者、写者、管理员三种角色。文件读写接口会校验当前用户是否对这个项目有写权限。这里用的是“项目内校验”而不是全局角色这样防止了一个管理员对整个平台有超权限。再往里是容器的网络隔离。Kubernetes NetworkPolicy 限制每个容器 Pod 不能主动访问平台内网段只能访问白名单内的服务如模型网关、对象存储。即使容器被攻破攻击者也无法横向移动。7.2 代码执行的沙箱边界WebCode 允许用户在自己的项目里执行终端命令这是一个功能也是最大的安全风险点。我做了几层加固。第一层是容器权限限制容器内运行的用户是非 root 用户并移除了 sudo 权限。第二层是资源限制每个容器设置 CPU 上限如 0.5 核、内存上限如 1GB、磁盘配额如 5GB。第三层是进程系统调用过滤容器开启 seccomp 白名单模式只允许常规的开发工具相关的系统调用。这三层对于防御常见的误操作和恶意脚本已经足够。不过要说明的是真正要达到银行级别的隔离还得用 Kata Containers 这类虚拟化隔离方案WebCode 目前采用的还是 Kubernetes 原生容器隔离适合中小规模团队自用或者创业初期的场景。7.3 数据安全与合规AI 代码生成后的责任归属AI 编程平台多了一个传统 IDE 没有的安全问题AI 生成的代码可能包含敏感信息或者未经授权的代码片段。我在 AI 生成结果的服务端增加了一个过滤层对所有生成代码做一次密钥检测正则匹配常见云厂商 AK/SK、数据库连接串和许可证指纹比对。发现问题时会阻断代码注入并向用户提示风险。从数据合规角度看用户项目里的代码默认不会用于模型训练。所有传给模型做推理的代码片段都会在 AI 网关层做脱敏处理移除文件路径、IP 地址、邮箱等个人信息。8. 性能优化与移动端适配让手机不再是二等公民8.1 编辑器启动性能从白屏到可用的 3 秒优化移动端的硬件资源有限编辑器的启动速度直接决定用户会不会流失。我做了三个层面的优化。首先是资源加载Monaco Editor 默认会加载很多语言服务我只保留了项目实际需要用到的语言包。比如一个 JavaScript 项目不需要加载 Python 的语言服务。这能让首次加载的 JS 体积减少 40%。其次是渲染性能。手机浏览器滚动长文件时Monaco 的渲染线程容易卡顿。我启用了 Monaco 的自动折叠优化和限制行数渲染模式在大文件中默认只渲染可视区域内的行。第三是缓存策略。编辑器的核心 JavaScript、CSS、Worker 脚本都设置了 service worker 缓存用户第二次打开时直接从本地缓存加载启动时间从 3 秒压缩到 1 秒以内。8.2 虚拟终端的体验优化手机上的终端是个难题虚拟键盘没有 Ctrl、Esc 这些键在终端里操作 Vim 极其痛苦。WebCode 的虚拟终端方案是自己实现的一个 WebSocket 通道连接容器内的 tty 进程前端用 xterm.js 渲染。我在原生 xterm.js 的基础上增加了一个“工具栏”把 Tab、Esc、方向键、Ctrl 和 Alt 做成可点击的虚拟按键还支持滑动屏幕来翻看终端历史输出。这些改动看起来很小实际使用体验提升了一个台阶。8.3 弱网环境下的适配策略移动网络经常出现高延迟、抖动和断线。我做了两类优化。第一类是请求合并。文件树加载、项目配置读取、最近运行记录查询这三个请求在项目打开时会并发发出后续优化为合并成一个接口减少弱网下的请求往返次数。第二类是 WebSocket 自动重连。断线后前端会以指数退避策略重连同时缓存断线期间产生的编辑操作。重连成功后通过 Yjs 的增量同步机制把离线变更推送给服务端。只要断线时间不超过 5 分钟用户几乎感知不到这次断线。9. 部署架构与监控把小平台做到稳定可运维9.1 单机部署到多节点集群的演进第一版 WebCode 是部署在一台 8C16G 的云服务器上的所有服务都用 Docker Compose 编排。这个阶段可以跑通完整流程但无法支撑多人同时使用。后来迁移到了 Kubernetes 集群架构上做了一个比较彻底的拆分。业务服务按功能拆成多个 Deployment每个副本数根据压力情况伸缩。CI/CD 流程使用 GitHub Actions 配合 Helm 实现代码合并到 main 分支后自动构建镜像、推送镜像仓库、更新集群内的 Deployment。9.2 关键指标监控与告警体系监控分三个维度平台级、容器级、用户级。平台级主要看 API 网关的请求量、错误率、P99 延迟。容器级看每个项目容器的 CPU、内存、文件系统占用趋势。用户级比较特殊看的是编辑器操作延迟、AI 补全请求的耗时分布和失败率。告警规则用 Prometheus 的 Alertmanager 实现重点告警条件是AI 网关的 P95 延迟超过 3 秒、服务器错误率超过 2%、容器内存连续 5 分钟超过 80%。告警通过 Webhook 推送到企业微信群里值班的同学能在手机上第一时间处理。9.3 成本控制AI 调用的费用黑洞怎么防AI 编程平台的日常运营成本大头不在服务器而在模型调用。尤其是大模型的对话和代码审查一次请求可能要消耗几千甚至上万 token。如果不做控制月底账单会吓死人。我的做法是三层配额控制。第一层是套餐配额不同套餐的用户有每月总 token 上限达到上限后可以继续使用编辑器基础功能但 AI 功能会被暂停。第二层是速率限制在 AI 网关层做 token 级别的滑动窗口限流防止一个用户短时间内大量调用。第三层是优先级队列付费额度高的用户请求优先进入队列低优先级的请求在系统繁忙时会排队。10. 从 0 到 1 的落地复盘什么招有效什么坑必须避10.1 必须提前想清楚的三件事复盘下来有三件事如果能提前想清楚整个项目进度会快很多。第一件是协作模型。协同编辑看起来是加分项但如果从第一天不按照协同架构去设计后期硬加协同功能简直等于把整个编辑器的数据层推翻重写。我的建议是哪怕一开始只用单人模式文件数据结构也要按可协同的模型来设计。第二件是 AI 网关抽象。模型这个东西更新太快如果没有一层独立的代理每次换模型都要动到业务代码非常痛。把“模型选择、参数配置、上下文截断、结果过滤”全部收敛到一个独立的模块里是无论如何都值得投入的工作。第三件是容器启动速度。开发环境下用户对等待非常敏感容器冷启动能不能在 5 秒内完成直接决定了用户是否愿意留下来。建议不要在请求时才创建容器而是做一个“预热池”提前创建好一批配置好环境的空闲容器用户请求时直接绑定。10.2 最容易翻车的技术细节文件监听是一个容易被低估的细节。在容器里做文件监听直接用 Node.js 的 fs.watch 在部分系统上会监听不到某些网络文件系统的变更尤其是挂载卷内的文件所以我在监听逻辑中加入了轮询兜底同时用防抖合并变更事件避免一次保存触发十几次同步。还有一个是终端的编码问题。手机端输入中文字符时如果终端的字符编码没有统一配置为 UTF-8会出现乱码。这在 xterm.js 和容器 tty 的桥接层特别常见解决办法是在建立 WebSocket 连接时显式发送一个包含字符集的协商参数。10.3 关于“手机上写代码”的最终体感很多人会问手机真的适合写代码吗我的答案分两层。如果手机上打开 WebCode 只做“应急修复”或者“临时查看”那体验已经非常好了几乎等同于桌面端。如果试图在手机上完成一整天的深度开发我相信短时间内更便携的硬件折叠屏、外接键盘可能会比软件方案更关键。但 WebCode 真正的价值也许不在于“把手机变成开发机”而是它证明了当开发环境的抽象程度足够高无论你在哪块屏幕上你的代码、你的工具、你的 AI 助手都是同一个生态。这才是从“手机上写代码”这个疯狂想法走到最后得到的最有意义的结论。