Web UI 环境部署全攻略：从预检查到故障排除的系统方法

预安装检查清单

在开始部署 Web UI 前，请确保您的系统满足以下条件：

检查项	最低要求	推荐配置	验证命令
操作系统	Linux/macOS/Windows	Ubuntu 22.04 LTS	uname -a (Linux) / systeminfo (Windows)
Python 版本	3.11.x	3.11.8	python --version
网络连接	稳定互联网	100Mbps以上	ping -c 5 github.com
磁盘空间	5GB 可用	10GB 可用	df -h (Linux/macOS) / dir (Windows)
Docker 环境	可选	Docker 20.10+	docker --version

专家提示：推荐使用 Linux 系统进行部署，兼容性最佳。Windows 用户需注意文件路径格式转换（如将 / 替换为 \）。

模块一：环境配置问题：Node.js 版本冲突解决方案

常见症状

• 启动时报错 "Error: Cannot find module 'node:fs'"
• 依赖安装时出现 "gyp ERR! stack Error: Python executable not found"
• 版本检查显示 Node.js 版本低于 16.x

处理步骤

1. 版本诊断

   node -v  # 检查当前 Node.js 版本
   npm -v   # 检查 npm 版本
   

2. 多版本管理

   # 使用 nvm 安装指定版本 Node.js
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
   source ~/.bashrc
   nvm install 18.18.0  # 安装推荐版本
   nvm use 18.18.0      # 切换到该版本
   

3. 环境变量配置 创建或编辑 .env 文件：

   # Node.js 环境配置
   NODE_ENV=production
   NODE_PATH=/usr/local/lib/node_modules
   # 代理设置（如需要）
   HTTP_PROXY=http://proxy.example.com:8080
   HTTPS_PROXY=http://proxy.example.com:8080
   

验证方式

# 检查 Node.js 版本是否正确
node -v | grep "v18.18.0" && echo "版本正确" || echo "版本错误"

# 验证 npm 安装功能
npm install -g serve
serve --version

模块二：浏览器集成问题：自定义浏览器配置与连接方案

常见症状

• 启动后提示 "Browser executable not found"
• 浏览器启动后立即崩溃
• Web UI 无法控制浏览器操作

处理步骤

1. 浏览器路径配置

   操作系统	浏览器路径配置
   Linux	BROWSER_PATH="/usr/bin/google-chrome"
   macOS	BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
   Windows	BROWSER_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"

   在 .env 文件中添加对应配置：

   BROWSER_PATH="/usr/bin/google-chrome"
   BROWSER_USER_DATA="~/.config/google-chrome/Default"
   USE_OWN_BROWSER=true
   

2. 浏览器启动参数配置 编辑 src/browser/custom_browser.py 文件，添加启动参数：

   # 添加在 browser.launch() 方法中
   launch_arguments = {
       "headless": False,
       "args": [
           "--no-sandbox",
           "--disable-dev-shm-usage",
           f"--user-data-dir={Config().BROWSER_USER_DATA}"
       ]
   }
   

3. 权限设置

   # Linux 系统需确保浏览器可执行权限
   chmod +x /usr/bin/google-chrome
   # 允许非root用户运行浏览器
   sudo sysctl -w kernel.unprivileged_userns_clone=1
   

验证方式

# 测试浏览器连接
python -c "from src.browser.custom_browser import CustomBrowser; browser = CustomBrowser().launch(); print('浏览器启动成功')"

模块三：容器化部署问题：Docker 环境隔离与网络配置

常见症状

• Docker 构建时报 "context deadline exceeded"
• 容器启动后 WebUI 无法访问
• 容器内无法连接外部网络

处理步骤

1. Docker 构建优化

   # 使用国内镜像源加速构建
   docker build --build-arg HTTP_PROXY=http://proxy.example.com:8080 \
                --build-arg HTTPS_PROXY=http://proxy.example.com:8080 \
                -t web-ui:latest .
   

2. 网络配置调整 编辑 docker-compose.yml 文件：

   version: '3'
   services:
     web-ui:
       build: .
       ports:
         - "7788:7788"
         - "6080:6080"
       environment:
         - VNC_PASSWORD=your_secure_password
         - DEFAULT_LLM=deepseek
       network_mode: "bridge"
       restart: unless-stopped
   

3. 容器状态监控

   # 启动服务
   docker compose up -d
   
   # 查看容器状态
   docker compose ps
   
   # 查看日志
   docker compose logs -f --tail=100
   

验证方式

# 检查服务健康状态
curl http://localhost:7788/health
# 预期返回: {"status": "healthy", "timestamp": "..."}

# 检查端口监听
netstat -tulpn | grep 7788

故障排查流程图

graph TD
    A[启动 Web UI] --> B{命令执行结果}
    B -->|成功| C[访问 http://localhost:7788]
    C --> D{页面加载情况}
    D -->|正常| E[使用系统]
    D -->|异常| F[检查浏览器控制台错误]
    B -->|失败| G[查看终端错误信息]
    G --> H{错误类型}
    H -->|Node.js 错误| I[检查 Node.js 版本和依赖]
    H -->|浏览器错误| J[检查浏览器路径和权限]
    H -->|Docker 错误| K[检查容器日志和网络配置]
    H -->|API 错误| L[检查 .env 文件配置]

配置文件参考

核心配置文件路径：

• 环境变量配置：.env
• 浏览器配置：src/browser/custom_browser.py
• WebUI 组件：src/webui/components/
• Docker 配置：docker-compose.yml

总结

通过本文介绍的系统化方法，您可以有效解决 Web UI 部署过程中的环境配置、浏览器集成和容器化部署三大类问题。关键在于遵循预安装检查清单，按照"问题定位-解决方案-验证方法"的框架处理每个问题，并善用提供的诊断命令和流程图进行故障排查。

对于复杂问题，建议先检查 .env 配置文件和容器日志，这两个位置通常包含最有价值的故障信息。如遇到持续问题，可尝试清理环境后重新部署，或参考项目中的 docs/troubleshooting.md 文档获取更多帮助。