ClaudeCLI2UI for Windows

基于 @cloudcli-ai/cloudcli 的 Claude Code 网页界面封装，提供浏览器端的 Claude Code 交互体验。

针对 Windows 平台做了多项修复和优化，修复了更新缓存、Service Worker 策略、Git SSL 等问题。

快速开始

# 安装依赖
npm install

# 启动服务（前台）
npm start

Windows 下推荐双击 start-claudecodeui.vbs 静默后台启动（无窗口）。

启动链路：VBS → launcher.exe (Windows GUI) → CreateProcess(DETACHED_PROCESS) → node.exe watch-restart.js → 服务器 node

启动后访问 **http://localhost:3001**，默认账号 admin / admin123。

启动方式

方式	说明
start.bat	后台启动（最小化窗口）
start-claudecodeui.vbs	静默启动，完全无窗口，适合开机自启
npm start	前台启动（终端可见）

重启方式

方式	说明
restart.bat	一键重启（会弹出终端窗口）
restart-claudecodeui.vbs	静默重启，完全无窗口，双击即可

看门狗（watch-restart.js）会在服务器意外退出时自动重启，并监控 package-lock.json 变化，检测到更新后自动重启。

自动补丁（patch-update.js）

每次 npm install 后自动运行，对 cloudcli 底层包做以下修补：

#	补丁	说明
1	spawn shell	用 cmd.exe /c（Windows）替换硬编码的 sh -c
2	npm install 本地模式	去掉全局 -g，改用 --force 本地安装，防止更新后变成空壳包
3	cwd 修复	Windows 下用 process.cwd() 而非 os.homedir()，避免嵌套 node_modules
4	静态资源缓存	immutable → must-revalidate，更新后浏览器能拿到新 JS 文件
5	更新哨兵文件	更新期间创建 .updating 文件，防止看门狗误杀
6	端口复用	启用 SO_REUSEADDR，解决 Windows TIME_WAIT 导致的重启端口冲突
7	Service Worker	/assets/ 缓存策略从 cache-first 改为 stale-while-revalidate，更新后自动获取新资源
8	更新命令自举	在 npm/git 更新命令后追加 && node patch-update.js，确保更新后所有补丁自动重打
9	Git HTTP/1.1	设置 GIT_HTTP_PROTOCOL_VERSION=1，修复 Windows schannel SSL HTTP/2 断连问题

更新

# 命令行更新（含自动打补丁）
npm install @cloudcli-ai/cloudcli@latest

# 或在 Web UI 设置页点击"立即更新"（更新后自动重启）

Web UI 更新会自动打完所有补丁（Patch 8 确保补丁在更新后重跑）。

常见问题

更新后刷新页面还是旧版本

根因： 云 cli 底层用 immutable 缓存 JS/CSS 资源，浏览器永远不请求新文件。Service Worker 也使用 cache-first 策略。

修复： patch-update.js 把缓存头改为 must-revalidate，同时把 SW 策略改为 stale-while-revalidate。点过"立即更新"后，清一下浏览器缓存或开无痕窗口即可。

Git clone 报 "server closed abruptly"

根因： Windows 的 schannel SSL 在 HTTP/2 下连接 GitHub 时偶发关闭通知丢失。

修复： patch-update.js 设置 GIT_HTTP_PROTOCOL_VERSION=1 强制走 HTTP/1.1。

Web UI 更新成功但版本未变

根因： 已从 @siteboon/claude-code-ui 迁移至 @cloudcli-ai/cloudcli，当前项目已使用新包，无需额外操作。

手动强制更新

npm install @cloudcli-ai/cloudcli@latest --force

端口被占用

如果 3001 端口被其他程序占用：

1. 找到占用进程：netstat -ano | findstr ":3001"
2. 杀掉进程：taskkill /f /pid <PID>
3. 或双击 restart.bat 自动处理

GitHub 推送被拒 (GH007)

remote: error: GH007: Your push would publish a private email address.

GitHub 开启了"阻止推送暴露私人邮箱"的保护。解决方法：

# 将 git 邮箱修改为 GitHub 的 noreply 地址
# 用户 ID 可通过 https://api.github.com/users/你的用户名 查询
git config user.email "45386748+kany2000@users.noreply.github.com"
git commit --amend --author="kany2000 <45386748+kany2000@users.noreply.github.com>" --no-edit

局域网访问

同一局域网内的其他设备可以通过浏览器访问本服务。

# 1. 以管理员身份运行以下脚本（只需执行一次）
enable-lan-access.bat

# 2. 查看本机局域网 IP
ipconfig | findstr IPv4

# 3. 其他设备在浏览器中访问 http://<你的局域网IP>:3001

脚本会添加 Windows 防火墙规则，允许局域网设备访问端口 3001。

静默启动不生效

开机启动目录：%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup

确保该目录下有 ClaudeCodeWebUI.vbs 文件。

项目结构

claudecli2ui/
├── package.json                # 项目配置
├── patch-update.js             # Windows 修复补丁（npm postinstall 自动运行）
├── watch-restart.js            # 看门狗（自动重启 + 文件日志）
├── launcher.cs                 # C# 静默启动器源码（P/Invoke + DETACHED_PROCESS）
├── launcher.exe                # 编译好的启动器（Windows GUI 应用）
├── start.bat                   # 后台启动脚本
├── start-claudecodeui.vbs      # 静默启动脚本（推荐）
├── restart.bat                 # 一键重启脚本（有窗口）
├── restart-claudecodeui.vbs    # 静默重启脚本（推荐）
├── enable-lan-access.bat       # 局域网访问设置
└── project/                    # 工作区目录

相关链接

• @cloudcli-ai/cloudcli - 底层 UI 包
• CloudCLI - 官方主页
• Claude Code - Anthropic 官方 CLI 工具