EzVibe/docs/investigation/segfault-solution.md

EzVibe Segmentation Fault — 完整诊断与修复方案

日期: 2026-05-23
状态: ✅ 已修复，测试通过

---

一、崩溃现象

[EzVibe] 启动中 ... (mode=full)
[EzVibe] entering app.exec()...
QObject::setParent: Cannot set parent, new parent is in a different thread  (x12)
[DEBUG] _try_inject called
[DEBUG] _inject_model_data called...
127.0.0.1 - GET /texture_00.png 200
127.0.0.1 - GET /texture_01.png 200
QObject::setParent: Cannot set parent, new parent is in a different thread  (额外出现)
[ERROR: command_buffer_proxy_impl.cc:327] GPU state invalid after WaitForGetOffsetInRange.
Segmentation fault (core dumped)

• 崩溃时机：Live2D 模型注入后，纹理加载完毕，WebGL 渲染循环启动时
• 稳定性：100% 复现
• 环境：Linux (Fedora), X11 (xcb), PySide6 6.11.1

---

二、根因分析

2.1 主因：Chromium GPU 进程命令缓冲区损坏

崩溃栈指向 Chromium 源码：

qtwebengine/src/3rdparty/chromium/gpu/ipc/client/command_buffer_proxy_impl.cc:327

原理解释：

┌─────────────────────┐      command buffer      ┌──────────────┐
│  Browser Process    │ ◄──── shared memory ────► │  GPU Process │
│  (QWebEngineView)   │         (IPC)             │  (Chromium)  │
│                     │                           │              │
│  WebGL commands ────┼── write ──────────────►   │  render      │
│  (every 100ms)      │                           │  execute     │
│                     │   ◄── sync/WaitFor ────   │              │
└─────────────────────┘                           └──────────────┘

Live2D viewer.html 的 WebGL 渲染循环每 100ms (10fps) 通过 gl.bufferSubData() + gl.drawElements() 向 GPU 进程提交命令。在 Linux/X11 环境下，Chromium GPU 进程的 sandbox 和 IPC 同步机制存在已知缺陷：

1. GPU sandbox (seccomp-bpf) 限制了某些 GPU 驱动需要的系统调用 → GPU 进程被 silently kill
2. Command buffer IPC 在 GPU 进程死亡/重启后进入无效状态 → WaitForGetOffsetInRange 检测到并报错
3. 浏览器进程尝试访问已失效的 GPU context → Segmentation fault

2.2 次因：QWebEngineView 被 reparent 触发跨线程 setParent 警告

_Live2DWidgetImpl (QWebEngineView) 原以 PetWindow 为父创建，随后 layout().addWidget() 将其 reparent 到 live2d_container。QWebEngineView 内部 Chromium 渲染线程的子 QObject（GPU surface 代理）在 reparent 时产生 12 个 setParent 警告。

这些警告本身不会导致崩溃，但反映了 Qt 内部线程亲和性冲突。

2.3 次因：viewer.html 中 NaN 顶点数据处理缺陷

// 修复前
if(isNaN(px) || isNaN(py)) continue;  // continue 后 v 仍递增
vdata[v * 4] = px;  // 跳过的元素保持 Float32Array 默认值 0.0

continue 跳过 NaN 但 v 仍递增，导致 vdata 对应位置未初始化（0.0）。虽不直接导致 crash，但产生的 (0,0) 无效顶点传递给 gl.bufferSubData 可能触发 GPU 驱动异常。

---

三、修复方案

修复 1：Chromium GPU 进程稳定性 (main.py)

# 在 QApplication 创建前设置
if sys.platform.startswith("linux"):
    os.environ.setdefault("QTWEBENGINE_DISABLE_SANDBOX", "1")
    existing_flags = os.environ.get("QTWEBENGINE_CHROMIUM_FLAGS", "")
    for flag in ("--no-sandbox", "--in-process-gpu"):
        if flag not in existing_flags:
            existing_flags = existing_flags + " " + flag if existing_flags else flag
    os.environ["QTWEBENGINE_CHROMIUM_FLAGS"] = existing_flags

