EzVibe/docs/investigation/segfault-root-cause-and-fix.md

EzVibe Segfault — 完整根因分析与修复方案

日期: 2026-05-23 状态: ✅ 已定位根因，已修复

---

一、崩溃现象

QObject::setParent: Cannot set parent, new parent is in a different thread (x12)
[JS→PY] init_start → webgl_ok → shader_ok → test_rect_ok → model_ok:d=307
[JS→PY] loading_textures:n=2 → texture_ok:0 → texture_ok:1 → textures_done:n=2
[JS→PY] building_buffers → buffers_ok:n=307 → scheduling_render
[JS→PY] ready → first_frame_ok
... 运行 20-30 秒正常 ...
Segmentation fault (core dumped)

• Live2D 初始化全部成功：WebGL 上下文、Shader、模型 307 drawables、纹理、缓冲区、首帧渲染
• 崩溃发生在 first_frame_ok 之后 20-30 秒
• 稳定复现，100%

---

二、诊断过程

阶段 1：排除 GPU 命令缓冲区损坏

早期崩溃在纹理加载后立即发生，伴随 GPU state invalid after WaitForGetOffsetInRange 错误。

修复: 添加 --no-sandbox --in-process-gpu Chromium 标志，消除了 GPU 进程 IPC 同步问题。

结果: GPU 命令缓冲区错误消失，但 segfault 仍然存在（只是延迟出现）。

阶段 2：排除连续 WebGL 渲染循环

原 viewer.html 使用 setInterval(100ms) 持续渲染 WebGL 帧。每次渲染触发 gl.bufferSubData + gl.drawElements，导致 Chromium GPU 对象频繁跨线程 reparent（产生额外 setParent 警告）。

修复: 将连续渲染改为单次 burst 模式（初始 10 帧后停止），按需渲染。

结果: setParent 警告数量从 23 个减少到 12 个（仅初始化阶段），且第一帧渲染成功。崩溃延迟到 ~30 秒。

阶段 3：追踪崩溃时间点

通过添加 QWebChannel 调试探针（[JS→PY] 消息）精确定位：

[JS→PY] first_frame_ok
(20-30 秒正常运行)
Segmentation fault

崩溃时间（启动后 ~30-40 秒，即 first_frame_ok 后 20-30 秒）精准对应 brain timer (_init_brain_timer.start(30_000))。

阶段 4：隔离确认

禁用 brain timer + test_reminder 后，应用稳定运行 2 分钟+，无崩溃。

确认: brain timer（每 30s）或 scheduler 触发的 show_reminder → _refresh_messages 是崩溃的直接触发点。

---

三、根因分析

崩溃路径

brain timer (30s)
  → _on_brain_tick()
    → 后台线程: asyncio loop → brain.decide_action()
      → _decide_proactive_action() → remind_water
    → QMetaObject.invokeMethod(_add_helper, "do_add", QueuedConnection)
      → 主线程: _do_add_message(text, is_self)
        → _refresh_messages()
          → deleteLater() 删除旧 QLabel
          → insertWidget() 添加新 QLabel
          → QLayout::invalidate() 向上传播到整个控件树
          → QWebEngineView 收到 resize/repaint 事件
          → Chromium compositor 尝试合成 WebGL 内容
          → 访问因 deleteLater 而处于无效状态的 GPU 资源
          → SIGSEGV

关键矛盾

• Live2D WebGL 渲染 + 聊天布局修改 两者单独运行时都稳定
• 两者同时启用时，任何消息添加（brain timer, scheduler, 用户输入）都会触发 _refresh_messages，从而在 WebGL compositor 活跃时修改 Qt 控件树
• deleteLater() + insertWidget() 的组合导致以下竞态：
  1. Qt 删除待销毁控件的内部引用
  2. Chromium compositor 在同一帧尝试合成 WebGL 内容
  3. compositor 访问已被删除的 Qt 内部对象

为什么首帧渲染后不立即崩溃

首帧渲染发生在 ~t=10s。此时没有消息触发 _refresh_messages。第一次可触发崩溃的 _refresh_messages 是：

• t=11s: scheduler test_reminder（如果启用）
• t=30s: brain timer remind_water

前者在测试中被禁用，后者精准对应崩溃时间。

---

四、修复方案

核心修复：_refresh_messages 控件复用

原理: 避免在 WebGL compositor 活跃时调用 deleteLater() / insertWidget() 修改 QLayout。

实现:

• 维护气泡 QLabel 缓存池 _bubble_widgets
• _refresh_messages 仅更新已有控件的 setText(), setStyleSheet(), show()/hide()
• 新控件仅在池容量不足时一次性创建（此时 WebGL 尚未渲染首帧）
• 完全消除 deleteLater() 调用

辅助修复

修复	文件	作用
纹理缩放至 1024×1024	viewer.html	GPU 内存从 128MB 降至 8MB
无 mipmap	viewer.html	减少 33% 纹理内存
QWebChannel JS 桥接	viewer.html + qwebchannel.js	JS→PY 调试探针
--no-sandbox --in-process-gpu	main.py	GPU 进程稳定性
gl.finish() 在首帧后	viewer.html	确保 GPU 操作完成后再发信号

---

五、验证结果

测试场景	时长	结果
brain timer 禁用	2 min+	无崩溃
brain timer 启用 + 控件复用	2 min+	无崩溃，消息正常显示

---

六、残余问题（已知）

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

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

来自 QWebEngineView 内部 Chromium 线程在初始化 GPU surface proxy 时的跨线程 reparent。Qt WebEngine 6.x 内部实现细节，不影响稳定性。

Live2D 白屏

如果 WebGL 上下文创建失败或纹理加载失败，Live2D 区域显示为透明/白色。当前通过 test_rect_ok 探针验证 WebGL 管线正常。

---

七、相关文件清单

文件	修改
ui/pet_window.py	_refresh_messages 控件复用；_scroll_to_bottom 直接引用；showEvent 显式 override
assets/live2d/march7/viewer.html	QWebChannel 集成；纹理缩放；Burst 渲染模式；WebGL 错误检查
ui/live2d_view.py	cleanup() 简化；onJsMessage 调试日志；playMotion/setExpression 按需渲染
main.py	Chromium flags: --no-sandbox --in-process-gpu --disable-gpu-rasterization --ignore-gpu-blocklist
agent/scheduler.py	(无最终修改，仅测试期间禁用 test_reminder)

---

八、经验教训

1. 不要在有 GPU compositor 的控件树中调用 deleteLater() + insertWidget()。Chromium 的合成器持有对其 Qt 控件的内部引用；在合成器活跃时销毁/创建控件会导致悬空指针。

2. --in-process-gpu 虽然避免了跨进程 IPC 崩溃，但会使 GPU 崩溃直接杀死整个进程。更好的做法是：先通过探针验证 WebGL 管线正常，然后减少 GPU 操作频率。

3. 控件复用总是比删除+重建更安全。对于聊天消息列表等动态内容，维护一个控件池并更新文本/可见性，而不是销毁和重建 QLabel。