修复复盘 · 技术复盘可视化

干部任免审批表编辑器 V5.0(麒麟飞腾版)修复复盘

起点:smbeditor_5.0-0_all.deb 在原厂中标麒麟/银河麒麟 + 飞腾 D2000 上装完即崩,无法使用。

终点:smbeditor_5.0-1fix16_all.deb,可正常启动、编辑、保存、导出 PDF、导入 Word/WPS。

共 16 轮修复 按 问题层次 归类 便于同类问题 对号入座
8
问题层次
27
编号修复项
16
修复轮次
9
调试元坑

各层修复项分布(编号问题 + 关键阶段)

一·运行环境层
5
二·Electron 兼容层
7
三·安装包集成层
5
四·功能层
6
五·导出层
4
六·Word/WPS 导入
6
七·调试元问题
9

一、运行环境层:装完就崩

5 项 · #1–#5

关键判断:不是"软件有 bug",而是"软件绑定的运行时与国产 CPU/内核/安全模块不兼容"。改应用代码解决不了,必须换运行时 + 加兼容层。

1
启动约 10 秒必崩(SIGBUS),无报错
根因
自带 Electron 9(V8 8.8)在飞腾 D2000 + 64K 页内核上不兼容
解决办法
弃用自带运行时,改用本机 WorkBuddy 的 Electron 37(Chromium 138)跑原应用代码
2
换运行时后窗口能开但白屏/报错
根因
asar 解包时 header 长度算法算错两次,package.json 解出来是坏的,Electron 回落成"默认应用"
解决办法
asar 头:headerSize 在 offset 4,base=8+headerSize,jsonLen 从 base+4 读,json 从 base+8 开始
3
首次运行弹"未授权程序"
根因
麒麟 KYSEC 拦未签名二进制
解决办法
postinst 调 kysec_set 加白名单 + 启动参数 --no-sandbox
4
与 GPU 相关的随机崩溃
根因
摩尔线程 S30 无 /dev/dri 节点,GPU 栈残缺
解决办法
见第二节"GPU 崩溃"(这是最顽固的一个)
5
装完连 sudo 都受影响
根因
原包 postinst chmod -R 777 /opt/smbeditor 破坏了 chrome-sandbox 的 setuid
解决办法
权限精细化:只对 resources/app/temp 开放 777,chrome-sandbox 保持 4755

二、Electron 9 → 37 兼容层(app/electron-compat.js)

7 项 · #6–#12

Electron 9 到 37 跨了 28 个大版本,API 语义变了但不报错,全部表现为"点了没反应"。逐个踩。

6
渲染层整页 require is not defined,表单"静态假活"
根因
兼容层劫持 Module._load 用 __ecompatProxied 标记防重复包装,第二次 require('electron') 返回了原始对象 → nodeIntegration 没生效
解决办法
改成 proxyCache,每次调用都返回代理
7
关窗口报 event.sender 为 undefined
根因
E37 的 close/closed 事件对象不再带 sender
解决办法
改为 xxxWindow.webContents.send(...)
8
保存无效、另存为无文件
根因
渲染层大量沿用同步写法调 dialog,E37 返回 Promise,被当成路径字符串用
解决办法
兼容层做"回调签名适配",渲染层 confirmFun 统一返回 .then(r=>r.response),全部判断点 Promise 化(VerifyRulePars.js 用重入标志续存)
9
弹框选了"确定"但程序不继续
根因
showMessageBox(win, opts, callback) 第三参被忽略,回调永不执行
解决办法
同上,回调改 .then()
10
物理打印卡死
根因
E25+ 删除了 webContents.print 的回调版本
解决办法
兼容层补 print 适配,与 printToPDF 一致
11
打印/预览报错
根因
node-native-printer 原生模块 ABI 不兼容
解决办法
用 CUPS lp 命令做桩
12
打印机列表为空
根因
webContents.getPrinters 由同步变异步
解决办法
缓存 + 返回上次结果

三、安装包与系统集成层

5 项 · #13–#17
13
装完其它软件"默认打开方式"被抢,改不回来
根因
原包 MIME 多声明 application/ext + *.ext weight=60,update-desktop-database 把 application/ext=smbeditor.desktop 写进全局 mimeinfo.cache
解决办法
去掉 application/ext;postinst 删孤儿 ext.xml(先 grep 校验 owner)→ 重建 mime 库 → 重建 desktop cache → 遍历各用户 mimeapps.list 只删 ^application/ext=.*smbeditor 行
14
卸载后关联仍是坏的
根因
postrm 只删符号链接,desktop/mime 定义残留
解决办法
postrm 清理 desktop + mime 定义并刷新缓存
15
新版装上仍跑老代码
根因
旧版 Electron9 结构与新结构混在 /opt
解决办法
新增 preinst,安装前 rm -rf /opt/smbeditor
16
一输入内容就弹 EACCES 报错
根因
应用把自动保存/缓存写在安装目录 resources/app/temp/,原包靠全局 777 放行,收权后普通用户写不进
解决办法
postinst 只对 resources/app/temp 递归 777 并预建 4 个子目录
17
手工打的包双击安装静默失败
根因
control.tar.gz 被打成 DEBIAN/control 嵌套结构,dpkg 解析失败
解决办法
必须 tar -czf x -C DEBIAN control preinst postinst postrm 平铺;打完必跑 dpkg-deb -I 校验

