Gemini-CLI-UI 架构揭秘:React + Express + WebSocket 如何协同驱动 AI 编程
Gemini-CLI-UI 架构揭秘:React + Express + WebSocket 如何协同驱动 AI 编程
Gemini-CLI-UI 是一个为 Google 官方 Gemini CLI 打造的 Web 版 AI 编程界面,它用 React 构建前端、Express 支撑后端、WebSocket 负责实时通信,让你在任何设备(包括手机)上都能流畅进行 AI 辅助编程。这篇文章将带你由浅入深拆解它的整体架构,看看这三大技术是如何分工协作的。
三大组件一览:前端、后端与 Gemini CLI
先看全局。整个系统由三块组成,职责边界非常清晰:
- 前端(React + Vite,默认端口 4009):聊天界面、文件编辑器、Git 面板、会话列表等所有 UI
- 后端(Express + WebSocket,默认端口 4008):REST API、实时通信、进程调度、认证系统
- Gemini CLI(外部进程):真正干活的 AI 引擎,负责代码生成和管理
~/.gemini/projects/下的项目数据
后端通过"进程 spawn"的方式调用 Gemini CLI——它并不重写 AI 能力,而是把命令行工具包装成 Web 服务,这正是本项目架构最巧妙的一点。
前端层:React + Vite 打造跨设备界面
前端采用 React 18 + Vite + Tailwind CSS 的经典组合,核心组件都在 src/components/ 目录下:
| 组件 | 作用 |
|---|---|
| ChatInterface.jsx | 聊天主界面,与 Gemini 实时对话 |
| CodeEditor.jsx | 基于 CodeMirror 的代码编辑器,支持语法高亮和实时编辑 |
| Shell.jsx | 内置终端,基于 xterm.js 直接操作 Gemini CLI |
| FileTree.jsx | 交互式文件树,支持展开/折叠浏览 |
| GitPanel.jsx | Git 可视化:查看变更、暂存、提交、切换分支 |
| Sidebar.jsx | 项目与会话侧边栏 |
值得一提的是响应式设计:项目采用 Mobile-first 思路,配合 MobileNav.jsx 底部导航,手机体验接近原生 PWA,还可以"添加到主屏幕"。
开发模式下,vite.config.js 通过代理把 /api 请求转发到后端 4008 端口,/ws 路径则以 WebSocket 协议代理,前端因此无需关心跨域问题。
后端层:Express API 与 Gemini 进程调度
后端入口是 server/index.js,它在同一进程里承载了 Express HTTP 服务和 ws 库创建的 WebSocketServer,主要职责包括:
- REST API:项目列表、会话管理、文件读写等接口(server/projects.js 负责扫描
~/.gemini/projects/目录) - 进程调度:server/gemini-cli.js 中的
spawnGemini函数会启动 Gemini CLI 子进程,传入--prompt参数,并把 AI 输出逐块捕获、通过 WebSocket 推给前端——这就是"流式回复"的实现原理 - 文件监听:使用 chokidar 监听
~/.gemini/projects/目录变化,300ms 防抖后向所有在线客户端广播projects_updated消息,侧边栏因此能实时刷新 - 内置终端:借助
node-pty提供伪终端,让 Shell 面板拥有完整的命令行体验
会话持久化由 server/sessionManager.js 完成:每次对话都会追加消息到 ~/.gemini/sessions/,并重建会话上下文,保证上下文不丢失。
实时通信:WebSocket 如何串联前后端
如果说 REST API 是"请求-响应"的骨架,WebSocket 就是让界面"活起来"的血液。前端封装了一个 useWebSocket 自定义 Hook,它做了三件关键的事:
- 认证连接:从 localStorage 取出 JWT token,以
?token=查询参数附加到/ws连接上,后端在握手阶段校验身份 - 自动重连:连接断开后 3 秒自动重连,弱网环境也能保持稳定
- 消息分发:统一解析 JSON 消息,各组件订阅感兴趣的事件(AI 输出流、项目更新、终端输出等)
整条数据流非常清晰:浏览器 → WebSocket → Express 后端 → Gemini CLI 子进程,AI 的每个输出片段都沿原路实时回传,用户看到的打字机效果就来自这里。
安全与配置:SQLite + JWT + 工具白名单
远程可用的 AI 编程工具,安全设计缺一不可。本项目用了一个轻量但完整的方案:
- 用户认证:server/database/db.js 基于 better-sqlite3 管理
geminicliui_auth.db,表结构定义在 server/database/init.sql。首次启动自动建库,第一个注册用户即为管理员 - 密码安全:密码经 bcrypt 哈希后存储,配合 JWT 令牌实现无状态鉴权(逻辑见 server/middleware/auth.js),登录组件在 src/components/LoginForm.jsx
- 工具白名单:所有 Gemini CLI 工具默认禁用,需在设置面板手动开启,YOLO 模式(跳过所有确认)也需谨慎使用
模型选择、YOLO 模式、通知声音等配置都在设置面板中完成:
上手体验:安装与启动步骤
想亲自跑起来看看,只需三步:
- 克隆仓库并安装依赖(需 Node.js v20+,且本机已安装 Gemini CLI)
git clone https://gitcode.com/gh_mirrors/ge/Gemini-CLI-UI
cd Gemini-CLI-UI
npm install
- 复制环境变量模板并填写端口等配置:
cp .env.example .env - 启动开发模式(前后端同时运行):
npm run dev,然后访问http://localhost:4009
生产部署则执行 npm start,会先构建前端再由 Express 直接托管静态文件,单一端口即可对外服务。
代码导读:从哪里开始阅读?
如果你是第一次读这个项目源码,建议按下面的顺序切入:
- server/index.js —— 后端骨架:路由挂载、WebSocket 握手、文件监听
- server/gemini-cli.js —— 看子进程如何被 spawn、输出如何流式回传
- src/utils/websocket.js —— 前端实时通信的全部奥秘
- src/components/ChatInterface.jsx —— UI 如何消费这些消息
- vite.config.js —— 开发环境代理规则,5 分钟理解端口关系
总结
Gemini-CLI-UI 的架构精髓在于**"轻量包装,各司其职"**:React 负责把 AI 交互做得丝滑,Express 负责安全地调度系统资源,WebSocket 负责让数据实时流动,而 AI 能力则完全交给 Gemini CLI 本身。对于想学习如何为命令行 AI 工具构建 Web 界面的开发者来说,这套 React + Express + WebSocket 的组合是一个干净、完整、值得精读的参考样本。🚀