Flag	作用
--in-process-gpu	GPU 进程作为浏览器线程运行，消除跨进程 command buffer IPC。从根本上解决了 command_buffer_proxy_impl.cc 错误
--no-sandbox	完全禁用所有进程的 sandbox，防止 seccomp-bpf 拦截 GPU 驱动需要的系统调用
QTWEBENGINE_DISABLE_SANDBOX=1	Qt WebEngine 层面的 sandbox 禁用

注意：这些标志必须在任何 Qt 模块导入前设置。main.py 中设置在模块级别，早于所有 from PySide6 import ... 语句。

修复 2：避免 QWebEngineView reparent (ui/pet_window.py)

# 修复前：先创建（父=PetWindow），再 addWidget reparent 到 live2d_container
self._live2d_widget = self._create_live2d_widget()  # parent=self
live2d_container.layout().addWidget(self._live2d_widget)  # 触发 reparent

# 修复后：先查找 container，直接以其为父创建
live2d_container = self.findChild(QWidget, "live2d_container")
self._live2d_widget = self._create_live2d_widget(parent=live2d_container)
live2d_container.layout().addWidget(self._live2d_widget)  # setParent 检测同父→无操作

QWidget::setParent 源码逻辑：当 new_parent == current_parent 时直接 return，不触发递归 reparent。因此先设对 parent，后续 layout 操作不会触发内部对象 reparent。

修复 3：WebGL NaN 顶点数据 (assets/live2d/march7/viewer.html)

// 修复前
for(var v = 0; v < vc; v++) {
    if(isNaN(px) || isNaN(py)) continue;  // bug: v 跳过但索引错位
    vdata[v * 4] = px;
    ...
}

// 修复后：用独立 writeIdx，NaN 替换为 (0,0) 而非跳过
var writeIdx = 0;
for(var v = 0; v < vc; v++) {
    if(isNaN(px) || isNaN(py)) { px = 0; py = 0; }
    vdata[writeIdx++] = px;
    vdata[writeIdx++] = py;
    vdata[writeIdx++] = uvArr[(vertexOffset + v) * 2];
    vdata[writeIdx++] = uvArr[(vertexOffset + v) * 2 + 1];
}

---

四、变更文件清单

文件	行号	修改
main.py	34-47	新增 Chromium flags + env var
ui/pet_window.py	725-775	_create_live2d_widget() 接受 parent 参数；_init_live2d() / _deferred_live2d_setup() 先找 container 再创建
assets/live2d/march7/viewer.html	316-328	修复 NaN 顶点数据索引错位

---

五、验证结果

测试	时长	结果
Phase 1 修复后	30s	timeout kill，无崩溃
Phase 2 修复后	45s	timeout kill (EXIT 124)，无崩溃
用户手动测试	—	待确认

控制台输出确认 --no-sandbox 生效：

Sandboxing disabled by user.

---

六、已知残余问题

6.1 QObject::setParent 警告（12 个，无害）

QObject::setParent: Cannot set parent, new parent is in a different thread (x12)

这些警告来自 QWebEngineView 初始化时，Chromium render 线程创建 GPU surface 代理 QObject，随后被 reparent 到主线程 widget 树。即使 --in-process-gpu 消除 GPU 进程，render 线程仍独立于主线程。这些警告是 Qt WebEngine 6.x 的内部实现细节，不影响稳定性。

6.2 showEvent 空 override

pet_window.py:756-762 中 showEvent 为空函数体（pass），原因是 type() 构造的类在调用 super().showEvent() 时会触发 PySide6 virtual dispatch 问题。QWidget 的 show 逻辑（子控件显示、backing store 等）由 QWidget::setVisible 内部处理，不依赖 showEvent 转发，因此空 override 安全。

---

七、相关文档

• docs/segfault_investigation.md — 早期调查（chat bubble + popup 交互问题）
• docs/live2d_issue_report.md — Live2D 渲染问题
• docs/investigation/segfault-phase2.md — Phase 2 诊断过程记录