【跑团工具实战】神话与科学 Part 2那些 bug 一样鬼畜的线上事故排查实录如果你维护过一个跑团辅助工具或者说你参与过任何“业务规则看起来很简单、真上线却总是出莫名其妙问题”的项目下面这些场景肯定不陌生跑团群里骰娘突然连续投出同样的点数玩家刷了几十条消息问“是不是服务器坏了”明明刚保存好的角色卡过几分钟再看技能值好像被人偷偷改回了旧版本日志文件刷了几百 MB搜关键字什么都搜不到本地构建一次通过部署到服务器上直接崩错误信息还是“cannot find native binding”这种让人摸不着头脑的提示。这类问题有一个共同特点现象足够鬼畜根因却不复杂。它们大多不是隐藏很深的算法缺陷而是落在并发控制、数据一致性、日志规范、依赖环境这几个最容易被低估的环节。这篇文章就以一套典型的跑团辅助工具项目为背景复盘四类高频“鬼畜 Bug”的完整排查过程。项目代号就叫“神话与科学 Part 2”因为跑团的世界观是神话而工程排错靠的是科学。如果你正在做类似的小型在线工具或者经历过“本地没问题、一发生产就出事”的绝望感那么这篇文章既是一次排错思路的梳理也是一份可以直接落地的工程检查清单。1. 跑团辅助工具到底在做什么为什么容易出 Bug先说项目背景。一套典型的在线跑团辅助工具通常包含几个核心模块角色卡管理玩家创建调查员角色保存属性、技能、装备、背景故事。骰子判定根据规则计算成功率执行1d100、3d6、1d205这类掷骰表达式。剧情存档主持人记录剧情节点、NPC 状态、关键线索。规则查询内置克苏鲁神话相关规则文本方便玩家随时翻阅。从架构上看这类系统并不复杂。前端一个 Vue 或 React 页面后端一组 REST API数据库存角色卡和剧情数据Redis 做会话与临时缓存整个工程可能还不到 2 万行代码。但正是这种“看起来简单”的项目反而容易在细节上翻车。角色卡是典型的多用户协作数据两个人可能同时编辑同一张卡骰子服务是高频调用接口一次跑团一个晚上可能产生几百次判定请求日志和异常处理如果一开始没做好规范线上事故发生时基本等于盲人摸象。换句话说这类项目最大的技术风险不在功能实现而在三件事写操作被并发覆盖时版本控制是否生效。随机数、共享对象在多线程下是否线程安全。日志是否足以支撑事故回放和根因定位。这也解释了为什么“神话与科学”这个项目里的 Bug 总是带着一股鬼畜气质你反复检查业务逻辑发现规则都没写错但用户看到的数据和行为就是不对。2. 基础概念并发控制、随机数与日志边界在进入具体案例之前先把后面要用到的几个关键技术概念讲清楚否则代码看起来会缺少上下文。2.1 并发控制所谓并发控制是指多个请求同时修改同一条数据时系统如何保证最终结果不是“最后一次覆盖”随意决定。跑团场景中最典型的就是角色卡玩家 A 在笔记本上修改敏捷值玩家 B 在手机上同步修改技能点两个人几乎同时点了保存。如果不加控制数据库里保留的往往是后提交的那一条完整数据前一个人的修改被整体覆盖。解决思路一般两种乐观锁适合读多写少的场景。在数据表中增加版本号字段更新时带上WHERE version ?如果版本号匹配不上就说明数据已被别人改过直接报错或提示冲突。悲观锁用数据库行锁把当前事务锁住让其他操作等待。适合写冲突非常频繁的场景但同一张角色卡通常不存在那么高的并发使用悲观锁反而会增加锁等待。对跑团辅助工具来说乐观锁是更自然的方案因为大部分时间玩家在看规则、聊天、翻剧情真正保存角色卡的频率很低。2.2 随机数线程安全骰子判定的本质是生成随机数。Java 中最容易出问题的是直接使用Random实例。Random的核心方法是基于一个 48 位的种子计算如果多个线程共享同一个Random实例在并发较高时可能出现种子竞争导致部分线程拿到的随机序列出现明显的周期性或重复。等到了 JDK 1.7 之后更好的选择是ThreadLocalRandom。它把随机数生成器按线程隔离每个线程维护自己的种子既避免了竞争又不会因为大量创建Random对象造成性能损耗。2.3 日志边界日志不是越多越好而是要在“能回放问题”和“不噪音刷屏”之间找到平衡。真正有效的日志格式至少应该包含时间、线程、日志级别、Logger 名称、完整堆栈或结构化上下文信息。反过来最常见的坑是只打e.getMessage()不打印堆栈导致日志里看不到异常发生在哪一行。错误信息被catch后静默吞掉线上只剩一个“操作失败”。日志文件无滚动策略磁盘被打满后新日志写不进去事故现场反而丢失。这三个问题会直接导致一种诡异现象日志明明记录了错误但按关键字搜索后你根本定位不到原因。3. 鬼畜 Bug 一骰子连续重复是随机数还是并发3.1 现象玩家反馈某个跑团房里的骰娘连续十几次投出d100之后结果集中在不到 5 个数值之间甚至连续出现一模一样的点数。掷骰服务没有报错接口响应时间正常数据库也没有异常记录。从用户视角看这就像一个“灵异事件”。3.2 初步排查第一反应是检查掷骰逻辑。项目里最初使用的代码大约是下面这种写法// 文件路径src/main/java/com/example/trpg/service/DiceService.java public class DiceService { private final Random random new Random(); public int rollD100() { return random.nextInt(100) 1; } }单看逻辑nextInt(100) 1的范围是 1 到 100没有越界问题。但问题出在random这个成员变量上。Random实例作为 Spring 单例 Bean 被全局共享当跑团房间数量多、掷骰请求并发上来之后多个线程同时调用同一个Random的nextInt内部 CAS 更新种子时会不断重试极端情况下会出现种子回退或竞争加剧最终导致的表象就是随机序列异常集中。另外还有一种更隐蔽的写法如果项目里有任何地方使用了new Random(seed)并且 seed 是固定值那么每次重新启动后生成的序列会完全一样。这种问题在测试环境很难发现因为开发时请求量小并发竞争不明显一旦线上流量起来Bug 就“复现”了。3.3 根因Random的线程安全设计是通过原子变量更新种子来实现的它本身是线程安全的意思是不会导致数据损坏或抛出异常但不代表在高并发下依然能保证统计意义上的随机质量。多个线程争抢同一个原子种子时CAS 循环次数飙升部分线程拿到的连续随机数可能呈现出短周期特征。3.4 修复修复方案很简单改成ThreadLocalRandom同时支持3d6、1d1005这种复杂表达式的解析与掷骰。// 文件路径src/main/java/com/example/trpg/service/DiceService.java import java.util.concurrent.ThreadLocalRandom; public class DiceService { public int rollD100() { return ThreadLocalRandom.current().nextInt(1, 101); } public int rollDice(int diceCount, int sides, int modifier) { ThreadLocalRandom random ThreadLocalRandom.current(); int sum 0; for (int i 0; i diceCount; i) { sum random.nextInt(1, sides 1); } return sum modifier; } }这里有两个容易踩坑的细节nextInt(1, 101)的范围是左闭右开所以上界要写成 101才能生成 1 到 100 的整数。ThreadLocalRandom.current()在每次调用时获取当前线程的随机数生成器不要把它缓存到类的静态字段里复用。3.5 小结这个案例真正想说明的是不要因为 API 文档写着“线程安全”就认为它在所有场景下都合适。线程安全和并发质量是两回事。对随机数这种高频调用场景优先选择ThreadLocalRandom同时要警惕任何形式的固定种子。4. 鬼畜 Bug 二角色卡越改越少覆盖写丢了数据4.1 现象有玩家反馈角色卡保存后某些技能数值“凭空消失”变成初始值。一开始以为是个别手误后来越来越多人报告类似问题才意识到是系统级缺陷。4.2 数据现状检查数据库后发现一个规律出问题的角色卡都是被多人编辑过的。比如主持人代玩家调整属性玩家自己同时也在手机上改技能点。两个请求到达后端的时间相差不到一秒数据库里的最终记录却是其中一个人的旧版本另一个人的新值完全丢失。这就是典型的“丢失更新”问题。数据库层面没有任何保护最后的UPDATE直接覆盖了之前提交的数据。4.3 根因回到代码层面角色卡更新逻辑最初非常简单// 文件路径src/main/java/com/example/trpg/service/CharacterCardService.java public void update(CharacterCard card) { characterCardMapper.updateById(card); }updateById的执行逻辑是根据主键找到记录然后把传入的非空字段全部更新掉。整个过程没有版本判断没有冲突检测后提交的请求直接覆盖先提交的请求。如果前端再把整张角色卡的值都提交到后端那么多人协作编辑时任何一方的保存都会把另一方的改动抹掉。4.4 修复使用乐观锁第一步在角色卡表中增加version字段。ALTER TABLE character_card ADD COLUMN version INT NOT NULL DEFAULT 0;第二步修改实体类增加Version注解。// 文件路径src/main/java/com/example/trpg/entity/CharacterCard.java public class CharacterCard { private Long id; private String name; /** * 核心属性例如力量、敏捷、理智值等 */ private String attributes; /** * 版本号用于乐观锁控制 */ Version private Integer version; // getter / setter 省略 }第三步在 MyBatis-Plus 配置中注册乐观锁插件。// 文件路径src/main/java/com/example/trpg/config/MybatisPlusConfig.java Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor()); return interceptor; } }配置完成后调用updateById生成的 SQL 自动变成UPDATE character_card SET attributes ?, version version 1 WHERE id ? AND version ?如果影响行数为 0说明版本号不匹配数据已经被其他请求修改过。此时不能在 Service 层静默吞掉必须把冲突信息反馈给前端。// 文件路径src/main/java/com/example/trpg/service/CharacterCardService.java public void update(CharacterCard card) { int rows characterCardMapper.updateById(card); if (rows 0) { throw new BusinessException(SAVE_CONFLICT, 角色卡已被他人修改请刷新后重试); } }4.5 前端交互也要跟着改后端增加冲突提示后前端不能还在原地“干等”。更好的交互是保存前获取角色卡当前版本号保存时随请求提交。收到SAVE_CONFLICT错误后弹窗提示“角色卡已被修改是否查看最新版本”。玩家确认后刷新角色卡而不是直接覆盖。这个设计对跑团场景尤其重要因为玩家和主持人经常在同一场团里维护同一张角色卡冲突不是异常而是常态。4.6 小结丢失更新类的 Bug 最大的迷惑性在于很难用一个简单的单元测试复现只有多人同时操作时才触发。乐观锁方案成本低、侵入小是这类业务场景的默认选择。如果你正在设计任何涉及多人编辑同一份数据的系统建议直接在表结构里预留版本号字段不要等出事故再补。5. 鬼畜 Bug 三日志里全是错却找不到根因5.1 现象某次线上事故是这样的服务运行一段时间后某个接口开始大量返回 500用户反馈保存角色卡失败。开发人员登录服务器查看日志发现日志文件巨大打开后里面每隔几秒就刷出一行ERROR但所有错误信息都只有一句话operation failed。没有任何堆栈信息没有请求参数没有具体是哪个接口。5.2 排查过程我先把这种日志放在面前说一下实际排查时的感受你明知道系统已经报错了但你完全没有线索。你甚至不知道该从哪个类开始查因为你根本不知道异常是从哪里被捕获的。后来通过“暴力排查”才发现代码里存在一个非常宽泛的 catch// 文件路径src/main/java/com/example/trpg/controller/CharacterCardController.java PutMapping(/cards) public ResultVoid updateCard(RequestBody CharacterCard card) { try { characterCardService.update(card); return Result.success(); } catch (Exception e) { // 这里只打印了消息没有打印堆栈 log.error(operation failed: {}, e.getMessage()); return Result.fail(500, 操作失败); } }数据库连接池耗尽、参数校验失败、乐观锁冲突、空指针……所有这些不同类型的异常最终都只会输出一行operation failed。日志彻底失去了“定位根因”的能力。5.3 根因这里的问题不是某个单一 Bug而是整个项目的日志规范没有建立起来。典型错误包括捕获异常后只打印e.getMessage()不打印完整堆栈。多个异常类型被合并到一个 catch 中没有分类处理。日志没有配置滚动策略大量老日志占用磁盘新日志写入失败。日志级别不统一业务日志和系统日志混在一起。5.4 修复统一异常处理与日志格式首先去掉 Controller 里散落的 try-catch改为全局异常处理让异常在某一处统一记录。// 文件路径src/main/java/com/example/trpg/handler/GlobalExceptionHandler.java import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; RestControllerAdvice public class GlobalExceptionHandler { private static final Logger log LoggerFactory.getLogger(GlobalExceptionHandler.class); ExceptionHandler(BusinessException.class) public ResponseEntityResultVoid handleBusinessException(BusinessException e) { // 打印完整堆栈同时保留结构化上下文 log.error(业务异常: code{}, message{}, e.getCode(), e.getMessage(), e); return ResponseEntity.badRequest().body(Result.fail(e.getCode(), e.getMessage())); } ExceptionHandler(Exception.class) public ResponseEntityResultVoid handleException(Exception e) { // 兜底异常必须打完整堆栈 log.error(系统异常, e); return ResponseEntity.status(500).body(Result.fail(500, 系统繁忙请稍后重试)); } }其次配置 logback 的滚动日志避免日志把磁盘打满。!-- 文件路径src/main/resources/logback-spring.xml -- configuration appender nameFILE classch.qos.logback.core.rolling.RollingFileAppender filelogs/trpg-app.log/file rollingPolicy classch.qos.logback.core.rolling.TimeBasedRollingPolicy fileNamePatternlogs/trpg-app.%d{yyyy-MM-dd}.log/fileNamePattern maxHistory30/maxHistory /rollingPolicy encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n/pattern charsetUTF-8/charset /encoder /appender appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n/pattern /encoder /appender logger namecom.example.trpg levelDEBUG/ root levelINFO appender-ref refCONSOLE/ appender-ref refFILE/ /root /configuration最后还要约定一个排查铁律异常日志必须包含三部分内容——异常类型与完整堆栈、当前请求的上下文参数、能够区分业务场景的标识信息例如角色卡 ID、用户 ID。5.5 小结很多项目会用“线上日志太多打堆栈太占空间”来反驳但真实情况是日志文件再大也没有一台磁盘放不下的问题真正占空间的是无意义日志而不是那几行堆栈。宁可日志多一些也绝对不要让异常丢失现场。如果项目里存在catch (Exception e) { log.error(e.getMessage()); }这种写法建议尽早改成完整堆栈输出。6. 鬼畜 Bug 四本地能跑服务器一启动就崩6.1 现象前面几个问题都和业务逻辑相关。最后一类鬼畜 Bug 发生在部署环境特征非常统一本地开发时一切正常npm run build也没什么问题一部署到服务器前端服务启动后立刻报类似下面的错误cannot find native binding. npm has a bug related to optional dependencies后端日志同时可能出现内核层面的告警kernel:watchdog: bug: soft lockup - cpu#2 stuck for 23s!如果你只看报错信息很容易陷入“这是什么魔法”的困惑。实际上这两类问题的本质都是环境与依赖不一致。6.2 排查过程先看cannot find native binding。这个错误常见于前端项目依赖了包含原生模块的包例如sharp、bcrypt、node-sass这类带有编译产物的依赖。本地开发时npm 会下载并编译当前平台的二进制文件当你把项目整体拷贝到服务器或者只提交了源码没有重新执行依赖安装时原生模块的二进制文件与服务器平台不匹配就会报错。NPM 的optional dependencies是另一个雷区。当某个可选依赖下载失败时npm 的某些版本会出现内部状态不一致最终导致依赖树结构错乱node_modules里出现莫名其妙的缺失或重复。至于kernel soft lockup这个更偏向服务器宿主层面。它表示某个 CPU 长时间被一个内核线程占用系统在 23 秒内无法完成调度。遇到这种情况优先要判断是宿主机压力过大还是某一批请求触发了异常的资源消耗。跑团辅助工具这样的 Web 应用很少直接导致soft lockup但如果服务器上同时跑着大量容器、日志采集任务和构建进程CPU 抢占就可能发生。6.3 修复前端构建与部署的修复方向是放弃在服务器上做增量依赖更新改用干净构建和依赖锁定。# 删除本地依赖确保没有缓存脏数据 rm -rf node_modules package-lock.json # 重新安装使用 lockfile 锁定版本 npm install # 如果项目使用 package-lock.json推荐使用 npm ci 做干净构建 npm ci如果确实存在原生模块和可选依赖的兼容问题可以尝试# 安装时跳过 optional dependencies避免下载失败导致的依赖树污染 npm install --omitoptional部署时还要检查是否把node_modules直接提交到了服务器而不是在服务器上重新安装。前端构建用的 Node 版本和本地是否一致建议在部署脚本里显式指定 Node 版本。原生模块是否使用 Docker 镜像构建镜像的 CPU 架构与宿主机是否相同。对soft lockup这类宿主机问题第一件事不是改代码而是检查服务器监控。看是不是 CPU 已经持续跑满、内存是否不足导致频繁换页或者磁盘 IO 是否异常。如果镜像和宿主机配置没问题再考虑是否要调整容器 CPU 配额。# 查看服务器负载 top # 查看内核日志中的 lockup 相关信息 dmesg | tail -100 # 查看占用 CPU 的进程 ps -eo pid,pcpu,pmem,comm --sort-pcpu | head -206.4 小结“本地能跑、线上崩”的教训几乎每个项目都会遇到。核心解决办法不是期待一次配置终身免疫而是把构建环境和部署环境尽可能统一用 lockfile 锁依赖版本用 Docker 固定镜像用 CI/CD 脚本重新安装依赖不要在服务器上手工修node_modules。这类 Bug 一旦发生排查成本往往远超修复成本。7. 排查鬼畜 Bug 的通用方法论看完四个案例很多人会记住具体的修复代码但真正值得沉淀的是排查思路。面对“看起来不可能”的 Bug建议按下面这个顺序进行结构化排查。7.1 先复现再定位灵异 Bug 最忌讳上来就看代码。正确做法是先稳定复现。复现不了至少也要复现出发生条件。在跑团项目里“双人同时编辑角色卡”“高频掷骰请求”都是可以人为构造的复现路径。如果复现不出来就去看日志、监控和版本信息。很多时候Bug 只存在于某一批请求、某一种浏览器、某一个服务器节点下这本身就是一个重要线索。7.2 分清症状和根因“角色卡属性消失”是症状“UPDATE 语句无条件覆盖”是根因“日志全是 ERROR”是症状“catch 后没打印堆栈”是根因。排查时不要停留在症状层面反复猜测必须顺着调用链往下追找到那个真正让系统偏离预期的逻辑判断。7.3 用分层排查缩小范围可以把一次线上问题按以下层次拆分排查层次关注点典型例子症状层用户看到什么、接口返回什么500 错误、保存失败、重复数据接入层参数是否完整、请求是否到达后端参数校验失败、前端缺少 version 字段业务逻辑层核心规则是否符合预期骰子表达式解析错误、技能公式算错数据层数据是否被并发修改、事务是否生效乐观锁失效、事务未提交、脏数据环境层依赖和部署是否一致原生模块缺失、Node 版本不一致、CPU 资源不足每一层都有对应的验证方式。例如怀疑数据层就直接查数据库当前值怀疑环境层就在服务器上重新执行一遍构建命令。通过层层排除最终定位到具体环节。7.4 时刻保留“现场”任何时候都不要关掉现场的日志。磁盘满之前先压缩归档崩溃前先采集堆栈出现软锁定时先记录 dmesg 输出。很多项目事后复盘失败不是因为问题复杂而是因为“现场已经被清理干净了”。8. 工程实践建议让鬼畜 Bug 少一半根据前面的案例我整理了一套对实际项目更实用的工程建议。8.1 事务与并发控制提前设计每张核心数据表从设计第一天就加上version字段。写操作尽可能带上乐观锁判断不要等到出现覆盖事故再补。涉及多张表更新的业务操作必须使用Transactional并且明确测试事务回滚路径。8.2 日志规范从第一个接口开始所有异常必须在全局异常处理中统一打印禁止在业务代码里到处 catch。日志信息要包含请求 ID、用户 ID、业务主键方便串联一次完整调用。日志文件必须配置滚动策略禁止无上限写入。对第三方工具类日志保留原始输出不要二次包装成一句error。8.3 依赖管理以可复现为准前端项目提交 package-lock.json后端项目提交 pom.xml 或 build.gradle 的锁定版本。不要在服务器上手工修改依赖统一走 CI 脚本执行干净安装。原生模块依赖尽量固定 Node 版本或用 Docker 隔离构建环境。遇到类似cannot find native binding的错误先做一次rm -rf node_modules npm ci不要在一个被污染的node_modules上继续调试。8.4 静态检查与自动化测试除了运行时排查静态代码分析可以帮助提前拦截一部分问题。例如Polyspace Bug Finder、Code Prover 这类工具能对内存安全、逻辑缺陷做更严格的静态证明虽然商用工具的完整评估流程较重但至少要在项目中启用基础的静态检查插件避免低级的空指针、数据库连接未关闭和异常被吞等问题。8.5 关于 AI 辅助排错的提醒现在很多人遇到 Bug 会直接扔给 AI 助手分析。AI 在定位已知问题、生成修复示例方面确实很高效但有一个负面现象值得警惕当你给它的信息不足时它会“一直分析”给出大量看起来合理但方向错误的推测。原因很简单AI 看不到你的日志、数据、堆栈和请求链路。所以更好的实践是让 AI 做单点问题的解答器而不是整体事故的侦探。你先用结构化的方法把排查范围缩小到某一个类、某一 SQL、某一个依赖再把完整上下文丢给它通常能够得到更准确的答案。8.6 不同数据库产品的惯性差异如果项目做过数据库迁移比如从 MySQL 迁移到达梦、Oracle 等产品要特别注意聚合函数的行为差异。某个 SQL 在本地测试时结果正确不代表在生产数据库版本上语义一致。例如LISTAGG这类字符串聚合函数在不同数据库、不同版本上对 NULL 值处理和排序结果都有差异。遇到这类问题不要靠直觉直接在目标数据库版本上验证。9. 总结与后续方向回到开头说的“神话与科学”。跑团的世界观是神话但工程排错必须依赖科学。所谓科学不是知道多少个框架、会多少种高级写法而是有一套能应对不确定性的方法论数据被覆盖时先想到版本控制随机数集中时先想到并发日志找不出根因时先反省异常处理本地线上不一致时先检查依赖环境。这篇文章整理了四类高频 Bug 的完整案例从现象、根因、修复到预防措施都做了拆解。如果你正在维护跑团辅助工具、小型在线协作平台或者只是为团队写一个内部小系统建议把这篇文章里的检查项保存下来等下一次线上事故发生时逐条对照。后续可以继续深入的方向包括跑团场景下的持久化与事务边界设计、高频掷骰服务的性能优化、多人协作编辑的冲突 UI 交互方案以及如何把日志、监控和告警体系做成一套完整的可观测性方案。技术问题永远是具体的但只要排查思路是对的再鬼畜的 Bug 也一定能被拆穿。