Gemini-CLI-UI 架构揭秘:React + Express + WebSocket 如何协同驱动 AI 编程

原创2026-11-02 17:01:022,269 阅读

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/ 下的项目数据

Gemini-CLI-UI 系统架构图:前端、Express后端与Gemini CLI三大组件协同关系

后端通过"进程 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 协议代理,前端因此无需关心跨域问题。

Gemini-CLI-UI 聊天界面:项目列表、AI 回复流式输出与模型选择

后端层: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,它做了三件关键的事:

  1. 认证连接:从 localStorage 取出 JWT token,以 ?token= 查询参数附加到 /ws 连接上,后端在握手阶段校验身份
  2. 自动重连:连接断开后 3 秒自动重连,弱网环境也能保持稳定
  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 模式、通知声音等配置都在设置面板中完成:

Gemini-CLI-UI 设置界面:Gemini 模型选择、YOLO 模式与工具权限配置

上手体验:安装与启动步骤

想亲自跑起来看看,只需三步:

  1. 克隆仓库并安装依赖(需 Node.js v20+,且本机已安装 Gemini CLI)
git clone https://gitcode.com/gh_mirrors/ge/Gemini-CLI-UI
cd Gemini-CLI-UI
npm install
  1. 复制环境变量模板并填写端口等配置:cp .env.example .env
  2. 启动开发模式(前后端同时运行):npm run dev,然后访问 http://localhost:4009

生产部署则执行 npm start,会先构建前端再由 Express 直接托管静态文件,单一端口即可对外服务。

代码导读:从哪里开始阅读?

如果你是第一次读这个项目源码,建议按下面的顺序切入:

总结

Gemini-CLI-UI 的架构精髓在于**"轻量包装,各司其职"**:React 负责把 AI 交互做得丝滑,Express 负责安全地调度系统资源,WebSocket 负责让数据实时流动,而 AI 能力则完全交给 Gemini CLI 本身。对于想学习如何为命令行 AI 工具构建 Web 界面的开发者来说,这套 React + Express + WebSocket 的组合是一个干净、完整、值得精读的参考样本。🚀

登录后查看全文
Gemini-CLI-UI