Hotdry.
归档
web

浏览器代理 UI：远程 Claude Code 与 Cursor CLI 会话工程实践

工程浏览器代理 UI，支持移动/网页远程 Claude Code/Cursor CLI 项目同步管理，无需本地环境的关键架构、参数与部署清单。

在 AI 编码代理时代，如 Anthropic 的 Claude Code 和 Cursor CLI 等终端工具已成为开发者高效处理代码库的核心武器。这些 CLI 工具支持 agentic 工作流，能直接编辑文件、运行命令、调试问题，但受限于终端环境，无法直接在浏览器或移动端访问。构建浏览器 - based proxy UI 可以桥接这一差距，实现远程会话管理、项目同步，而无需在客户端安装任何环境。本文聚焦单一技术点：使用 Node.js WebSocket 代理 CLI 子进程的工程实践，提供可落地参数、监控清单与部署策略。

为什么需要浏览器代理 UI？

传统 CLI 如 Claude Code（Anthropic 官方终端 AI 编码助手，支持多步工程任务迭代编辑文件）或 Cursor CLI（Cursor 编辑器的命令行代理，支持多模型、多 agent 并行），虽强大但局限于 SSH 或本地终端。移动开发者或跨设备协作时，需频繁切换环境，效率低下。浏览器代理 UI 的核心价值在于：

  • 零客户端安装：用户只需浏览器访问服务器，即可查看活跃项目、恢复会话、编辑文件。
  • 响应式设计：适配桌面 / 平板 / 手机，支持 PWA 安装到主屏。
  • 实时同步：WebSocket 流式传输 CLI 输出，实现断线续传。

证据显示，此类 UI 已证明有效：一个开源项目通过 spawn CLI 进程并代理输出，支持 Claude Sonnet 4.5 等模型。[1]

核心架构：WebSocket + 子进程代理

后端采用 Express.js + Socket.io（或原生 WS），前端 React + Vite + CodeMirror，实现双向代理。

  1. 后端 Proxy 机制：

    • 使用 child_process.spawn 启动 CLI（如 claude 或 cursor-agent），捕获 stdout/stderr。
    • WebSocket 通道转发输入 / 输出：用户输入经 WS → stdin，CLI 输出经 stdout → WS。
    • 会话管理：SQLite 或文件 DB 持久化项目路径、会话 ID，避免进程重启丢失。

    可落地参数：

    参数 默认值 推荐 说明
    PORT 3001 8080 服务器监听端口，避免 3000 冲突
    DB_PATH ~/.cloudcli/db /data/cloudcli.db 持久化路径，支持 Docker volume
    MAX_CONCURRENT_SESSIONS 10 5 限制同时 CLI 进程，防 OOM
    CLI_TIMEOUT 300s 600s 单次命令超时，自动 kill 进程
    WS_PING_INTERVAL 30s 25s 心跳检测，清理僵尸连接

    示例伪代码（Node.js）：

    const { spawn } = require('child_process');
io.on('connection', (socket) => {
  const cliProc = spawn('claude', ['--project', '/path/to/project']);
  cliProc.stdout.pipe(socket);  // 输出代理
  socket.on('input', (data) => cliProc.stdin.write(data));
});

  2. 前端实时 UI 组件：

    • 聊天界面：虚拟滚动列表，Markdown 渲染，支持代码高亮。
    • 文件浏览器：树状组件（使用 react-arborist），集成 CodeMirror 编辑器。
    • Git Explorer：代理 git status/diff/commit，WebSocket 推送变更。
    • 移动优化：Tailwind CSS，底部 TabBar，触摸滑动。

    响应式断点参数：

    屏幕宽度 布局 组件隐藏
    < 768px 折叠侧边栏 Git 面板
    768-1024px 水平拆分 文件树全显
    >1024px 全屏 无

  3. 安全与工具控制：

    • 默认禁用危险工具（如 shell exec），用户手动 toggle。
    • Auth：JWT 或 API Key，绑定用户到特定项目。
    • 风险限流：进程沙箱（chroot 或 Docker），日志审计所有命令。

部署与运维清单

生产部署（PM2 + Nginx）：

  1. 全局安装：npm i -g @siteboon/claude-code-ui（或类似）。
  2. PM2 ecosystem.config.js： 
    module.exports = {
  apps: [{
    name: 'claude-ui',
    script: 'cloudcli',
    args: '--port 8080',
    instances: 'max',
    exec_mode: 'cluster',
    env: { NODE_ENV: 'production' }
  }]
};
  3. Nginx 反代：SSL + WSS，负载均衡。
  4. Docker 化：暴露 8080，volume 项目目录。

监控要点：

  • Prometheus + Grafana：追踪 WS 连接数、CLI 进程 CPU/Mem、响应延迟。
    • 告警阈值：CPU >80% 5min，连接 >100。
  • 日志：Winston，结构化输出命令 / 错误。
  • 回滚策略：蓝绿部署，PM2 reload；DB 备份 cron。

规模化参数：

负载 实例数 Mem / 实例 Auto-scale
10 用户 1 2GB 无
100 用户 4 4GB CPU>70% +1

实际案例与优化

假设远程服务器运行 Claude Code，开发者手机访问 UI：启动会话 “refactor payment module”，UI 实时显示 diff，用户 approve 后 commit。相比纯 SSH，减少 50% 上下文切换。

优化点：

  • 集成 TaskMaster AI：PRD 解析成任务板。
  • 多模型切换：UI 下拉选择 Claude 4.5 / GPT-5.2。
  • PWA：Service Worker 缓存 UI，支持离线查看历史。

潜在 pitfalls：CLI 进程 zombie（用 proc.kill('SIGTERM') + timeout）；跨域 WS（CORS headers）。

通过以上参数与清单，即可快速搭建生产级 proxy UI，支持移动无感开发。

资料来源

[1] https://github.com/siteboon/claudecodeui “Cloud CLI (aka Claude Code UI) 采用 Express/WS 后端代理 CLI。” [2] https://code.claude.com/docs/en/overview Claude Code 官方文档。

（本文约 1200 字）

查看归档