四、功能层:启动参数与文件打开

6 项 · #18–#23
18
双击 .lrmx 打开是空白表单
根因
给 desktop 的 Exec 加了 --no-sandbox,argv[1] 变成参数而不是文件路径,原代码直接取 argv[1]
解决办法
extractFileArg() 扫描全部 argv,取第一个不以 - 开头、后缀合法的参数(first/second-instance 两处都改)
19
双击 .docx 只启动不导入
根因
extractFileArg 正则只认 .lrmx/.lrm;渲染层 SMB_Open_Default 也没有 docx 分支
解决办法
两处都加 docx|doc|wps,大小写不敏感
20
应用内"打开"对话框选任何文件都毫无反应
根因
兼容层 showOpenDialog 单文件时返回字符串;而 open-file.js 按数组遍历 → files[0] 是路径第一个字符 /,扩展名判断全失败,静默丢弃
解决办法
normalizeFilePaths() 数组/字符串统一;对话框与拖拽两个入口都归一化
21
打开无效路径(如 -1.lrmx)弹异常窗
根因
readFilePathSync 直接 fs.readFileSync,无存在性/后缀校验
解决办法
加校验 + showErrorBox 全换异步 showMessageBox(6 处)+ 主进程 uncaughtException 兜底
22
打开 docx 后整个窗口消失
根因
GPU 进程 FATAL:导入时注入照片 base64 大图,摩尔线程驱动崩,GPU process isn't usable. Goodbye. 整进程被杀
解决办法
必须在进程命令行加 --disable-gpu(disableHardwareAcceleration() 单独用无效)
23
导入 docx"没有内容"
根因
第 20、22 两个问题叠加,一个静默丢文件、一个崩进程
解决办法
分别修复后,导入链路才真正跑通

第 20 条最隐蔽:不报错、不写日志、任何文件都没反应,容易误判成"解析函数坏了"。定位手法是用桩件模拟对话框回调,拿旧代码跑一遍,把中间变量打出来——一眼看到逐字符 . d o c x,真相立刻明确。

五、导出层:保存格式 与 PDF

4 项 · #24–#27
24
另存为选任何格式都存成 .lrmx
根因
Linux GTK 保存框不会按所选过滤器自动补扩展名;E37 的 showSaveDialog 结果也不含所选 filter
解决办法
改为"先弹格式选择框(6 按钮)→ 再弹单格式保存框(defaultPath 带正确扩展名)";去掉写死的补 .lrmx
25
另存 PDF 打开全空白
根因
打印隐藏窗口 appendHtml 后 1 秒定时器就派发,不等页面导航/渲染完成
解决办法
主进程维护 did-start-navigation/did-finish-load 状态;渲染端 whenPrintContentReady(图片字体就绪 + 3 秒兜底)再触发;打印窗口 backgroundThrottling:false
26
另存 PDF 不生成文件(重试也无反应)
根因
mainHandleCompleted 里写成 webContents.fromId(id).webContents.send,E37 下 .webContents 为 undefined → 抛异常 → 外层 catch 把状态误置为"完成" → 任务重入队 → 管线死锁
解决办法
改为直接 send;调度器加 60 秒看门狗(超时重试 ≤3 次);全链路 pipeline.log 打点
27
PDF 本该 2 页却出 3 页,第二页顶部大片空白
根因
printToPDF 未指定纸型时 Chromium 默认 Letter(612×792pt),比 A4 矮约 50pt,内容挤出第 3 页
解决办法
兼容层 sanitizePrintOptions 兜底 pageSize=A4(8.27×11.69in) + margins=0

六、Word/WPS 导入层(fix11 → fix16)

6 阶段

这一层最能体现"改一个 bug 冒一个 bug"的连锁性。

fix11
原本没有"打开 Word"入口
问题
过滤器被注释掉
处理
打开/拖拽加 docx/doc/wps;文件头嗅探:PK\x03\x04 走 zip 解析(docx 及 docx 内核的 wps),D0CF11E0 是老二进制格式 → 弹提示并用系统 WPS 打开让用户另存 docx
fix12
双击 docx 不导入
问题
双击 docx 不导入
处理
见第四节第 19 条
fix13
导入后无内容、窗口消失
问题
导入后无内容、窗口消失
处理
见第四节第 22 条(GPU)
fix15
应用内打开全失效
问题
应用内打开全失效
处理
见第四节第 20 条(对话框返回值类型)
fix16
导入内容与编辑器项目对不上
问题
导入内容与编辑器项目对不上
处理
见下 · 按"标签"定位,而不是按固定行列号

