Files

zg c4023c1623 初始化

2026-07-15 16:13:27 +08:00

name, description, metadata

name

description

metadata

session-20260618-1

2026-06-18 第1次会话 — 网关SocketTimeout日志分析 + Widget接入指南补全（后端文档+前端页面）

type	date	sessionNumber	startTime
session	2026-06-18	1	2026-06-18T01:18:00+08:00

2026-06-18 第1次会话

会话摘要

分析网关日志中频繁出现的 SocketTimeoutException / Broken pipe 错误，确认是下游 devops.server.zgitm.com 响应太慢导致客户端超时断开，不是网关 Bug
将 Widget 接入详细指南补充到 deployServer 文档体系（新建 06-gateway-widget.md）
将 Widget 接入详细内容更新到网关前端公网文档页面 IntegrationDoc.vue（https://web.gw.zgitm.com/docs/:token）

做了什么: 分析了 mokee-gateway-gateway 服务日志中大量 AsyncRequestNotUsableException → ClientAbortException → SocketTimeoutException / Broken pipe 异常栈
根因: 下游 devops.server.zgitm.com 的 /api/apps/{8,9,10}/builds 接口响应时间 >3秒，浏览器/前端超时主动断开连接，网关尝试写响应时发现 socket 已关闭
结论:
- 🔴 主要问题：下游 devops 服务响应太慢
- ⚠️ 网关问题：GlobalExceptionHandler 把客户端断开当成 ERROR 记录，应降级为 WARN 或静默忽略
- 🟡 前端问题：超时设置过短（~3秒），并发请求多导致日志刷屏

做了什么: 将 mokee-gateway-widget-integration.md 内容格式化后新建为编号文档 docs/06-gateway-widget.md
原因: 文档目录中原只有 01-05 号文档，Widget 接入指南是独立的未编号文件，需要纳入体系
涉及文件:
- 新建：deployServer/docs/06-gateway-widget.md
- 更新：deployServer/README.md（文档导航新增链接）
- 更新：deployServer/docs/05-implementation-plan.md（文件清单树形图）

做了什么: 将原来 3 行简略 HTML 代码替换为完整接入指南
新增内容:
- 🚫 常见错误说明：process is not defined 的原因（Vue 3.x 打包引用 process.env，浏览器无此全局变量）
- 步骤 1：index.html 引入 CSS（不引入 JS、不放占位 div）
- 步骤 2：TopBar.vue 中放置占位 div（必须在 Vue 模板中，不在 index.html）
- 步骤 3：main.js 中 mount 后动态加载脚本 + window.process = { env: {} } polyfill
- 原理说明：ASCII 流程图展示加载时序
- 排查清单：5 项常见问题对照表（Widget 不显示 / process 报错 / 登录不识别 / 样式错乱 / 跨域报错）
- CDN 资源地址
涉及文件: mokee-gateway-web/src/views/docs/IntegrationDoc.vue
- 注释头更新：8 个章节 → 10 个章节
- 模板：第 3.6 节完全重写
- Script：新增 widgetTroubleshooting 数据

IntegrationDoc.vue 修改需要重新构建部署 mokee-gateway-web 前端才能在 https://web.gw.zgitm.com/docs/:token 看到更新
网关 GlobalExceptionHandler 需要优化：ClientAbortException / AsyncRequestNotUsableException 降级为 WARN 或静默处理
排查 devops.server.zgitm.com 的 /api/apps/{8,9,10}/builds 接口性能，优化响应时间
前端可考虑增加超时时间或减少并发请求数