Linege

Appearance

故障排查指南 ​

遇到问题？这里有解决方案

启动问题 ​

错误：EADDRINUSE (端口被占用) ​

完整错误信息：

Error: listen EADDRINUSE: address already in use :::7788

原因：Sidecar WebSocket 服务器端口 7788 被占用

解决方案：

  1. 方法1：任务管理器强制结束

    Ctrl+Shift+Esc → 详细信息
找到所有 chrome.exe → 右键 → 结束任务
找到所有 electron.exe → 右键 → 结束任务

  2. 方法2：命令行杀进程

    powershell
    taskkill /F /IM chrome.exe
taskkill /F /IM electron.exe

  3. 方法3：检查端口占用

    powershell
    netstat -ano | findstr :7788
taskkill /F /PID <进程ID>

首次启动 Chrome 下载失败 ​

现象：进度条卡在 0% 或报网络错误

解决方案：

  1. 检查网络连接

    ping api.linege.com

  2. 关闭防火墙/杀毒软件

    • 临时关闭 Windows Defender
    • 临时关闭第三方杀毒软件

  3. 手动下载 Chrome 内核

    下载地址：https://api.linege.com/download/chrome/latest
解压到：%APPDATA%\Linege\core\

  4. 检查磁盘空间

    • Chrome 内核约需 500MB 空间
    • 确保 C:\Users\<用户名>\AppData\Roaming\Linege 目录可写

自我测试失败 ​

现象：启动后自动测试 4 个浏览器时失败

排查步骤：

  1. 查看日志

    打开：%APPDATA%\Linege\logs\main.log
搜索：[CRITICAL] 或 [ERROR]

  2. 常见错误：

    • CreateBrowserWindow failed：Chrome 路径不正确
    • WebSocket connection timeout：Sidecar 未启动
    • Port 9222 occupied：CDP 端口被占用

  3. 手动测试

    • 跳过自动测试，手动创建环境并启动
    • 如启动成功，说明自动测试脚本问题，可忽略

连接问题 ​

浏览器启动后无法连接 Sidecar ​

现象：浏览器状态为 Active，但群控不生效

排查步骤：

  1. 检查 profile.json

    位置：%APPDATA%\Linege\data\<env_id>\profile.json

必须包含：
{
  "profileId": "...",
  "envId": "..."  ← 必须存在
}

    如果缺少 envId：

    json
    {
  "profileId": "env_xxx_profile",
  "envId": "env_xxx"
}

  2. 检查 WebSocket 连接

    • 打开浏览器开发者工具（F12）
    • Console 标签
    • 搜索 WebSocket 或 ws://localhost:7788
    • 应该显示 WebSocket connection established

  3. 检查 Chrome 扩展

    • 访问 chrome://extensions/
    • 确认 Linege 扩展已加载
    • 检查扩展是否报错

WebSocket 连接超时 ​

错误信息：

WebSocket connection to 'ws://localhost:7788' failed

解决方案：

  1. 检查 Sidecar 是否运行

    主进程日志中应有：
[SidecarServer] Server started on port 7788

  2. 检查防火墙规则

    Windows 设置 → 防火墙 → 允许应用
添加：Linege.exe
允许：专用网络 + 公用网络

  3. 检查 hosts 文件

    C:\Windows\System32\drivers\etc\hosts

确保包含：
127.0.0.1  localhost

群控问题 ​

主浏览器操作不同步到从浏览器 ​

排查清单：

1. 群控模式已开启？

检查：应用边框是否有琥珀色高亮
检查：左侧按钮是否显示 "群控已开"

2. 主浏览器窗口在前台？

问题：主浏览器窗口最小化或被遮挡
解决：点击主浏览器窗口，确保在最顶层

3. 所有浏览器已连接 Sidecar？

检查：浏览器 Console 是否有 WebSocket 连接
检查：日志中是否有 "Linege browser connected" 记录

4. Master/Slave 角色正确？

日志中应显示：
[SidecarServer] Master elected: <profile_id>
[Chrome] Role: Master  ← 第一个启动的浏览器
[Chrome] Role: Slave   ← 后续启动的浏览器

粘贴（Ctrl+V）不同步 ​

原因：Windows 在 RDP 远程桌面中，粘贴检测失败

解决方案：

  1. 使用本地机器测试

    • RDP 会话中可能无法捕获剪贴板事件

  2. 手动触发粘贴

    • 在主浏览器中右键 → 粘贴
    • 或使用文本组输入功能批量填写