fix16:按"标签"定位,而不是按固定行列号

sections/SMB.js · 解决 Word 表格错位导致字段串味

❌ 旧实现

  • temp/template/cellPosition.json 写死了"姓名取第 1 行第 2 格、民族取第 2 行第 2 格……"

为什么必然出问题

  • 文档表格行/列与模板有一点差异(多一行"到龄时间"、家庭主要成员行数不同),从差异处开始整体错位,A 项内容塞进 B 字段
  • 旧映射本身也错——"呈报单位"写的是 row 15 / col 1,那一格是标签文字本身
  • 编辑器没有的项目(到龄时间、审批机关意见、行政任免机关意见)随错位被塞进别的字段

✅ 新实现

  1. WORD_LABEL_FIELDS 白名单:19 个中文标签 ↔ lrmx 字段,只导入白名单内的标签
  2. 逐行扫描单元格,"标签在左、值在右"成对取值
  3. 标签不在白名单 → 整格丢弃,不写入任何字段
  4. 标签文字被 Word 打散也能认("年核度结考果" → "年度考核结果",用字符排序后比对)
  5. 学历/学位:同格两行且第二行含"学士/硕士/博士"才拆,否则按排版折行合并
  6. 毕业院校:取整格全文,旧实现按 w:t 切片会截断
  7. 简历:按段落换行(旧实现会丢掉 7 字以下的条目)
  8. 家庭主要成员:按表头列名逐行扫描,遇到"呈报单位/审批机关意见"结束,空行不生成条目——有几条导几条
  9. 导入前 clearEditorFormForImport() 清空表单,避免上篇文档身份证、成员行残留
  10. xmlObjParserStr 加 XML 转义,内容含 & < > 时不再生成非法 XML
验证方式(可复跑)
test_word_map.js gen_variants.py e2e_map_check.js
实测:真实 docx 20 个字段 + 4 条成员全对;删掉整行后其余字段不错位;插入"职级/备注"行并给"到龄时间"填值 → 界面上零出现。

七、调试环境本身的坑(元问题,最浪费时间)

9 个坑
坑表现绕过方式
KYSEC 拦脚本bash xx.sh、bash -n file 报"权限不够"bash < file / bash -s < script 管道方式
/opt 受 file protect直接 cp 覆盖(root 也不行)只能重新打 deb 安装
sudo 坏了sudoers.so 必须属于用户 ID 0走 deb 安装,debroot 目录权限放开直接改文件
单实例锁残留新实例静默退出(status 0),像"双击没反应"删 ~/.config/…/SingletonLock
命令跑在 PID 命名空间ps/pgrep 看不到真实进程,误判"没启动"用 systemd-run --user --pipe --wait + X 视角(wmctrl/xwininfo)判断
--disable-software-rasterizer加了它 jQuery 变 undefined、ligerUI 全崩 → 误判"jQuery 缺失"只用 --no-sandbox --disable-gpu;任何诊断先跑 lrmx 基线
CDP target 正则太宽URL 里含用户名 zzbqf,宽松正则误配到 ZZB 页面主窗口锚定 /SMB\.html$/
/tmp 只有 10M打 146M 的 deb 时 tar 失败TMPDIR 设到项目目录
用户测的是旧进程改完代码但用户窗口还是老进程,验证结论对不上交付时提醒"装新包 + 完全退出重启"

八、如果重来一次,建议的排查顺序

7 步
  1. 先分清是哪一层:装不上 / 启动崩 / 界面假活 / 功能没反应 / 输出不对。四层用的手段完全不同。
  2. 启动崩:先看是不是运行时与 CPU/内核不兼容(换运行时成本最低),再看安全模块(KYSEC 白名单)。
  3. 界面假活(能看见表单但按钮全无效):几乎都是 require('electron') 拿到原始模块,检查兼容层的代理缓存。
  4. 功能没反应但无报错:在 IPC 两端都打日志,重点核对参数类型(字符串 vs 数组),这类 bug 从不报错。
  5. 进程消失:翻主进程日志找 FATAL,GPU 相关一律先加 --disable-gpu。
  6. 输出不对(PDF 页数/版式/内容错位):先确认是不是"默认参数"问题(纸型、边距、扩展名),再查映射逻辑。
  7. 每轮修复都保留一个可复跑的脚本(e2e_*.js / test_*.js),否则下一轮很容易把上一轮改坏。