志睿源官网｜稳定性加固上线记录（连接池治理）
官网偶发 500 的根因已定位并根治：借出的数据库连接未能归还，池被逐步耗尽。三项改动（收尾流程解耦 / 连接池三层保险 / 连接台账与阈值告警）已上线，全量回归 262 条断言通过，上线后连接台账归零、错误日志零新增；官网、MD 分享服务与在线产品服务三站同时受益。
上线日期：2026-09-17 涉及服务：志睿源官网、MD 阅读分享服务、在线产品服务（三站共用同一套自研 Web 框架公共层） 结论：本轮连接池治理（S1 / S2 / S3）三项改动已全部落地并上线。全量回归 262 条断言通过，上线后线上连接台账保持归零，错误日志零新增。
一、要解决的问题
官网此前存在一类难以复现的异常：偶发 500，单独刷新同一页面却一切正常。
真实表现是——连续浏览十几个页面后，后续请求开始排队、超时，重启服务即恢复；单点复现困难，容易误判成"网络抖动"。
二、根因
框架层有一条不变量被写错了。
对于需要访问数据库的接口，框架会先借出一条数据库连接，再由统一的收尾流程负责提交并归还。但收尾流程的第一行是"如果响应已结束就直接返回"——而有一部分业务代码会自行结束响应。
结果是：这条连接既不提交、也不归还，被永久占用。 池的容量被逐步吃满，新请求只能排队，排队超时后池被置空，进而出现空对象异常。
一句话概括：不是数据库扛不住，是借出去的连接忘了还。
三、三项改动
S1 · 收尾流程解耦 把"结束响应"和"归还连接"彻底拆开：资源回收无条件执行且可重复执行，只有真正写响应时才判断响应是否已经发出。同时保证收尾流程自身永不抛错，避免因重复触发导致异常。
S2 · 连接池三层保险
- 识别"孤儿连接"并代为归还——此前超时分支下会有一条连接被静默丢弃，既不产生日志、计数也看不出来
- 池失效后自动重建，且每次重试都重新确认池状态，不再出现空对象异常
- 并发建池只允许一个执行者，其余等待复用，消除冷启动抖动
- 关闭池时加上限时保护，避免个别连接长期占用导致重启卡住
S3 · 连接台账与阈值告警 新增实时台账，持续记录借出、归还、未归还、孤儿、失败、超时六项数据，每 30 秒输出一行；任一指标越过阈值即发出告警，并对外提供接口供监控程序读取。
同期修掉的既有隐患 改造过程中额外发现并修复 4 处既有问题，其中包括一条"仅在特定配置下才会触发、一旦触发就是全站 500"的引用错误。
四、验收
| 验证维度 | 结果 |
|---|---|
| 全量回归 | 7 套 262 条断言全部通过 |
| 端到端（真实数据库） | 借出与归还逐笔配平，未归还与孤儿连接均为 0 |
| 全站漏点扫描 | 借出 109 == 归还 109，零泄漏 |
| 上线后线上观测 | 三个站点未归还连接均为 0；长期为 0 的可用连接已恢复 |
| 错误日志 | 与修复前同一数量，零新增 |
| 站点探活 | 官网、MD 分享服务、接口、前端上报全部正常 |
| 持续监控 | 每 5 分钟运行的连接看门狗稳定触发，无告警 |
值得一提：本轮测试特意做了反向验证——把修复逐条改回旧写法，确认能复现出原来的故障现象（池被耗尽、出现同样的异常信息）。正向测试全绿只说明"没改坏"，能复现出故障才算真的修住了。
五、影响范围
改动位于公共框架层，因此官网、MD 阅读分享服务、在线产品服务三个站点同时受益，都获得了同等的连接治理与监控能力。
六、后续
- 连接看门狗已按每 5 分钟一次持续运行，监控连接台账、错误日志与端口探活；异常需连续出现两次才升级为告警，避免重启误报。
- 继续观察真实流量下的台账表现，根据运行数据校准告警阈值。
- 已排查站点静态资源的公开暴露面，相关处置与加固在推进中。
本文为对外发布版本，记录官网稳定性治理的阶段性进展。