滚轮同步不生效 ​

原因1：RawInput Hook 未启动

检查日志：

[SidecarServer] Mouse wheel hook spawned: <script_path>
[SidecarServer] Mouse wheel hook ready

原因2：Windows Server RDP 环境

已知限制：

  • Windows Server 远程桌面中，低级钩子（WH_MOUSE_LL）不工作
  • 改用 RawInput API，但需前台窗口焦点

解决方案：

  • 使用本地 Windows 10/11 测试
  • 或使用物理机而非虚拟机

文本输入问题 ​

点击"顺序输入"没反应 ​

排查步骤：

1. 文本组是否为空？

检查：文本框中至少有一行非空内容

2. 浏览器是否全部启动？

检查：环境状态是否为 Active（绿色）
数量：文本行数 ≤ 启动的浏览器数量

3. 选择器是否正确？

默认：留空（使用 :focus 自动聚焦）
自定义：确保页面中存在该选择器（如 #username）

4. 检查日志

日志中应显示：
[SidecarServer] distribute_text_sequential ENTER
[SidecarServer] distribute_text_sequential SENT, i=0, targetProfile=...

窗口排列问题 ​

窗口排列顺序不是 1-2-3-4 ​

原因：窗口顺序基于启动时间（PID）

解决方案：

方法1：按顺序启动

1. 先启动第 1 个浏览器
2. 等待完全启动（状态变为 Active）
3. 再启动第 2 个
4. 依此类推...

方法2：检查 PID

任务管理器 → 详细信息 → 按 PID 排序
PID 最小的是第 1 个窗口

性能问题 ​

CPU 占用 100% ​

场景1：首次打开大型网站（正常）

现象：打开 Poly 等网站时 CPU 100%，持续 20-30 秒
原因：页面加载、JavaScript 初始化、资源下载
解决：等待页面完全加载后 CPU 会恢复正常

场景2：同时运行过多浏览器

现象：启动 10+ 个浏览器后 CPU 持续高位
解决：
  - 分批启动（每批 4-6 个）
  - 关闭不用的浏览器
  - 升级硬件（推荐 16GB 内存）

内存占用过高 ​

正常占用：

单个浏览器：300-500MB
10 个浏览器：3-5GB

代理问题 ​

代理连接失败 ​

错误信息：

ERR_PROXY_CONNECTION_FAILED
ERR_TUNNEL_CONNECTION_FAILED

排查步骤：

  1. 检查代理格式

    正确：http://user:[email protected]:8080
错误：192.168.1.100:8080  ← 缺少协议
错误：http://192.168.1.100  ← 缺少端口

  2. 检查代理服务器

    powershell
    curl -x http://user:pass@ip:port https://ip-api.com/json

  3. 检查代理认证

    用户名/密码是否正确
是否包含特殊字符（需 URL 编码）

日志分析 ​

日志位置 ​

%APPDATA%\Linege\logs\
├── main.log          # 主进程日志（IPC、启动、Sidecar）
├── renderer.log      # 渲染进程日志（React UI）
└── sidecar.log       # WebSocket 服务器日志（群控、文本输入）

关键日志标记 ​

错误级别：

[CRITICAL]  # 致命错误（应用崩溃）
[ERROR]     # 错误（功能失败）
[WARN]      # 警告（可恢复的问题）
[INFO]      # 信息（正常流程）
[DEBUG]     # 调试信息

关键流程标记：

[LAUNCH]             # 浏览器启动流程
[SidecarServer]      # WebSocket 服务器
[IPC]                # 进程间通信
[Chrome]             # Chrome 扩展
[STATE_INVALID]      # 状态异常

完全重置（最后手段） ​

如所有方法都无效，可完全重置：

WARNING

会删除所有数据，请提前备份

步骤：

  1. 关闭应用

    任务管理器 → 结束 Linege.exe

  2. 备份重要数据（可选）

    备份：%APPDATA%\Linege\data\<env_id>\

  3. 删除数据目录

    删除：%APPDATA%\Linege

  4. 重新启动应用

    应用会重新初始化、下载 Chrome 内核

联系支持 ​

如以上方法都无法解决，请联系技术支持并提供以下信息：

  1. 系统信息：Win+R → winver
  2. 应用版本：设置 → 关于
  3. 日志文件：%APPDATA%\Linege\logs\
  4. 复现步骤：详细操作描述 + 截图/录屏

Linege Anti-Browser Documentation

Copyright 2026 Linege Team